1056N/A<?
xml version="1.0" encoding="UTF-8"?>
1276N/A<
html xmlns="http://www.w3.org/1999/xhtml"><
head><
meta http-
equiv="Content-Type" content="text/html; charset=UTF-8" /><
title>Inter-Client Communication Conventions Manual</
title><
meta name="generator" content="DocBook XSL Stylesheets Vsnapshot_9276" /><
style xmlns="" type="text/css">/*
1276N/A * Copyright (c) 2011 Gaetan Nadon
1276N/A * Copyright (c) 2010, Oracle
and/
or its affiliates. All rights reserved.
1276N/A * Permission is hereby granted, free of charge, to any person obtaining a
1276N/A * copy of this software and associated documentation files (the "Software"),
1276N/A * to deal in the Software without restriction, including without limitation
1276N/A * the rights to use, copy, modify, merge, publish, distribute, sublicense,
1276N/A *
and/
or sell copies of the Software, and to permit persons to whom the
1276N/A * Software is furnished to do so, subject to the following conditions:
1276N/A * The above copyright notice and this permission notice (including the next
1276N/A * paragraph) shall be included in all copies or substantial portions of the
1276N/A * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1276N/A * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
1276N/A * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
1276N/A * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1276N/A * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
1276N/A * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
1276N/A * DEALINGS IN THE SOFTWARE.
1276N/A * Shared stylesheet for
X.Org documentation translated to HTML format
1276N/A * The sans-serif fonts are considered more legible on a computer screen
1276N/A font-family: "Bitstream Vera Sans", "DejaVu Sans", Tahoma, Geneva, Arial, Sans-serif;
1276N/A /* In support of using "em" font size unit, the w3c recommended method */
1276N/A * Selection: all elements requiring mono spaced fonts.
1276N/A * The family names attempt to match the proportionally spaced font
1276N/A * family names such that the same font name is used for both.
1276N/A * We'd like to use Bitstream, for example, in both proportionally and
1276N/A font-family: "Bitstream Vera Sans Mono", "DejaVu Sans Mono", Courier, "Liberation Mono", Monospace;
1276N/A * Books have a title page, a preface, some chapters and appendices,
1276N/A * a glossary, an index and a bibliography, in that order.
1276N/A * An Article has no preface and no chapters. It has sections, appendices,
1276N/A * a glossary, an index and a bibliography.
1276N/A * Selection: book main title and subtitle
1276N/A * Selection: article main title and subtitle
1276N/A * Selection: various types of authors and collaborators, individuals or corporate
1276N/A * These authors are not always contained inside an authorgroup.
1276N/A * They can be contained inside a lot of different parent types where they might
1276N/A * Reducing the margin at the bottom makes a visual separation between authors
1276N/A * We specify here the ones on the title page, others may be added based on merit.
1276N/A * Selection: the affiliation of various types of authors and collaborators,
1276N/A * individuals or corporate.
1276N/A * Selection: product release information (X Version 11, Release 7)
1276N/A * The releaseinfo element can be contained inside a lot of different parent
1276N/A * types where it might not be centered.
1276N/A * We specify here the one on the title page, others may be added based on merit.
1276N/A * Selection: publishing date
1276N/A * The legal notices are displayed in smaller sized fonts
1276N/A * Justification is only supported in IE and therefore not requested.
1276N/A * For documentation having multiple licenses, the copyright and legalnotice
1276N/A * elements sequence cannot instantiated multiple times.
1276N/A * The copyright notice and license text are therefore coded inside a legalnotice
1276N/A * element. The role attribute on the paragraph is used to allow styling of the
1276N/A * copyright notice text which should not be italicized.
1276N/A * Selection: book or article main ToC title
1276N/A * A paragraph is generated for the title rather than a level 2 heading.
1276N/A * We do not want to select chapters sub table of contents, only the main one
1276N/A * Selection: major sections of a book or an article
1276N/A * Unlike books, articles do not have a titlepage element for appendix.
1276N/A /* Add a border top over the major parts, just like printed books */
1276N/A /* The Gray color is already used for the ruler over the main ToC. */
1276N/A /* Put some space between the border and the title */
1276N/A * A Screen is a verbatim environment for displaying text that the user might
1276N/A * see on a computer terminal. It is often used to display the results of a command.
1276N/A /* Browser's vendor properties prior to CSS 3 */
1276N/A -webkit-border-radius: 1.0em;
1276N/A -khtml-border-radius: 1.0em;
1276N/A * Emphasis program listings with a light shade of gray similar to what
1276N/A * Found many C API docs on the web using like shades of gray.
1276N/A * Emphasis functions synopsis using a darker shade of gray.
1276N/A * Add a border such that it stands out more.
1276N/A * Set the padding so the text does not touch the border.
1276N/A * Selection: paragraphs inside synopsis
1276N/A * Removes the default browser margin, let the container set the padding.
1276N/A * Paragraphs are not always used in synopsis
1276N/A * Selection: variable lists, informal tables and tables
1276N/A * Set the left margin so it is indented to the right
1276N/A * Display informal tables with single line borders
1276N/A * Selection: paragraphs inside tables
1276N/A * Removes the default browser margin, let the container set the padding.
1276N/A * Paragraphs are not always used in tables
1276N/A * Add some space between the left and right column.
1276N/A * The vertical alignment helps the reader associate a term
1276N/A * with a multi-line definition.
1276N/A</
style></
head><
body><
div class="book"><
div class="titlepage"><
div><
div><
h1 class="title"><
a id="icccm"></
a>Inter-Client Communication Conventions Manual</
h1></
div><
div><
h2 class="subtitle">X Consortium Standard</
h2></
div><
div><
div class="authorgroup"><
div class="author"><
h3 class="author"><
span class="firstname">David</
span> <
span class="surname">Rosenthal</
span></
h3><
div class="affiliation"><
span class="orgname">Sun Microsystems, Inc.<
br /></
span></
div></
div><
div class="editor"><
h4 class="editedby">Edited by</
h4><
h3 class="editor"><
span class="firstname">Stuart</
span> <
span class="othername">W.</
span> <
span class="surname">Marks</
span></
h3><
div class="affiliation"><
span class="orgname">SunSoft, Inc.<
br /></
span></
div></
div></
div></
div><
div><
p class="releaseinfo">X Version 11, Release 7.7</
p></
div><
div><
p class="releaseinfo">Version 2.0</
p></
div><
div><
p class="copyright">Copyright © 1988, 1991, 1993, 1994 X Consortium</
p></
div><
div><
div class="legalnotice"><
a id="id2527033"></
a><
p>
1056N/APermission is hereby granted, free of charge, to any person obtaining
1056N/Aa copy of this software and associated documentation files (the
1056N/A"Software"), to deal in the Software without restriction, including
1056N/Awithout limitation the rights to use, copy, modify, merge, publish,
1056N/Adistribute, sublicense,
and/
or sell copies of the Software, and to
1056N/Apermit persons to whom the Software is furnished to do so, subject to
1056N/AThe above copyright notice and this permission notice shall be included
1056N/Ain all copies or substantial portions of the Software.
1276N/ATHE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS
1056N/AOR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
1056N/AMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
1056N/AIN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
1056N/AOTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
1056N/AARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
1056N/AOTHER DEALINGS IN THE SOFTWARE.
1056N/AExcept as contained in this notice, the name of the X Consortium shall
1056N/Anot be used in advertising or otherwise to promote the sale, use or
1056N/Aother dealings in this Software without prior written authorization
1276N/A</
p><
p>X Window System is a trademark of The Open Group.</
p></
div></
div><
div><
div class="legalnotice"><
a id="id2554215"></
a><
p class="multiLicensing">
1056N/ACopyright © 1987, 1988, 1989, 1993, 1994 Sun Microsystems, Inc
1056N/APermission to use, copy, modify, and distribute this documentation
1056N/Afor any purpose and without fee is hereby granted, provided
1056N/Athat the above copyright notice and this permission
1056N/Anotice appear in all copies.
1056N/ASun Microsystems makes no representations about the
1056N/Asuitability for any purpose of the information in this document.
1056N/AThis documentation is provided as is without express or implied warranty.
1276N/A</
p></
div></
div></
div><
hr /></
div><
div class="toc"><
p><
strong>Table of Contents</
strong></
p><
dl><
dt><
span class="preface"><
a href="#id2554237">Preface to Version 2.0</
a></
span></
dt><
dt><
span class="preface"><
a href="#id2554285">Preface to Version 1.1</
a></
span></
dt><
dt><
span class="chapter"><
a href="#Introduction">1. Introduction</
a></
span></
dt><
dd><
dl><
dt><
span class="sect1"><
a href="#Evolution_of_the_Conventions">Evolution of the Conventions</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Atoms">Atoms</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#What_Are_Atoms">What Are Atoms?</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Predefined_Atoms">Predefined Atoms</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Naming_Conventions">Naming Conventions</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Semantics">Semantics</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Name_Spaces">Name Spaces</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Discriminated_Names">Discriminated Names</
a></
span></
dt></
dl></
dd></
dl></
dd><
dt><
span class="chapter"><
a href="#Peer_to_Peer_Communication_by_Means_of_Selections">2. Peer-to-Peer Communication by Means of Selections</
a></
span></
dt><
dd><
dl><
dt><
span class="sect1"><
a href="#Acquiring_Selection_Ownership">Acquiring Selection Ownership</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Responsibilities_of_the_Selection_Owner">Responsibilities of the Selection Owner</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Giving_Up_Selection_Ownership">Giving Up Selection Ownership</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#Voluntarily_Giving_Up_Selection_Ownership">Voluntarily Giving Up Selection Ownership</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Forcibly_Giving_Up_Selection_Ownership">Forcibly Giving Up Selection Ownership</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Requesting_a_Selection">Requesting a Selection</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Large_Data_Transfers">Large Data Transfers</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Use_of_Selection_Atoms">Use of Selection Atoms</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#Selection_Atoms">Selection Atoms</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Target_Atoms">Target Atoms</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Selection_Targets_with_Side_Effects">Selection Targets with Side Effects</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Use_of_Selection_Properties">Use of Selection Properties</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#TEXT_Properties">TEXT Properties</
a></
span></
dt><
dt><
span class="sect2"><
a href="#INCR_Properties">INCR Properties</
a></
span></
dt><
dt><
span class="sect2"><
a href="#DRAWABLE_Properties">DRAWABLE Properties</
a></
span></
dt><
dt><
span class="sect2"><
a href="#SPAN_Properties">SPAN Properties</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Manager_Selections">Manager Selections</
a></
span></
dt></
dl></
dd><
dt><
span class="chapter"><
a href="#Peer_to_Peer_Communication_by_Means_of_Cut_Buffers">3. Peer-to-Peer Communication by Means of Cut Buffers</
a></
span></
dt><
dt><
span class="chapter"><
a href="#Client_to_Window_Manager_Communication">4. Client-to-Window-Manager Communication</
a></
span></
dt><
dd><
dl><
dt><
span class="sect1"><
a href="#Clients_Actions">Client's Actions</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#Creating_a_Top_Level_Window">Creating a Top-Level Window</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Client_Properties">Client Properties</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Window_Manager_Properties">Window Manager Properties</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Changing_Window_State">Changing Window State</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Configuring_the_Window">Configuring the Window</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Changing_Window_Attributes">Changing Window Attributes</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Input_Focus">Input Focus</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Colormaps">Colormaps</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Icons">Icons</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Pop_up_Windows">Pop-up Windows</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Window_Groups">Window Groups</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Client_Responses_to_Window_Manager_Actions">Client Responses to Window Manager Actions</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#Reparenting">Reparenting</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Redirection_of_Operations">Redirection of Operations</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Window_Move">Window Move</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Window_Resize">Window Resize</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Iconify_and_Deiconify">Iconify and Deiconify</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Colormap_Change">Colormap Change</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Input_Focus_2">Input Focus</
a></
span></
dt><
dt><
span class="sect2"><
a href="#ClientMessage_Events">ClientMessage Events</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Redirecting_Requests">Redirecting Requests</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Communication_with_the_Window_Manager_by_Means_of_Selections">Communication with the Window Manager by Means of Selections</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Summary_of_Window_Manager_Property_Types">Summary of Window Manager Property Types</
a></
span></
dt></
dl></
dd><
dt><
span class="chapter"><
a href="#Session_Management_and_Additional_Inter_Client_Exchanges">5. Session Management and Additional Inter-Client Exchanges</
a></
span></
dt><
dd><
dl><
dt><
span class="sect1"><
a href="#Client_Support_for_Session_Management">Client Support for Session Management</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Window_Manager_Support_for_Session_Management">Window Manager Support for Session Management</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Support_for_ICE_Client_Rendezvous">Support for ICE Client Rendezvous</
a></
span></
dt></
dl></
dd><
dt><
span class="chapter"><
a href="#Manipulation_of_Shared_Resources">6. Manipulation of Shared Resources</
a></
span></
dt><
dd><
dl><
dt><
span class="sect1"><
a href="#The_Input_Focus">The Input Focus</
a></
span></
dt><
dt><
span class="sect1"><
a href="#The_Pointer">The Pointer</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Grabs">Grabs</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Colormaps_2">Colormaps</
a></
span></
dt><
dt><
span class="sect1"><
a href="#The_Keyboard_Mapping">The Keyboard Mapping</
a></
span></
dt><
dt><
span class="sect1"><
a href="#The_Modifier_Mapping">The Modifier Mapping</
a></
span></
dt></
dl></
dd><
dt><
span class="chapter"><
a href="#Device_Color_Characterization">7. Device Color Characterization</
a></
span></
dt><
dd><
dl><
dt><
span class="sect1"><
a href="#XYZ_lt_gt_RGB_Conversion_Matrices">XYZ <-> RGB Conversion Matrices</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Intensity_dA_RGB_Value_Conversion">Intensity (dA RGB Value Conversion</
a></
span></
dt></
dl></
dd><
dt><
span class="chapter"><
a href="#Conclusion">8. Conclusion</
a></
span></
dt><
dd><
dl><
dt><
span class="sect1"><
a href="#The_X_Registry">The X Registry</
a></
span></
dt></
dl></
dd><
dt><
span class="appendix"><
a href="#revision_history">A. Revision History</
a></
span></
dt><
dd><
dl><
dt><
span class="sect1"><
a href="#The_X11R2_Draft">The X11R2 Draft</
a></
span></
dt><
dt><
span class="sect1"><
a href="#The_July_27_1988_Draft">The July 27, 1988, Draft</
a></
span></
dt><
dt><
span class="sect1"><
a href="#The_Public_Review_Drafts">The Public Review Drafts</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Version_10_July_1989">Version 1.0, July 1989</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Version_11">Version 1.1</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Public_Review_Draft_December_1993">Public Review Draft, December 1993</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Version_20_April_1994">Version 2.0, April 1994</
a></
span></
dt></
dl></
dd><
dt><
span class="appendix"><
a href="#suggested_protocol_revisions">B. Suggested Protocol Revisions</
a></
span></
dt><
dt><
span class="appendix"><
a href="#obsolete_session_manager_conventions">C. Obsolete Session Manager Conventions</
a></
span></
dt><
dd><
dl><
dt><
span class="sect1"><
a href="#Properties">Properties</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#WM_COMMAND_Property">WM_COMMAND Property</
a></
span></
dt><
dt><
span class="sect2"><
a href="#WM_CLIENT_MACHINE_Property_2">WM_CLIENT_MACHINE Property</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Termination">Termination</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Client_Responses_to_Session_Manager_Actions">Client Responses to Session Manager Actions</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#Saving_Client_State">Saving Client State</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Window_Deletion_2">Window Deletion</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Summary_of_Session_Manager_Property_Types">Summary of Session Manager Property Types</
a></
span></
dt></
dl></
dd></
dl></
div><
div class="preface"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="id2554237"></
a>Preface to Version 2.0</
h2></
div></
div></
div><
p>
1056N/AThe goal of the ICCCM Version 2.0 effort was to add new facilities, to fix
1056N/Aproblems with earlier drafts, and to improve readability and
1056N/Aunderstandability, while maintaining compatibility with the earlier
1056N/Aversions. This document is the product of over two years of discussion among
1056N/Athe members of the X Consortium's <
code class="function">wmtalk</
code> working group.
1056N/AThe following people deserve thanks for their contributions:
1056N/A</
p><
pre class="literallayout">
1056N/ASusan Dahlberg Bob Scheifler
1056N/AAndrew deBlois Jim VanGilder
1056N/AIt has been a privilege for me to work with this fine group of people.
1276N/A</
p></
div><
div class="preface"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="id2554285"></
a>Preface to Version 1.1</
h2></
div></
div></
div><
p>
1056N/ADavid Rosenthal had overall architectural responsibility
1056N/Afor the conventions defined in this document;
1056N/Ahe wrote most of the text and edited the document,
1056N/Abut its development has been a communal effort.
1056N/AThe details were thrashed out in meetings at the January 1988 MIT X Conference
1056N/Aand at the 1988 Summer Usenix conference,
1056N/Aand through months (and megabytes) of argument
1056N/A<
code class="function">wmtalk</
code>
1056N/AThanks are due to everyone who contributed,
1056N/Aand especially to the following people.
1056N/A</
p><
pre class="literallayout">
1056N/A</
p><
pre class="literallayout">
1056N/AFor the Window and Session Manager sections:
1056N/A</
p><
pre class="literallayout">
1056N/AKerry Kimbrough Glenn Widener
1056N/AFor the Device Color Characterization section:
1056N/A</
p><
pre class="literallayout">
1056N/AIn addition, thanks are due to those who contributed to the public review:
1056N/A</
p><
pre class="literallayout">
1276N/A</
pre></
div><
div class="chapter"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="Introduction"></
a>Chapter 1. Introduction</
h2></
div></
div></
div><
div class="toc"><
p><
strong>Table of Contents</
strong></
p><
dl><
dt><
span class="sect1"><
a href="#Evolution_of_the_Conventions">Evolution of the Conventions</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Atoms">Atoms</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#What_Are_Atoms">What Are Atoms?</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Predefined_Atoms">Predefined Atoms</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Naming_Conventions">Naming Conventions</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Semantics">Semantics</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Name_Spaces">Name Spaces</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Discriminated_Names">Discriminated Names</
a></
span></
dt></
dl></
dd></
dl></
div><
p>
1056N/AIt was an explicit design goal of X Version 11 to specify mechanism,
1056N/Aa client that converses with the server using the protocol defined
1056N/Aby the <
span class="emphasis"><
em>X Window System Protocol</
em></
span>, <
span class="emphasis"><
em>Version 11</
em></
span> may operate correctly
1056N/Ain isolation but may not coexist properly with others sharing the same server.
1056N/ABeing a good citizen in the X Version 11 world involves adhering to
1056N/Aconventions that govern inter-client communications in the following areas:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AManipulation of shared resources
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ADevice color characterization
1056N/AThis document proposes suitable conventions without attempting to enforce
1056N/Aany particular user interface.
1056N/ATo permit clients written in different languages to communicate,
1056N/Athese conventions are expressed solely in terms of protocol operations,
1056N/Anot in terms of their associated Xlib interfaces,
1056N/Awhich are probably more familiar.
1056N/AThe binding of these operations to the Xlib interface for C
1056N/Aand to the equivalent interfaces for other languages
1056N/Ais the subject of other documents.
1276N/A</
p><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Evolution_of_the_Conventions"></
a>Evolution of the Conventions</
h2></
div></
div></
div><
p>
1056N/AIn the interests of timely acceptance,
1056N/Athe <
span class="emphasis"><
em>Inter-Client Communication Conventions Manual</
em></
span> (ICCCM)
1056N/Acovers only a minimal set of required conventions.
1056N/AThese conventions will be added to and updated as appropriate,
1056N/Abased on the experiences of the X Consortium.
1056N/Athese conventions are upwardly compatible with those in the February 25, 1988,
1056N/Adraft that was distributed with the X Version 11, Release 2, of the software.
1056N/Asemantic problems were discovered with those conventions,
1056N/Aand, thus, complete upward compatibility could not be assured.
1056N/AThese areas are noted in the text and are summarized in Appendix A.
1056N/AIn the course of developing these conventions,
1056N/Aa number of minor changes to the protocol were identified as desirable.
1056N/AThey also are identified in the text, are summarized in Appendix B,
1056N/Aand are offered as input to a future protocol revision process.
1056N/AIf and when a protocol revision incorporating these changes is undertaken,
1056N/Ait is anticipated that the ICCCM will need to be revised.
1056N/ABecause it is difficult to ensure that clients and servers are upgraded
1056N/Aclients using the revised conventions should examine the minor protocol
1056N/Arevision number and be prepared to use the older conventions
1056N/Awhen communicating with an older server.
1056N/AIt is expected that these revisions will ensure that clients using
1056N/Athe conventions appropriate to protocol minor revision <
span class="emphasis"><
em>n</
em></
span>
1056N/Awill interoperate correctly with those that use the conventions
1056N/Aappropriate to protocol minor revision
1056N/A<
span class="emphasis"><
em>n</
em></
span> + 1 if the server supports both.
1276N/A</
p></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Atoms"></
a>Atoms</
h2></
div></
div></
div><
p>
1056N/AMany of the conventions use atoms.
1056N/Athe following sections attempt to amplify the description of atoms
1056N/Athat is provided in the protocol specification.
1276N/A</
p><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="What_Are_Atoms"></
a>What Are Atoms?</
h3></
div></
div></
div><
p>
1056N/Aatoms are unique names that clients can use to communicate information
1056N/AThey can be thought of as a bundle of octets,
1056N/Alike a string but without an encoding being specified.
1056N/AThe elements are not necessarily ASCII characters,
1056N/Aand no case folding happens.
1056N/AThe protocol designers felt that passing these
1056N/Asequences of bytes back and forth across the wire would be too costly.
1056N/AFurther, they thought it important that events
1056N/Aas they appear on the wire have a fixed size (in fact, 32 bytes)
1056N/Aand that because some events contain atoms, a fixed-size representation
1056N/ATo allow a fixed-size representation,
1056N/A( <
code class="function">InternAtom</
code> )
1056N/Awas provided to register a byte sequence with the server,
1056N/Awhich returns a 32-bit value (with the top three bits zero)
1056N/Athat maps to the byte sequence.
1056N/AThe inverse operator is also available
1056N/A( <
code class="function">GetAtomName</
code> ).
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Predefined_Atoms"></
a>Predefined Atoms</
h3></
div></
div></
div><
p>
1056N/AThe protocol specifies a number of atoms as being predefined:
1056N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
p>
1056N/APredefined atoms are not strictly necessary
1056N/Aand may not be useful in all environments,
1056N/Abut they will eliminate many
1056N/A<
code class="function">InternAtom</
code>
1056N/Arequests in most applications.
1056N/ANote that they are predefined only in the sense of having numeric values,
1056N/Anot in the sense of having required semantics.
1056N/APredefined atoms are an implementation trick to avoid the cost of interning
1056N/Amany of the atoms that are expected to be used during the startup phase
1056N/A<
code class="function">InternAtom</
code>
1056N/Arequests, which require a handshake, can be assumed <
span class="emphasis"><
em>a priori</
em></
span>.
1056N/ALanguage interfaces should probably cache the atom-name mappings
1056N/Aand get them only when required.
1056N/AThe CLX interface, for instance, makes no distinction between predefined atoms
1056N/Aand other atoms; all atoms are viewed as symbols at the interface.
1056N/AHowever, a CLX implementation will typically keep a symbol or atom cache
1056N/Aand will typically initialize this cache with the predefined atoms.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Naming_Conventions"></
a>Naming Conventions</
h3></
div></
div></
div><
p>
1056N/AThe built-in atoms are composed of uppercase ASCII characters with the
1056N/Alogical words separated by an underscore character (_), for example,
1056N/AThe protocol specification recommends that atoms used
1056N/Afor private vendor-specific reasons should begin with an underscore.
1056N/ATo prevent conflicts among organizations,
1056N/Aadditional prefixes should be chosen
1056N/A(for example, _DEC_WM_DECORATION_GEOMETRY).
1056N/AThe names were chosen in this fashion to make it easy to use them in a
1056N/AKeyword constructors allow the programmer to specify the atoms as LISP atoms.
1056N/AIf the atoms were not all uppercase,
1056N/Aspecial quoting conventions would have to be used.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Semantics"></
a>Semantics</
h3></
div></
div></
div><
p>
1056N/AThe core protocol imposes no semantics on atoms except as they are used in
1056N/AFor further information on FONTPROP semantics,
1056N/Asee the <
span class="emphasis"><
em>X Logical Font Description Conventions</
em></
span>.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Name_Spaces"></
a>Name Spaces</
h3></
div></
div></
div><
p>
1056N/AThe protocol defines six distinct spaces in which atoms are interpreted.
1056N/AAny particular atom may or may not have some valid interpretation
1056N/Awith respect to each of these name spaces.
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Space</
th><
th align="left">Briefly</
th><
th align="left">Examples</
th></
tr></
thead><
tbody><
tr><
td align="left">Property name</
td><
td align="left">Name</
td><
td align="left">WM_HINTS, WM_NAME, RGB_BEST_MAP, ...</
td></
tr><
tr><
td align="left">Property type</
td><
td align="left">Type</
td><
td align="left">WM_HINTS, CURSOR, RGB_COLOR_MAP, ...</
td></
tr><
tr><
td align="left">Selection name</
td><
td align="left">Selection</
td><
td align="left">PRIMARY, SECONDARY, CLIPBOARD</
td></
tr><
tr><
td align="left">Selection target</
td><
td align="left">Target</
td><
td align="left">FILE_NAME, POSTSCRIPT, PIXMAP, ...</
td></
tr><
tr><
td align="left">Font property</
td><
td align="left"> </
td><
td align="left">QUAD_WIDTH, POINT_SIZE, ...</
td></
tr><
tr><
td align="left"><
code class="function">ClientMessage</
code> type</
td><
td align="left"> </
td><
td align="left">WM_SAVE_YOURSELF, _DEC_SAVE_EDITS, &...</
td></
tr></
tbody></
table></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Discriminated_Names"></
a>Discriminated Names</
h3></
div></
div></
div><
p>
1056N/ASometimes a protocol requires an arbitrary number of similar
1056N/Aobjects that need unique names (usually because the objects are created
1056N/Adynamically, so that names cannot be invented in advance). For example, a
1056N/Acolormap-generating program might use the selection mechanism to offer
1056N/Acolormaps for each screen and so needs a selection name for each screen.
1056N/ASuch names are called "discriminated names" and are discriminated by
1056N/Asome entity. This entity can be:
1056N/A</
p><
pre class="literallayout">
1056N/A An X resource (a window, a colormap, a visual, etc.)
1056N/AIf it is only necessary to generate a fixed set of names for each value
1056N/Aof the discriminating entity, then the discriminated names are formed by
1056N/Asuffixing an ordinary name according to the value of the entity.
1056N/AIf <
span class="emphasis"><
em>name</
em></
span> is a descriptive portion for the name, <
span class="emphasis"><
em>d</
em></
span> is a decimal
1056N/Anumber with no leading zeroes, and <
span class="emphasis"><
em>x</
em></
span> is a hexadecimal number with
1056N/Aexactly 8 digits, and using uppercase letters, then such discriminated names
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Name Discriminated by</
th><
th align="left">Form</
th><
th align="left">Example</
th></
tr></
thead><
tbody><
tr><
td align="left">screen number</
td><
td align="left"><
span class="emphasis"><
em>name</
em></
span>_S<
span class="emphasis"><
em>d</
em></
span></
td><
td align="left">WM_COMMS_S2</
td></
tr><
tr><
td align="left">X resource</
td><
td align="left"><
span class="emphasis"><
em>name</
em></
span>_R<
span class="emphasis"><
em>x</
em></
span></
td><
td align="left">GROUP_LEADER_R1234ABCD</
td></
tr></
tbody></
table></
div><
p>
1056N/ATo discriminate a name by client, use an X resource ID created by that
1056N/Aclient. This resource can be of any type.
1056N/ASometimes it is simply necessary to generate a unique set of names (for
1056N/Aexample, for the properties on a window used by a MULTIPLE selection).
1056N/AThese names should have the form:
1056N/A</
p><
pre class="literallayout">
1056N/AU<
span class="emphasis"><
em>d</
em></
span> (
e.g., U0 U1 U2 U3 ...)
1056N/Aif the names stand totally alone, and the form:
1056N/A</
p><
pre class="literallayout">
1056N/A<
span class="emphasis"><
em>name</
em></
span>_U<
span class="emphasis"><
em>d</
em></
span> (
e.g., FOO_U0 BAR_U0 FOO_U1 BAR_U1 ...)
1056N/Aif they come in sets (here there are two sets, named "FOO" and
1056N/A"BAR"). The stand-alone U<
span class="emphasis"><
em>d</
em></
span> form should be used only if it is
1056N/Aclear that the module using it has complete control over the relevant
1056N/Anamespace or has the active cooperation of all other entities that might
1056N/Aalso use these names. (Naming properties on a window created specifically
1056N/Afor a particular selection is such a use; naming properties on the root
1056N/Awindow is almost certainly not.)
1056N/AIn a particularly difficult case, it might be necessary to combine both
1056N/Aforms of discrimination. If this happens, the U form should come after
1056N/A</
p><
pre class="literallayout">
1276N/A</
pre><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Rationale</
strong></
p></
div><
p>
1056N/AExisting protocols will not be changed to use these naming conventions,
1056N/Abecause doing so will cause too much disruption. However, it is expected
1056N/Athat future protocols -- both standard and private -- will use these
1276N/A</
p></
blockquote></
div></
div></
div><
div class="footnotes"><
br /><
hr width="100" align="left" /><
div class="footnote"><
p><
a id="ftn.id2526497" href="#id2526497" class="para"><
sup>[1] </
sup></
a>
1056N/AThe comment in the protocol specification for
1056N/A<
code class="function">InternAtom</
code>
1056N/Athat ISO Latin-1 encoding should be used is in the nature of a convention;
1056N/Athe server treats the string as a byte sequence.
1276N/A</
p></
div></
div></
div><
div class="chapter"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="Peer_to_Peer_Communication_by_Means_of_Selections"></
a>Chapter 2. Peer-to-Peer Communication by Means of Selections</
h2></
div></
div></
div><
div class="toc"><
p><
strong>Table of Contents</
strong></
p><
dl><
dt><
span class="sect1"><
a href="#Acquiring_Selection_Ownership">Acquiring Selection Ownership</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Responsibilities_of_the_Selection_Owner">Responsibilities of the Selection Owner</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Giving_Up_Selection_Ownership">Giving Up Selection Ownership</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#Voluntarily_Giving_Up_Selection_Ownership">Voluntarily Giving Up Selection Ownership</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Forcibly_Giving_Up_Selection_Ownership">Forcibly Giving Up Selection Ownership</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Requesting_a_Selection">Requesting a Selection</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Large_Data_Transfers">Large Data Transfers</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Use_of_Selection_Atoms">Use of Selection Atoms</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#Selection_Atoms">Selection Atoms</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Target_Atoms">Target Atoms</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Selection_Targets_with_Side_Effects">Selection Targets with Side Effects</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Use_of_Selection_Properties">Use of Selection Properties</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#TEXT_Properties">TEXT Properties</
a></
span></
dt><
dt><
span class="sect2"><
a href="#INCR_Properties">INCR Properties</
a></
span></
dt><
dt><
span class="sect2"><
a href="#DRAWABLE_Properties">DRAWABLE Properties</
a></
span></
dt><
dt><
span class="sect2"><
a href="#SPAN_Properties">SPAN Properties</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Manager_Selections">Manager Selections</
a></
span></
dt></
dl></
div><
p>
1056N/ASelections are the primary mechanism that X Version 11 defines
1056N/Afor the exchange of information between clients,
1056N/Afor example, by cutting and pasting between windows.
1056N/ANote that there can be an arbitrary number of selections
1056N/A(each named by an atom) and that they are global to the server.
1276N/A<
a class="xref" href="#Use_of_Selection_Atoms" title="Use of Selection Atoms">Use of Selection Atoms</
a>.
1056N/Adiscusses the choice of an atom.
1056N/AEach selection is owned by a client and is attached to a window.
1056N/ASelections communicate between an owner and a requestor.
1056N/AThe owner has the data representing the value of its selection,
1056N/Aand the requestor receives it.
1056N/AA requestor wishing to obtain the value of a selection provides the following:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe atom representing the data type required
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AOptionally, some parameters for the request
1056N/AIf the selection is currently owned,
1056N/Athe owner receives an event and is expected to do the following:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AConvert the contents of the selection to the requested data type
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/APlace this data in the named property on the named window
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ASend the requestor an event to let it know the property is available
1056N/AClients are strongly encouraged to use this mechanism.
1056N/Adisplaying text in a permanent window without providing the ability
1056N/Ato select and convert it into a string is definitely considered antisocial.
1056N/ANote that all data transferred between an owner and a requestor must usually
1056N/Ago by means of the server in an X Version 11 environment.
1056N/AA client cannot assume that another client can open the same files
1056N/Aor even communicate directly.
1056N/AThe other client may be talking to the server by means of
1056N/Aa completely different networking mechanism (for example, one client might
1056N/AThus, passing indirect references to data
1056N/A(such as, file names, host names, and port numbers)
1056N/Ais permitted only if both clients specifically agree.
1276N/A</
p><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Acquiring_Selection_Ownership"></
a>Acquiring Selection Ownership</
h2></
div></
div></
div><
p>
1056N/AA client wishing to acquire ownership of a particular selection
1056N/A<
code class="function">SetSelectionOwner,</
code>
1056N/Awhich is defined as follows:
1056N/A<
code class="function">SetSelectionOwner</
code>
1276N/A</
p><
div class="informaltable"><
table border="0"><
colgroup><
col align="left" class="c1" /></
colgroup><
tbody><
tr><
td align="left"><
span class="emphasis"><
em>selection</
em></
span>: ATOM</
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>owner</
em></
span>: WINDOW or
1056N/A<
code class="function">None</
code>
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>time</
em></
span>: TIMESTAMP or
1056N/A<
code class="function">CurrentTime</
code>
1056N/A </
td></
tr></
tbody></
table></
div><
p>
1056N/AThe client should set the specified selection to the atom that represents
1056N/Aset the specified owner to some window that the client created,
1056N/Aand set the specified time to some time between the current last-change time
1056N/Aof the selection concerned and the current server time.
1056N/AThis time value usually will be obtained from the timestamp of the event
1056N/Athat triggers the acquisition of the selection.
1056N/AClients should not set the time
1056N/A<
code class="function">CurrentTime</
code>,
1056N/Abecause if they do so, they have no way of finding
1056N/Awhen they gained ownership of the selection.
1056N/AClients must use a window they created so that requestors
1276N/Acan route events to the owner of the selection.<
a id="id2535529" href="#ftn.id2535529" class="footnote"><
sup>[2]</
sup></
a>
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AClients attempting to acquire a selection must set the time value of the
1056N/A<
code class="function">SetSelectionOwner</
code>
1056N/Arequest to the timestamp of the event triggering the acquisition attempt,
1056N/A<
code class="function">CurrentTime</
code>.
1056N/AA zero-length append to a property is a way to obtain a timestamp for
1056N/Athe timestamp is in the corresponding
1056N/A<
code class="function">PropertyNotify</
code>
1056N/A<
code class="function">SetSelectionOwner</
code>
1056N/Arequest is in the future relative to the server's current time
1056N/Aor is in the past relative to the last time the specified selection
1056N/A<
code class="function">SetSelectionOwner</
code>
1056N/Arequest appears to the client to succeed,
1056N/Abut ownership is not actually transferred.
1056N/ABecause clients cannot name other clients directly,
1056N/Athe specified owner window is used to refer to the owning client
1056N/A<
code class="function">GetSelectionOwner</
code>, in
1056N/A<
code class="function">SelectionRequest</
code> and
1056N/A<
code class="function">SelectionClear</
code>
1056N/Aevents, and possibly as a place to put properties describing the selection
1056N/ATo discover the owner of a particular selection,
1056N/A<
code class="function">GetSelectionOwner</
code>,
1056N/Awhich is defined as follows:
1056N/A<
code class="function">GetSelectionOwner</
code>
1276N/A</
p><
div class="informaltable"><
table border="0"><
colgroup><
col align="left" class="c1" /></
colgroup><
tbody><
tr><
td align="left"><
span class="emphasis"><
em>selection</
em></
span>: ATOM</
td></
tr><
tr><
td align="left">-></
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>owner</
em></
span>: WINDOW or
1056N/A<
code class="function">None</
code>
1276N/A </
td></
tr></
tbody></
table></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AClients are expected to provide some visible confirmation
1056N/ATo make this feedback reliable,
1056N/Aa client must perform a sequence like the following:
1056N/A</
p></
blockquote></
div><
pre class="literallayout">
1056N/ASetSelectionOwner(selection=PRIMARY, owner=Window, time=timestamp)
1056N/Aowner = GetSelectionOwner(selection=PRIMARY)
1056N/Aif (owner != Window) Failure
1056N/A<
code class="function">SetSelectionOwner</
code>
1056N/Arequest succeeds (not merely appears to succeed),
1056N/Athe client that issues it is recorded by the server as being the owner
1056N/Aof the selection for the time period starting at the specified time.
1276N/A</
p></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Responsibilities_of_the_Selection_Owner"></
a>Responsibilities of the Selection Owner</
h2></
div></
div></
div><
p>
1056N/AWhen a requestor wants the value of a selection,
1056N/A<
code class="function">SelectionRequest</
code>
1056N/Aevent, which is defined as follows:
1056N/A<
code class="function">SelectionRequest</
code>
1276N/A</
p><
div class="informaltable"><
table border="0"><
colgroup><
col align="left" class="c1" /></
colgroup><
tbody><
tr><
td align="left"><
span class="emphasis"><
em>owner</
em></
span>: WINDOW</
td></
tr><
tr><
td align="left"><
span class="emphasis"><
em>selection</
em></
span>: ATOM</
td></
tr><
tr><
td align="left"><
span class="emphasis"><
em>selection</
em></
span>: ATOM</
td></
tr><
tr><
td align="left"><
span class="emphasis"><
em>target</
em></
span>: ATOM</
td></
tr><
tr><
td align="left"><
span class="emphasis"><
em>property</
em></
span>: ATOM or
1056N/A<
code class="function">None</
code></
td></
tr><
tr><
td align="left"><
span class="emphasis"><
em>requestor</
em></
span>: WINDOW</
td></
tr><
tr><
td align="left"><
span class="emphasis"><
em>time</
em></
span>: TIMESTAMP or
1056N/A<
code class="function">CurrentTime</
code></
td></
tr></
tbody></
table></
div><
p>
1056N/AThe specified owner and selection will be the values that were specified in
1056N/A<
code class="function">SetSelectionOwner</
code>
1056N/AThe owner should compare the timestamp with the period
1056N/Ait has owned the selection and, if the time is outside,
1056N/A<
code class="function">SelectionRequest</
code>
1056N/Aby sending the requestor window a
1056N/A<
code class="function">SelectionNotify</
code>
1056N/Aevent with the property set to
1056N/A<
code class="function">None</
code>
1056N/A<
code class="function">SendEvent</
code>
1056N/Arequest with an empty event mask).
1056N/AMore advanced selection owners are free to maintain a history
1056N/Aof the value of the selection and to respond to requests for the
1056N/Avalue of the selection during periods they owned it
1056N/Aeven though they do not own it now.
1056N/AIf the specified property is
1056N/A<
code class="function">None</
code>,
1056N/Athe requestor is an obsolete client.
1056N/AOwners are encouraged to support these clients by using the specified target
1056N/Aatom as the property name to be used for the reply.
1056N/Athe owner should use the target to decide the form into which the selection
1056N/ASome targets may be defined such that requestors can pass parameters
1056N/Aalong with the request. The owner will find these parameters in the
1056N/Aproperty named in the selection request. The type, format, and
1056N/Acontents of this property are dependent upon the definition of the
1056N/Atarget. If the target is not defined to have parameters, the owner
1056N/Ashould ignore the property if it is present.
1056N/AIf the selection cannot be converted
1056N/Ainto a form based on the target (and parameters, if any),
1056N/A<
code class="function">SelectionRequest</
code>
1056N/AIf the specified property is not
1056N/A<
code class="function">None</
code>,
1056N/Athe owner should place the data resulting from converting the selection
1056N/Ainto the specified property on the requestor window
1056N/Aand should set the property's type to some appropriate value,
1056N/Awhich need not be the same as the specified target.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AAll properties used to reply to
1056N/A<
code class="function">SelectionRequest</
code>
1056N/Aevents must be placed on the requestor window.
1056N/Aif the data comprising the selection cannot be stored on the requestor window
1056N/A(for example, because the server cannot provide sufficient memory),
1056N/A<
code class="function">SelectionRequest</
code>,
1276N/A<
a class="xref" href="#Large_Data_Transfers" title="Large Data Transfers">Large Data Transfers</
a>.
1056N/AIf the property is successfully stored,
1056N/Athe owner should acknowledge the successful conversion
1056N/Aby sending the requestor window a
1056N/A<
code class="function">SelectionNotify</
code>
1056N/A<
code class="function">SendEvent</
code>
1056N/Arequest with an empty mask).
1056N/A<
code class="function">SelectionNotify</
code>
1056N/A<
code class="function">SelectionNotify</
code>
1276N/A</
p><
div class="informaltable"><
table border="0"><
colgroup><
col align="left" class="c1" /></
colgroup><
tbody><
tr><
td align="left"><
span class="emphasis"><
em>requestor</
em></
span>: WINDOW</
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>selection</
em></
span>,
1056N/A<
span class="emphasis"><
em>target</
em></
span>: ATOM
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>property</
em></
span>: ATOM or
1056N/A<
code class="function">None</
code>
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>time</
em></
span>: TIMESTAMP or
1056N/A<
code class="function">CurrentTime</
code>
1056N/A </
td></
tr></
tbody></
table></
div><
p>
1056N/AThe owner should set the specified selection, target, time,
1056N/Aand property arguments to the values received in the
1056N/A<
code class="function">SelectionRequest</
code>
1056N/A(Note that setting the property argument to
1056N/A<
code class="function">None</
code>
1056N/Aindicates that the conversion requested could not be made.)
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AThe selection, target, time, and property arguments in the
1056N/A<
code class="function">SelectionNotify</
code>
1056N/Aevent should be set to the values received in the
1056N/A<
code class="function">SelectionRequest</
code>
1056N/AIf the owner receives more than one
1056N/A<
code class="function">SelectionRequest</
code>
1056N/Aevent with the same requestor, selection, target, and timestamp it must
1056N/Arespond to them in the same order in which they were received.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Rationale</
strong></
p></
div><
p>
1056N/AIt is possible for a requestor to have multiple outstanding requests that
1056N/Ause the same requestor window, selection, target, and timestamp, and that
1056N/Adiffer only in the property. If this occurs, and one of the conversion
1056N/Arequests fails, the resulting
1056N/A<
code class="function">SelectionNotify</
code>
1056N/Aevent will have its property argument set to
1056N/A<
code class="function">None</
code>.
1056N/AThis may make it impossible for the requestor to determine which conversion
1056N/Arequest had failed, unless the requests are responded to in order.
1056N/AThe data stored in the property must eventually be deleted.
1056N/AA convention is needed to assign the responsibility for doing so.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/ASelection requestors are responsible for deleting properties whose
1056N/A<
code class="function">SelectionNotify</
code>
1276N/A<
a class="xref" href="#Requesting_a_Selection" title="Requesting a Selection">Requesting a Selection</
a>
1056N/A) or in properties with type MULTIPLE.
1056N/AA selection owner will often need confirmation that the data comprising the
1056N/Aselection has actually been transferred.
1056N/Aif the operation has side effects on the owner's internal data structures,
1056N/Athese should not take place until the requestor has indicated
1056N/Athat it has successfully received the data.)
1056N/AOwners should express interest in
1056N/A<
code class="function">PropertyNotify</
code>
1056N/Aevents for the specified requestor window
1056N/Aand wait until the property in the
1056N/A<
code class="function">SelectionNotify</
code>
1056N/Aevent has been deleted before assuming that the selection data has been
1056N/Atransferred. For the MULTIPLE request, if the different conversions require
1056N/Aseparate confirmation, the selection owner can also watch for the deletion
1056N/Aof the individual properties named in the property in the
1056N/A<
code class="function">SelectionNotify</
code>
1056N/AWhen some other client acquires a selection,
1056N/Athe previous owner receives a
1056N/A<
code class="function">SelectionClear</
code>
1056N/Aevent, which is defined as follows:
1056N/A<
code class="function">SelectionClear</
code>
1276N/A</
p><
div class="informaltable"><
table border="0"><
colgroup><
col align="left" class="c1" /></
colgroup><
tbody><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>owner</
em></
span>: WINDOW
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>selection</
em></
span>: ATOM
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>time</
em></
span>: TIMESTAMP
1056N/A </
td></
tr></
tbody></
table></
div><
p>
1056N/AThe timestamp argument is the time at which the ownership changed hands,
1056N/Aand the owner argument is the window the previous owner specified in its
1056N/A<
code class="function">SetSelectionOwner</
code>
1056N/AIf an owner loses ownership while it has a transfer in progress (that is,
1056N/Abefore it receives notification that the requestor has received all the data),
1056N/Ait must continue to service the ongoing transfer until it is complete.
1056N/AIf the selection value completely changes, but the owner happens
1056N/Ato be the same client (for example, selecting a totally different
1056N/Apiece of text in the same <
code class="function">xterm</
code> as before),
1056N/Areacquire the selection ownership as if it were not the owner,
1056N/Aproviding a new timestamp. If the selection value is modified, but
1056N/Acan still reasonably be viewed as the same selected object,
1056N/Athe owner should take no action.
1276N/A</
p></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Giving_Up_Selection_Ownership"></
a>Giving Up Selection Ownership</
h2></
div></
div></
div><
p>
1056N/AClients may either give up selection ownership voluntarily
1056N/Aor lose it forcibly as the result of some other client's actions.
1276N/A</
p><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Voluntarily_Giving_Up_Selection_Ownership"></
a>Voluntarily Giving Up Selection Ownership</
h3></
div></
div></
div><
p>
1056N/ATo relinquish ownership of a selection voluntarily,
1056N/A<
code class="function">SetSelectionOwner</
code>
1056N/Arequest for that selection atom, with owner specified as
1056N/A<
code class="function">None</
code>
1056N/Aand the time specified as the timestamp that was used to acquire the selection.
1056N/Athe client may destroy the window used as the owner value of the
1056N/A<
code class="function">SetSelectionOwner</
code>
1056N/Arequest, or the client may terminate.
1056N/Athe ownership of the selection involved will revert to
1056N/A<
code class="function">None</
code>.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Forcibly_Giving_Up_Selection_Ownership"></
a>Forcibly Giving Up Selection Ownership</
h3></
div></
div></
div><
p>
1056N/AIf a client gives up ownership of a selection
1056N/Aor if some other client executes a
1056N/A<
code class="function">SetSelectionOwner</
code>
1056N/Afor it and thus reassigns it forcibly,
1056N/Athe previous owner will receive a
1056N/A<
code class="function">SelectionClear</
code>
1056N/Aevent. For the definition of a
1056N/A<
code class="function">SelectionClear</
code>
1276N/A<
a class="xref" href="#Responsibilities_of_the_Selection_Owner" title="Responsibilities of the Selection Owner">Responsibilities of the Selection Owner</
a>
1056N/AThe timestamp is the time the selection changed hands.
1056N/AThe specified owner is the window that was specified by the current owner
1056N/A<
code class="function">SetSelectionOwner</
code>
1276N/A</
p></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Requesting_a_Selection"></
a>Requesting a Selection</
h2></
div></
div></
div><
p>
1056N/AA client that wishes to obtain the value of a selection in a particular
1056N/Aform (the requestor) issues a
1056N/A<
code class="function">ConvertSelection</
code>
1056N/Arequest, which is defined as follows:
1056N/A<
code class="function">ConvertSelection</
code>
1276N/A</
p><
div class="informaltable"><
table border="0"><
colgroup><
col align="left" class="c1" /></
colgroup><
tbody><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>selection</
em></
span>,
1056N/A<
span class="emphasis"><
em>target</
em></
span>: ATOM
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>property</
em></
span>: ATOM or
1056N/A<
code class="function">None</
code>
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>requestor</
em></
span>: WINDOW
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>time</
em></
span>: TIMESTAMP or
1056N/A<
code class="function">CurrentTime</
code>
1056N/A </
td></
tr></
tbody></
table></
div><
p>
1056N/AThe selection argument specifies the particular selection involved,
1056N/Aand the target argument specifies the required form of the information.
1056N/AFor information about the choice of suitable atoms to use,
1276N/A<
a class="xref" href="#Use_of_Selection_Atoms" title="Use of Selection Atoms">Use of Selection Atoms</
a>
1056N/AThe requestor should set the requestor argument to a window that it created;
1056N/Athe owner will place the reply property there.
1056N/AThe requestor should set the time argument to the timestamp on the event
1056N/Athat triggered the request for the selection value.
1056N/ANote that clients should not specify
1056N/A<
code class="function">CurrentTime</
code>.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/A<
code class="function">CurrentTime</
code>
1056N/A<
code class="function">ConvertSelection</
code>
1056N/AInstead, they should use the timestamp of the event that caused the request
1056N/AThe requestor should set the property argument to the name of a property
1056N/Athat the owner can use to report the value of the selection.
1056N/ARequestors should ensure that the named property does not exist
1056N/Aon the window before issuing the
1056N/A<
code class="function">ConvertSelection</
code>
1056N/AThe exception to this rule is when the requestor intends to pass
1056N/Aparameters with the request (see below).
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Rationale</
strong></
p></
div><
p>
1056N/AIt is necessary for requestors to delete the property before issuing the
1056N/Arequest so that the target can later be extended to take parameters without
1056N/Aintroducing an incompatibility. Also note that the requestor of a selection
1056N/Aneed not know the client that owns the selection nor the window on which
1056N/ASome targets may be defined such that requestors can pass parameters
1056N/Aalong with the request. If the requestor wishes to provide parameters
1056N/Ato a request, they should be placed in the specified property on the
1056N/Arequestor window before the requestor issues the
1056N/A<
code class="function">ConvertSelection</
code>
1056N/Arequest, and this property should be named in the request.
1056N/ASome targets may be defined so that parameters are optional. If no
1056N/Aparameters are to be supplied with the request of such a target, the
1056N/Arequestor must ensure that the property does not exist before issuing
1056N/A<
code class="function">ConvertSelection</
code>
1056N/AThe protocol allows the property field to be set to
1056N/A<
code class="function">None</
code>,
1056N/Ain which case the owner is supposed to choose a property name.
1056N/AHowever, it is difficult for the owner to make this choice safely.
1276N/A</
p><
p><
span class="bold"><
strong>Conventions</
strong></
span></
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A<
code class="function">None</
code>
1056N/Afor the property argument of a
1056N/A<
code class="function">ConvertSelection</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">ConvertSelection</
code>
1056N/Arequests with a property argument of
1056N/A<
code class="function">None</
code>
1056N/Aare talking to an obsolete client.
1056N/AThey should choose the target atom as the property name to be used
1056N/A<
code class="function">ConvertSelection</
code>
1056N/A<
code class="function">SelectionNotify</
code>
1056N/A<
code class="function">SelectionNotify</
code>
1276N/A<
a class="xref" href="#Responsibilities_of_the_Selection_Owner" title="Responsibilities of the Selection Owner">Responsibilities of the Selection Owner</
a>.
1056N/AThe requestor, selection, time, and target arguments will be the same
1056N/A<
code class="function">ConvertSelection</
code>
1056N/A<
code class="function">None</
code>,
1056N/Athe conversion has been refused.
1056N/AThis can mean either that there is no owner for the selection,
1056N/Athat the owner does not support the conversion implied by the target,
1056N/Aor that the server did not have sufficient space to accommodate the data.
1056N/AIf the property argument is not
1056N/A<
code class="function">None</
code>,
1056N/Athen that property will exist on the requestor window.
1056N/AThe value of the selection can be retrieved from this
1056N/A<
code class="function">GetProperty</
code>
1056N/Arequest, which is defined as follows:
1056N/A<
code class="function">GetProperty</
code>
1276N/A</
p><
div class="informaltable"><
table border="0"><
colgroup><
col align="left" class="c1" /></
colgroup><
tbody><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>window</
em></
span>: WINDOW
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>property</
em></
span>: ATOM
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>type</
em></
span>: ATOM or
1056N/A<
code class="function">AnyPropertyType</
code>
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>long-offset</
em></
span>,
1056N/A<
span class="emphasis"><
em>long-length</
em></
span>: CARD32
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>delete</
em></
span>: BOOL
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A </
td></
tr><
tr><
td align="left">
1056N/Atype: ATOM or <
code class="function">None</
code>
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A </
td></
tr><
tr><
td align="left">
1056N/Avalue: LISTofINT8 or LISTofINT16 or LISTofINT32
1056N/A </
td></
tr></
tbody></
table></
div><
p>
1056N/A<
code class="function">GetProperty</
code>
1056N/Ato retrieve the value of a selection,
1056N/Athe property argument should be set to the corresponding value in the
1056N/A<
code class="function">SelectionNotify</
code>
1056N/ABecause the requestor has no way of knowing beforehand what type
1056N/Athe selection owner will use,
1056N/Athe type argument should be set to
1056N/A<
code class="function">AnyPropertyType</
code>.
1056N/A<
code class="function">GetProperty</
code>
1056N/Arequests may be needed to retrieve all the data in the selection;
1056N/Aeach should set the long-offset argument to the amount of data received so far,
1056N/Aand the size argument to some reasonable buffer size (see
1276N/A<
a class="xref" href="#Large_Data_Transfers" title="Large Data Transfers">Large Data Transfers</
a>.
1056N/AIf the returned value of bytes-after is zero,
1056N/Athe whole property has been transferred.
1056N/AOnce all the data in the selection has been retrieved
1056N/A(which may require getting the values of several properties --
1276N/A<
a class="xref" href="#Use_of_Selection_Properties" title="Use of Selection Properties">Use of Selection Properties</
a>.
1056N/Athe requestor should delete the property in the
1056N/A<
code class="function">SelectionNotify</
code>
1056N/A<
code class="function">GetProperty</
code>
1056N/Arequest with the delete argument set to
1056N/A<
code class="function">True</
code>.
1056N/Athe owner has no way of knowing when the data has been
1056N/Atransferred to the requestor unless the property is removed.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AThe requestor must delete the property named in the
1056N/A<
code class="function">SelectionNotify</
code>
1056N/Aonce all the data has been retrieved.
1056N/AThe requestor should invoke either
1056N/A<
code class="function">DeleteProperty</
code> or
1056N/A<
code class="function">GetProperty</
code>
1056N/Aafter it has successfully retrieved all the data in the selection.
1276N/A<
a class="xref" href="#Large_Data_Transfers" title="Large Data Transfers">Large Data Transfers</
a>.
1276N/A</
p></
blockquote></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Large_Data_Transfers"></
a>Large Data Transfers</
h2></
div></
div></
div><
p>
1056N/ASelections can get large, which poses two problems:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/ATransferring large amounts of data to the server is expensive.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AAll servers will have limits on the amount of data that can be stored
1056N/AExceeding this limit will result in an
1056N/A<
code class="function">Alloc</
code>
1056N/A<
code class="function">ChangeProperty</
code>
1056N/Arequest that the selection owner uses to store the data.
1056N/AThe problem of limited server resources is addressed by the following
1056N/A<
span class="bold"><
strong>Conventions</
strong></
span>
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/ASelection owners should transfer the data describing a large selection
1056N/A(relative to the maximum-request-size they received
1056N/Ain the connection handshake) using the INCR property mechanism
1276N/A<
a class="xref" href="#INCR_Properties" title="INCR Properties">INCR Properties</
a>.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">SetSelectionOwner</
code>
1056N/Ato acquire selection ownership should arrange to process
1056N/A<
code class="function">Alloc</
code>
1056N/Aerrors in property change requests.
1056N/Afunction to override the default handler.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AA selection owner must confirm that no
1056N/A<
code class="function">Alloc</
code>
1056N/Aerror occurred while storing the properties for a selection
1056N/Abefore replying with a confirming
1056N/A<
code class="function">SelectionNotify</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AWhen storing large amounts of data (relative to maximum-request-size),
1056N/Aclients should use a sequence of
1056N/A<
code class="function">ChangeProperty (mode==Append)</
code>
1056N/Arequests for reasonable quantities of data.
1056N/AThis avoids locking servers up and limits the waste of data an
1056N/A<
code class="function">Alloc</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">Alloc</
code>
1056N/Aerror occurs during the storing of the selection data,
1056N/Aall properties stored for this selection should be deleted
1056N/A<
code class="function">ConvertSelection</
code>
1056N/Arequest should be refused (see
1276N/A<
a class="xref" href="#Responsibilities_of_the_Selection_Owner" title="Responsibilities of the Selection Owner">Responsibilities of the Selection Owner</
a>.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ATo avoid locking servers up for inordinate lengths of time,
1056N/Arequestors retrieving large quantities of data from a property
1056N/A<
code class="function">GetProperty</
code>
1056N/Arequests, each asking for a reasonable amount of data.
1276N/A </
p></
li></
ul></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Advice to Implementors</
strong></
p></
div><
p>
1056N/ASingle-threaded servers should take care to avoid locking up during large
1276N/A</
p></
blockquote></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Use_of_Selection_Atoms"></
a>Use of Selection Atoms</
h2></
div></
div></
div><
p>
1056N/ADefining a new atom consumes resources in the server
1056N/Athat are not released until the server reinitializes.
1056N/AThus, reducing the need for newly minted atoms is an important goal
1056N/Afor the use of the selection atoms.
1276N/A</
p><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Selection_Atoms"></
a>Selection Atoms</
h3></
div></
div></
div><
p>
1056N/AThere can be an arbitrary number of selections, each named by an atom.
1056N/ATo conform with the inter-client conventions, however,
1056N/Aclients need deal with only these three selections:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AOther selections may be used freely for private communication among
1276N/A</
p><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="The_PRIMARY_Selection"></
a>The PRIMARY Selection</
h4></
div></
div></
div><
p>
1056N/AThe selection named by the atom PRIMARY is used for all commands
1056N/Athat take only a single argument and is the principal means of communication
1056N/Abetween clients that use the selection mechanism.
1276N/A</
p></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="The_SECONDARY_Selection"></
a>The SECONDARY Selection</
h4></
div></
div></
div><
p>
1056N/AThe selection named by the atom SECONDARY is used:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AAs the second argument to commands taking two arguments
1056N/A(for example, "exchange primary and secondary selections")
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AAs a means of obtaining data when there is a primary selection
1056N/Aand the user does not want to disturb it
1276N/A </
p></
li></
ul></
div></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="The_CLIPBOARD_Selection"></
a>The CLIPBOARD Selection</
h4></
div></
div></
div><
p>
1056N/AThe selection named by the atom CLIPBOARD is used to hold data
1056N/Athat is being transferred between clients,
1056N/Athat is, data that usually is being cut and then pasted
1056N/AWhenever a client wants to transfer data to the clipboard:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AIt should assert ownership of the CLIPBOARD.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIf it succeeds in acquiring ownership,
1056N/Ait should be prepared to respond to a request for the contents of the CLIPBOARD
1056N/Ain the usual way (retaining the data to be able to return it).
1056N/AThe request may be generated by the clipboard client described below.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIf it fails to acquire ownership,
1056N/Aa cutting client should not actually perform the cut or provide feedback
1056N/Athat would suggest that it has actually transferred data to the clipboard.
1056N/AThe owner should repeat this process whenever the data to be transferred
1056N/AClients wanting to paste data from the clipboard should request
1056N/Athe contents of the CLIPBOARD selection in the usual way.
1056N/AExcept while a client is actually deleting or copying data,
1056N/Athe owner of the CLIPBOARD selection may be a single, special client
1056N/Aimplemented for the purpose.
1056N/AThis client maintains the content of the clipboard up-to-date
1056N/Aand responds to requests for data from the clipboard as follows:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AIt should assert ownership of the CLIPBOARD selection
1056N/Aand reassert it any time the clipboard data changes.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIf it loses the selection (because another client has some new data
1276N/A </
p><
div class="itemizedlist"><
ul class="itemizedlist" type="circle"><
li class="listitem"><
p>
1056N/AObtain the contents of the selection from the new owner by using the timestamp
1056N/A<
code class="function">SelectionClear</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AAttempt to reassert ownership of the CLIPBOARD selection
1056N/Aby using the same timestamp.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ARestart the process using a newly acquired timestamp if this attempt fails.
1056N/AThis timestamp should be obtained by asking the current owner of the
1056N/ACLIPBOARD selection to convert it to a TIMESTAMP.
1056N/AIf this conversion is refused or if the same timestamp is received twice,
1056N/Athe clipboard client should acquire a fresh timestamp in the
1056N/Ausual way (for example by a zero-length append to a property).
1276N/A </
p></
li></
ul></
div></
li><
li class="listitem"><
p>
1056N/AIt should respond to requests for the CLIPBOARD contents in the usual way.
1056N/AA special CLIPBOARD client is not necessary.
1056N/AThe protocol used by the cutting client and the pasting client
1056N/Ais the same whether the CLIPBOARD client is running or not.
1056N/AThe reasons for running the special client include:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AStability - If the cutting client were to crash or terminate,
1056N/Athe clipboard value would still be available.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AFeedback - The clipboard client can display the contents of the clipboard.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ASimplicity - A client deleting data does not have to retain it for so long,
1056N/Athus reducing the chance of race conditions causing problems.
1056N/AThe reasons not to run the clipboard client include:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/APerformance - Data is transferred only if it is actually required
1056N/A(that is, when some client actually wants the data).
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AFlexibility - The clipboard data may be available as more than one target.
1276N/A </
p></
li></
ul></
div></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Target_Atoms"></
a>Target Atoms</
h3></
div></
div></
div><
p>
1056N/AThe atom that a requestor supplies as the target of a
1056N/A<
code class="function">ConvertSelection</
code>
1056N/Arequest determines the form of the data supplied.
1056N/AThe set of such atoms is extensible,
1056N/Abut a generally accepted base set of target atoms is needed.
1056N/AAs a starting point for this,
1056N/Athe following table contains those that have been suggested so far.
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Atom</
th><
th align="left">Type </
th><
th align="left">Data Received</
th></
tr></
thead><
tbody><
tr><
td align="left">ADOBE_PORTABLE_DOCUMENT_FORMAT</
td><
td align="left">STRING</
td><
td align="left">[1]</
td></
tr><
tr><
td align="left">APPLE_PICT</
td><
td align="left">APPLE_PICT</
td><
td align="left">[2]</
td></
tr><
tr><
td align="left">BACKGROUND</
td><
td align="left">PIXEL</
td><
td align="left">A list of pixel values</
td></
tr><
tr><
td align="left">BITMAP</
td><
td align="left">BITMAP</
td><
td align="left">A list of bitmap IDs</
td></
tr><
tr><
td align="left">CHARACTER_POSITION</
td><
td align="left">SPAN</
td><
td align="left">The start and end of the selection in bytes</
td></
tr><
tr><
td align="left">CLASS</
td><
td align="left">TEXT</
td><
td align="left">(see
1276N/A<
a class="xref" href="#WM_CLASS_Property" title="WM_CLASS Property">WM_CLASS Property</
a>.
1056N/A)</
td></
tr><
tr><
td align="left">CLIENT_WINDOW</
td><
td align="left">WINDOW</
td><
td align="left">Any top-level window owned by the selection owner</
td></
tr><
tr><
td align="left">COLORMAP</
td><
td align="left">COLORMAP</
td><
td align="left">A list of colormap IDs</
td></
tr><
tr><
td align="left">COLUMN_NUMBER</
td><
td align="left">SPAN</
td><
td align="left">The start and end column numbers</
td></
tr><
tr><
td align="left">COMPOUND_TEXT</
td><
td align="left">COMPOUND_TEXT</
td><
td align="left">Compound Text</
td></
tr><
tr><
td align="left">DELETE</
td><
td align="left">NULL</
td><
td align="left">(see
1276N/A<
a class="xref" href="#DELETE" title="DELETE">DELETE</
a>.
1056N/A)</
td></
tr><
tr><
td align="left">DRAWABLE</
td><
td align="left">DRAWABLE</
td><
td align="left">A list of drawable IDs</
td></
tr><
tr><
td align="left">ENCAPSULATED_POSTSCRIPT</
td><
td align="left">STRING</
td><
td align="left">[3], Appendix H
1276N/A </
td></
tr><
tr><
td align="left">ENCAPSULATED_POSTSCRIPT_INTERCHANGE</
td><
td align="left">STRING</
td><
td align="left">[3], Appendix H</
td></
tr><
tr><
td align="left">FILE_NAME</
td><
td align="left">TEXT</
td><
td align="left">The full path name of a file</
td></
tr><
tr><
td align="left">FOREGROUND</
td><
td align="left">PIXEL</
td><
td align="left">A list of pixel values</
td></
tr><
tr><
td align="left">HOST_NAME</
td><
td align="left">TEXT</
td><
td align="left">(see
1276N/A<
a class="xref" href="#WM_CLIENT_MACHINE_Property" title="WM_CLIENT_MACHINE Property">WM_CLIENT_MACHINE Property</
a>.
1056N/A)</
td></
tr><
tr><
td align="left">INSERT_PROPERTY</
td><
td align="left">NULL</
td><
td align="left">(see
1276N/A<
a class="xref" href="#INSERT_PROPERTY" title="INSERT_PROPERTY">INSERT_PROPERTY</
a>.
1056N/A)</
td></
tr><
tr><
td align="left">INSERT_SELECTION</
td><
td align="left">NULL</
td><
td align="left">(see
1276N/A<
a class="xref" href="#INSERT_SELECTION" title="INSERT_SELECTION">INSERT_SELECTION</
a>.
1056N/A)</
td></
tr><
tr><
td align="left">LENGTH</
td><
td align="left">INTEGER</
td><
td align="left">The number of bytes in the selection
1056N/A </
td></
tr><
tr><
td align="left">LINE_NUMBER</
td><
td align="left">SPAN</
td><
td align="left">The start and end line numbers</
td></
tr><
tr><
td align="left">LIST_LENGTH</
td><
td align="left">INTEGER</
td><
td align="left">The number of disjoint parts of the selection</
td></
tr><
tr><
td align="left">MODULE</
td><
td align="left">TEXT</
td><
td align="left">The name of the selected procedure</
td></
tr><
tr><
td align="left">MULTIPLE</
td><
td align="left">ATOM_PAIR</
td><
td align="left">(see the discussion that follows)</
td></
tr><
tr><
td align="left">NAME</
td><
td align="left">TEXT</
td><
td align="left">(see
1276N/A<
a class="xref" href="#WM_NAME_Property" title="WM_NAME Property">WM_NAME Property</
a>.
1056N/A)</
td></
tr><
tr><
td align="left">ODIF</
td><
td align="left">TEXT</
td><
td align="left">ISO Office Document Interchange Format</
td></
tr><
tr><
td align="left">OWNER_OS</
td><
td align="left">TEXT</
td><
td align="left">The operating system of the owner client</
td></
tr><
tr><
td align="left">PIXMAP</
td><
td align="left">PIXMAP
1276N/A </
td><
td align="left">A list of pixmap IDs</
td></
tr><
tr><
td align="left">POSTSCRIPT</
td><
td align="left">STRING</
td><
td align="left">[3]</
td></
tr><
tr><
td align="left">PROCEDURE</
td><
td align="left">TEXT</
td><
td align="left">The name of the selected procedure</
td></
tr><
tr><
td align="left">PROCESS</
td><
td align="left">INTEGER, TEXT</
td><
td align="left">The process ID of the owner</
td></
tr><
tr><
td align="left">STRING</
td><
td align="left">STRING</
td><
td align="left">ISO Latin-1 (+TAB+NEWLINE) text</
td></
tr><
tr><
td align="left">TARGETS</
td><
td align="left">ATOM</
td><
td align="left">A list of valid target atoms</
td></
tr><
tr><
td align="left">TASK</
td><
td align="left">INTEGER, TEXT</
td><
td align="left">The task ID of the owner</
td></
tr><
tr><
td align="left">TEXT</
td><
td align="left">TEXT</
td><
td align="left">The text in the owner's choice of encoding</
td></
tr><
tr><
td align="left">TIMESTAMP</
td><
td align="left">INTEGER</
td><
td align="left">The timestamp used to acquire the selection</
td></
tr><
tr><
td align="left">USER</
td><
td align="left">TEXT</
td><
td align="left">The name of the user running the owner</
td></
tr></
tbody><
tbody class="footnotes"><
tr><
td colspan="3"><
div class="footnote"><
p><
a id="ftn.id2590014" href="#id2590014" class="para"><
sup>[a] </
sup></
a>
1056N/AEarlier versions of this document erroneously specified that conversion of
1056N/Athe PIXMAP target returns a property of type DRAWABLE instead of PIXMAP.
1056N/AImplementors should be aware of this and may want to support the DRAWABLE
1056N/Atype as well to allow for compatibility with older clients.
1276N/A</
p></
div><
div class="footnote"><
p><
a id="ftn.id2590147" href="#id2590147" class="para"><
sup>[b] </
sup></
a>
1056N/AThe targets ENCAPSULATED_POSTSCRIPT and ENCAPSULATED_POSTSCRIPT_INTERCHANGE
1056N/Aare equivalent to the targets _ADOBE_EPS and _ADOBE_EPSI (respectively) that
1056N/Aappear in the selection targets registry. The _ADOBE_ targets are
1056N/Adeprecated, but clients are encouraged to continue to support them for
1276N/A</
p></
div><
div class="footnote"><
p><
a id="ftn.id2590282" href="#id2590282" class="para"><
sup>[c] </
sup></
a>
1056N/AThis definition is ambiguous, as the selection may be converted into any of
1056N/Aseveral targets that may return differing amounts of data. The requestor
1056N/Ahas no way of knowing which, if any, of these targets corresponds to the
1056N/Aresult of LENGTH. Clients are advised that no guarantees can be made about
1056N/Athe result of a conversion to LENGTH; its use is thus deprecated.
1056N/A</
p></
div></
td></
tr></
tbody></
table></
div><
p>
1276N/A</
p><
div class="orderedlist"><
ol class="orderedlist" type="1"><
li class="listitem"><
p>
1056N/AAdobe Systems, Incorporated.
1056N/A<
span class="emphasis"><
em>Portable Document Format Reference Manual.</
em></
span>
1056N/AReading, MA, Addison-Wesley, ISBN 0-201-62628-4.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AApple Computer, Incorporated.
1056N/A<
span class="emphasis"><
em>Inside Macintosh, Volume V.</
em></
span>
1056N/AChapter 4, "Color QuickDraw," Color Picture Format.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AAdobe Systems, Incorporated.
1056N/A<
span class="emphasis"><
em>PostScript Language Reference Manual.</
em></
span>
1056N/AReading, MA, Addison-Wesley, ISBN 0-201-18127-4.
1056N/AIt is expected that this table will grow over time.
1056N/ASelection owners are required to support the following targets.
1056N/AAll other targets are optional.
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/ATARGETS - The owner should return a list of atoms that represent
1056N/Athe targets for which an attempt to convert the current selection
1056N/Awill succeed (barring unforseeable problems such as
1056N/A<
code class="function">Alloc</
code>
1056N/AThis list should include all the required atoms.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AMULTIPLE - The MULTIPLE target atom is valid only when a property
1056N/A<
code class="function">ConvertSelection</
code>
1056N/AIf the property argument in the
1056N/A<
code class="function">SelectionRequest</
code>
1056N/A<
code class="function">None</
code>
1056N/AWhen a selection owner receives a
1056N/A<
code class="function">SelectionRequest (target==MULTIPLE)</
code>
1056N/Athe contents of the property named in the request will be a list of atom pairs:
1056N/Athe first atom naming a target and the second naming a property
1056N/A<
code class="function">( None</
code>
1056N/AThe effect should be as if the owner had received a sequence of
1056N/A<
code class="function">SelectionRequest</
code>
1056N/Aevents (one for each atom pair) except that:
1276N/A </
p><
div class="itemizedlist"><
ul class="itemizedlist" type="circle"><
li class="listitem"><
p>
1056N/AThe owner should reply with a
1056N/A<
code class="function">SelectionNotify</
code>
1056N/Aonly when all the requested conversions have been performed.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIf the owner fails to convert the target named by an atom
1056N/Ait should replace that atom in the property with
1056N/A<
code class="function">None</
code>.
1276N/A </
p></
li></
ul></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AThe entries in a MULTIPLE property must be processed in the order
1056N/Athey appear in the property.
1276N/A<
a class="xref" href="#Selection_Targets_with_Side_Effects" title="Selection Targets with Side Effects">Selection Targets with Side Effects</
a>.
1056N/AThe requestor should delete each individual property when it has
1056N/Acopied the data from that conversion, and the property specified in the
1056N/AMULTIPLE request when it has copied all the data.
1056N/AThe requests are otherwise to be processed independently, and they
1056N/Ashould succeed or fail independently. The MULTIPLE target is an
1056N/Aoptimization that reduces the amount of protocol traffic between the
1056N/Aowner and the requestor; it is not a transaction mechanism. For
1056N/Aexample, a client may issue a MULTIPLE request with two targets: a data
1056N/Atarget and the DELETE target. The DELETE target will still be processed
1056N/Aeven if the conversion of the data target fails.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ATIMESTAMP - To avoid some race conditions,
1056N/Ait is important that requestors be able to discover the timestamp
1056N/Athe owner used to acquire ownership.
1056N/AUntil and unless the protocol is changed so that a
1056N/A<
code class="function">GetSelectionOwner</
code>
1056N/Arequest returns the timestamp used to acquire ownership,
1056N/Aselection owners must support conversion to TIMESTAMP,
1056N/Areturning the timestamp they used to obtain the selection.
1276N/A </
p></
li></
ul></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Selection_Targets_with_Side_Effects"></
a>Selection Targets with Side Effects</
h3></
div></
div></
div><
p>
1056N/ASome targets (for example, DELETE) have side effects.
1056N/ATo render these targets unambiguous,
1056N/Athe entries in a MULTIPLE property must be processed in the order
1056N/Athat they appear in the property.
1056N/Atargets with side effects will return no information,
1056N/Athat is, they will return a zero length property of type NULL.
1056N/A(Type NULL means the result of
1056N/A<
code class="function">InternAtom</
code>
1056N/Aon the string "NULL", not the value zero.)
1056N/Athe requested side effect must be performed before the conversion is accepted.
1056N/AIf the requested side effect cannot be performed,
1056N/Athe corresponding conversion request must be refused.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Conventions</
strong></
p></
div><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/ATargets with side effects should return no information
1056N/A(that is, they should have a zero-length property of type NULL).
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe side effect of a target must be performed before the conversion is accepted.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIf the side effect of a target cannot be performed,
1056N/Athe corresponding conversion request must be refused.
1276N/A </
p></
li></
ul></
div></
blockquote></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Problem</
strong></
p></
div><
p>
1056N/AThe need to delay responding to the
1056N/A<
code class="function">ConvertSelection</
code>
1056N/Arequest until a further conversion has succeeded poses problems
1056N/Afor the Intrinsics interface that need to be addressed.
1056N/AThese side-effect targets are used to implement operations such as
1056N/A"exchange PRIMARY and SECONDARY selections."
1276N/A</
p><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="DELETE"></
a>DELETE</
h4></
div></
div></
div><
p>
1056N/AWhen the owner of a selection receives a request to convert it to DELETE,
1056N/Ait should delete the corresponding selection
1056N/A(whatever doing so means for its internal data structures)
1056N/Aand return a zero-length property of type NULL if the deletion was successful.
1276N/A</
p></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="INSERT_SELECTION"></
a>INSERT_SELECTION</
h4></
div></
div></
div><
p>
1056N/AWhen the owner of a selection receives a request to convert it to
1056N/Athe property named will be of type ATOM_PAIR.
1056N/AThe first atom will name a selection,
1056N/Aand the second will name a target.
1056N/AThe owner should use the selection mechanism to convert the named selection
1056N/Ainto the named target and should insert it at the location of the selection
1056N/Afor which it got the INSERT_SELECTION request
1056N/A(whatever doing so means for its internal data structures).
1276N/A</
p></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="INSERT_PROPERTY"></
a>INSERT_PROPERTY</
h4></
div></
div></
div><
p>
1056N/AWhen the owner of a selection receives a request to convert it to
1056N/Ait should insert the property named in the request at the location
1056N/Aof the selection for which it got the INSERT_SELECTION request
1056N/A(whatever doing so means for its internal data structures).
1276N/A</
p></
div></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Use_of_Selection_Properties"></
a>Use of Selection Properties</
h2></
div></
div></
div><
p>
1056N/AThe names of the properties used in selection data transfer are chosen by
1056N/A<
code class="function">None</
code>
1056N/A<
code class="function">ConvertSelection</
code>
1056N/Arequests (which request the selection owner to choose a name)
1056N/Ais not permitted by these conventions.
1056N/AThe selection owner always chooses the type of the property
1056N/Ain the selection data transfer.
1056N/ASome types have special semantics assigned by convention,
1056N/Aand these are reviewed in the following sections.
1056N/Aa request for conversion to a target should return either
1056N/Aa property of one of the types listed in the previous table for that target
1056N/Aor a property of type INCR and then a property of one of the listed types.
1056N/ACertain selection properties may contain resource IDs. The selection owner
1056N/Ashould ensure that the resource is not destroyed and that its contents are
1056N/Anot changed until after the selection transfer is complete. Requestors that
1056N/Arely on the existence or on the proper contents of a resource must operate
1056N/Aon the resource (for example, by copying the contents of a pixmap) before
1056N/Adeleting the selection property.
1056N/AThe selection owner will return a list of zero or more items
1056N/Aof the type indicated by the property type.
1056N/Athe number of items in the list will correspond to the number
1056N/Aof disjoint parts of the selection.
1056N/ASome targets (for example, side-effect targets) will be of length zero
1056N/Airrespective of the number of disjoint selection parts.
1056N/AIn the case of fixed-size items,
1056N/Athe requestor may determine the number of items by the property size.
1056N/ASelection property types are listed in the table below.
1056N/AFor variable-length items such as text,
1056N/Athe separators are also listed.
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Type Atom</
th><
th align="left">Format</
th><
th align="left">Separator</
th></
tr></
thead><
tbody><
tr><
td align="left">APPLE_PICT</
td><
td align="left">8</
td><
td align="left">Self-sizing</
td></
tr><
tr><
td align="left">ATOM</
td><
td align="left">32</
td><
td align="left">Fixed-size</
td></
tr><
tr><
td align="left">ATOM_PAIR</
td><
td align="left">32</
td><
td align="left">Fixed-size</
td></
tr><
tr><
td align="left">BITMAP</
td><
td align="left">32</
td><
td align="left">Fixed-size</
td></
tr><
tr><
td align="left">C_STRING</
td><
td align="left">8</
td><
td align="left">Zero</
td></
tr><
tr><
td align="left">COLORMAP</
td><
td align="left">32</
td><
td align="left">Fixed-size</
td></
tr><
tr><
td align="left">COMPOUND_TEXT</
td><
td align="left">8</
td><
td align="left">Zero</
td></
tr><
tr><
td align="left">DRAWABLE</
td><
td align="left">32</
td><
td align="left">Fixed-size</
td></
tr><
tr><
td align="left">INCR</
td><
td align="left">32</
td><
td align="left">Fixed-size</
td></
tr><
tr><
td align="left">INTEGER</
td><
td align="left">32</
td><
td align="left">Fixed-size</
td></
tr><
tr><
td align="left">PIXEL</
td><
td align="left">32</
td><
td align="left">Fixed-size</
td></
tr><
tr><
td align="left">PIXMAP</
td><
td align="left">32</
td><
td align="left">Fixed-size</
td></
tr><
tr><
td align="left">SPAN</
td><
td align="left">32</
td><
td align="left">Fixed-size</
td></
tr><
tr><
td align="left">STRING</
td><
td align="left">8</
td><
td align="left">Zero</
td></
tr><
tr><
td align="left">WINDOW</
td><
td align="left">32</
td><
td align="left">Fixed-size</
td></
tr></
tbody></
table></
div><
p>
1056N/AIt is expected that this table will grow over time.
1276N/A</
p><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="TEXT_Properties"></
a>TEXT Properties</
h3></
div></
div></
div><
p>
1056N/Athe encoding for the characters in a text string property is specified
1056N/AIt is highly desirable for there to be a simple, invertible mapping
1056N/Abetween string property types and any character set names
1056N/Aembedded within font names in any font naming standard adopted by the
1056N/AThe atom TEXT is a polymorphic target.
1056N/ARequesting conversion into TEXT will convert into whatever encoding
1056N/Ais convenient for the owner.
1056N/AThe encoding chosen will be indicated by the type of the property returned.
1056N/ATEXT is not defined as a type;
1056N/Ait will never be the returned type from a selection conversion request.
1056N/AIf the requestor wants the owner to return the contents of the selection
1056N/Ait should request conversion into the name of that encoding.
1276N/A<
a class="xref" href="#Target_Atoms" title="Target Atoms">Target Atoms</
a>,
1056N/Athe word TEXT (in the Type column) is used to indicate one
1056N/Aof the registered encoding names.
1056N/AThe type would not actually be TEXT;
1056N/Ait would be STRING or some other ATOM naming the encoding chosen by the owner.
1056N/ASTRING as a type or a target specifies the ISO Latin-1 character set plus the
1056N/Acontrol characters TAB (octal 11) and NEWLINE (octal 12).
1056N/AThe spacing interpretation of TAB is context dependent.
1056N/AOther ASCII control characters are explicitly not included in STRING
1056N/ACOMPOUND_TEXT as a type or a target specifies the Compound Text interchange
1056N/A<
span class="emphasis"><
em>Compound Text Encoding</
em></
span>.
1056N/AThere are some text objects where the source or intended user, as the
1056N/Acase may be, does not have a specific character set for the text, but
1056N/Ainstead merely requires a zero-terminated sequence of bytes with no
1056N/Aother restriction; no element of the selection mechanism may assume that
1056N/Aany byte value is forbidden or that any two differing sequences are
1056N/A For these objects, the type C_STRING should be used.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Rationale</
strong></
p></
div><
p>
1056N/AAn example of the need for C_STRING is to transmit the names of
1056N/Afiles; many operating systems do not interpret filenames as having
1056N/Aa character set. For example, the same character string uses a
1056N/Adifferent sequence of bytes in ASCII and EBCDIC, and so most
1056N/Aoperating systems see these as different filenames and offer no
1056N/Away to treat them as the same. Thus no character-set based
1056N/AType STRING, COMPOUND_TEXT, and C_STRING properties will consist of a list
1056N/Aof elements separated by null characters; other encodings will need to
1056N/Aspecify an appropriate list format.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="INCR_Properties"></
a>INCR Properties</
h3></
div></
div></
div><
p>
1056N/ARequestors may receive a property of type INCR
1056N/Ain response to any target that results in selection data.
1056N/AThis indicates that the owner will send the actual data incrementally.
1056N/AThe contents of the INCR property will be an integer,
1056N/Awhich represents a lower bound on the number of bytes of data in the selection.
1056N/AThe requestor and the selection owner transfer the data in the selection
1056N/AThe selection requestor starts the transfer process by deleting
1056N/Athe (type==INCR) property forming the reply to the selection.
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AAppends the data in suitable-size chunks to the
1056N/Asame property on the same window as the selection reply
1056N/Awith a type corresponding to the actual type of the converted selection.
1056N/AThe size should be less than the maximum-request-size in the connection
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AWaits between each append for a
1056N/A<
code class="function">PropertyNotify</
code>
1056N/A(state==Deleted) event that shows that the requestor has read the data.
1056N/AThe reason for doing this is to limit the consumption of space in the server.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AWaits (after the entire data has been transferred to the server) until a
1056N/A<
code class="function">PropertyNotify</
code>
1056N/Aevent that shows that the data has been read by the requestor
1056N/Aand then writes zero-length data to the property.
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A<
code class="function">SelectionNotify</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p><
div class="itemizedlist"><
ul class="itemizedlist" type="circle"><
li class="listitem"><
p>
1056N/A<
code class="function">GetProperty</
code>
1056N/A<
code class="function">True</
code>.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">PropertyNotify</
code>
1056N/A<
code class="function">NewValue</
code>.
1276N/A </
p></
li></
ul></
div></
li><
li class="listitem"><
p>
1056N/AWaits until the property named by the
1056N/A<
code class="function">PropertyNotify</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ADeletes the zero-length property.
1056N/AThe type of the converted selection is the type of the first partial property.
1056N/AThe remaining partial properties must have the same type.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="DRAWABLE_Properties"></
a>DRAWABLE Properties</
h3></
div></
div></
div><
p>
1056N/ARequestors may receive properties of type PIXMAP, BITMAP, DRAWABLE, or WINDOW,
1056N/Awhich contain an appropriate ID.
1056N/AWhile information about these drawables is available from the server by means of
1056N/A<
code class="function">GetGeometry</
code> request,
1056N/Athe following items are not:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/Arequestors converting into targets whose returned type in the table in
1276N/A<
a class="xref" href="#Target_Atoms" title="Target Atoms">Target Atoms</
a>
1056N/Ais one of the DRAWABLE types should expect to convert also
1056N/Ainto the following targets (using the MULTIPLE mechanism):
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AFOREGROUND returns a PIXEL value.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ABACKGROUND returns a PIXEL value.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ACOLORMAP returns a colormap ID.
1276N/A </
p></
li></
ul></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="SPAN_Properties"></
a>SPAN Properties</
h3></
div></
div></
div><
p>
1056N/AProperties with type SPAN contain a list of cardinal-pairs
1056N/Awith the length of the cardinals determined by the format.
1056N/AThe first specifies the starting position,
1056N/Aand the second specifies the ending position plus one.
1056N/Athe span is zero-length and is before the specified position.
1056N/AThe units are implied by the target atom,
1056N/Asuch as LINE_NUMBER or CHARACTER_POSITION.
1276N/A</
p></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Manager_Selections"></
a>Manager Selections</
h2></
div></
div></
div><
p>
1056N/ACertain clients, often called managers, take on responsibility
1056N/Afor managing shared resources. A client that manages a shared
1056N/Aresource should take ownership of an appropriate selection,
1056N/Anamed using the conventions described in
1276N/A<
a class="xref" href="#Naming_Conventions" title="Naming Conventions">Naming Conventions</
a>
1276N/A<
a class="xref" href="#Discriminated_Names" title="Discriminated Names">Discriminated Names</
a>.
1056N/AA client that manages multiple
1056N/Ashared resources (or groups of resources) should take
1056N/Aownership of a selection for each one.
1056N/AThe manager may support conversion of various targets
1056N/Afor that selection. Managers are encouraged to use this
1056N/Atechnique as the primary means by which clients interact
1056N/Awith the managed resource. Note that the conventions for
1056N/Ainteracting with the window manager predate this section;
1056N/Aas a result many interactions with the window manager use
1056N/ABefore a manager takes ownership of a manager selection, it
1056N/A<
code class="function">GetSelectionOwner</
code>
1056N/Arequest to check whether the selection is already owned by another client,
1056N/Aand, where appropriate, it should ask the user if the new manager should
1056N/Areplace the old one. If so, it may then take ownership of the selection.
1056N/AManagers should acquire the selection using a window created expressly for
1056N/Athis purpose. Managers must conform to the rules for selection owners
1276N/A<
a class="xref" href="#Acquiring_Selection_Ownership" title="Acquiring Selection Ownership">Acquiring Selection Ownership</
a>
1276N/A<
a class="xref" href="#Responsibilities_of_the_Selection_Owner" title="Responsibilities of the Selection Owner">Responsibilities of the Selection Owner</
a>
1056N/A, and they must also support the required
1276N/A<
a class="xref" href="#Use_of_Selection_Atoms" title="Use of Selection Atoms">Use of Selection Atoms</
a>.
1056N/AIf a manager loses ownership of a manager selection, this
1056N/Ameans that a new manager is taking over its responsibilities.
1056N/AThe old manager must release all resources it has managed
1056N/Aand must then destroy the window that owned the selection.
1056N/AFor example, a window manager losing ownership of WM_S2
1056N/A<
code class="function">SubstructureRedirect</
code>
1056N/Aon the root window of screen 2 before destroying the window that owned
1056N/AWhen the new manager notices that the window owning the selection
1056N/Ahas been destroyed, it knows that it can successfully proceed to
1056N/Acontrol the resource it is planning to manage. If the old
1056N/Amanager does not destroy the window within a reasonable time,
1056N/Athe new manager should check with the user before destroying
1056N/Athe window itself or killing the old manager.
1056N/AIf a manager wants to give up, on its own, management of a shared
1056N/Aresource controlled by a selection, it must do so by releasing
1056N/Athe resources it is managing and then by destroying the
1056N/Awindow that owns the selection. It should not first disown
1056N/Athe selection, since this introduces a race condition.
1056N/AClients who are interested in knowing when the owner of a
1056N/Amanager selection is no longer managing the corresponding shared
1056N/A<
code class="function">StructureNotify</
code>
1056N/Aon the window owning the selection so they can be notified when the window
1056N/Ais destroyed. Clients are warned that after doing a
1056N/A<
code class="function">GetSelectionOwner</
code>
1056N/A<
code class="function">StructureNotify</
code>,
1056N/A<
code class="function">GetSelectionOwner</
code>
1056N/Aagain to ensure that the owner did not change after initially getting the
1056N/Aselection owner and before selecting for
1056N/A<
code class="function">StructureNotify</
code>.
1056N/AImmediately after a manager successfully acquires ownership of a
1056N/Amanager selection, it should announce its arrival by sending a
1056N/A<
code class="function">ClientMessage</
code>
1056N/Aevent. This event should be sent using the
1056N/A<
code class="function">SendEvent</
code>
1056N/Aprotocol request with the following arguments:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /></
colgroup><
thead><
tr><
th align="left">Argument</
th><
th align="left">Value</
th></
tr></
thead><
tbody><
tr><
td align="left">destination:</
td><
td align="left">
1056N/Athe root window of screen 0, or the root
1056N/Awindow of the appropriate screen if the
1276N/Amanager is managing a screen-specific resource</
td></
tr><
tr><
td align="left">propogate:</
td><
td align="left">False</
td></
tr><
tr><
td align="left">event-mask:</
td><
td align="left"><
code class="function">StructureNotify</
code></
td></
tr><
tr><
td align="left">event:</
td><
td align="left"><
code class="function">ClientMessage</
code></
td></
tr><
tr><
td align="left"> type:</
td><
td align="left">MANAGER</
td></
tr><
tr><
td align="left"> format:</
td><
td align="left">32</
td></
tr><
tr><
td align="left"> data[0]
1276N/A </
td><
td align="left">timestamp</
td></
tr><
tr><
td align="left"> data[1]:</
td><
td align="left">manager selection atom</
td></
tr><
tr><
td align="left"> data[2]:</
td><
td align="left">the window owning the selection</
td></
tr><
tr><
td align="left"> data[3]:</
td><
td align="left">manager-selection-specific data</
td></
tr><
tr><
td align="left"> data[4]:</
td><
td align="left">manager-selection-specific data</
td></
tr></
tbody><
tbody class="footnotes"><
tr><
td colspan="2"><
div class="footnote"><
p><
a id="ftn.id2592224" href="#id2592224" class="para"><
sup>[a] </
sup></
a>
1056N/AWe use the notation data[n] to indicate the n
1056N/Aof the LISTofINT8, LISTofINT16, or LISTofINT32 in the data field of the
1056N/A<
code class="function">ClientMessage</
code>,
1056N/Aaccording to the format field.
1056N/AThe list is indexed from zero.
1056N/A</
p></
div></
td></
tr></
tbody></
table></
div><
p>
1056N/AClients that wish to know when a specific manager has started should
1056N/A<
code class="function">StructureNotify</
code>
1056N/Aon the appropriate root window and should watch for the appropriate MANAGER
1056N/A<
code class="function">ClientMessage</
code>.
1276N/A</
p></
div><
div class="footnotes"><
br /><
hr width="100" align="left" /><
div class="footnote"><
p><
a id="ftn.id2535529" href="#id2535529" class="para"><
sup>[2] </
sup></
a>
1056N/AAt present, no part of the protocol requires requestors
1056N/Ato send events to the owner of a selection.
1056N/AThis restriction is imposed to prepare for possible future extensions.
1276N/A</
p></
div><
div class="footnote"><
p><
a id="ftn.id2588275" href="#id2588275" class="para"><
sup>[3] </
sup></
a>
1056N/AThe division between these two cases is a matter of judgment
1056N/Aon the part of the software developer.
1276N/A</
p></
div><
div class="footnote"><
p><
a id="ftn.id2588624" href="#id2588624" class="para"><
sup>[4] </
sup></
a>
1056N/AThis requirement is new in version 2.0, and, in general, existing
1056N/Aclients do not conform to this requirement. To prevent these clients
1056N/Afrom breaking, no existing targets should be extended to take
1056N/Aparameters until sufficient time has passed for clients to be updated.
1056N/ANote that the MULTIPLE target was defined to take parameters in version
1056N/A1.0 and its definition is not changing. There is thus no conformance
1276N/A</
p></
div><
div class="footnote"><
p><
a id="ftn.id2591528" href="#id2591528" class="para"><
sup>[5] </
sup></
a>
1056N/ANote that this is different from STRING, where many byte values are
1056N/Aforbidden, and from COMPOUND_TEXT, where, for example, inserting the
1056N/Asequence 27,\ 40,\ 66 (designate ASCII into GL) at the start does not alter
1276N/A </
p></
div><
div class="footnote"><
p><
a id="ftn.id2591579" href="#id2591579" class="para"><
sup>[6] </
sup></
a>
1056N/AThese properties were called INCREMENTAL in an earlier draft.
1056N/AThe protocol for using them has changed,
1056N/Aand so the name has changed to avoid confusion.
1276N/A</
p></
div></
div></
div><
div class="chapter"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="Peer_to_Peer_Communication_by_Means_of_Cut_Buffers"></
a>Chapter 3. Peer-to-Peer Communication by Means of Cut Buffers</
h2></
div></
div></
div><
p>
1056N/AThe cut buffer mechanism is much simpler but much less powerful
1056N/Athan the selection mechanism.
1056N/AThe selection mechanism is active in that it provides a link
1056N/Abetween the owner and requestor clients.
1056N/AThe cut buffer mechanism is passive;
1056N/Aan owner places data in a cut buffer from which a requestor retrieves
1056N/Athe data at some later time.
1056N/AThe cut buffers consist of eight properties on the root of screen zero,
1056N/Anamed by the predefined atoms CUT_BUFFER0 to CUT_BUFFER7.
1056N/AThese properties must, at present, have type STRING and format 8.
1056N/AA client that uses the cut buffer mechanism must initially ensure that
1056N/Aall eight properties exist by using
1056N/A<
code class="function">ChangeProperty</
code>
1056N/Arequests to append zero-length data to each.
1056N/AA client that stores data in the cut buffers (an owner) first must rotate the
1056N/Aring of buffers by plus 1 by using
1056N/A<
code class="function">RotateProperties</
code>
1056N/Arequests to rename each buffer;
1056N/Athat is, CUT_BUFFER0 to CUT_BUFFER1, CUT_BUFFER1 to CUT_BUFFER2, ...,
1056N/Aand CUT_BUFFER7 to CUT_BUFFER0.
1056N/AIt then must store the data into CUT_BUFFER0 by using a
1056N/A<
code class="function">ChangeProperty</
code>
1056N/AA client that obtains data from the cut buffers should use a
1056N/A<
code class="function">GetProperty</
code>
1056N/Arequest to retrieve the contents of CUT_BUFFER0.
1056N/AIn response to a specific user request,
1056N/Aa client may rotate the cut buffers by minus 1 by using
1056N/A<
code class="function">RotateProperties</
code>
1056N/Arequests to rename each buffer;
1056N/Athat is, CUT_BUFFER7 to CUT_BUFFER6, CUT_BUFFER6 to CUT_BUFFER5, ...,
1056N/Aand CUT_BUFFER0 to CUT_BUFFER7.
1056N/AData should be stored to the cut buffers
1056N/Aand the ring rotated only when requested by explicit user action.
1056N/AUsers depend on their mental model of cut buffer operation
1056N/Aand need to be able to identify operations that transfer data to and fro.
1276N/A</
p></
div><
div class="chapter"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="Client_to_Window_Manager_Communication"></
a>Chapter 4. Client-to-Window-Manager Communication</
h2></
div></
div></
div><
div class="toc"><
p><
strong>Table of Contents</
strong></
p><
dl><
dt><
span class="sect1"><
a href="#Clients_Actions">Client's Actions</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#Creating_a_Top_Level_Window">Creating a Top-Level Window</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Client_Properties">Client Properties</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Window_Manager_Properties">Window Manager Properties</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Changing_Window_State">Changing Window State</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Configuring_the_Window">Configuring the Window</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Changing_Window_Attributes">Changing Window Attributes</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Input_Focus">Input Focus</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Colormaps">Colormaps</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Icons">Icons</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Pop_up_Windows">Pop-up Windows</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Window_Groups">Window Groups</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Client_Responses_to_Window_Manager_Actions">Client Responses to Window Manager Actions</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#Reparenting">Reparenting</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Redirection_of_Operations">Redirection of Operations</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Window_Move">Window Move</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Window_Resize">Window Resize</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Iconify_and_Deiconify">Iconify and Deiconify</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Colormap_Change">Colormap Change</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Input_Focus_2">Input Focus</
a></
span></
dt><
dt><
span class="sect2"><
a href="#ClientMessage_Events">ClientMessage Events</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Redirecting_Requests">Redirecting Requests</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Communication_with_the_Window_Manager_by_Means_of_Selections">Communication with the Window Manager by Means of Selections</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Summary_of_Window_Manager_Property_Types">Summary of Window Manager Property Types</
a></
span></
dt></
dl></
div><
p>
1056N/ATo permit window managers to perform their role of mediating the competing
1056N/Ademands for resources such as screen space,
1056N/Athe clients being managed must adhere to certain conventions
1056N/Aand must expect the window managers to do likewise.
1056N/AThese conventions are covered here from the client's point of view.
1056N/Athese conventions are somewhat complex
1056N/Aand will undoubtedly change as new window management paradigms are developed.
1056N/AThus, there is a strong bias toward defining only those conventions
1056N/Athat are essential and that apply generally to all window management paradigms.
1056N/AClients designed to run with a particular window manager can easily
1056N/Adefine private protocols to add to these conventions,
1056N/Abut they must be aware that their users may decide to run some other
1056N/Awindow manager no matter how much the designers of the private protocol
1056N/Aare convinced that they have seen the "one true light" of user interfaces.
1056N/AIt is a principle of these conventions that a general client should
1056N/Aneither know nor care which window manager is running or, indeed,
1056N/AThe conventions do not support all client functions
1056N/Awithout a window manager running;
1056N/Afor example, the concept of Iconic
1056N/Ais not directly supported by clients.
1056N/AIf no window manager is running,
1056N/Athe concept of Iconic does not apply.
1056N/AA goal of the conventions is to make it possible to kill and
1056N/Arestart window managers without loss of functionality.
1056N/AEach window manager will implement a particular window management policy;
1056N/Athe choice of an appropriate window management policy
1056N/Afor the user's circumstances is not one for an individual client to
1056N/Amake but will be made by the user or the user's system administrator.
1056N/AThis does not exclude the possibility of writing clients that
1056N/Ause a private protocol to restrict themselves to operating only
1056N/Aunder a specific window manager.
1056N/Ait merely ensures that no claim of general utility is made for such programs.
1056N/A"The client I'm writing is important, and it needs to be on top."
1056N/APerhaps it is important when it is being run in earnest,
1056N/Aand it should then be run under the control of a window manager
1056N/Athat recognizes "important" windows through some private protocol
1056N/Aand ensures that they are on top.
1056N/AHowever, imagine, for example, that the "important" client is being debugged.
1056N/AThen, ensuring that it is always on top is no longer
1056N/Athe appropriate window management policy,
1056N/Aand it should be run under a window manager that allows other windows
1056N/A(for example, the debugger) to appear on top.
1276N/A</
p><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Clients_Actions"></
a>Client's Actions</
h2></
div></
div></
div><
p>
1056N/Athe object of the X Version 11 design is that clients should,
1056N/Aas far as possible, do exactly what they would do in the absence
1056N/Aof a window manager, except for the following:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AHinting to the window manager about the resources they would like
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ACooperating with the window manager by accepting the resources they
1056N/Aare allocated even if they are not those requested
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ABeing prepared for resource allocations to change at any time
1276N/A </
p></
li></
ul></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Creating_a_Top_Level_Window"></
a>Creating a Top-Level Window</
h3></
div></
div></
div><
p>
1056N/A<
span class="emphasis"><
em>top-level window</
em></
span> is a window whose
1056N/Aoverride-redirect attribute is
1056N/A<
code class="function">False</
code>.
1056N/AIt must either be a child of a root window, or it must have been a child of
1056N/Aa root window immediately prior to having been reparented by the window
1056N/Amanager. If the client reparents the window away from the root, the window
1056N/Ais no longer a top-level window; but it can become a top-level window again
1056N/Aif the client reparents it back to the root.
1056N/AA client usually would expect to create its top-level windows
1056N/Aas children of one or more of the root windows by using some
1056N/Aboilerplate like the following:
1056N/A</
p><
pre class="literallayout">
1056N/AIf a particular one of the root windows was required, however,
1056N/Ait could use something like the following:
1056N/A</
p><
pre class="literallayout">
1056N/Ait should be possible to override the choice of a root window
1056N/Aand allow clients (including window managers) to treat a nonroot window
1056N/AThis would allow, for example, the testing of window managers and the
1056N/Ause of application-specific window managers to control the subwindows
1056N/Aowned by the members of a related suite of clients.
1056N/ADoing so properly requires an extension,
1056N/Athe design of which is under study.
1056N/AFrom the client's point of view,
1056N/Athe window manager will regard its top-level window as being in
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ANewly created windows start in the Withdrawn state.
1056N/ATransitions between states happen when the top-level window is mapped
1056N/Aand unmapped and when the window manager receives certain messages.
1276N/A<
a class="xref" href="#WM_HINTS_Property" title="WM_HINTS Property">WM_HINTS Property</
a>.
1276N/A<
a class="xref" href="#Changing_Window_State" title="Changing Window State">Changing Window State</
a>.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Client_Properties"></
a>Client Properties</
h3></
div></
div></
div><
p>
1056N/AOnce the client has one or more top-level windows,
1056N/Ait should place properties on those windows to inform the window manager
1056N/Aof the behavior that the client desires.
1056N/AWindow managers will assume values they find convenient
1056N/Afor any of these properties that are not supplied;
1056N/Aclients that depend on particular values must explicitly supply them.
1056N/AThe window manager will not change properties written by the client.
1056N/AThe window manager will examine the contents of these
1056N/Aproperties when the window makes the transition from the Withdrawn state
1056N/Aand will monitor some properties for changes while the window is
1056N/Ain the Iconic or Normal state.
1056N/AWhen the client changes one of these properties,
1056N/Amode to overwrite the entire property with new data;
1056N/Athe window manager will retain no memory of the old value of the property.
1056N/AAll fields of the property must be set to suitable values in a single
1056N/Amode <
code class="function">ChangeProperty</
code>
1056N/AThis ensures that the full contents of the property will be
1056N/Aavailable to a new window manager if the existing one crashes,
1056N/Aif it is shut down and restarted,
1056N/Aor if the session needs to be shut down and restarted by the session manager.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AClients writing or rewriting window manager properties must
1056N/Aensure that the entire content of each property remains valid
1056N/ASome of these properties may contain the IDs of resources, such as
1056N/Awindows or pixmaps. Clients should ensure that these resources exist
1056N/Afor at least as long as the window on which the property resides.
1056N/AIf these properties are longer than expected,
1056N/Aclients should ignore the remainder of the property.
1056N/AExtending these properties is reserved to the X Consortium;
1056N/Aprivate extensions to them are forbidden.
1056N/APrivate additional communication between clients and window managers
1056N/Ashould take place using separate properties.
1056N/AThe only exception to this rule is the WM_PROTOCOLS property, which may be
1056N/Aof arbitrary length and which may contain atoms representing private
1276N/A<
a class="xref" href="#WM_PROTOCOLS_Property" title="WM_PROTOCOLS Property">WM_PROTOCOLS Property</
a>
1056N/AThe next sections describe each of the properties the clients
1056N/AThey are summarized in the table in
1276N/A<
a class="xref" href="#Summary_of_Window_Manager_Property_Types" title="Summary of Window Manager Property Types">Summary of Window Manager Property Types</
a>
1276N/A</
p><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="WM_NAME_Property"></
a>WM_NAME Property</
h4></
div></
div></
div><
p>
1056N/AThe WM_NAME property is an uninterpreted string
1056N/Athat the client wants the window manager to display
1056N/Ain association with the window (for example, in a window headline bar).
1056N/AThe encoding used for this string
1056N/A(and all other uninterpreted string properties)
1056N/Ais implied by the type of the property.
1056N/AThe type atoms to be used for this purpose are described in
1276N/A<
a class="xref" href="#TEXT_Properties" title="TEXT Properties">TEXT Properties</
a>.
1056N/AWindow managers are expected to make an effort to display this information.
1056N/ASimply ignoring WM_NAME is not acceptable behavior.
1056N/AClients can assume that at least the first part of this string
1056N/Ais visible to the user and that if the information is not visible to the user,
1056N/Ait is because the user has taken an explicit action to make it invisible.
1056N/Athere is no guarantee that the user can see the WM_NAME string
1056N/Aeven if the window manager supports window headlines.
1056N/AThe user may have placed the headline off-screen
1056N/Aor have covered it by other windows.
1056N/AWM_NAME should not be used for application-critical information
1056N/Aor to announce asynchronous changes of an application's state
1056N/Athat require timely user response.
1056N/AThe expected uses are to permit the user to identify one of a
1056N/Anumber of instances of the same client
1056N/Aand to provide the user with noncritical state information.
1056N/AEven window managers that support headline bars will place some limit
1056N/Aon the length of the WM_NAME string that can be visible;
1056N/Abrevity here will pay dividends.
1276N/A</
p></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="WM_ICON_NAME_Property"></
a>WM_ICON_NAME Property</
h4></
div></
div></
div><
p>
1056N/AThe WM_ICON_NAME property is an uninterpreted string
1056N/Athat the client wants to be displayed in association with the window
1056N/Awhen it is iconified (for example, in an icon label).
1056N/Aincluding the type, it is similar to WM_NAME.
1056N/AFor obvious geometric reasons,
1056N/Afewer characters will normally be visible in WM_ICON_NAME than WM_NAME.
1056N/AClients should not attempt to display this string in their icon pixmaps
1056N/Aor windows; rather, they should rely on the window manager to do so.
1276N/A</
p></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="WM_NORMAL_HINTS_Property"></
a>WM_NORMAL_HINTS Property</
h4></
div></
div></
div><
p>
1056N/AThe type of the WM_NORMAL_HINTS property is WM_SIZE_HINTS.
1056N/AIts contents are as follows:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Field</
th><
th align="left">Type</
th><
th align="left">Comments</
th></
tr></
thead><
tbody><
tr><
td align="left">flags</
td><
td align="left">CARD32</
td><
td align="left">(see the next table)</
td></
tr><
tr><
td align="left">pad</
td><
td align="left">4*CARD32</
td><
td align="left">For backwards compatibility</
td></
tr><
tr><
td align="left">min_width</
td><
td align="left">INT32</
td><
td align="left">If missing, assume base_width</
td></
tr><
tr><
td align="left">min_height</
td><
td align="left">INT32</
td><
td align="left">If missing, assume base_height</
td></
tr><
tr><
td align="left">max_width</
td><
td align="left">INT32</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left">max_height</
td><
td align="left">INT32</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left">width_inc</
td><
td align="left">INT32</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left">height_inc</
td><
td align="left">INT32</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left">min_aspect</
td><
td align="left">(INT32,INT32)</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left">max_aspect</
td><
td align="left">(INT32,INT32)</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left">base_width</
td><
td align="left">INT32</
td><
td align="left">If missing, assume min_width</
td></
tr><
tr><
td align="left">base_height</
td><
td align="left">INT32</
td><
td align="left">If missing, assume min_height</
td></
tr><
tr><
td align="left">win_gravity</
td><
td align="left">INT32</
td><
td align="left">If missing, assume <
code class="function">NorthWest</
code></
td></
tr></
tbody></
table></
div><
p>
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Name</
th><
th align="left">Value</
th><
th align="left">Field</
th></
tr></
thead><
tbody><
tr><
td align="left"><
code class="function">USPosition</
code></
td><
td align="left">1</
td><
td align="left">User-specified x, y</
td></
tr><
tr><
td align="left"><
code class="function">USSize</
code></
td><
td align="left">2</
td><
td align="left">User-specified width, height</
td></
tr><
tr><
td align="left"><
code class="function">PPosition</
code></
td><
td align="left">4</
td><
td align="left">Program-specified position</
td></
tr><
tr><
td align="left"><
code class="function">PSize</
code></
td><
td align="left">8</
td><
td align="left">Program-specified size</
td></
tr><
tr><
td align="left"><
code class="function">PMinSize</
code></
td><
td align="left">16</
td><
td align="left">Program-specified minimum size</
td></
tr><
tr><
td align="left"><
code class="function">PMaxSize</
code></
td><
td align="left">32</
td><
td align="left">Program-specified maximum size</
td></
tr><
tr><
td align="left"><
code class="function">PResizeInc</
code></
td><
td align="left">64</
td><
td align="left">Program-specified resize increments</
td></
tr><
tr><
td align="left"><
code class="function">PAspect</
code></
td><
td align="left">128</
td><
td align="left">Program-specified min and max aspect ratios</
td></
tr><
tr><
td align="left"><
code class="function">PBaseSize</
code></
td><
td align="left">256</
td><
td align="left">Program-specified base size</
td></
tr><
tr><
td align="left"><
code class="function">PWinGravity</
code></
td><
td align="left">512</
td><
td align="left">Program-specified window gravity</
td></
tr></
tbody></
table></
div><
p>
1056N/ATo indicate that the size and position of the window
1056N/A(when a transition from the Withdrawn state occurs) was specified by the user,
1056N/A<
code class="function">USPosition</
code>
1056N/A<
code class="function">USSize</
code>
1056N/Awhich allow a window manager to know that the user specifically asked where
1056N/Athe window should be placed or how the window should be sized and that
1056N/Afurther interaction is superfluous.
1056N/ATo indicate that it was specified by the client without any user involvement,
1056N/A<
code class="function">PPosition</
code>
1056N/A<
code class="function">PSize</
code>.
1056N/AThe size specifiers refer to the width and height of the client's
1056N/AThe win_gravity may be any of the values specified for WINGRAVITY in
1056N/Athe core protocol except for
1056N/A<
code class="function">Unmap</
code>:
1056N/A<
code class="function">NorthWest</
code>
1056N/A<
code class="function">North</
code>
1056N/A<
code class="function">NorthEast</
code>
1056N/A<
code class="function">West</
code>
1056N/A<
code class="function">Center</
code>
1056N/A<
code class="function">East</
code>
1056N/A<
code class="function">SouthWest</
code>
1056N/A<
code class="function">South</
code>
1056N/A<
code class="function">SouthEast</
code>
1056N/A(9). It specifies how and whether the client window wants to be shifted to
1056N/Amake room for the window manager frame.
1056N/A<
code class="function">Static</
code>,
1056N/Athe window manager frame is positioned
1056N/Aso that the inside border of the client window inside the frame is
1056N/Ain the same position on the screen as it was when the client
1056N/Arequested the transition from Withdrawn state. Other values of
1056N/Awin_gravity specify a window reference point. For
1056N/A<
code class="function">NorthWest</
code>,
1056N/A<
code class="function">NorthEast</
code>,
1056N/A<
code class="function">SouthWest</
code>,
1056N/A<
code class="function">SouthEast</
code>
1056N/Athe reference point is the specified outer corner of the window (on the
1056N/A<
code class="function">North</
code>,
1056N/A<
code class="function">South</
code>,
1056N/A<
code class="function">East</
code>
1056N/A<
code class="function">West</
code>
1056N/Athe reference point is the center of the specified outer edge of the window
1056N/A<
code class="function">Center</
code>
1056N/Athe reference point is the center of the window. The reference point of the
1056N/Awindow manager frame is placed at the location on the screen where the
1056N/Areference point of the client window was when the client requested the
1056N/Atransition from Withdrawn state.
1056N/AThe min_width and min_height elements specify the
1056N/Aminimum size that the window can be for the client to be useful.
1056N/AThe max_width and max_height elements specify the maximum size.
1056N/AThe base_width and base_height elements in conjunction with width_inc
1056N/Aand height_inc define an arithmetic progression of preferred window
1056N/Awidths and heights for non-negative integers
1056N/A<
span class="emphasis"><
em>i</
em></
span> and <
span class="emphasis"><
em>j</
em></
span>:
1056N/A</
p><
pre class="literallayout">
1056N/Awidth = base_width + ( i x width_inc )
1056N/Aheight = base_height + ( j x height_inc )
1056N/AWindow managers are encouraged to use
1056N/A<
span class="emphasis"><
em>i</
em></
span> and <
span class="emphasis"><
em>j</
em></
span>
1056N/Ainstead of width and height in reporting window sizes to users.
1056N/AIf a base size is not provided,
1056N/Athe minimum size is to be used in its place and vice versa.
1056N/AThe min_aspect and max_aspect fields are fractions with the numerator first
1056N/Aand the denominator second, and they allow a client to specify the range of
1056N/Aaspect ratios it prefers. Window managers that honor aspect ratios should
1056N/Atake into account the base size in determining the preferred window size. If
1056N/Aa base size is provided along with the aspect ratio fields, the base size
1056N/Ashould be subtracted from the window size prior to checking that the aspect
1056N/Aratio falls in range. If a base size is not provided, nothing should be
1056N/Asubtracted from the window size. (The minimum size is not to be used in
1056N/Aplace of the base size for this purpose.)
1276N/A</
p></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="WM_HINTS_Property"></
a>WM_HINTS Property</
h4></
div></
div></
div><
p>
1056N/AThe WM_HINTS property (whose type is WM_HINTS)
1056N/Ais used to communicate to the window manager.
1056N/AIt conveys the information the window manager needs
1056N/Aother than the window geometry,
1056N/Awhich is available from the window itself;
1056N/Athe constraints on that geometry,
1056N/Awhich is available from the WM_NORMAL_HINTS structure;
1056N/Awhich need separate properties, such as WM_NAME.
1056N/AThe contents of the properties are as follows:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Field</
th><
th align="left">Type</
th><
th align="left">Comments</
th></
tr></
thead><
tbody><
tr><
td align="left">flags</
td><
td align="left">CARD32</
td><
td align="left">(see the next table)</
td></
tr><
tr><
td align="left">input</
td><
td align="left">CARD32</
td><
td align="left">The client's input model</
td></
tr><
tr><
td align="left">initial_state</
td><
td align="left">CARD32</
td><
td align="left">The state when first mapped</
td></
tr><
tr><
td align="left">icon_pixmap</
td><
td align="left">PIXMAP</
td><
td align="left">The pixmap for the icon image</
td></
tr><
tr><
td align="left">icon_window</
td><
td align="left">WINDOW</
td><
td align="left">The window for the icon image</
td></
tr><
tr><
td align="left">icon_x</
td><
td align="left">INT32</
td><
td align="left">The icon location</
td></
tr><
tr><
td align="left">icon_y</
td><
td align="left">INT32</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left">icon_mask</
td><
td align="left">PIXMAP</
td><
td align="left">The mask for the icon shape</
td></
tr><
tr><
td align="left">window_group</
td><
td align="left">WINDOW</
td><
td align="left">The ID of the group leader window</
td></
tr></
tbody></
table></
div><
p>
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Name</
th><
th align="left">Value</
th><
th align="left">Field</
th></
tr></
thead><
tbody><
tr><
td align="left"><
code class="function">InputHint</
code></
td><
td align="left">1</
td><
td align="left">input</
td></
tr><
tr><
td align="left"><
code class="function">StateHint</
code></
td><
td align="left">2</
td><
td align="left">initial_state</
td></
tr><
tr><
td align="left"><
code class="function">IconPixmapHint</
code></
td><
td align="left">4</
td><
td align="left">icon_pixmap</
td></
tr><
tr><
td align="left"><
code class="function">IconWindowHint</
code></
td><
td align="left">8</
td><
td align="left">icon_window</
td></
tr><
tr><
td align="left"><
code class="function">IconPositionHint</
code></
td><
td align="left">16</
td><
td align="left">icon_x & icon_y</
td></
tr><
tr><
td align="left"><
code class="function">IconMaskHint</
code></
td><
td align="left">32</
td><
td align="left">icon_mask</
td></
tr><
tr><
td align="left"><
code class="function">WindowGroupHint</
code></
td><
td align="left">64</
td><
td align="left">window_group</
td></
tr><
tr><
td align="left"><
code class="function">MessageHint</
code></
td><
td align="left">128</
td><
td align="left">(this bit is obsolete)</
td></
tr><
tr><
td align="left"><
code class="function">UrgencyHint</
code></
td><
td align="left">256</
td><
td align="left">urgency</
td></
tr></
tbody></
table></
div><
p>
1056N/AWindow managers are free to assume convenient values for all fields of
1056N/Athe WM_HINTS property if a window is mapped without one.
1056N/AThe input field is used to communicate to the window manager the input focus
1056N/Amodel used by the client (see
1276N/A<
a class="xref" href="#Input_Focus" title="Input Focus">Input Focus</
a>
1056N/AClients with the Globally Active and No Input models should set the
1056N/A<
code class="function">False</
code>.
1056N/AClients with the Passive and Locally Active models should set the input
1056N/A<
code class="function">True</
code>.
1056N/AFrom the client's point of view,
1056N/Athe window manager will regard the client's top-level window as being
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe semantics of these states are described in
1276N/A<
a class="xref" href="#Changing_Window_State" title="Changing Window State">Changing Window State</
a>.
1056N/ANewly created windows start in the Withdrawn state.
1056N/ATransitions between states happen when a
1056N/Atop-level window is mapped and unmapped
1056N/Aand when the window manager receives certain messages.
1056N/AThe value of the initial_state field determines the state the client
1056N/Awishes to be in at the time the top-level window is mapped
1056N/Afrom the Withdrawn state, as shown in the following table:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">State</
th><
th align="left">Value</
th><
th align="left">Comments</
th></
tr></
thead><
tbody><
tr><
td align="left">NormalState</
td><
td align="left">1</
td><
td align="left">The window is visible</
td></
tr><
tr><
td align="left">IconicState</
td><
td align="left">3</
td><
td align="left">The icon is visible</
td></
tr></
tbody></
table></
div><
p>
1056N/AThe icon_pixmap field may specify a pixmap to be used as an icon.
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AOne of the sizes specified in the WM_ICON_SIZE property
1056N/Aon the root if it exists (see
1276N/A<
a class="xref" href="#WM_ICON_SIZE_Property" title="WM_ICON_SIZE Property">WM_ICON_SIZE Property</
a>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe window manager will select, through the defaults database,
1056N/Asuitable background (for the 0 bits) and foreground (for the 1 bits) colors.
1056N/AThese defaults can, of course, specify different colors for the icons
1056N/AThe icon_mask specifies which pixels of the icon_pixmap should be used as the
1056N/Aicon, allowing for icons to appear nonrectangular.
1056N/AThe icon_window field is the ID of a window the client wants used as its icon.
1056N/AMost, but not all, window managers will support icon windows.
1056N/AThose that do not are likely to have a user interface in which small
1056N/Awindows that behave like icons are completely inappropriate.
1056N/AClients should not attempt to remedy the omission by working around it.
1056N/AClients that need more capabilities from the icons than a simple 2-color
1056N/Abitmap should use icon windows.
1056N/ARules for clients that do are set out in
1276N/A<
a class="xref" href="#Icons" title="Icons">Icons</
a>.
1056N/AThe (icon_x,icon_y) coordinate is a hint to the window manager
1056N/Aas to where it should position the icon.
1056N/AThe policies of the window manager control the positioning of icons,
1056N/Aso clients should not depend on attention being paid to this hint.
1056N/AThe window_group field lets the client specify that this window belongs
1056N/AAn example is a single client manipulating multiple
1056N/Achildren of the root window.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Conventions</
strong></
p></
div><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AThe window_group field should be set to the ID of the group leader.
1056N/AThe window group leader may be a window that exists only for that purpose;
1056N/Aa placeholder group leader of this kind would never be mapped
1056N/Aeither by the client or by the window manager.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe properties of the window group leader are those for the group as
1056N/Aa whole (for example, the icon to be shown when the entire group is iconified).
1056N/A </
p></
li></
ul></
div></
blockquote></
div><
p>
1056N/AWindow managers may provide facilities for manipulating the group as a whole.
1056N/AClients, at present, have no way to operate on the group as a whole.
1056N/AThe messages bit, if set in the flags field, indicates that the
1056N/Aclient is using an obsolete window manager communication protocol,
1056N/Arather than the WM_PROTOCOLS mechanism of
1276N/A<
a class="xref" href="#WM_PROTOCOLS_Property" title="WM_PROTOCOLS Property">WM_PROTOCOLS Property</
a>
1056N/A<
code class="function">UrgencyHint</
code>
1056N/Aflag, if set in the flags field, indicates that the client deems the window
1056N/Acontents to be urgent, requiring the timely response of the user. The
1056N/Awindow manager must make some effort to draw the user's attention to this
1056N/Awindow while this flag is set. The window manager must also monitor the
1056N/Astate of this flag for the entire time the window is in the Normal or Iconic
1056N/Astate and must take appropriate action when the state of the flag changes.
1056N/AThe flag is otherwise independent of the window's state; in particular, the
1056N/Awindow manager is not required to deiconify the window if the client sets
1056N/Athe flag on an Iconic window. Clients must provide some means by which the
1056N/A<
code class="function">UrgencyHint</
code>
1056N/Aflag to be set to zero or the window to be withdrawn. The user's action can
1056N/Aeither mitigate the actual condition that made the window urgent, or it can
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Rationale</
strong></
p></
div><
p>
1056N/AThis mechanism is useful for alarm dialog boxes or reminder windows, in
1056N/Acases where mapping the window is not enough (
e.g., in the presence of
1056N/Amulti-workspace or virtual desktop window managers), and where using an
1056N/Aoverride-redirect window is too intrusive. For example, the window manager
1056N/Amay attract attention to an urgent window by adding an indicator to its
1056N/Atitle bar or its icon. Window managers may also take additional action
1056N/Afor a window that is newly urgent, such as by flashing its icon (if the
1056N/Awindow is iconic) or by raising it to the top of the stack.
1276N/A</
p></
blockquote></
div></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="WM_CLASS_Property"></
a>WM_CLASS Property</
h4></
div></
div></
div><
p>
1056N/AThe WM_CLASS property (of type STRING without control characters)
1056N/Acontains two consecutive null-terminated strings.
1056N/AThese specify the Instance and Class names to be used by both the client
1056N/Aand the window manager for looking up resources for the application
1056N/Aor as identifying information.
1056N/AThis property must be present when the window leaves the Withdrawn state
1056N/Aand may be changed only while the window is in the Withdrawn state.
1056N/AWindow managers may examine the property only when they start up
1056N/Aand when the window leaves the Withdrawn state,
1056N/Abut there should be no need for a client to change its state dynamically.
1056N/AThe two strings, respectively, are:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AA string that names the particular instance of the application to which
1056N/Athe client that owns this window belongs.
1056N/AResources that are specified by instance name override any resources
1056N/Athat are specified by class name.
1056N/AInstance names can be specified by the user in an operating-system specific
1056N/AOn POSIX-conformant systems,
1056N/Athe following conventions are used:
1276N/A </
p><
div class="itemizedlist"><
ul class="itemizedlist" type="circle"><
li class="listitem"><
p>
1056N/AIf "-name NAME" is given on the command line,
1056N/ANAME is used as the instance name.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AOtherwise, if the environment variable RESOURCE_NAME is set,
1056N/Aits value will be used as the instance name.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AOtherwise, the trailing part of the name used to invoke the program
1056N/A(argv[0] stripped of any directory names) is used as the instance name.
1276N/A </
p></
li></
ul></
div></
li><
li class="listitem"><
p>
1056N/AA string that names the general class of applications to which the client
1056N/Athat owns this window belongs.
1056N/AResources that are specified by class apply to all applications
1056N/Athat have the same class name.
1056N/AClass names are specified by the application writer.
1056N/AExamples of commonly used class names include:
1056N/A"Emacs", "XTerm", "XClock", "XLoad", and so on.
1056N/ANote that WM_CLASS strings are null-terminated
1056N/Aand, thus, differ from the general conventions that STRING properties
1056N/AThis inconsistency is necessary for backwards compatibility.
1276N/A</
p></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="WM_TRANSIENT_FOR_Property"></
a>WM_TRANSIENT_FOR Property</
h4></
div></
div></
div><
p>
1056N/AThe WM_TRANSIENT_FOR property (of type WINDOW)
1056N/Acontains the ID of another top-level window.
1056N/AThe implication is that this window is a pop-up on behalf of the named window,
1056N/Aand window managers may decide not to decorate transient windows
1056N/Aor may treat them differently in other ways.
1056N/Awindow managers should present newly mapped WM_TRANSIENT_FOR
1056N/Awindows without requiring any user interaction,
1056N/Aeven if mapping top-level windows normally does require interaction.
1056N/ADialogue boxes, for example, are an example of windows that should have
1056N/AIt is important not to confuse WM_TRANSIENT_FOR with override-redirect.
1056N/AWM_TRANSIENT_FOR should be used in those cases where the pointer
1056N/Ais not grabbed while the window is mapped (in other words,
1056N/Aif other windows are allowed to be active while the transient is up).
1056N/AIf other windows must be prevented from processing input
1056N/A(for example, when implementing pop-up menus),
1056N/Ause override-redirect and grab the pointer while the window is mapped.
1276N/A</
p></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="WM_PROTOCOLS_Property"></
a>WM_PROTOCOLS Property</
h4></
div></
div></
div><
p>
1056N/AThe WM_PROTOCOLS property (of type ATOM) is a list of atoms.
1056N/AEach atom identifies a communication protocol between the client
1056N/Aand the window manager in which the client is willing to participate.
1056N/AAtoms can identify both standard protocols and private protocols
1056N/Aspecific to individual window managers.
1056N/AAll the protocols in which a client can volunteer to take part
1056N/Ainvolve the window manager sending the client a
1056N/A<
code class="function">ClientMessage</
code>
1056N/Aevent and the client taking appropriate action.
1056N/AFor details of the contents of the event,
1276N/A<
a class="xref" href="#ClientMessage_Events" title="ClientMessage Events">ClientMessage Events</
a>
1056N/Athe protocol transactions are initiated by the window manager.
1056N/AThe WM_PROTOCOLS property is not required.
1056N/Athe client does not want to participate in any window manager protocols.
1056N/AThe X Consortium will maintain a registry of protocols to avoid collisions
1056N/AThe following table lists the protocols that have been defined to date.
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Protocol</
th><
th align="left">Section</
th><
th align="left">Purpose</
th></
tr></
thead><
tbody><
tr><
td align="left">WM_TAKE_FOCUS</
td><
td align="left">
1276N/A<
a class="xref" href="#Input_Focus" title="Input Focus">Input Focus</
a>
1056N/A </
td><
td align="left">Assignment of input focus</
td></
tr><
tr><
td align="left">WM_SAVE_YOURSELF</
td><
td align="left">Appendix C</
td><
td align="left">Save client state request (deprecated)</
td></
tr><
tr><
td align="left">WM_DELETE_WINDOW</
td><
td align="left">
1276N/A<
a class="xref" href="#Window_Deletion" title="Window Deletion">Window Deletion</
a>
1056N/A </
td><
td align="left">Request to delete top-level window</
td></
tr></
tbody></
table></
div><
p>
1056N/AIt is expected that this table will grow over time.
1276N/A</
p></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="WM_COLORMAP_WINDOWS_Property"></
a>WM_COLORMAP_WINDOWS Property</
h4></
div></
div></
div><
p>
1056N/AThe WM_COLORMAP_WINDOWS property (of type WINDOW) on a top-level window
1056N/Ais a list of the IDs of windows that may need colormaps installed
1056N/Athat differ from the colormap of the top-level window.
1056N/AThe window manager will watch this list of windows for changes in their
1056N/AThe top-level window is always (implicitly or explicitly) on the watch list.
1056N/AFor the details of this mechanism,
1276N/A<
a class="xref" href="#Colormaps" title="Colormaps">Colormaps</
a>
1276N/A</
p></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="WM_CLIENT_MACHINE_Property"></
a>WM_CLIENT_MACHINE Property</
h4></
div></
div></
div><
p>
1056N/AThe client should set the WM_CLIENT_MACHINE property (of one of the TEXT
1056N/Atypes) to a string that forms the name of the machine running the client as
1056N/Aseen from the machine running the server.
1276N/A</
p></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Window_Manager_Properties"></
a>Window Manager Properties</
h3></
div></
div></
div><
p>
1056N/AThe properties that were described in the previous section are those
1056N/Athat the client is responsible for maintaining on its top-level windows.
1056N/AThis section describes the properties that the window manager places on
1056N/Aclient's top-level windows and on the root.
1276N/A</
p><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="WM_STATE_Property"></
a>WM_STATE Property</
h4></
div></
div></
div><
p>
1056N/AThe window manager will place a WM_STATE property (of type WM_STATE) on each
1056N/Atop-level client window that is not in the Withdrawn state. Top-level
1056N/Awindows in the Withdrawn state may or may not have the WM_STATE property.
1056N/AOnce the top-level window has been withdrawn, the client may re-use it for
1056N/Aanother purpose. Clients that do so should remove the WM_STATE property if
1056N/ASome clients (such as <
code class="function">xprop</
code>) will ask the user to
1056N/Aon which the program is to operate. Typically, the intent is for this to be
1056N/Aa top-level window. To find a top-level window, clients should search the
1056N/Awindow hierarchy beneath the selected location for a window with the
1056N/AWM_STATE property. This search must be recursive in order to cover all
1056N/Awindow manager reparenting possibilities. If no window with a WM_STATE
1056N/Aproperty is found, it is recommended that programs use a mapped
1056N/Achild-of-root window if one is present beneath the selected location.
1056N/AThe contents of the WM_STATE property are defined as follows:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Field</
th><
th align="left">Type</
th><
th align="left">Comments</
th></
tr></
thead><
tbody><
tr><
td align="left">state</
td><
td align="left">CARD32</
td><
td align="left">(see the next table)</
td></
tr><
tr><
td align="left">icon</
td><
td align="left">WINDOW</
td><
td align="left">ID of icon window</
td></
tr></
tbody></
table></
div><
p>
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /></
colgroup><
thead><
tr><
th align="left">State</
th><
th align="left">Value</
th></
tr></
thead><
tbody><
tr><
td align="left">WithdrawnState</
td><
td align="left">0</
td></
tr><
tr><
td align="left">NormalState</
td><
td align="left">1</
td></
tr><
tr><
td align="left">IconicState</
td><
td align="left">3</
td></
tr></
tbody></
table></
div><
p>
1056N/AAdding other fields to this property is reserved to the X Consortium.
1056N/AValues for the state field other than those defined in the above
1056N/Atable are reserved for use by the X Consortium.
1056N/AThe state field describes the window manager's idea of the state
1056N/Athe window is in, which may not match the client's idea as expressed
1056N/Ain the initial_state field of the WM_HINTS property
1056N/A(for example, if the user has asked the window manager to iconify the window).
1056N/A<
code class="function">NormalState</
code>,
1056N/Athe window manager believes the client should be animating its window.
1056N/A<
code class="function">IconicState</
code>,
1056N/Athe client should animate its icon window.
1056N/Aclients should be prepared to handle exposure events from either window.
1056N/AWhen the window is withdrawn, the window manager will either change the
1056N/A<
code class="function">WithdrawnState</
code>
1056N/Aor it will remove the WM_STATE property entirely.
1056N/AThe icon field should contain the window ID of the window that the
1056N/Awindow manager uses as the icon for the window on which this property is
1056N/Aset. If no such window exists, the icon field should be
1056N/A<
code class="function">None</
code>.
1056N/ANote that this window could be but is not necessarily the same window as the
1056N/Aicon window that the client may have specified in its WM_HINTS property.
1056N/AThe WM_STATE icon may be a window that the window manager has supplied and
1056N/Athat contains the client's icon pixmap, or it may be an ancestor of the
1276N/A</
p></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="WM_ICON_SIZE_Property"></
a>WM_ICON_SIZE Property</
h4></
div></
div></
div><
p>
1056N/AA window manager that wishes to place constraints on the sizes of icon
1056N/Apixmaps
and/
or windows should place a property called WM_ICON_SIZE on the root.
1056N/AThe contents of this property are listed in the following table.
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Field</
th><
th align="left">Type</
th><
th align="left">Comments</
th></
tr></
thead><
tbody><
tr><
td align="left">min_width</
td><
td align="left">CARD32</
td><
td align="left">The data for the icon size series</
td></
tr><
tr><
td align="left">min_height</
td><
td align="left">CARD32</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left">max_width</
td><
td align="left">CARD32</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left">max_height</
td><
td align="left">CARD32</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left">width_inc</
td><
td align="left">CARD32</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left">height_inc</
td><
td align="left">CARD32</
td><
td class="auto-generated"> </
td></
tr></
tbody></
table></
div><
p>
1056N/AFor more details see section 14.1.12 in
1056N/A<
span class="emphasis"><
em>Xlib - C Language X Interface</
em></
span>.
1276N/A</
p></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Changing_Window_State"></
a>Changing Window State</
h3></
div></
div></
div><
p>
1056N/AFrom the client's point of view,
1056N/Athe window manager will regard each of the client's top-level
1056N/Awindows as being in one of three states,
1056N/Awhose semantics are as follows:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A<
code class="function">NormalState</
code>
1056N/A- The client's top-level window is viewable.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">IconicState</
code>
1056N/A- The client's top-level window is iconic
1056N/A(whatever that means for this window manager).
1056N/AThe client can assume that its top-level window is not viewable,
1056N/Aits icon_window (if any) will be viewable
1056N/Aits icon_pixmap (if any) or its WM_ICON_NAME will be displayed.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">WithdrawnState</
code>
1056N/A- Neither the client's top-level window nor its icon is visible.
1056N/Athe window manager may implement states with semantics
1056N/Aother than those described above.
1056N/Aa window manager might implement a concept of an "inactive" state
1056N/Ain which an infrequently used client's window would be represented
1056N/ABut this state is invisible to the client,
1056N/Awhich would see itself merely as being in the Iconic state.
1056N/ANewly created top-level windows are in the Withdrawn state.
1056N/AOnce the window has been provided with suitable properties,
1056N/Athe client is free to change its state as follows:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AWithdrawn -> Normal - The client should map the window with
1056N/A<
code class="function">NormalState</
code>.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AWithdrawn -> Iconic - The client should map the window with
1056N/A<
code class="function">IconicState</
code>.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ANormal -> Iconic - The client should send a
1056N/A<
code class="function">ClientMessage</
code>
1056N/Aevent as described later in this section.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ANormal -> Withdrawn - The client should unmap the window and follow it
1056N/A<
code class="function">UnmapNotify</
code>
1056N/Aevent as described later in this section.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIconic -> Normal - The client should map the window.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIconic -> Withdrawn - The client should unmap the window
1056N/Aand follow it with a synthetic
1056N/A<
code class="function">UnmapNotify</
code>
1056N/Aevent as described later in this section.
1056N/AOnly the client can effect a transition into or out of the Withdrawn
1056N/Ahas left the Withdrawn state,
1056N/Athe window will be mapped if it is in the Normal state and the window will be
1056N/Aunmapped if it is in the Iconic state. Reparenting window managers
1056N/Amust unmap the client's window when it is in the Iconic state, even if an
1056N/Aancestor window being unmapped renders the client's window unviewable.
1056N/AConversely, if a reparenting window manager renders the client's window
1056N/Aunviewable by unmapping an ancestor, the client's window is by definition in
1056N/Athe Iconic state and must also be unmapped.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Advice to Implementors</
strong></
p></
div><
p>
1056N/A<
code class="function">StructureNotify</
code>
1056N/Atop-level windows to track transitions between Normal and Iconic states.
1056N/A<
code class="function">MapNotify</
code>
1056N/Aevent will indicate a transition to the Normal state, and receipt of an
1056N/A<
code class="function">UnmapNotify</
code>
1056N/Aevent will indicate a transition to the Iconic state.
1056N/AWhen changing the state of the window to Withdrawn, the client must (in
1056N/Aaddition to unmapping the window) send a synthetic
1056N/A<
code class="function">UnmapNotify</
code>
1056N/A<
code class="function">SendEvent</
code>
1056N/Arequest with the following arguments:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Argument</
th><
th align="left">Value</
th></
tr></
thead><
tbody><
tr><
td align="left">destination</
td><
td align="left">The root</
td></
tr><
tr><
td align="left">propogate</
td><
td align="left"><
span class="bold"><
strong>False</
strong></
span></
td></
tr><
tr><
td align="left">event-mask</
td><
td align="left">(<
span class="bold"><
strong>SubstructureRedirect|SubstructureNotify</
strong></
span>)</
td></
tr><
tr><
td align="left">event: an <
code class="function">UnmapNotify</
code> with:</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left"> event:</
td><
td align="left">The root</
td></
tr><
tr><
td align="left"> window:</
td><
td align="left">The window itself</
td></
tr><
tr><
td align="left"> from-configure:</
td><
td align="left"><
span class="bold"><
strong>False</
strong></
span></
td></
tr></
tbody></
table></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Rationale</
strong></
p></
div><
p>
1056N/AThe reason for requiring the client to send a synthetic
1056N/A<
code class="function">UnmapNotify</
code>
1056N/Aevent is to ensure that the window manager
1056N/Agets some notification of the client's desire to change state,
1056N/Aeven though the window may already be unmapped when the desire is expressed.
1276N/A</
p></
blockquote></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Advice to Implementors</
strong></
p></
div><
p>
1056N/AFor compatibility with obsolete clients,
1056N/Awindow managers should trigger the transition to the Withdrawn state
1056N/A<
code class="function">UnmapNotify</
code>
1056N/Arather than waiting for the synthetic one.
1056N/AThey should also trigger the transition if they receive a synthetic
1056N/A<
code class="function">UnmapNotify</
code>
1056N/Aon a window for which they have not yet received a real
1056N/A<
code class="function">UnmapNotify</
code>.
1056N/AWhen a client withdraws a window,
1056N/Athe window manager will then update or remove the WM_STATE
1276N/A<
a class="xref" href="#WM_STATE_Property" title="WM_STATE Property">WM_STATE Property</
a>.
1056N/AClients that want to re-use a client window (
e.g., by mapping it again or
1056N/Areparenting it elsewhere) after withdrawing it must wait for the
1056N/Awithdrawal to be complete before proceeding. The preferred method for
1056N/Adoing this is for clients to wait for the window manager to update or
1056N/Aremove the WM_STATE property.
1056N/AIf the transition is from the Normal to the Iconic state,
1056N/A<
code class="function">ClientMessage</
code>
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AWindow == the window to be iconified
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li></
ul></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Rationale</
strong></
p></
div><
p>
1056N/A<
code class="function">ClientMessage</
code>
1056N/Aevent does not match the format of
1056N/A<
code class="function">ClientMessages</
code>
1276N/A<
a class="xref" href="#ClientMessage_Events" title="ClientMessage Events">ClientMessage Events</
a>.
1056N/AThis is because they are sent by the window manager to clients,
1056N/Aand this message is sent by clients to the window manager.
1056N/AOther values of data[0] are reserved for future extensions to these
1056N/Aconventions. The parameters of the
1056N/A<
code class="function">SendEvent</
code>
1056N/Arequest should be those described for the synthetic
1056N/A<
code class="function">UnmapNotify</
code>
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Advice to Implementors</
strong></
p></
div><
p>
1056N/A<
code class="function">VisibilityChange</
code>
1056N/Aevents on their top-level or icon windows.
1056N/A<
code class="function">VisibilityNotify</
code>
1056N/Aevent when the window concerned becomes completely
1056N/Aobscured even though mapped (and thus, perhaps a waste
1056N/A<
code class="function">VisibilityNotify</
code>
1056N/Aevent when it becomes even partly viewable.
1276N/A</
p></
blockquote></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Advice to Implementors</
strong></
p></
div><
p>
1056N/AWhen a window makes a transition from the Normal state to either the Iconic
1056N/Aor the Withdrawn state, clients should be aware that the window manager
1056N/Amay make transients for this window inaccessible. Clients should not rely
1056N/Aon transient windows being available to the user when the transient owner
1056N/Awindow is not in the Normal state. When withdrawing a window, clients are
1056N/Aadvised to withdraw transients for the window.
1276N/A</
p></
blockquote></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Configuring_the_Window"></
a>Configuring the Window</
h3></
div></
div></
div><
p>
1056N/AClients can resize and reposition their top-level windows by using the
1056N/A<
code class="function">ConfigureWindow</
code>
1056N/AThe attributes of the window that can be altered
1056N/Awith this request are as follows:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AThe [x,y] location of the window's upper left-outer corner
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe [width,height] of the inner region of the window (excluding
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe border width of the window
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe window's position in the stack
1056N/AThe coordinate system in which the location is expressed is that of the root
1056N/A(irrespective of any reparenting that may have occurred).
1056N/AThe border width to be used and win_gravity position hint
1056N/Ato be used are those most recently requested by the client.
1056N/AClient configure requests are interpreted by the window manager
1056N/Ain the same manner as the initial window geometry mapped from
1056N/Athe Withdrawn state, as described in
1276N/A<
a class="xref" href="#WM_NORMAL_HINTS_Property" title="WM_NORMAL_HINTS Property">WM_NORMAL_HINTS Property</
a>
1056N/AClients must be aware that there is no guarantee that the window manager
1056N/Awill allocate them the requested size or location and must be prepared to
1056N/Adeal with any size and location.
1056N/AIf the window manager decides to respond to a
1056N/A<
code class="function">ConfigureRequest</
code>
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/ANot changing the size, location, border width, or stacking order
1056N/AA client will receive a synthetic
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Aevent that describes the (unchanged) geometry of the window.
1056N/AThe (x,y) coordinates will be in the root coordinate system,
1056N/Aadjusted for the border width the client requested,
1056N/Airrespective of any reparenting that has taken place.
1056N/AThe border_width will be the border width the client requested.
1056N/AThe client will not receive a real
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Aevent because no change has actually taken place.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AMoving or restacking the window without resizing it or
1056N/AA client will receive a synthetic
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Aevent following the change that describes the new geometry of the window.
1056N/AThe event's (x,y) coordinates will be in the root coordinate system adjusted
1056N/Afor the border width the client requested.
1056N/AThe border_width will be the border width the client requested.
1056N/AThe client may not receive a real
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Aevent that describes this change because the window manager may have reparented
1056N/AIf the client does receive a real event,
1056N/Athe synthetic event will follow the real one.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AResizing the window or changing its border width (regardless of whether the
1056N/Awindow was also moved or restacked).
1056N/AA client that has selected for
1056N/A<
code class="function">StructureNotify</
code>
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/ANote that the coordinates in this event are relative to the parent,
1056N/Awhich may not be the root if the window has been reparented.
1056N/AThe coordinates will reflect the actual border width of the window
1056N/A(which the window manager may have changed).
1056N/A<
code class="function">TranslateCoordinates</
code>
1056N/Arequest can be used to convert the coordinates if required.
1056N/AThe general rule is that coordinates in real
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Aevents are in the parent's space;
1056N/Ain synthetic events, they are in the root space.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Advice to Implementors</
strong></
p></
div><
p>
1056N/AClients cannot distinguish between the case where a top-level window is
1056N/Aresized and moved from the case where the window is resized but not moved,
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Aevent will be received in both cases. Clients that are concerned with
1056N/Akeeping track of the absolute position of a top-level window should keep a
1056N/Apiece of state indicating whether they are certain of its position. Upon
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Aevent on the top-level window, the client should note that the position is
1056N/Aunknown. Upon receipt of a synthetic
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Aevent, the client should note the position as known, using the position in
1056N/Athis event. If the client receives a
1056N/A<
code class="function">KeyPress</
code>,
1056N/A<
code class="function">KeyRelease</
code>,
1056N/A<
code class="function">ButtonPress</
code>,
1056N/A<
code class="function">ButtonRelease</
code>,
1056N/A<
code class="function">MotionNotify</
code>,
1056N/A<
code class="function">EnterNotify</
code>
1056N/A<
code class="function">LeaveNotify</
code>
1056N/Aevent on the window (or on any descendant), the client can deduce the
1056N/Atop-level window's position from the difference between the (event-x,
1056N/Aevent-y) and (root-x, root-y) coordinates in these events. Only when the
1056N/Aposition is unknown does the client need to use the
1056N/A<
code class="function">TranslateCoordinates</
code>
1056N/Arequest to find the position of a top-level window.
1056N/AClients should be aware that their borders may not be visible.
1056N/AWindow managers are free to use reparenting techniques to
1056N/Adecorate client's top-level windows with borders containing
1056N/Atitles, controls, and other details to maintain a consistent look-and-feel.
1056N/Athey are likely to override the client's attempts to set the border width
1056N/AClients, therefore, should not depend on the top-level window's border
1056N/Abeing visible or use it to display any critical information.
1056N/AOther window managers will allow the top-level windows border to
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AClients should set the desired value of the border-width attribute on all
1056N/A<
code class="function">ConfigureWindow</
code>
1056N/Arequests to avoid a race condition.
1056N/AClients that change their position in the stack must be aware
1056N/Athat they may have been reparented,
1056N/Awhich means that windows that used to be siblings no longer are.
1056N/AUsing a nonsibling as the sibling parameter on a
1056N/A<
code class="function">ConfigureWindow</
code>
1056N/Arequest will cause an error.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/A<
code class="function">ConfigureWindow</
code>
1056N/Arequest to request a change in their position in the stack
1056N/A<
code class="function">None</
code>
1056N/AClients that must position themselves in the stack relative to some
1056N/Awindow that was originally a sibling must do the
1056N/A<
code class="function">ConfigureWindow</
code>
1056N/Arequest (in case they are running under a nonreparenting window manager),
1056N/Abe prepared to deal with a resulting error,
1056N/Aand then follow with a synthetic
1056N/A<
code class="function">ConfigureRequest</
code>
1056N/A<
code class="function">SendEvent</
code>
1056N/Arequest with the following arguments:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /></
colgroup><
thead><
tr><
th align="left">Argument</
th><
th align="left">Value</
th></
tr></
thead><
tbody><
tr><
td align="left">destination</
td><
td align="left">The root</
td></
tr><
tr><
td align="left">propogate</
td><
td align="left"><
span class="bold"><
strong>False</
strong></
span></
td></
tr><
tr><
td align="left">event-mask</
td><
td align="left">(<
span class="bold"><
strong>SubstructureRedirect|SubstructureNotify</
strong></
span>)</
td></
tr><
tr><
td align="left">event: an <
code class="function">ConfigureRequest</
code> with:</
td><
td class="auto-generated"> </
td></
tr><
tr><
td align="left"> event:</
td><
td align="left">The root</
td></
tr><
tr><
td align="left"> window:</
td><
td align="left">The window itself</
td></
tr><
tr><
td align="left"> ...</
td><
td align="left">Other parameters from the <
span class="bold"><
strong>ConfigureWindow</
strong></
span> request</
td></
tr></
tbody></
table></
div><
p>
1056N/AWindow managers are in any case free to position windows in the stack as
1056N/Athey see fit, and so clients should not rely on receiving the stacking
1056N/Aorder they have requested. Clients should ignore the above-sibling
1056N/Afield of both real and synthetic
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Aevents received on their top-level windows because this field may not
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Changing_Window_Attributes"></
a>Changing Window Attributes</
h3></
div></
div></
div><
p>
1056N/AThe attributes that may be supplied when a window is created may be
1056N/A<
code class="function">ChangeWindowAttributes</
code>
1056N/AThe window attributes are listed in the following table:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /></
colgroup><
thead><
tr><
th align="left">Attribute</
th><
th align="left">Private to Client</
th></
tr></
thead><
tbody><
tr><
td align="left">Background pixmap</
td><
td align="left">Yes</
td></
tr><
tr><
td align="left">Background pixel</
td><
td align="left">Yes</
td></
tr><
tr><
td align="left">Border pixmap</
td><
td align="left">Yes</
td></
tr><
tr><
td align="left">Border pixel</
td><
td align="left">Yes</
td></
tr><
tr><
td align="left">Bit gravity</
td><
td align="left">Yes</
td></
tr><
tr><
td align="left">Window gravity</
td><
td align="left">No</
td></
tr><
tr><
td align="left">Backing-store hint</
td><
td align="left">Yes</
td></
tr><
tr><
td align="left">Save-under hint</
td><
td align="left">No</
td></
tr><
tr><
td align="left">Event Mask</
td><
td align="left">No</
td></
tr><
tr><
td align="left">Do-not-propagate mask</
td><
td align="left">Yes</
td></
tr><
tr><
td align="left">Override-redirect flag</
td><
td align="left">No</
td></
tr><
tr><
td align="left">Colormap</
td><
td align="left">Yes</
td></
tr><
tr><
td align="left">Cursor</
td><
td align="left">Yes</
td></
tr></
tbody></
table></
div><
p>
1056N/AMost attributes are private to the client and will never be interfered with
1056N/AFor the attributes that are not private to the client:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AThe window manager is free to override the window gravity;
1056N/Aa reparenting window manager may want to set the top-level window's
1056N/Awindow gravity for its own purposes.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClients are free to set the save-under hint on their top-level windows,
1056N/Abut they must be aware that the hint may be overridden by the window manager.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AWindows, in effect, have per-client event masks,
1056N/Aand so, clients may select for whatever events are convenient irrespective
1056N/Aof any events the window manager is selecting for.
1056N/AThere are some events for which only one client at a time may select,
1056N/Abut the window manager should not select for them on any of the client's
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClients can set override-redirect on top-level windows but are
1056N/Aencouraged not to do so except as described in
1276N/A<
a class="xref" href="#Pop_up_Windows" title="Pop-up Windows">Pop-up Windows</
a>.
1276N/A<
a class="xref" href="#Redirecting_Requests" title="Redirecting Requests">Redirecting Requests</
a>.
1276N/A </
p></
li></
ul></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Input_Focus"></
a>Input Focus</
h3></
div></
div></
div><
p>
1056N/AThere are four models of input handling:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/ANo Input - The client never expects keyboard input.
1056N/A<
code class="function">xload</
code>
1056N/Aor another output-only client.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/APassive Input - The client expects keyboard input but never explicitly sets
1056N/AAn example would be a simple client with no subwindows,
1056N/A<
code class="function">PointerRoot</
code>
1056N/Amode or when the window manager sets the input focus to its top-level window
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ALocally Active Input - The client expects keyboard input and explicitly sets
1056N/Abut it only does so when one of its windows already has the focus.
1056N/AAn example would be a client with subwindows defining various data
1056N/Aentry fields that uses Next and Prev keys to move the input focus
1056N/AIt does so when its top-level window has acquired the focus in
1056N/A<
code class="function">PointerRoot</
code>
1056N/Amode or when the window manager sets the input focus to its top-level window
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AGlobally Active Input - The client expects keyboard input and explicitly sets
1056N/Aeven when it is in windows the client does not own.
1056N/AAn example would be a client with a scroll bar that wants to allow
1056N/Ausers to scroll the window without disturbing the input focus even if
1056N/AIt wants to acquire the input focus when the user clicks in the scrolled
1056N/Aregion but not when the user clicks in the scroll bar itself.
1056N/AThus, it wants to prevent the window manager from setting the input focus
1056N/AThe four input models and the corresponding values of the input field
1056N/Aand the presence or absence of the WM_TAKE_FOCUS atom in the
1056N/AWM_PROTOCOLS property are listed in the following table:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Input Model</
th><
th align="left">Input Field</
th><
th align="left">WM_TAKE_FOCUS</
th></
tr></
thead><
tbody><
tr><
td align="left">No Input</
td><
td align="left"><
span class="bold"><
strong>False</
strong></
span></
td><
td align="left">Absent</
td></
tr><
tr><
td align="left">Passive</
td><
td align="left"><
span class="bold"><
strong>True</
strong></
span></
td><
td align="left">Absent</
td></
tr><
tr><
td align="left">Locally Active</
td><
td align="left"><
span class="bold"><
strong>True</
strong></
span></
td><
td align="left">Present</
td></
tr><
tr><
td align="left">Globally Active</
td><
td align="left"><
span class="bold"><
strong>False</
strong></
span></
td><
td align="left">Present</
td></
tr></
tbody></
table></
div><
p>
1056N/APassive and Locally Active clients set the input field of WM_HINTS to
1056N/A<
code class="function">True</
code>,
1056N/Awhich indicates that they require window manager assistance in acquiring the
1056N/ANo Input and Globally Active clients set the input field to
1056N/A<
code class="function">False</
code>,
1056N/Awhich requests that the window manager not set the input focus
1056N/A<
code class="function">SetInputFocus</
code>
1056N/Arequest must set the time field to the timestamp of the event
1056N/Athat caused them to make the attempt.
1056N/A<
code class="function">FocusIn</
code>
1056N/Aevent because they do not have timestamps.
1056N/Athe focus without a corresponding
1056N/A<
code class="function">EnterNotify</
code>.
1056N/ANote that clients must not use
1056N/A<
code class="function">CurrentTime</
code>
1056N/AClients using the Globally Active model can only use a
1056N/A<
code class="function">SetInputFocus</
code>
1056N/Arequest to acquire the input focus when they do not already have it on
1056N/Areceipt of one of the following events:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A<
code class="function">ButtonPress</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">ButtonRelease</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">KeyPress</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">KeyRelease</
code>
1056N/Aclients should avoid using passive-grabbed key events for this purpose,
1056N/Aexcept when they are unavoidable (as, for example, a selection tool
1056N/Athat establishes a passive grab on the keys that cut, copy, or paste).
1056N/AThe method by which the user commands the window manager to
1056N/Aset the focus to a window is up to the window manager.
1056N/Aclients cannot determine whether they will see the click
1056N/AWindows with the atom WM_TAKE_FOCUS in their WM_PROTOCOLS property
1056N/A<
code class="function">ClientMessage</
code>
1056N/Aevent from the window manager (as described in
1276N/A<
a class="xref" href="#ClientMessage_Events" title="ClientMessage Events">ClientMessage Events</
a>.
1056N/Awith WM_TAKE_FOCUS in its data[0] field and a valid timestamp
1056N/A<
code class="function">CurrentTime</
code>)
1056N/A<
code class="function">SetInputFocus</
code>
1056N/Arequest with its window field set to the window of theirs
1056N/Athat last had the input focus or to their default input window,
1056N/Aand the time field set to the timestamp in the message.
1276N/A<
a class="xref" href="#Input_Focus" title="Input Focus">Input Focus</
a>
1056N/AA client could receive WM_TAKE_FOCUS when opening from an icon
1056N/Aor when the user has clicked outside the top-level window in an area that
1056N/Aindicates to the window manager that it should assign the focus
1056N/A(for example, clicking in the headline bar can be used to assign the focus).
1056N/AThe goal is to support window managers that want to assign the input focus
1056N/Ato a top-level window in such a way that the top-level window either
1056N/Acan assign it to one of its subwindows or can decline the offer of the focus.
1056N/AFor example, a clock or a text editor with no currently open frames
1056N/Amight not want to take focus even though the window manager generally
1056N/Abelieves that clients should take the input focus after being deiconified
1056N/AClients that set the input focus need to decide a value for the
1056N/A<
code class="function">SetInputFocus</
code>
1056N/AThis determines the behavior of the input focus
1056N/Aif the window the focus has been set to becomes not viewable.
1056N/AThe value can be any of the following:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A<
code class="function">Parent</
code>
1056N/Aclients should use this value when assigning focus to one of their subwindows.
1056N/AUnmapping the subwindow will cause focus to revert to the parent,
1056N/Awhich is probably what you want.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">PointerRoot</
code>
1056N/Athis value with a click-to-type focus management policy
1056N/Aleads to race conditions because the window becoming unviewable may
1056N/Acoincide with the window manager deciding to move the focus elsewhere.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">None</
code>
1056N/Athis value causes problems if the window manager reparents
1056N/Athe window, as most window managers will, and then crashes.
1056N/A<
code class="function">None</
code>,
1056N/Aand there will probably be no way to change it.
1056N/A<
code class="function">PointerRoot</
code>
1056N/A<
code class="function">None</
code>
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/A<
code class="function">SetInputFocus</
code>
1056N/Arequest should set the revert-to argument to
1056N/A<
code class="function">Parent</
code>.
1056N/AA convention is also required for clients that want to give up the
1056N/AThere is no safe value set for them to set the input focus to;
1056N/Atherefore, they should ignore input material.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AClients should not give up the input focus of their own volition.
1056N/AThey should ignore input that they receive instead.
1276N/A</
p></
blockquote></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Colormaps"></
a>Colormaps</
h3></
div></
div></
div><
p>
1056N/AThe window manager is responsible for installing and uninstalling
1056N/Acolormaps on behalf of clients with top-level windows that
1056N/AClients provide the window manager with hints as to which colormaps to
1056N/Ainstall and uninstall. Clients must not install or uninstall colormaps
1056N/Athemselves (except under the circumstances noted below). When a client's
1056N/Atop-level window gets the colormap focus (as a result of whatever colormap
1056N/Afocus policy is implemented by the window manager), the window manager will
1056N/Aensure that one or more of the client's colormaps are installed.
1056N/AClients whose top-level windows and subwindows all use the same colormap
1056N/Ashould set its ID in the colormap field of the top-level window's
1056N/Aattributes. They should not set a WM_COLORMAP_WINDOWS property on the
1056N/Atop-level window. If they want to change the colormap, they should change
1056N/Athe top-level window's colormap attribute. The window manager will track
1056N/Achanges to the window's colormap attribute and install colormaps as
1056N/AClients that create windows can use the value
1056N/A<
code class="function">CopyFromParent</
code>
1056N/Ato inherit their parent's colormap. Window managers will ensure that the
1056N/Aroot window's colormap field contains a colormap that is suitable for
1056N/Aclients to inherit. In particular, the colormap will provide
1056N/A<
code class="function">BlackPixel</
code>
1056N/A<
code class="function">WhitePixel</
code>.
1056N/ATop-level windows that have subwindows or override-redirect pop-up windows
1056N/Awhose colormap requirements differ from the top-level window should have a
1056N/AWM_COLORMAP_WINDOWS property. This property contains a list of IDs for
1056N/Awindows whose colormaps the window manager should attempt to have installed
1056N/Awhen, in the course of its individual colormap focus policy, it assigns the
1056N/Acolormap focus to the top-level window (see
1276N/A<
a class="xref" href="#WM_COLORMAP_WINDOWS_Property" title="WM_COLORMAP_WINDOWS Property">WM_COLORMAP_WINDOWS Property</
a>
1056N/Aordered by the importance to the client of having the colormaps installed.
1056N/AThe window manager will track changes to this property and will track
1056N/Achanges to the colormap attribute of the windows in the property.
1056N/AIf the relative importance of colormaps changes, the client should update
1056N/Athe WM_COLORMAP_WINDOWS property to reflect the new ordering. If the
1056N/Atop-level window does not appear in the list, the window manager will assume
1056N/Ait to be of higher priority than any window in the list.
1056N/AWM_TRANSIENT_FOR windows can either have their own WM_COLORMAP_WINDOWS
1056N/Aproperty or appear in the property of the window they are transient for,
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Rationale</
strong></
p></
div><
p>
1056N/AAn alternative design was considered for how clients should hint to the
1056N/Awindow manager about their colormap requirements. This alternative design
1056N/Aspecified a list of colormaps instead of a list of windows. The current
1056N/Adesign, a list of windows, was chosen for two reasons. First, it allows
1056N/Awindow managers to find the visuals of the colormaps, thus permitting
1056N/Avisual-dependent colormap installation policies. Second, it allows window
1056N/A<
code class="function">VisibilityChange</
code>
1056N/Aevents on the windows concerned and to ensure that colormaps are only
1056N/Ainstalled if the windows that need them are visible. The alternative design
1056N/Aallows for neither of these policies.
1276N/A</
p></
blockquote></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Advice to Implementors</
strong></
p></
div><
p>
1056N/AClients should be aware of the min-installed-maps and max-installed-maps
1056N/Afields of the connection setup information, and the effect that the minimum
1056N/Avalue has on the "required list" defined by the Protocol in the
1056N/A<
code class="function">InstallColormap</
code>
1056N/Arequest. Briefly, the min-installed-maps most recently installed maps are
1056N/Aguaranteed to be installed. This value is often one; clients needing
1056N/Amultiple colormaps should beware.
1056N/AWhenever possible, clients should use the mechanisms described above and let
1056N/Athe window manager handle colormap installation. However, clients are
1056N/Apermitted to perform colormap installation on their own while they have the
1056N/Apointer grabbed. A client performing colormap installation must notify the
1056N/Awindow manager prior to the first installation. When the client has
1056N/Afinished its colormap installation, it must also notify the window manager.
1056N/AThe client notifies the window manager by issuing a
1056N/A<
code class="function">SendEvent</
code>
1056N/Arequest with the following arguments:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /></
colgroup><
thead><
tr><
th align="left">Argument</
th><
th align="left">Value</
th></
tr></
thead><
tbody><
tr><
td align="left">destination</
td><
td align="left">
1056N/AThe root window of the screen on which the colormap is installed
1276N/A </
td></
tr><
tr><
td align="left">propogate</
td><
td align="left"><
span class="bold"><
strong>False</
strong></
span></
td></
tr><
tr><
td align="left">event-mask</
td><
td align="left"><
span class="bold"><
strong>ColormapChange</
strong></
span></
td></
tr><
tr><
td align="left">event: an <
code class="function">ClientMessage</
code> with:</
td><
td align="left"> </
td></
tr><
tr><
td align="left"> window:</
td><
td align="left">The root window, as above</
td></
tr><
tr><
td align="left"> type:</
td><
td align="left">WM_COLORMAP_NOTIFY</
td></
tr><
tr><
td align="left"> format</
td><
td align="left">32</
td></
tr><
tr><
td align="left"> data[0]</
td><
td align="left">
1056N/Athe timestampe of the event that caused the client to start or stop
1276N/A </
td></
tr><
tr><
td align="left"> data[1]</
td><
td align="left">
1056N/A1 if the client is starting colormap installation,
1056N/A0 if the client is finished with colormap installation
1276N/A </
td></
tr><
tr><
td align="left"> data[2]</
td><
td align="left">
1276N/A </
td></
tr><
tr><
td align="left"> data[3]</
td><
td align="left">
1276N/A </
td></
tr><
tr><
td align="left"> data[4]</
td><
td align="left">
1056N/A </
td></
tr></
tbody></
table></
div><
p>
1056N/AThis feature was introduced in version 2.0 of this document, and there will
1056N/Abe a significant period of time before all window managers can be expected
1056N/Ato implement this feature. Before using this feature, clients must check
1056N/Athe compliance level of the window manager (using the mechanism described in
1276N/A<
a class="xref" href="#Communication_with_the_Window_Manager_by_Means_of_Selections" title="Communication with the Window Manager by Means of Selections">Communication with the Window Manager by Means of Selections</
a>
1056N/A) to verify that it supports this feature. This is necessary to
1056N/Aprevent colormap installation conflicts between clients and older window
1056N/AWindow managers should refrain from installing colormaps while a client has
1056N/Arequested control of colormap installation. The window manager should
1056N/Acontinue to track the set of installed colormaps so that it can reinstate
1056N/Aits colormap focus policy when the client has finished colormap installation.
1056N/AThis technique has race conditions that may result in the colormaps
1056N/Acontinuing to be installed even after a client has issued its notification
1056N/Amessage. For example, the window manager may have issued some
1056N/A<
code class="function">InstallColormap</
code>
1056N/Arequests that are not executed until after the
1056N/A<
code class="function">SendEvent</
code>
1056N/A<
code class="function">InstallColormap</
code>
1056N/Arequests, thus uninstalling the client's colormaps. If this occurs while
1056N/Athe client still has the pointer grabbed and before the client has issued
1056N/Athe "finished" message, the client may reinstall the desired colormaps.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Advice to Implementors</
strong></
p></
div><
p>
1056N/AClients are expected to use this mechanism for things such as
1056N/Apop-up windows and for animations that use override-redirect windows.
1056N/AIf a client fails to issue the "finished" message, the window manager
1056N/Amay be left in a state where its colormap installation policy is suspended.
1056N/AWindow manager implementors may want to implement a feature that resets
1056N/Acolormap installation policy in response to a command from the user.
1276N/A</
p></
blockquote></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Icons"></
a>Icons</
h3></
div></
div></
div><
p>
1056N/AA client can hint to the window manager about the desired appearance
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/Abecause it provides a fallback for window managers whose ideas
1056N/Aabout icons differ widely from those of the client.
1056N/A<
code class="function">Pixmap</
code>
1056N/Ainto the icon_pixmap field of the WM_HINTS property
1056N/Aand possibly another into the icon_mask field.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe window manager is expected to display the pixmap masked by the mask.
1056N/AThe pixmap should be one of the sizes found in the WM_ICON_SIZE property
1056N/AIf this property is not found,
1056N/Athe window manager is unlikely to display icon pixmaps.
1056N/AWindow managers usually will clip or tile pixmaps that do not match
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AA window into the icon_window field of the WM_HINTS property.
1056N/AThe window manager is expected to map that window whenever the client is
1056N/Athe size of the icon window should be one of those specified in WM_ICON_SIZE
1056N/AWindow managers are free to resize icon windows.
1056N/Athe window manager usually will ensure that:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/Athe window it names is visible.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/Athe pixmap it names is visible.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/Athe window's WM_ICON_NAME string is visible.
1056N/AClients should observe the following conventions about their icon windows:
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Conventions</
strong></
p></
div><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AThe icon window should be an
1056N/A<
code class="function">InputOutput</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe icon window should be one of the sizes specified
1056N/Ain the WM_ICON_SIZE property on the root.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe icon window should use the root visual and default colormap
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClients should not map their icon windows.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClients should not unmap their icon windows.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClients should not configure their icon windows.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClients should not set override-redirect on their icon windows
1056N/A<
code class="function">ResizeRedirect</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClients must not depend on being able to receive input events
1056N/Aby means of their icon windows.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClients must not manipulate the borders of their icon windows.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">Exposure</
code>
1056N/Aevents on their icon window and repaint it when requested.
1056N/A </
p></
li></
ul></
div></
blockquote></
div><
p>
1056N/AWindow managers will differ as to whether they support input events
1056N/Amost will allow the client to receive some subset of the keys and buttons.
1056N/AWindow managers will ignore any WM_NAME, WM_ICON_NAME, WM_NORMAL_HINTS,
1056N/AWM_HINTS, WM_CLASS, WM_TRANSIENT_FOR, WM_PROTOCOLS, WM_COLORMAP_WINDOWS,
1056N/AWM_COMMAND, or WM_CLIENT_MACHINE
1056N/Aproperties they find on icon windows.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Pop_up_Windows"></
a>Pop-up Windows</
h3></
div></
div></
div><
p>
1056N/AClients that wish to pop up a window can do one of three things:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AThey can create and map another normal top-level window,
1056N/Awhich will get decorated and managed as normal by the window manager.
1056N/ASee the discussion of window groups that follows.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIf the window will be visible for a relatively short time
1056N/Aand deserves a somewhat lighter treatment,
1056N/Athey can set the WM_TRANSIENT_FOR property.
1056N/AThey can expect less decoration but can set all the normal
1056N/Awindow manager properties on the window.
1056N/AAn example would be a dialog box.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIf the window will be visible for a very short time
1056N/Aand should not be decorated at all,
1056N/Athe client can set override-redirect on the window.
1056N/Athis should be done only if the pointer is grabbed while the window is mapped.
1056N/AThe window manager will never interfere with these windows,
1056N/Awhich should be used with caution.
1056N/AAn example of an appropriate use is a pop-up menu.
1276N/A </
p></
li></
ul></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Advice to Implementors</
strong></
p></
div><
p>
1056N/AThe user will not be able to move, resize, restack, or transfer the input
1056N/Afocus to override-redirect windows, since the window manager is not managing
1056N/Athem. If it is necessary for a client to receive keystrokes on an
1056N/Aoverride-redirect window, either the client must grab the keyboard or the
1056N/Aclient must have another top-level window that is not override-redirect and
1056N/Athat has selected the Locally Active or Globally Active focus model. The
1056N/Aclient may set the focus to the override-redirect window when the other
1056N/Awindow receives a WM_TAKE_FOCUS message or one of the events listed in
1276N/A<
a class="xref" href="#Input_Focus" title="Input Focus">Input Focus</
a>
1056N/Ain the description of the Globally Active focus model.
1056N/AWindow managers are free to decide if WM_TRANSIENT_FOR windows
1056N/Ashould be iconified when the window they are transient for is.
1056N/AClients displaying WM_TRANSIENT_FOR windows that have
1056N/A(or request to have) the window they are transient for iconified
1056N/Ado not need to request that the same operation be performed
1056N/Aon the WM_TRANSIENT_FOR window;
1056N/Athe window manager will change its state if that is the policy it wishes
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Window_Groups"></
a>Window Groups</
h3></
div></
div></
div><
p>
1056N/AA set of top-level windows that should be treated from the user's point of view
1056N/Aas related (even though they may belong to a number of clients) should be linked
1056N/Atogether using the window_group field of the WM_HINTS structure.
1056N/AOne of the windows (that is, the one the others point to)
1056N/Awill be the group leader and will carry the group as opposed
1056N/Ato the individual properties.
1056N/AWindow managers may treat the group leader differently
1056N/Afrom other windows in the group.
1056N/Agroup leaders may have the full set of decorations,
1056N/Aand other group members may have a restricted set.
1056N/AIt is not necessary that the client ever map the group leader;
1056N/Ait may be a window that exists solely as a placeholder.
1056N/AIt is up to the window manager to determine the policy
1056N/Afor treating the windows in a group.
1056N/Athere is no way for a client to request a group,
1056N/Aas opposed to an individual, operation.
1276N/A</
p></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Client_Responses_to_Window_Manager_Actions"></
a>Client Responses to Window Manager Actions</
h2></
div></
div></
div><
p>
1056N/AThe window manager performs a number of operations on client resources,
1056N/Aprimarily on their top-level windows.
1056N/AClients must not try to fight this but may elect to receive notification
1056N/Aof the window manager's operations.
1276N/A</
p><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Reparenting"></
a>Reparenting</
h3></
div></
div></
div><
p>
1056N/AClients must be aware that some window managers will reparent
1056N/Aso that a window that was created as a child of the root will be displayed
1056N/Aas a child of some window belonging to the window manager.
1056N/AThe effects that this reparenting will have on the client are as follows:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AThe parent value returned by a
1056N/A<
code class="function">QueryTree</
code>
1056N/Arequest will no longer be the value supplied to the
1056N/A<
code class="function">CreateWindow</
code>
1056N/Arequest that created the reparented window.
1056N/AThere should be no need for the client to be aware of the identity
1056N/Aof the window to which the top-level window has been reparented.
1056N/Aa client that wishes to create further top-level windows should continue
1056N/Ato use the root as the parent for these new windows.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe server will interpret the (x,y) coordinates in a
1056N/A<
code class="function">ConfigureWindow</
code>
1056N/Arequest in the new parent's coordinate space.
1056N/AIn fact, they usually will not be interpreted by the server
1056N/Abecause a reparenting window manager usually will have intercepted
1276N/A<
a class="xref" href="#Redirection_of_Operations" title="Redirection of Operations">Redirection of Operations</
a>
1056N/AClients should use the root coordinate space for these requests
1276N/A<
a class="xref" href="#Configuring_the_Window" title="Configuring the Window">Configuring the Window</
a>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">ConfigureWindow</
code>
1056N/Arequests that name a specific sibling window may fail because the window named,
1056N/Awhich used to be a sibling, no longer is after the reparenting operation
1276N/A<
a class="xref" href="#Configuring_the_Window" title="Configuring the Window">Configuring the Window</
a>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe (x,y) coordinates returned by a
1056N/A<
code class="function">GetGeometry</
code>
1056N/Arequest are in the parent's coordinate space
1056N/Aand are thus not directly useful after a reparent operation.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">ParentRelative</
code>
1056N/Awill have unpredictable results.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">None</
code>
1056N/Awill have unpredictable results.
1056N/AClients that want to be notified when they are reparented can select for
1056N/A<
code class="function">StructureNotify</
code>
1056N/Aevents on their top-level window.
1056N/A<
code class="function">ReparentNotify</
code>
1056N/Aevent if and when reparenting takes place.
1056N/AWhen a client withdraws a top-level window, the window manager will
1056N/Areparent it back to the root window if the window had been reparented
1056N/AIf the window manager reparents a client's window,
1056N/Athe reparented window will be placed in the save-set
1056N/AThis means that the reparented window will not be destroyed
1056N/Aif the window manager terminates and will be remapped if it was unmapped.
1056N/ANote that this applies to all client windows the window manager reparents,
1056N/Aincluding transient windows and client icon windows.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Redirection_of_Operations"></
a>Redirection of Operations</
h3></
div></
div></
div><
p>
1056N/AClients must be aware that some window managers will arrange
1056N/Afor some client requests to be intercepted and redirected.
1056N/ARedirected requests are not executed;
1056N/Athey result instead in events being sent to the window manager,
1056N/Awhich may decide to do nothing, to alter the arguments,
1056N/Aor to perform the request on behalf of the client.
1056N/AThe possibility that a request may be redirected means
1056N/Athat a client cannot assume that any redirectable request is actually
1056N/Aperformed when the request is issued or is actually performed at all.
1056N/AThe requests that may be redirected are
1056N/A<
code class="function">MapWindow</
code>,
1056N/A<
code class="function">ConfigureWindow</
code>,
1056N/A<
code class="function">CirculateWindow</
code>.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Advice to Implementors</
strong></
p></
div><
p>
1056N/AThe following is incorrect because the
1056N/A<
code class="function">MapWindow</
code>
1056N/Arequest may be intercepted and the
1056N/A<
code class="function">PolyLine</
code>
1056N/Aoutput made to an unmapped window:
1056N/A</
p><
pre class="literallayout">
1056N/APolyLine A GC <point> <point> ...
1056N/A<
code class="function">Expose</
code>
1056N/Aevent before drawing in the window.
1056N/AThis next example incorrectly assumes that the
1056N/A<
code class="function">ConfigureWindow</
code>
1056N/Arequest is actually executed with the arguments supplied:
1056N/A</
p><
pre class="literallayout">
1056N/AConfigureWindow width=N height=M
1056N/A<output assuming window is N by M>
1056N/AThe client should select for
1056N/A<
code class="function">StructureNotify</
code>
1056N/Aon its window and monitor the window's size by tracking
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/AClients must be especially careful when attempting to set the focus to a
1056N/Awindow that they have just mapped. This sequence may result in an X
1056N/A</
p><
pre class="literallayout">
1056N/A<
code class="function">MapWindow</
code>
1056N/Arequest has been intercepted, the window will still be
1056N/A<
code class="function">SetInputFocus</
code>
1056N/Arequest to generate the error. The solution to this problem is for clients
1056N/A<
code class="function">VisibilityChange</
code>
1056N/Aon the window and to delay the issuance of the
1056N/A<
code class="function">SetInputFocus</
code>
1056N/Arequest until they have received a
1056N/A<
code class="function">VisibilityNotify</
code>
1056N/Aevent indicating that the window is visible.
1056N/AThis technique does not guarantee correct operation. The user may have
1056N/Aiconified the window by the time the
1056N/A<
code class="function">SetInputFocus</
code>
1056N/Arequest reaches the server, still causing an error. Or the window manager
1056N/Amay decide to map the window into Iconic state, in which case the window
1056N/Awill not be visible. This will delay the generation of the
1056N/A<
code class="function">VisibilityNotify</
code>
1056N/Aevent indefinitely. Clients must be prepared to handle these cases.
1056N/AA window with the override-redirect bit set is immune from redirection,
1056N/Abut the bit should be set on top-level windows only in cases
1056N/Awhere other windows should be prevented from processing input
1056N/Awhile the override-redirect window is mapped (see
1276N/A<
a class="xref" href="#Pop_up_Windows" title="Pop-up Windows">Pop-up Windows</
a>
1056N/A<
code class="function">ResizeRequest</
code>
1276N/A<
a class="xref" href="#Redirecting_Requests" title="Redirecting Requests">Redirecting Requests</
a>
1056N/AClients that have no non-Withdrawn top-level windows
1056N/Aand that map an override-redirect top-level window are taking over total
1056N/Aresponsibility for the state of the system.
1056N/AIt is their responsibility to:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/APrevent any preexisting window manager from interfering with their activities
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ARestore the status quo exactly after they unmap the window
1056N/Aso that any preexisting window manager does not get confused
1056N/AIn effect, clients of this kind are acting as temporary window managers.
1056N/ADoing so is strongly discouraged because these clients will be unaware
1056N/Aof the user interface policies the window manager is trying to maintain
1056N/Aand because their user interface behavior is likely to conflict with that of
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Window_Move"></
a>Window Move</
h3></
div></
div></
div><
p>
1056N/AIf the window manager moves a top-level window without changing its size,
1056N/Athe client will receive a synthetic
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Aevent following the move that describes the new location
1056N/Ain terms of the root coordinate space.
1056N/AClients must not respond to being moved by attempting to move
1056N/Athemselves to a better location.
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Aevent on a top-level window implies that the window's position
1056N/Aon the root may have changed,
1056N/Aeven though the event reports that the window's position
1056N/Ain its parent is unchanged because the window may have been reparented.
1056N/ANote that the coordinates in the event will not, in this case,
1056N/AThe window manager will send these events by using a
1056N/A<
code class="function">SendEvent</
code>
1056N/Arequest with the following arguments:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /></
colgroup><
thead><
tr><
th align="left">Argument</
th><
th align="left">Value</
th></
tr></
thead><
tbody><
tr><
td align="left">destination</
td><
td align="left">The client's window</
td></
tr><
tr><
td align="left">propagate</
td><
td align="left"><
span class="bold"><
strong>False</
strong></
span></
td></
tr><
tr><
td align="left">event-mask</
td><
td align="left"><
span class="bold"><
strong>StructureNotify</
strong></
span></
td></
tr></
tbody></
table></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Window_Resize"></
a>Window Resize</
h3></
div></
div></
div><
p>
1056N/AThe client can elect to receive notification of being resized by selecting for
1056N/A<
code class="function">StructureNotify</
code>
1056N/Aevents on its top-level windows.
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/AThe size information in the event will be correct,
1056N/Abut the location will be in the parent window (which may not be the root).
1056N/AThe response of the client to being resized should be to accept
1056N/Athe size it has been given and to do its best with it.
1056N/AClients must not respond to being resized by attempting to resize
1056N/Athemselves to a better size.
1056N/AIf the size is impossible to work with,
1056N/Aclients are free to request to change to the Iconic state.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Iconify_and_Deiconify"></
a>Iconify and Deiconify</
h3></
div></
div></
div><
p>
1056N/AA top-level window that is not Withdrawn will be
1056N/Ain the Normal state if it is mapped and in the Iconic state if it is unmapped.
1056N/AThis will be true even if the window has been reparented;
1056N/Athe window manager will unmap the window as well as its parent
1056N/Awhen switching to the Iconic state.
1056N/AThe client can elect to be notified of these state changes by selecting for
1056N/A<
code class="function">StructureNotify</
code>
1056N/Aevents on the top-level window.
1056N/A<
code class="function">UnmapNotify</
code>
1056N/Aevent when it goes Iconic and a
1056N/A<
code class="function">MapNotify</
code>
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Colormap_Change"></
a>Colormap Change</
h3></
div></
div></
div><
p>
1056N/AClients that wish to be notified of their colormaps being installed
1056N/Aor uninstalled should select for
1056N/A<
code class="function">ColormapNotify</
code>
1056N/Aevents on their top-level windows and on any windows they have named
1056N/Ain WM_COLORMAP_WINDOWS properties on their top-level windows.
1056N/A<
code class="function">ColormapNotify</
code>
1056N/Aevents with the new field FALSE when the colormap for that window
1056N/Ais installed or uninstalled.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Input_Focus_2"></
a>Input Focus</
h3></
div></
div></
div><
p>
1056N/AClients can request notification that they have the input focus by selecting
1056N/A<
code class="function">FocusChange</
code>
1056N/Aevents on their top-level windows;
1056N/A<
code class="function">FocusIn</
code>
1056N/A<
code class="function">FocusOut</
code>
1056N/AClients that need to set the input focus to one of their
1056N/Asubwindows should not do so unless
1056N/Athey have set WM_TAKE_FOCUS in their WM_PROTOCOLS property
1056N/Aand have done one of the following:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/ASet the input field of WM_HINTS to
1056N/A<
code class="function">True</
code>
1056N/Aand actually have the input focus in one of their top-level windows
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ASet the input field of WM_HINTS to
1056N/A<
code class="function">False</
code>
1056N/Aand have received a suitable event as described in
1276N/A<
a class="xref" href="#Input_Focus" title="Input Focus">Input Focus</
a>.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AHave received a WM_TAKE_FOCUS message as described in
1276N/A<
a class="xref" href="#Input_Focus" title="Input Focus">Input Focus</
a>.
1056N/AClients should not warp the pointer in an attempt to transfer the focus;
1056N/Athey should set the focus and leave the pointer alone.
1276N/A<
a class="xref" href="#The_Pointer" title="The Pointer">The Pointer</
a>.
1056N/AOnce a client satisfies these conditions,
1056N/Ait may transfer the focus to another of its windows by using the
1056N/A<
code class="function">SetInputFocus</
code>
1056N/Arequest, which is defined as follows:
1056N/A<
code class="function">SetInputFocus</
code>
1276N/A</
p><
div class="informaltable"><
table border="0"><
colgroup><
col align="left" class="c1" /></
colgroup><
tbody><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>focus</
em></
span>: WINDOW or
1056N/A<
span class="bold"><
strong>PointerRoot</
strong></
span> or
1056N/A<
span class="bold"><
strong>None</
strong></
span>
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>revert-to</
em></
span>:
1056N/A{ <
span class="bold"><
strong>Parent</
strong></
span>,
1056N/A<
span class="bold"><
strong>PointerRoot</
strong></
span>,
1056N/A<
span class="bold"><
strong>None</
strong></
span> }
1056N/A </
td></
tr><
tr><
td align="left">
1056N/A<
span class="emphasis"><
em>time</
em></
span>: TIMESTAMP or CurrentTime
1276N/A </
td></
tr></
tbody></
table></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Conventions</
strong></
p></
div><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A<
code class="function">SetInputFocus</
code>
1056N/Arequest must set the time argument to the timestamp of the event
1056N/Athat caused them to make the attempt.
1056N/A<
code class="function">FocusIn</
code>
1056N/Aevent because they do not have timestamps.
1056N/AClients may also acquire the focus without a corresponding
1056N/A<
code class="function">EnterNotify</
code>
1056N/A<
code class="function">CurrentTime</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">SetInputFocus</
code>
1056N/Arequest to set the focus to one of their windows must set
1056N/A<
code class="function">Parent</
code>.
1276N/A </
p></
li></
ul></
div></
blockquote></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="ClientMessage_Events"></
a>ClientMessage Events</
h3></
div></
div></
div><
p>
1056N/AThere is no way for clients to prevent themselves being sent
1056N/A<
code class="function">ClientMessage</
code>
1056N/ATop-level windows with a WM_PROTOCOLS property may be sent
1056N/A<
code class="function">ClientMessage</
code>
1056N/Aevents specific to the protocols named by the atoms in the property
1276N/A<
a class="xref" href="#WM_PROTOCOLS_Property" title="WM_PROTOCOLS Property">WM_PROTOCOLS Property</
a>
1056N/A<
code class="function">ClientMessage</
code>
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AWM_PROTOCOLS as the type field
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe atom that names their protocol in the data[0] field
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AA timestamp in their data[1] field
1056N/AThe remaining fields of the event,
1056N/Aare determined by the protocol.
1056N/AThese events will be sent by using a
1056N/A<
code class="function">SendEvent</
code>
1056N/Arequest with the following arguments:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /></
colgroup><
thead><
tr><
th align="left">Argument</
th><
th align="left">Value</
th></
tr></
thead><
tbody><
tr><
td align="left">destination</
td><
td align="left">The client's window</
td></
tr><
tr><
td align="left">propagate</
td><
td align="left"><
span class="bold"><
strong>False</
strong></
span></
td></
tr><
tr><
td align="left">event-mask</
td><
td align="left">() empty</
td></
tr><
tr><
td align="left">event</
td><
td align="left">As specified by the protocol</
td></
tr></
tbody></
table></
div><
div class="sect3"><
div class="titlepage"><
div><
div><
h4 class="title"><
a id="Window_Deletion"></
a>Window Deletion</
h4></
div></
div></
div><
p>
1056N/AClients, usually those with multiple top-level windows, whose server
1056N/Aconnection must survive the deletion of some of their top-level windows,
1056N/Ashould include the atom WM_DELETE_WINDOW in the WM_PROTOCOLS property on
1056N/Aeach such window. They will receive a
1056N/A<
code class="function">ClientMessage</
code>
1056N/Aevent as described above whose data[0] field is WM_DELETE_WINDOW.
1056N/AClients receiving a WM_DELETE_WINDOW message should behave as if the user
1056N/Aselected "delete window" from a hypothetical menu.
1056N/AThey should perform any confirmation dialog with the user
1056N/Aand, if they decide to complete the deletion, should do the following:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AEither change the window's state to Withdrawn (as described in
1276N/A<
a class="xref" href="#Changing_Window_State" title="Changing Window State">Changing Window State</
a>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ADestroy any internal state associated with the window.
1056N/AIf the user aborts the deletion during the confirmation dialog,
1056N/Athe client should ignore the message.
1056N/AClients are permitted to interact with the user and ask, for example,
1056N/Awhether a file associated with the window to be deleted should be saved
1056N/Aor the window deletion should be cancelled.
1056N/AClients are not required to destroy the window itself;
1056N/Abut all associated state (for example, backing store) should be released.
1056N/AIf the client aborts a destroy and the user then selects DELETE WINDOW again,
1056N/Athe window manager should start the WM_DELETE_WINDOW protocol again.
1056N/AWindow managers should not use
1056N/A<
code class="function">DestroyWindow</
code>
1056N/Arequests on a window that has WM_DELETE_WINDOW in its WM_PROTOCOLS property.
1056N/AClients that choose not to include WM_DELETE_WINDOW in the WM_PROTOCOLS
1056N/Aproperty may be disconnected from the server
1056N/Aif the user asks for one of the client's top-level windows to be deleted.
1276N/A</
p></
div></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Redirecting_Requests"></
a>Redirecting Requests</
h3></
div></
div></
div><
p>
1056N/ANormal clients can use the redirection mechanism just as window managers do
1056N/A<
code class="function">SubstructureRedirect</
code>
1056N/Aevents on a parent window or
1056N/A<
code class="function">ResizeRedirect</
code>
1056N/Aone client per window can select for these events,
1056N/Aand a convention is needed to avoid clashes.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AClients (including window managers) should select for
1056N/A<
code class="function">SubstructureRedirect</
code>
1056N/A<
code class="function">ResizeRedirect</
code>
1056N/Aevents only on windows that they own.
1056N/Aclients that need to take some special action if they are resized can select
1056N/A<
code class="function">ResizeRedirect</
code>
1056N/Aevents on their top-level windows.
1056N/A<
code class="function">ResizeRequest</
code>
1056N/Aevent if the window manager resizes their window,
1056N/Aand the resize will not actually take place.
1056N/AClients are free to make what use they like of the information
1056N/Athat the window manager wants to change their size,
1056N/Abut they must configure the window to the width and height specified
1056N/Ain the event in a timely fashion.
1056N/ATo ensure that the resize will actually happen at this stage
1056N/Ainstead of being intercepted and executed by the window manager
1056N/A(and thus restarting the process),
1056N/Athe client needs temporarily to set override-redirect on the window.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/A<
code class="function">ResizeRequest</
code>
1056N/Aevents must respond by doing the following:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/ASetting override-redirect on the window specified in the event
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AConfiguring the window specified in the event
1056N/Ato the width and height specified in the event as soon as possible
1056N/Aand before making any other geometry requests
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClearing override-redirect on the window specified in the event
1056N/A </
p></
li></
ul></
div></
blockquote></
div><
p>
1056N/AIf a window manager detects that a client is not obeying this convention,
1056N/Ait is free to take whatever measures it deems appropriate to deal with
1276N/A</
p></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Communication_with_the_Window_Manager_by_Means_of_Selections"></
a>Communication with the Window Manager by Means of Selections</
h2></
div></
div></
div><
p>
1056N/AFor each screen they manage, window managers will acquire ownership of a
1056N/Aselection named WM_S<
span class="emphasis"><
em>n</
em></
span>, where
1056N/A<
span class="emphasis"><
em>n</
em></
span> is the screen number, as
1276N/A<
a class="xref" href="#Discriminated_Names" title="Discriminated Names">Discriminated Names</
a>
1056N/AWindow managers should comply with the
1056N/Aconventions for "Manager Selections" described in
1276N/A<
a class="xref" href="#Manager_Selections" title="Manager Selections">Manager Selections</
a>.
1056N/Aintent is for clients to be able to request a variety of information or
1056N/Aservices by issuing conversion requests on this selection. Window managers
1056N/Ashould support conversion of the following target on their manager
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Atom</
th><
th align="left">Type</
th><
th align="left">Data Received</
th></
tr></
thead><
tbody><
tr><
td align="left">VERSION</
td><
td align="left">INTEGER</
td><
td align="left">
1056N/ATwo integers, which are the major and minor release numbers (respectively) of
1056N/Athe ICCCM with which the window manager complies. For this version of the
1056N/AICCCM, the numbers are 2 and 0.
1276N/A </
td></
tr></
tbody><
tbody class="footnotes"><
tr><
td colspan="3"><
div class="footnote"><
p><
a id="ftn.id2600194" href="#id2600194" class="para"><
sup>[a] </
sup></
a>
1056N/AAs a special case, clients not wishing to implement a selection
1056N/A<
code class="function">GetSelectionOwner</
code>
1056N/Arequest on the appropriate WM_S<
span class="emphasis"><
em>n</
em></
span> selection.
1056N/Aclients may assume that the window manager complies with ICCCM version 2.0
1276N/A</
p></
div></
td></
tr></
tbody></
table></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Summary_of_Window_Manager_Property_Types"></
a>Summary of Window Manager Property Types</
h2></
div></
div></
div><
p>
1056N/AThe window manager properties are summarized in the following table
1056N/A<
span class="emphasis"><
em>Xlib - C Language X Interface</
em></
span>).
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /><
col align="left" class="c4" /></
colgroup><
thead><
tr><
th align="left">Name</
th><
th align="left">Type</
th><
th align="left">Format</
th><
th align="left">See Section</
th></
tr></
thead><
tbody><
tr><
td align="left">WM_CLASS</
td><
td align="left">STRING</
td><
td align="left">8</
td><
td align="left">
1276N/A<
a class="xref" href="#WM_CLASS_Property" title="WM_CLASS Property">WM_CLASS Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_CLIENT_MACHINE</
td><
td align="left">TEXT</
td><
td align="left"> </
td><
td align="left">
1276N/A<
a class="xref" href="#WM_CLIENT_MACHINE_Property" title="WM_CLIENT_MACHINE Property">WM_CLIENT_MACHINE Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_COLORMAP_WINDOWS</
td><
td align="left">WINDOW</
td><
td align="left">32</
td><
td align="left">
1276N/A<
a class="xref" href="#WM_COLORMAP_WINDOWS_Property" title="WM_COLORMAP_WINDOWS Property">WM_COLORMAP_WINDOWS Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_HINTS</
td><
td align="left">WM_HINTS</
td><
td align="left">32</
td><
td align="left">
1276N/A<
a class="xref" href="#WM_HINTS_Property" title="WM_HINTS Property">WM_HINTS Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_ICON_NAME</
td><
td align="left">TEXT</
td><
td align="left"> </
td><
td align="left">
1276N/A<
a class="xref" href="#WM_ICON_NAME_Property" title="WM_ICON_NAME Property">WM_ICON_NAME Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_ICON_SIZE</
td><
td align="left">WM_ICON_SIZE</
td><
td align="left">32</
td><
td align="left">
1276N/A<
a class="xref" href="#WM_ICON_SIZE_Property" title="WM_ICON_SIZE Property">WM_ICON_SIZE Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_NAME</
td><
td align="left">TEXT</
td><
td align="left"> </
td><
td align="left">
1276N/A<
a class="xref" href="#WM_NAME_Property" title="WM_NAME Property">WM_NAME Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_NORMAL_HINTS</
td><
td align="left">WM_SIZE_HINTS</
td><
td align="left">32</
td><
td align="left">
1276N/A<
a class="xref" href="#WM_NORMAL_HINTS_Property" title="WM_NORMAL_HINTS Property">WM_NORMAL_HINTS Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_PROTOCOLS</
td><
td align="left">ATOM</
td><
td align="left">32</
td><
td align="left">
1276N/A<
a class="xref" href="#WM_PROTOCOLS_Property" title="WM_PROTOCOLS Property">WM_PROTOCOLS Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_STATE</
td><
td align="left">WM_STATE</
td><
td align="left">32</
td><
td align="left">
1276N/A<
a class="xref" href="#WM_STATE_Property" title="WM_STATE Property">WM_STATE Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_TRANSIENT_FOR</
td><
td align="left">WINDOW</
td><
td align="left">32</
td><
td align="left">
1276N/A<
a class="xref" href="#WM_TRANSIENT_FOR_Property" title="WM_TRANSIENT_FOR Property">WM_TRANSIENT_FOR Property</
a>
1276N/A </
td></
tr></
tbody></
table></
div></
div><
div class="footnotes"><
br /><
hr width="100" align="left" /><
div class="footnote"><
p><
a id="ftn.id2594445" href="#id2594445" class="para"><
sup>[7] </
sup></
a>
1056N/AThis obsolete protocol was described in the July 27, 1988,
1056N/AWindows using it can also be detected because their WM_HINTS properties are
1056N/A4 bytes longer than expected.
1056N/AWindow managers are free to support clients using the obsolete protocol
1056N/Ain a backwards compatibility mode.
1276N/A</
p></
div><
div class="footnote"><
p><
a id="ftn.id2595860" href="#id2595860" class="para"><
sup>[8] </
sup></
a>
1056N/AEarlier versions of these conventions prohibited clients from
1056N/Areading the WM_STATE property. Clients operating under the earlier
1056N/Aconventions used the technique of tracking
1056N/A<
code class="function">ReparentNotify</
code>
1056N/Aevents to wait for the top-level window to be reparented back to the root
1056N/Awindow. This is still a valid technique; however, it works only for
1056N/Areparenting window managers, and the WM_STATE technique is to be preferred.
1276N/A</
p></
div><
div class="footnote"><
p><
a id="ftn.id2595905" href="#id2595905" class="para"><
sup>[9] </
sup></
a>
1056N/A<
code class="function">ClientMessage</
code>
1056N/Aevent (called the message_type field by Xlib) should not be confused with
1056N/Athe code field of the event itself,
1056N/Awhich will have the value 33
1056N/A<
code class="function">( ClientMessage</
code>).
1276N/A</
p></
div><
div class="footnote"><
p><
a id="ftn.id2598803" href="#id2598803" class="para"><
sup>[10] </
sup></
a>
1056N/AThis is true even if the client set the backing-store attribute to
1056N/A<
code class="function">Always</
code>.
1056N/AThe backing-store attribute is a only a hint,
1056N/Aand the server may stop maintaining backing store contents at any time.
1276N/A</
p></
div></
div></
div><
div class="chapter"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="Session_Management_and_Additional_Inter_Client_Exchanges"></
a>Chapter 5. Session Management and Additional Inter-Client Exchanges</
h2></
div></
div></
div><
div class="toc"><
p><
strong>Table of Contents</
strong></
p><
dl><
dt><
span class="sect1"><
a href="#Client_Support_for_Session_Management">Client Support for Session Management</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Window_Manager_Support_for_Session_Management">Window Manager Support for Session Management</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Support_for_ICE_Client_Rendezvous">Support for ICE Client Rendezvous</
a></
span></
dt></
dl></
div><
p>
1056N/AThis section contains some conventions for clients that participate in
1056N/A<
span class="emphasis"><
em>X Session Management Protocol</
em></
span>
1056N/Afor further details. Clients that do not support this protocol cannot
1056N/Aexpect their window state (
e.g., WM_STATE, position, size, and stacking order)
1056N/Ato be preserved across sessions.
1276N/A</
p><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Client_Support_for_Session_Management"></
a>Client Support for Session Management</
h2></
div></
div></
div><
p>
1056N/AEach session participant will obtain a unique client identifier (client-ID)
1056N/Afrom the session manager. The client must identify one top-level window as
1056N/Athe "client leader." This window must be created by the client. It may
1056N/Abe in any state, including the Withdrawn state. The client leader window
1056N/Amust have a SM_CLIENT_ID property, which contains the client-ID obtained
1056N/Afrom the session management protocol. That property must:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AContain the client-ID as a string of XPCS characters encoded using ISO
1056N/AAll top-level, nontransient windows created by a client on the same display
1056N/Aas the client leader must have a WM_CLIENT_LEADER property. This property
1056N/Acontains a window ID that identifies the client leader window. The client
1056N/Aleader window must have a WM_CLIENT_LEADER property containing its own
1056N/Awindow ID (
i.e., the client leader window is pointing to itself). Transient
1056N/Awindows need not have a WM_CLIENT_LEADER property if the client leader can
1056N/Abe determined using the information in the WM_TRANSIENT_FOR property. The
1056N/AWM_CLIENT_LEADER property must:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AContain the window ID of the client leader window
1056N/AA client must withdraw all of its top-level windows on the same display
1056N/Abefore modifiying either the WM_CLIENT_LEADER or the SM_CLIENT_ID property
1056N/Aof its client leader window.
1056N/AIt is necessary that other clients be able to uniquely identify a window
1056N/A(across sessions) among all windows related to the same client-ID. For
1056N/Aexample, a window manager can require this unique ID to restore geometry
1056N/Ainformation from a previous session, or a workspace manager could use it to
1056N/Arestore information about which windows are in which workspace. A client
1056N/Amay optionally provide a WM_WINDOW_ROLE property to uniquely identify a
1056N/Awindow within the scope specified above. The combination of SM_CLIENT_ID
1056N/Aand WM_WINDOW_ROLE can be used by other clients to uniquely identify a
1056N/AIf the WM_WINDOW_ROLE property is not specified on a top-level window, a
1056N/Aclient that needs to uniquely identify that window will try to use instead
1056N/Athe values of WM_CLASS and WM_NAME. If a client has multiple windows with
1056N/Aidentical WM_CLASS and WM_NAME properties, then it should provide a
1056N/AThe client must set the WM_WINDOW_ROLE property to a string that uniquely
1056N/Aidentifies that window among all windows that have the same client leader
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AContain a string restricted to the XPCS characters, encoded in ISO 8859-1
1276N/A </
p></
li></
ul></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Window_Manager_Support_for_Session_Management"></
a>Window Manager Support for Session Management</
h2></
div></
div></
div><
p>
1056N/AA window manager supporting session management must register with the
1056N/Asession manager and obtain its own client-ID. The window manager should
1056N/Asave and restore information such as the WM_STATE, the layout of windows on
1056N/Athe screen, and their stacking order for every client window that has a
1056N/Avalid SM_CLIENT_ID property (on itself, or on the window named by
1056N/AWM_CLIENT_LEADER) and that can be uniquely identified.
1056N/AClients are allowed to change this state during the first phase of the
1056N/Asession checkpoint process. Therefore, window managers should request a
1056N/Asecond checkpoint phase and save clients' state only during that phase.
1276N/A</
p></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Support_for_ICE_Client_Rendezvous"></
a>Support for ICE Client Rendezvous</
h2></
div></
div></
div><
p>
1056N/AThe Inter-Client Exchange protocol (ICE) defined as of X11R6
1056N/Aspecifies a generic communication framework, independent of the X
1056N/Aserver, for data exchange between arbitrary clients. ICE also defines
1056N/Aa protocol for any two ICE clients who also have X connections
1056N/Ato the same X server to locate (rendezvous with) each other.
1056N/AThis protocol, called the "ICE X Rendezvous" protocol, is defined in
1056N/Athe ICE specification, Appendix B,
1056N/Aand uses the property ICE_PROTOCOLS plus
1056N/A<
code class="function">ClientMessage</
code>
1056N/Aevents. Refer to that specification for complete details.
1276N/A</
p></
div></
div><
div class="chapter"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="Manipulation_of_Shared_Resources"></
a>Chapter 6. Manipulation of Shared Resources</
h2></
div></
div></
div><
div class="toc"><
p><
strong>Table of Contents</
strong></
p><
dl><
dt><
span class="sect1"><
a href="#The_Input_Focus">The Input Focus</
a></
span></
dt><
dt><
span class="sect1"><
a href="#The_Pointer">The Pointer</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Grabs">Grabs</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Colormaps_2">Colormaps</
a></
span></
dt><
dt><
span class="sect1"><
a href="#The_Keyboard_Mapping">The Keyboard Mapping</
a></
span></
dt><
dt><
span class="sect1"><
a href="#The_Modifier_Mapping">The Modifier Mapping</
a></
span></
dt></
dl></
div><
p>
1056N/AX Version 11 permits clients to manipulate a number of shared resources,
1056N/Afor example, the input focus, the pointer, and colormaps.
1056N/AConventions are required so that clients share resources in an
1276N/A</
p><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="The_Input_Focus"></
a>The Input Focus</
h2></
div></
div></
div><
p>
1056N/AClients that explicitly set the input focus must observe one of two modes:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li></
ul></
div><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Conventions</
strong></
p></
div><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/ALocally active clients should set the input focus to one of their windows
1056N/Aonly when it is already in one of their windows
1056N/Aor when they receive a WM_TAKE_FOCUS message.
1056N/AThey should set the input field of the WM_HINTS structure to
1056N/A<
code class="function">True</
code>.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AGlobally active clients should set the input focus to one of their windows
1056N/Aonly when they receive a button event and a passive-grabbed key event,
1056N/Aor when they receive a WM_TAKE_FOCUS message.
1056N/AThey should set the input field of the WM_HINTS structure to
1056N/A<
code class="function">False</
code>.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIn addition, clients should use the timestamp of the event
1056N/Athat caused them to attempt to set the input focus as the time field on the
1056N/A<
code class="function">SetInputFocus</
code>
1056N/A<
code class="function">CurrentTime</
code>.
1276N/A </
p></
li></
ul></
div></
blockquote></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="The_Pointer"></
a>The Pointer</
h2></
div></
div></
div><
p>
1056N/AIn general, clients should not warp the pointer.
1056N/AWindow managers, however, may do so
1056N/A(for example, to maintain the invariant that the pointer is always
1056N/Ain the window with the input focus).
1056N/AOther window managers may want to preserve the illusion that the user
1056N/Ais in sole control of the pointer.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Conventions</
strong></
p></
div><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AClients should not warp the pointer.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClients that insist on warping the pointer should do so only
1056N/Awith the src-window argument of the
1056N/A<
code class="function">WarpPointer</
code>
1056N/Arequest set to one of their windows.
1276N/A </
p></
li></
ul></
div></
blockquote></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Grabs"></
a>Grabs</
h2></
div></
div></
div><
p>
1056N/AA client's attempt to establish a button or a key grab on a window
1056N/Awill fail if some other client has already established a conflicting
1056N/AThe grabs, therefore, are shared resources,
1056N/Aand their use requires conventions.
1056N/AIn conformance with the principle that clients should behave,
1056N/Awhen a window manager is running as they would when it is not,
1056N/Aa client that has the input focus may assume that it can receive all
1056N/Athe available keys and buttons.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AWindow managers should ensure that they provide some mechanism for
1056N/Atheir clients to receive events from all keys and all buttons,
1056N/Aexcept for events involving keys whose KeySyms are registered as being for
1056N/Awindow management functions (for example, a hypothetical WINDOW KeySym).
1056N/Awindow managers must provide some mechanism by which a client
1056N/Acan receive events from every key and button (regardless of modifiers)
1056N/Aunless and until the X Consortium registers some KeySyms as being reserved
1056N/Afor window management functions.
1056N/ACurrently, no KeySyms are registered for window management functions.
1056N/AEven so, clients are advised to allow the key and button combinations
1056N/Aused to elicit program actions to be modified,
1056N/Abecause some window managers may choose not to observe this convention
1056N/Aor may not provide a convenient method for the user to transmit events
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AClients should establish button and key grabs only on windows that
1056N/AIn particular, this convention means that a window manager that wishes
1056N/Ato establish a grab over the client's top-level window should either establish
1056N/Athe grab on the root or reparent the window and establish the grab
1056N/Aa window manager may want to consume the event received,
1056N/Aplacing the window in a state where a subsequent such event will go to
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AClicking in a window to set focus with the click not being offered
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClicking in a buried window to raise it, again, with the click not offered
1056N/Aa window manager should add to, rather than replace, the client's semantics
1056N/Afor key+button combinations by allowing the event to be used by the client
1056N/Aafter the window manager is done with it.
1056N/Athe window manager should establish the grab on the parent
1056N/A</
p><
pre class="literallayout">
1056N/AThen, the window manager should release the grab by using an
1056N/A<
code class="function">AllowEvents</
code>
1056N/Arequest with the following specified:
1056N/A</
p><
pre class="literallayout">
1056N/Athe client will receive the events as if they had not been intercepted.
1056N/Athese conventions place some constraints on possible user interface policies.
1056N/AThere is a trade-off here between freedom for window managers to implement
1056N/Atheir user interface policies and freedom for clients to implement theirs.
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AAllowing window managers to decide if and when a client will receive an
1056N/Aevent from any given key or button
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/APlacing a requirement on the window manager to provide some mechanism,
1056N/Aby which the user can send an event from any key or button to the client
1276N/A </
p></
li></
ul></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Colormaps_2"></
a>Colormaps</
h2></
div></
div></
div><
p>
1276N/A<
a class="xref" href="#Colormaps" title="Colormaps">Colormaps</
a>
1056N/Aprescribes conventions for clients to communicate with the
1056N/Awindow manager about their colormap needs. If your clients are
1056N/A<
code class="function">DirectColor</
code>
1056N/Ayou should consult section 14.3 of
1056N/A<
span class="emphasis"><
em>Xlib - C Language X Interface</
em></
span>
1056N/Afor conventions connected with sharing standard colormaps.
1056N/AThey should look for and create the properties described there on
1056N/Athe root window of the appropriate screen.
1056N/AThe contents of the RGB_COLOR_MAP type property are as follows:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Field</
th><
th align="left">Type</
th><
th align="left">Comments</
th></
tr></
thead><
tbody><
tr><
td align="left">colormap</
td><
td align="left">COLORMAP</
td><
td align="left">ID of the colormap described</
td></
tr><
tr><
td align="left">red_max</
td><
td align="left">CARD32</
td><
td align="left">Values for pixel calculations</
td></
tr><
tr><
td align="left">red_mult</
td><
td align="left">CARD32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">green_max</
td><
td align="left">CARD32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">green_mult</
td><
td align="left">CARD32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">blue_max</
td><
td align="left">CARD32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">blue_mult</
td><
td align="left">CARD32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">base_pixel</
td><
td align="left">CARD32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">visual_id</
td><
td align="left">VISUALID</
td><
td align="left">Visual to which colormap belongs</
td></
tr><
tr><
td align="left">kill_id</
td><
td align="left">CARD32</
td><
td align="left">ID for destroying the resources</
td></
tr></
tbody></
table></
div><
p>
1056N/AWhen deleting or replacing an RGB_COLOR_MAP,
1056N/Ait is not sufficient to delete the property;
1056N/Ait is important to free the associated colormap resources as well.
1056N/AIf kill_id is greater than one,
1056N/Athe resources should be freed by issuing a
1056N/A<
code class="function">KillClient</
code>
1056N/Arequest with kill_id as the argument.
1056N/Athe resources should be freed by issuing a
1056N/A<
code class="function">FreeColormap</
code>
1056N/Arequest with colormap as the colormap
1056N/Ano attempt should be made to free the resources.
1056N/AA client that creates an RGB_COLOR_MAP for which the colormap resource
1056N/Ais created specifically for this purpose should set kill_id to one
1056N/A(and can create more than one such standard colormap
1056N/AA client that creates an RGB_COLOR_MAP for which the colormap resource
1056N/Ais shared in some way (for example, is the default colormap
1056N/Afor the root window) should create an arbitrary resource and use its
1056N/Aresource ID for kill_id (and should create no other standard colormaps
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AIf an RGB_COLOR_MAP property is too short to contain the visual_id field,
1056N/Ait can be assumed that the visual_id is the root visual
1056N/AIf an RGB_COLOR_MAP property is too short to contain the kill_id field,
1056N/Aa value of zero can be assumed.
1056N/ADuring the connection handshake,
1056N/Athe server informs the client of the default colormap for each screen.
1056N/AThis is a colormap for the root visual,
1056N/Aand clients can use it to improve the extent of colormap sharing
1056N/Aif they use the root visual.
1276N/A</
p></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="The_Keyboard_Mapping"></
a>The Keyboard Mapping</
h2></
div></
div></
div><
p>
1056N/AThe X server contains a table (which is read by
1056N/A<
code class="function">GetKeyboardMapping</
code>
1056N/Arequests) that describes the set of symbols appearing
1056N/Aon the corresponding key for each keycode generated by the server.
1056N/AThis table does not affect the server's operations in any way;
1056N/Ait is simply a database used by clients that attempt to understand
1056N/ANevertheless, it is a shared resource and requires conventions.
1056N/AIt is possible for clients to modify this table by using a
1056N/A<
code class="function">ChangeKeyboardMapping</
code>
1056N/AIn general, clients should not do this.
1056N/AIn particular, this is not the way in which clients should implement
1056N/Akey bindings or key remapping.
1056N/AThe conversion between a sequence of keycodes received from the server
1056N/Aand a string in a particular encoding is a private matter for each client
1056N/A(as it must be in a world where applications may be using different
1056N/Aencodings to support different languages and fonts).
1056N/ASee the Xlib reference manual for converting keyboard events to text.
1056N/AThe only valid reason for using a
1056N/A<
code class="function">ChangeKeyboardMapping</
code>
1056N/Arequest is when the symbols written on the keys have changed as, for example,
1056N/Awhen a Dvorak key conversion kit or a set of APL keycaps has been installed.
1056N/AOf course, a client may have to take the change to the keycap on trust.
1056N/AThe following illustrates a permissible interaction between a client
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A"You just started me on a server without a Pause key.
1056N/APlease choose a key to be the Pause key and press it now."
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A"Adding Pause to the symbols on the Scroll Lock key: Confirm or Abort."
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">ChangeKeyboardMapping</
code>
1056N/Arequest to add Pause to the keycode that already contains Scroll Lock and
1056N/Aissues this request, "Please paint Pause on the Scroll Lock key."
1056N/A<
code class="function">ChangeKeyboardMapping</
code>
1056N/AIf a client succeeds in changing the keyboard mapping table,
1056N/A<
code class="function">MappingNotify</
code>
1056N/AThere is no mechanism to avoid receiving these events.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/A<
code class="function">MappingNotify</
code>
1056N/Aevents should update any internal keycode translation tables they are using.
1276N/A</
p></
blockquote></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="The_Modifier_Mapping"></
a>The Modifier Mapping</
h2></
div></
div></
div><
p>
1056N/AX Version 11 supports 8 modifier bits of which 3 are preassigned
1056N/Ato Shift, Lock, and Control.
1056N/AEach modifier bit is controlled by the state of a set of keys,
1056N/Aand these sets are specified in a table accessed by
1056N/A<
code class="function">GetModifierMapping</
code> and
1056N/A<
code class="function">SetModifierMapping</
code> requests.
1056N/AThis table is a shared resource and requires conventions.
1056N/AA client that needs to use one of the preassigned modifiers should assume
1056N/Athat the modifier table has been set up correctly to control these modifiers.
1056N/AThe Lock modifier should be interpreted as Caps Lock or Shift Lock
1056N/Aaccording as the keycodes in its controlling set include XK_Caps_Lock
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/AClients should determine the meaning of a modifier bit from the KeySyms
1056N/AA client that needs to use an extra modifier (for example, META) should do
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AScan the existing modifier mappings.
1056N/AIf it finds a modifier that contains a keycode whose set of KeySyms
1056N/Aincludes XK_Meta_L or XK_Meta_R,
1056N/Ait should use that modifier bit.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIf there is no existing modifier controlled by XK_Meta_L or XK_Meta_R,
1056N/Ait should select an unused modifier bit (one with an empty controlling set)
1276N/A </
p><
div class="itemizedlist"><
ul class="itemizedlist" type="circle"><
li class="listitem"><
p>
1056N/AIf there is a keycode with XL_Meta_L in its set of KeySyms,
1056N/Aadd that keycode to the set for the chosen modifier.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIf there is a keycode with XL_Meta_R in its set of KeySyms,
1056N/Aadd that keycode to the set for the chosen modifier.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIf the controlling set is still empty,
1056N/Ainteract with the user to select one or more keys to be META.
1276N/A </
p></
li></
ul></
div></
li><
li class="listitem"><
p>
1056N/AIf there are no unused modifier bits,
1056N/Aask the user to take corrective action.
1276N/A </
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Conventions</
strong></
p></
div><
div class="itemizedlist"><
ul class="itemizedlist" type="circle"><
li class="listitem"><
p>
1056N/AClients needing a modifier not currently in use should assign keycodes
1056N/Acarrying suitable KeySyms to an unused modifier bit.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClients assigning their own modifier bits should ask the user politely to
1056N/Aremove his or her hands from the key in question if their
1056N/A<
code class="function">SetModifierMapping</
code>
1056N/A<
code class="function">Busy</
code>
1056N/A </
p></
li></
ul></
div></
blockquote></
div></
li></
ul></
div><
p>
1056N/AThere is no good solution to the problem of reclaiming assignments
1056N/Ato the five nonpreassigned modifiers when they are no longer being used.
1276N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
div class="blockquote-title"><
p><
strong>Convention</
strong></
p></
div><
p>
1056N/A<
code class="function">xmodmap</
code>
1056N/Aor some other utility to deassign obsolete modifier mappings by hand.
1056N/AWhen a client succeeds in performing a
1056N/A<
code class="function">SetModifierMapping</
code>
1056N/A<
code class="function">MappingNotify</
code>
1056N/AThere is no mechanism for preventing these events from being received.
1056N/AA client that uses one of the nonpreassigned modifiers that receives
1056N/Aone of these events should do a
1056N/A<
code class="function">GetModifierMapping</
code>
1056N/Arequest to discover the new mapping,
1056N/Aand if the modifier it is using has been cleared,
1056N/Ait should reinstall the modifier.
1056N/A<
code class="function">GrabServer</
code>
1056N/Arequest must be used to make the
1056N/A<
code class="function">GetModifierMapping</
code>
1056N/A<
code class="function">SetModifierMapping</
code>
1056N/Apair in these transactions atomic.
1276N/A</
p></
div></
div><
div class="chapter"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="Device_Color_Characterization"></
a>Chapter 7. Device Color Characterization</
h2></
div></
div></
div><
div class="toc"><
p><
strong>Table of Contents</
strong></
p><
dl><
dt><
span class="sect1"><
a href="#XYZ_lt_gt_RGB_Conversion_Matrices">XYZ <-> RGB Conversion Matrices</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Intensity_dA_RGB_Value_Conversion">Intensity (dA RGB Value Conversion</
a></
span></
dt></
dl></
div><
p>
1056N/AThe X protocol provides explicit Red, Green, and Blue (RGB) values,
1056N/Awhich are used to directly drive a monitor, and color names. RGB values
1056N/Aprovide a mechanism for accessing the full capabilities of the display
1056N/Adevice, but at the expense of having the color perceived by the user remain
1056N/Aunknowable through the protocol. Color names were originally designed to
1056N/Aprovide access to a device-independent color database by having the server
1056N/Avendor tune the definitions of the colors in that textual database.
1056N/AUnfortunately, this still does not provide the client any way of using
1056N/Aan existing device-independent color, nor for the client to get
1056N/Adevice-independent color information back about colors that it has selected.
1056N/AFurthermore, the client must be able to discover which set of colors are
1056N/Adisplayable by the device (the device gamut), both to allow colors to be
1056N/Aintelligently modified to fit within the device capabilities (gamut
1056N/Acompression) and to enable the user interface to display a representation of
1056N/Athe reachable color space to the user (gamut display).
1056N/ATherefore, a system is needed that will provide full access to
1056N/Adevice-independent color spaces for X clients. This system should use a
1056N/Astandard mechanism for naming the colors, be able to provide names for
1056N/Aexisting colors, and provide means by which unreachable colors can be
1056N/Amodified to fall within the device gamut.
1056N/AWe are fortunate in this area to have a seminal work, the 1931 CIE color
1056N/Astandard, which is nearly universally agreed upon as adequate for describing
1056N/Acolors on CRT devices. This standard uses a tri-stimulus model called CIE
1056N/AXYZ in which each perceivable color is specified as a triplet of numbers.
1056N/AOther appropriate device-independent color models do exist, but most of them
1056N/Aare directly traceable back to this original work.
1056N/AX device color characterization
1056N/Aprovides device-independent color spaces to X clients. It does this by
1056N/Aproviding the barest possible amount of information to the client that
1056N/Aallows the client to construct a mapping between CIE XYZ and the regular X
1056N/ADevice color characterization is defined by
1056N/Athe name and contents of two window properties that,
1056N/Atogether, permit converting between CIE XYZ space and
1056N/Alinear RGB device space (such as standard CRTs).
1056N/ALinear RGB devices require just two
1056N/Apieces of information to completely characterize them:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AA 3 x 3 matrix M and its inverse M<
sup>-1</
sup>,
1056N/AXYZ and RGB intensity (RGB<
sub>intensity</
sub>):
1056N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
p>
1056N/ARGB<
sub>intensity</
sub> = M x XYZ
1056N/AXYZ = M<
sup>-1</
sup> x RGB<
sub>intensity</
sub>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AA way of mapping between RGB intensity and RGB protocol value. XDCCC
1056N/Asupports three mechanisms which will be outlined later.
1056N/AIf other device types are eventually necessary, additional
1056N/Aproperties will be required to describe them.
1276N/A</
p><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="XYZ_lt_gt_RGB_Conversion_Matrices"></
a>XYZ <-> RGB Conversion Matrices</
h2></
div></
div></
div><
p>
1056N/ABecause of the limited dynamic range of both XYZ and RGB intensity,
1056N/Athese matrices will be encoded using a fixed-point representation of a
1056N/A32-bit two's complement number scaled by 2<
sup>27</
sup>,
1056N/Agiving a range of -16 to 16 - Ε, where
1056N/AThese matrices will be packed into an 18-element list of 32-bit values,
1056N/AXYZ -> RGB matrix first, in row major order and stored in the
1056N/AXDCCC_LINEAR_RGB_MATRICES properties (format = 32) on the root window of
1056N/Aeach screen, using values appropriate for that screen.
1056N/AThis will be encoded as shown in the following table:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Field</
th><
th align="left">Type</
th><
th align="left">Comments</
th></
tr></
thead><
tbody><
tr><
td align="left">M<
sub>0,0</
sub></
td><
td align="left">INT32</
td><
td align="left">Interpreted as a fixed-point number -16 ≤ x < 16</
td></
tr><
tr><
td align="left">M<
sub>0,1</
sub></
td><
td align="left">INT32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">...</
td><
td align="left">INT32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">M<
sub>3,3</
sub></
td><
td align="left">INT32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">M<
sup>-1</
sup><
sub>0,0</
sub></
td><
td align="left">INT32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">M<
sup>-1</
sup><
sub>0,1</
sub></
td><
td align="left">INT32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">...</
td><
td align="left">INT32</
td><
td align="left"> </
td></
tr><
tr><
td align="left">M<
sup>-1</
sup><
sub>3,3</
sub></
td><
td align="left">INT32</
td><
td align="left"> </
td></
tr></
tbody></
table></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Intensity_dA_RGB_Value_Conversion"></
a>Intensity (dA RGB Value Conversion</
h2></
div></
div></
div><
p>
1056N/AXDCCC provides two representations for describing the conversion
1056N/Abetween RGB intensity and the actual X protocol RGB values:
1056N/A</
p><
pre class="literallayout">
1056N/AIn both cases, the relevant data will be stored in the
1056N/AXDCCC_LINEAR_RGB_CORRECTION properties on the root window of each screen,
1056N/Ausing values appropriate for that screen, in whatever format provides
1056N/Aadequate resolution. Each property can consist of multiple entries
1056N/Aconcatenated together, if different visuals for the screen require different
1056N/Aconversion data. An entry with a VisualID of 0 specifies data for all
1056N/Avisuals of the screen that are not otherwise explicitly listed.
1056N/Athe RGB values in strictly increasing order. When converting, the client must
1056N/Alinearly interpolate between adjacent entries in the table to compute the
1056N/Adesired value. This allows the server to perform gamma correction
1056N/Aitself and encode that fact in a short two-element correction table. The
1056N/Aintensity will be encoded as an unsigned number to be interpreted as a value
1056N/Abetween 0 and 1 (inclusive). The precision of this value will depend on the
1056N/Aformat of the property in which it is stored (8, 16, or 32 bits). For 16-bit
1056N/Aand 32-bit formats, the RGB value will simply be the value stored in the
1056N/Aproperty. When stored in 8-bit format, the RGB value can be computed from
1056N/Athe value in the property by:
1056N/ARGB sub value ~ = ~ { Property ~ Value ~ times ~ 65535 } over 255
1056N/ABecause the three electron guns in the device may not be exactly alike in
1056N/Aresponse characteristics, it is necessary to allow for three separate
1056N/Atables, one each for red, green, and blue. Therefore, each table will be
1056N/Apreceded by the number of entries in that table, and the set of tables will be
1056N/Apreceded by the number of tables.
1056N/AWhen three tables are provided, they will be in red, green, blue order.
1056N/AThis will be encoded as shown in the following table:
1056N/AXDCCC_LINEAR_RGB_CORRECTION Property Contents for Type 0 Correction
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Field</
th><
th align="left">Type</
th><
th align="left">Comments</
th></
tr></
thead><
tbody><
tr><
td align="left">VisualID0</
td><
td align="left">CARD</
td><
td align="left">Most significant portion of VisualID</
td></
tr><
tr><
td align="left">VisualID1</
td><
td align="left">CARD</
td><
td align="left">Exists if and only if the property format is 8</
td></
tr><
tr><
td align="left">VisualID2</
td><
td align="left">CARD</
td><
td align="left">Exists if and only if the property format is 8</
td></
tr><
tr><
td align="left">VisualID3</
td><
td align="left">CARD</
td><
td align="left">
1056N/ALeast significant portion, exists if and only if the property
1056N/A </
td></
tr><
tr><
td align="left">type</
td><
td align="left">CARD</
td><
td align="left">0 for this type of correction</
td></
tr><
tr><
td align="left">count</
td><
td align="left">CARD</
td><
td align="left">Number of tables following (either 1 or 3)</
td></
tr><
tr><
td align="left">length</
td><
td align="left">CARD</
td><
td align="left">Number of pairs -1 following in this table</
td></
tr><
tr><
td align="left">value</
td><
td align="left">CARD</
td><
td align="left">X Protocol RBG value</
td></
tr><
tr><
td align="left">intensity</
td><
td align="left">CARD</
td><
td align="left">
1056N/AInterpret as number 0 ≤ <
span class="emphasis"><
em>intensity</
em></
span> ≤ 1
1056N/A </
td></
tr><
tr><
td align="left">...</
td><
td align="left">...</
td><
td align="left">
1056N/ATotal of <
span class="emphasis"><
em>length+1</
em></
span> pairs of
1056N/A </
td></
tr><
tr><
td align="left">lengthg</
td><
td align="left">CARD</
td><
td align="left">
1056N/ANumber of pairs -1 following in this table (if and only if
1056N/A<
span class="emphasis"><
em>count</
em></
span> is 3
1056N/A </
td></
tr><
tr><
td align="left">value</
td><
td align="left">CARD</
td><
td align="left">X Protocol RBG value</
td></
tr><
tr><
td align="left">intensity</
td><
td align="left">CARD</
td><
td align="left">
1056N/AInterpret as a number 0 ≤ <
span class="emphasis"><
em>intensity</
em></
span> ≤ 1
1056N/A </
td></
tr><
tr><
td align="left">...</
td><
td align="left">...</
td><
td align="left">
1056N/ATotal of <
span class="emphasis"><
em>length+1</
em></
span> pairs of
1056N/A </
td></
tr><
tr><
td align="left">lengthb</
td><
td align="left">CARD</
td><
td align="left">
1056N/ANumber of pairs -1 following in this table (if and only if
1056N/A<
span class="emphasis"><
em>count</
em></
span> is 3
1056N/A </
td></
tr><
tr><
td align="left">value</
td><
td align="left">CARD</
td><
td align="left">X Protocol RBG value</
td></
tr><
tr><
td align="left">intensity</
td><
td align="left">CARD</
td><
td align="left">
1056N/AInterpret as a number 0 ≤ <
span class="emphasis"><
em>intensity</
em></
span> ≤ 1
1056N/A </
td></
tr><
tr><
td align="left">...</
td><
td align="left">...</
td><
td align="left">
1056N/ATotal of <
span class="emphasis"><
em>length+1</
em></
span> pairs of
1056N/A </
td></
tr></
tbody></
table></
div><
p>
1056N/AThe VisualID is stored in 4, 2, or 1 pieces, depending on whether
1056N/Athe property format is 8, 16, or 32, respectively. The VisualID is always
1056N/Astored most significant piece first.
1056N/ANote that the length fields are stored as one less than the actual length,
1056N/Aso 256 entries can be stored in format 8.
1056N/AThe second representation is a simple array of intensities for a linear subset
1056N/Aof RGB values. The expected size of this table is the bits-per-rgb-value of
1056N/Athe screen, but it can be any length. This is similar to the first mechanism,
1056N/Aexcept that the RGB value numbers are implicitly defined by the index in the
1056N/A</
p><
div class="blockquote"><
blockquote class="blockquote"><
p>
1056N/ARGB sub value ~ = ~ { Array ~ Index ~ times ~ 65535 } over
1056N/AWhen converting, the client may linearly interpolate between entries in this
1056N/Atable. The intensity values will be encoded just as in the first
1056N/AThis will be encoded as shown in the following table:
1056N/AXDCCC_LINEAR_RGB_CORRECTION Property Contents for Type 1 Correction
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /></
colgroup><
thead><
tr><
th align="left">Field</
th><
th align="left">Type</
th><
th align="left">Comments</
th></
tr></
thead><
tbody><
tr><
td align="left">VisualID0</
td><
td align="left">CARD</
td><
td align="left">Most significant portion of VisualID</
td></
tr><
tr><
td align="left">VisualID1</
td><
td align="left">CARD</
td><
td align="left">Exists if and only if the property format is 8</
td></
tr><
tr><
td align="left">VisualID2</
td><
td align="left">CARD</
td><
td align="left">Exists if and only if the property format is 8</
td></
tr><
tr><
td align="left">VisualID3</
td><
td align="left">CARD</
td><
td align="left">
1056N/ALeast significant portion, exists if and only if the property
1056N/A </
td></
tr><
tr><
td align="left">type</
td><
td align="left">CARD</
td><
td align="left">1 for this type of correction</
td></
tr><
tr><
td align="left">count</
td><
td align="left">CARD</
td><
td align="left">Number of tables following (either 1 or 3)</
td></
tr><
tr><
td align="left">length</
td><
td align="left">CARD</
td><
td align="left">Number of pairs -1 following in this table</
td></
tr><
tr><
td align="left">intensity</
td><
td align="left">CARD</
td><
td align="left">
1056N/AInterpret as number 0 ≤ <
span class="emphasis"><
em>intensity</
em></
span> ≤ 1
1056N/A </
td></
tr><
tr><
td align="left">...</
td><
td align="left">...</
td><
td align="left">
1056N/ATotal of <
span class="emphasis"><
em>length+1</
em></
span> pairs of
1056N/A </
td></
tr><
tr><
td align="left">lengthg</
td><
td align="left">CARD</
td><
td align="left">
1056N/ANumber of pairs -1 following in this table (if and only if
1056N/A<
span class="emphasis"><
em>count</
em></
span> is 3
1056N/A </
td></
tr><
tr><
td align="left">intensity</
td><
td align="left">CARD</
td><
td align="left">
1056N/AInterpret as a number 0 ≤ <
span class="emphasis"><
em>intensity</
em></
span> ≤ 1
1056N/A </
td></
tr><
tr><
td align="left">...</
td><
td align="left">...</
td><
td align="left">
1056N/ATotal of <
span class="emphasis"><
em>length+1</
em></
span> pairs of
1056N/A </
td></
tr><
tr><
td align="left">lengthb</
td><
td align="left">CARD</
td><
td align="left">
1056N/ANumber of pairs -1 following in this table (if and only if
1056N/A<
span class="emphasis"><
em>count</
em></
span> is 3
1056N/A </
td></
tr><
tr><
td align="left">intensity</
td><
td align="left">CARD</
td><
td align="left">
1056N/AInterpret as a number 0 ≤ <
span class="emphasis"><
em>intensity</
em></
span> ≤ 1
1056N/A </
td></
tr><
tr><
td align="left">...</
td><
td align="left">...</
td><
td align="left">
1056N/ATotal of <
span class="emphasis"><
em>length+1</
em></
span> pairs of
1276N/A </
td></
tr></
tbody></
table></
div></
div></
div><
div class="chapter"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="Conclusion"></
a>Chapter 8. Conclusion</
h2></
div></
div></
div><
div class="toc"><
p><
strong>Table of Contents</
strong></
p><
dl><
dt><
span class="sect1"><
a href="#The_X_Registry">The X Registry</
a></
span></
dt></
dl></
div><
p>
1056N/AThis document provides the protocol-level specification of the minimal
1056N/Aconventions needed to ensure that X Version 11 clients can interoperate
1056N/Aproperly. This document specifies interoperability conventions only for the
1056N/AX Version 11 protocol. Clients should be aware of other protocols that
1056N/Ashould be used for better interoperation in the X environment. The reader
1056N/A<
span class="emphasis"><
em>X Session Management Protocol</
em></
span>
1056N/Afor information on session management, and to
1056N/A<
span class="emphasis"><
em>Inter-Client Exchange Protocol</
em></
span>
1056N/Afor information on general-purpose communication among clients.
1276N/A</
p><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="The_X_Registry"></
a>The X Registry</
h2></
div></
div></
div><
p>
1056N/AThe X Consortium maintains a registry of certain X-related items, to aid in
1056N/Aavoiding conflicts and in sharing of such items. Readers are
1056N/Aencouraged to use the registry. The classes of items kept in the registry
1056N/Athat are relevant to the ICCCM include property names, property types,
1056N/Aselection names, selection targets, WM_PROTOCOLS protocols,
1056N/A<
code class="function">ClientMessage</
code>
1056N/Atypes, and application classes. Requests to register items, or questions
1056N/Aabout registration, should be addressed to
1056N/A </
p><
div class="address"><
p><
br />
1056N/A </
p><
div class="address"><
p><
br />
1056N/A Santa Clara, CA 95054<
br />
1056N/AElectronic mail will be acknowledged upon receipt. Please allow up to 4
1056N/Aweeks for a formal response to registration and inquiries.
1056N/AThe registry is published as part of the X software distribution from the
1056N/AX.Org Foundation. All registered items must have the postal address of someone
1056N/Aresponsible for the item or a reference to a document describing the item
1056N/Aand the postal address of where to write to obtain the document.
1276N/A</
p></
div></
div><
div class="appendix"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="revision_history"></
a>Appendix A. Revision History</
h2></
div></
div></
div><
div class="toc"><
p><
strong>Table of Contents</
strong></
p><
dl><
dt><
span class="sect1"><
a href="#The_X11R2_Draft">The X11R2 Draft</
a></
span></
dt><
dt><
span class="sect1"><
a href="#The_July_27_1988_Draft">The July 27, 1988, Draft</
a></
span></
dt><
dt><
span class="sect1"><
a href="#The_Public_Review_Drafts">The Public Review Drafts</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Version_10_July_1989">Version 1.0, July 1989</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Version_11">Version 1.1</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Public_Review_Draft_December_1993">Public Review Draft, December 1993</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Version_20_April_1994">Version 2.0, April 1994</
a></
span></
dt></
dl></
div><
p>
1056N/AThis appendix describes the revision history of this document and
1056N/Asummarizes the incompatibilities between this and earlier versions.
1276N/A</
p><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="The_X11R2_Draft"></
a>The X11R2 Draft</
h2></
div></
div></
div><
p>
1056N/AThe February 25, 1988, draft that was distributed as part of X Version 11,
1056N/ARelease 2, was clearly labeled as such,
1056N/Aand many areas were explicitly labeled as liable to change.
1056N/ANevertheless, in the revision work done since then,
1056N/Awe have been very careful not to introduce gratuitous incompatibility.
1056N/Awe have tried to ensure that clients obeying the conventions
1056N/Ain the X11R2 draft would still work.
1276N/A</
p></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="The_July_27_1988_Draft"></
a>The July 27, 1988, Draft</
h2></
div></
div></
div><
p>
1056N/AThe Consortium review was based on a draft dated July 27, 1988. This draft
1056N/Aincluded several areas in which incompatibilities with the X11R2 draft were
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A<
code class="function">None</
code>
1056N/A<
code class="function">ConvertSelection</
code>
1056N/Arequests is no longer allowed.
1056N/AOwners that receive them are free to use the target atom as the property
1056N/Awhich will work in most cases.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe protocol for INCREMENTAL type properties as selection replies has changed,
1056N/Aand the name has been changed to INCR.
1056N/ASelection requestors are free to implement the earlier protocol
1056N/Aif they receive properties of type INCREMENTAL.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe protocol for INDIRECT type properties as selection replies has changed,
1056N/Aand the name has been changed to MULTIPLE.
1056N/ASelection requestors are free to implement the earlier protocol
1056N/Aif they receive properties of type INDIRECT.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe protocol for the special CLIPBOARD client has changed.
1056N/AThe earlier protocol is subject to race conditions and should not be used.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/Abut the values that are still valid are unchanged.
1056N/AWindow managers should treat the other values sensibly.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe methods an application uses to change the state of its top-level window
1056N/Ahave changed but in such a way that cases that used to work will still work.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe x, y, width, and height fields have been removed from the WM_NORMAL_HINTS
1056N/Aproperty and replaced by pad fields.
1056N/AValues set into these fields will be ignored.
1056N/AThe position and size of the window should be set by setting the appropriate
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AA pair of base fields and a win_gravity field have been added
1056N/Ato the WM_NORMAL_HINTS property.
1056N/AWindow managers will assume values for these fields if the client
1276N/A </
p></
li></
ul></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="The_Public_Review_Drafts"></
a>The Public Review Drafts</
h2></
div></
div></
div><
p>
1056N/AThe Consortium review resulted in several incompatible changes. These
1056N/Achanges were included in drafts that were distributed for public review
1056N/Aduring the first half of 1989.
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AThe messages field of the WM_HINTS property was found to be unwieldy
1056N/AIt has been replaced by the WM_PROTOCOLS property,
1056N/Abut clients that use the earlier mechanism can be detected
1056N/Abecause they set the messages bit in the flags field of the WM_HINTS property,
1056N/Aand window managers can provide a backwards compatibility mode.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe mechanism described in the earlier draft by which clients installed
1056N/Atheir own subwindow colormaps could not be made to work reliably
1056N/Aand mandated some features of the look and feel.
1056N/AIt has been replaced by the WM_COLORMAP_WINDOWS property.
1056N/AClients that use the earlier mechanism can be detected by the WM_COLORMAPS
1056N/Aproperty they set on their top-level window,
1056N/Abut providing a reliable backwards compatibility mode is not possible.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe recommendations for window manager treatment of top-level window borders
1056N/Ahave been changed as those in the earlier draft produced problems
1056N/AFor nonwindow manager clients,
1056N/Athere is no incompatibility.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe pseudoroot facility in the earlier draft has been removed.
1056N/AAlthough it has been successfully implemented,
1056N/Ait turns out to be inadequate to support the uses envisaged.
1056N/AAn extension will be required to support these uses fully,
1056N/Aand it was felt that the maximum freedom should be left to the designers
1056N/Athe previous mechanism was invisible to clients and no incompatibility
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe addition of the WM_DELETE_WINDOW protocol (which prevents the danger
1056N/Athat multi-window clients may be terminated unexpectedly)
1056N/Ahas meant some changes in the WM_SAVE_YOURSELF protocol,
1056N/Ato ensure that the two protocols are orthogonal.
1056N/AClients using the earlier protocol can be detected (see WM_PROTOCOLS above)
1056N/Aand supported in a backwards compatibility mode.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe conventions in Section 14.3.1. of
1056N/A<
span class="emphasis"><
em>Xlib - C Language X Interface</
em></
span>
1056N/Aregarding properties of type RGB_COLOR_MAP have been changed,
1056N/Abut clients that use the earlier conventions can be detected
1056N/Abecause their properties are 4 bytes shorter.
1056N/AThese clients will work correctly if the server supports only a single Visual
1056N/Aor if they use only the Visual of the root.
1056N/AThese are the only cases in which they would have worked, anyway.
1276N/A </
p></
li></
ul></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Version_10_July_1989"></
a>Version 1.0, July 1989</
h2></
div></
div></
div><
p>
1056N/AThe public review resulted in a set of mostly editorial changes. The
1056N/Achanges in version 1.0 that introduced some degree of incompatibility with
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A<
a class="xref" href="#Grabs" title="Grabs">Grabs</
a>
1056N/A) was added covering the window manager's
1056N/AThe restrictions it imposes should affect only window managers.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe TARGETS selection target has been clarified,
1056N/Aand it may be necessary for clients to add some entries to their replies.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AA selection owner using INCR transfer should no longer replace targets in
1056N/Aa MULTIPLE property with the atom INCR.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">ClientMessage</
code>
1056N/Aevent sent by a client to iconify itself has been clarified,
1056N/Abut there should be no incompatibility because the earlier contents
1056N/Awould not in fact have worked.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe border-width in synthetic
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Abut this should not cause any incompatibility.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AClients are now asked to set a border-width on all
1056N/A<
code class="function">ConfigureWindow</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AWindow manager properties on icon windows now will be ignored,
1056N/Abut there should be no incompatibility
1056N/Abecause there was no specification that they be obeyed previously.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe ordering of real and synthetic
1056N/A<
code class="function">ConfigureNotify</
code>
1056N/Abut any incompatibility should affect only window managers.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe semantics of WM_SAVE_YOURSELF have been clarified and restricted to
1056N/Abe a checkpoint operation only.
1056N/AClients that were using it as part of a shutdown sequence may need to
1056N/Aespecially if they were interacting with the user during the shutdown.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AA kill_id field has been added to RGB_COLOR_MAP properties.
1056N/AClients using earlier conventions can be detected by the size of their
1056N/Aand the cases that would have worked will still work.
1276N/A </
p></
li></
ul></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Version_11"></
a>Version 1.1</
h2></
div></
div></
div><
p>
1056N/AVersion 1.1 was released with X11R5 in September 1991. In addition to some
1056N/Aminor editorial changes, there were a few semantic changes since Version
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AThe section on Device Color Characterization was added.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe meaning of the NULL property type was clarified.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AAppropriate references to Compound Text were added.
1276N/A </
p></
li></
ul></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Public_Review_Draft_December_1993"></
a>Public Review Draft, December 1993</
h2></
div></
div></
div><
p>
1056N/AThe following changes have been made in preparing the public review draft
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/A[P01] Addition of advice to clients on how to keep track of a top-level
1056N/Awindow's absolute position on the screen.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P03] A technique for clients to detect when it is safe to reuse a
1056N/Atop-level window has been added.
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A<
a class="xref" href="#Colormaps" title="Colormaps">Colormaps</
a>
1056N/A, on colormaps, has been rewritten. A new feature that
1056N/Aallows clients to install their own colormaps has also been added.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P08] The LENGTH target has been deprecated.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P11] The manager selections facility was added.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P17] The definition of the aspect ratio fields of the WM_NORMAL_HINTS
1056N/Aproperty has been changed to include the base size.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">StaticGravity</
code>
1056N/Ahas been added to the list of values allowed for the win_gravity field of
1056N/Athe WM_HINTS property. The meaning of the
1056N/A<
code class="function">CenterGravity</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P20] A means for clients to query the ICCCM compliance level of the window
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P22] The definition of the MULTIPLE selection target has been clarified.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P25] A definition of "top-level window" has been added. The WM_STATE
1056N/Aproperty has been defined and exposed to clients.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P26] The definition of window states has been clarified and the wording
1056N/Aregarding window state changes has been made more consistent.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P27] Clarified the rules governing when window managers are required to send
1056N/A<
code class="function">ConfigureNotify</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P28] Added a recommended technique for setting the input focus to a window
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P29] The required lifetime of resource IDs named in window manager
1056N/Aproperties has been specified.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P30] Advice for dealing with keystrokes and override-redirect windows has
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P31] A statement on the ownership of resources transferred through the
1056N/Aselection mechanism has been added.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P32] The definition of the CLIENT_WINDOW target has been clarified.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P33] A rule about requiring the selection owner to reacquire the
1056N/Aselection under certain circumstances has been added.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P42] Added several new selection targets.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P44] Ambiguous wording regarding the withdrawal of top-level windows
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P45] A facility for requestors to pass parameters during a selection
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P49] A convention on discrimated names has been added.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P57] The C_STRING property type was added.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P62] An ordering requirement on processing selection requests was added.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A<
code class="function">VisibleHint</
code>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/A[P64] The session management section has been updated to align with the new
1056N/Asession management protocol. The old session management conventions have
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AReferences to the never-forthcoming
1056N/A<
span class="emphasis"><
em>Window and Session Manager
1056N/AConventions Manual</
em></
span> have been removed.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AInformation on the X Registry and references to the session management and
1056N/AICE documents have been added.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ANumerous editorial and typographical improvements have been made.
1276N/A </
p></
li></
ul></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Version_20_April_1994"></
a>Version 2.0, April 1994</
h2></
div></
div></
div><
p>
1056N/AThe following changes have been made in preparation for releasing
1056N/Athe final edition of Version 2.0 with X11R6.
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AThe PIXMAP selection target has been revised to return a property of type
1056N/APIXMAP instead of type DRAWABLE.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe session management section has been revised slightly to correspond with
1056N/A<
span class="emphasis"><
em>X Session Management Protocol</
em></
span>.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AWindow managers are now prohibited from placing
1056N/A<
code class="function">CurrentTime</
code>
1056N/Ain the timestamp field of WM_TAKE_FOCUS messages.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AIn the WM_HINTS property, the
1056N/A<
code class="function">VisibleHint</
code>
1056N/A<
code class="function">UrgencyHint</
code>.
1056N/AIts semantics have also been defined more thoroughly.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AAdditional editorial and typographical changes have been made.
1276N/A </
p></
li></
ul></
div></
div></
div><
div class="appendix"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="suggested_protocol_revisions"></
a>Appendix B. Suggested Protocol Revisions</
h2></
div></
div></
div><
p>
1056N/ADuring the development of these conventions,
1056N/Aa number of inadequacies have been discovered in the
1056N/AThey are summarized here as input to an eventual protocol revision
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AThere is no way for anyone to find out the last-change time of
1056N/A<
code class="function">GetSelectionOwner</
code>
1056N/Arequest should be changed to return the last-change time as well as the owner.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThere is no way for a client to find out which selection atoms are valid.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThere would be no need for WM_TAKE_FOCUS if the
1056N/A<
code class="function">FocusIn</
code>
1056N/Aevent contained a timestamp and a previous-focus field.
1056N/AThis could avoid the potential race condition.
1056N/AThere is space in the event for this information;
1056N/Ait should be added at the next protocol revision.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThere is a race condition in the
1056N/A<
code class="function">InstallColormap</
code>
1056N/AIt does not take a timestamp and may be executed after the top-level colormap
1056N/AThe next protocol revision should provide the timestamp in the
1056N/A<
code class="function">InstallColormap</
code>,
1056N/A<
code class="function">UninstallColormap</
code>,
1056N/A<
code class="function">ListInstalledColormaps</
code>
1056N/A<
code class="function">ColormapNotify</
code>
1056N/AThe timestamp should be used in a similar way to the last-focus-change
1056N/Atime for the input focus. The lack of timestamps in these packets is the
1056N/Areason for restricting colormap installation to the window manager.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThe protocol needs to be changed to provide some way of identifying
1056N/Athe Visual and the Screen of a colormap.
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThere should be some way to reclaim assignments to the five nonpreassigned
1056N/Amodifiers when they are no longer needed. The manual method is unpleasantly
1276N/A </
p></
li></
ul></
div></
div><
div class="appendix"><
div class="titlepage"><
div><
div><
h2 class="title"><
a id="obsolete_session_manager_conventions"></
a>Appendix C. Obsolete Session Manager Conventions</
h2></
div></
div></
div><
div class="toc"><
p><
strong>Table of Contents</
strong></
p><
dl><
dt><
span class="sect1"><
a href="#Properties">Properties</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#WM_COMMAND_Property">WM_COMMAND Property</
a></
span></
dt><
dt><
span class="sect2"><
a href="#WM_CLIENT_MACHINE_Property_2">WM_CLIENT_MACHINE Property</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Termination">Termination</
a></
span></
dt><
dt><
span class="sect1"><
a href="#Client_Responses_to_Session_Manager_Actions">Client Responses to Session Manager Actions</
a></
span></
dt><
dd><
dl><
dt><
span class="sect2"><
a href="#Saving_Client_State">Saving Client State</
a></
span></
dt><
dt><
span class="sect2"><
a href="#Window_Deletion_2">Window Deletion</
a></
span></
dt></
dl></
dd><
dt><
span class="sect1"><
a href="#Summary_of_Session_Manager_Property_Types">Summary of Session Manager Property Types</
a></
span></
dt></
dl></
div><
p>
1056N/AThis appendix contains obsolete conventions for session management using X
1056N/Aproperties and messages. The conventions described here are deprecated and
1056N/Aare described only for historical interest. For further information on
1056N/A<
span class="emphasis"><
em>X Session Management Protocol</
em></
span>.
1276N/A</
p><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Properties"></
a>Properties</
h2></
div></
div></
div><
p>
1056N/AThe client communicates with the session manager by placing two properties
1056N/A(WM_COMMAND and WM_CLIENT_MACHINE) on its top-level window.
1056N/AIf the client has a group of top-level windows,
1056N/Athese properties should be placed on the group leader window.
1056N/AThe window manager is responsible for placing a WM_STATE property
1056N/Aon each top-level client window for use by session managers and other clients
1056N/Athat need to be able to identify top-level client windows and their state.
1276N/A</
p><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="WM_COMMAND_Property"></
a>WM_COMMAND Property</
h3></
div></
div></
div><
p>
1056N/AThe WM_COMMAND property represents the command used to start or restart the
1056N/Aclient. By updating this property, clients should ensure that it always
1056N/Areflects a command that will restart them in their current state. The
1056N/Acontent and type of the property depend on the operating system of the
1056N/Amachine running the client. On POSIX-conformant systems using ISO Latin-1
1056N/Acharacters for their command lines, the property should:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AContain a list of null-terminated strings
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AOther systems will need to set appropriate conventions for the type
1056N/Aand contents of WM_COMMAND properties.
1056N/AWindow and session managers should not assume that STRING is
1056N/Athe type of WM_COMMAND or that they will be able to understand
1056N/ANote that WM_COMMAND strings are null-terminated
1056N/Aand differ from the general conventions that STRING properties
1056N/AThis inconsistency is necessary for backwards compatibility.
1056N/AA client with multiple top-level windows should ensure
1056N/Athat exactly one of them has a WM_COMMAND with nonzero length.
1056N/AZero-length WM_COMMAND properties can be used to reply to WM_SAVE_YOURSELF
1056N/Amessages on other top-level windows but will otherwise be ignored.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="WM_CLIENT_MACHINE_Property_2"></
a>WM_CLIENT_MACHINE Property</
h3></
div></
div></
div><
p>
1056N/AThis property is described in
1276N/A<
a class="xref" href="#WM_CLIENT_MACHINE_Property" title="WM_CLIENT_MACHINE Property">WM_CLIENT_MACHINE Property</
a>.
1276N/A</
p></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Termination"></
a>Termination</
h2></
div></
div></
div><
p>
1056N/ABecause they communicate by means of unreliable network connections, clients
1056N/Amust be prepared for their connection to the server to be terminated at any
1056N/Atime without warning. They cannot depend on getting notification that
1056N/Atermination is imminent or on being able to use the server to negotiate with
1056N/Athe user about their fate. For example, clients cannot depend on being able
1056N/ASimilarly, clients may terminate at any time without notice to the session
1056N/Amanager. When a client terminates itself rather than being terminated by
1056N/Athe session manager, it is viewed as having resigned from the session in
1056N/Aquestion, and it will not be revived if the session is revived.
1276N/A</
p></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Client_Responses_to_Session_Manager_Actions"></
a>Client Responses to Session Manager Actions</
h2></
div></
div></
div><
p>
1056N/AClients may need to respond to session manager actions in two ways:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1276N/A </
p></
li><
li class="listitem"><
p>
1276N/A </
p></
li></
ul></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Saving_Client_State"></
a>Saving Client State</
h3></
div></
div></
div><
p>
1056N/AClients that want to be warned when the session manager feels
1056N/Athat they should save their internal state (for example,
1056N/Awhen termination impends) should include the atom WM_SAVE_YOURSELF
1056N/Ain the WM_PROTOCOLS property on their top-level windows to participate
1056N/Ain the WM_SAVE_YOURSELF protocol.
1056N/A<
code class="function">ClientMessage</
code>
1276N/A<
a class="xref" href="#ClientMessage_Events" title="ClientMessage Events">ClientMessage Events</
a>
1056N/Awith the atom WM_SAVE_YOURSELF in its data[0] field.
1056N/AClients that receive WM_SAVE_YOURSELF should place themselves in a state from
1056N/Awhich they can be restarted and should update WM_COMMAND to
1056N/Abe a command that will restart them in this state.
1056N/AThe session manager will be waiting for a
1056N/A<
code class="function">PropertyNotify</
code>
1056N/Aevent on WM_COMMAND as a confirmation that the client has saved its state.
1056N/ATherefore, WM_COMMAND should be updated (perhaps with a zero-length append)
1056N/Aeven if its contents are correct.
1056N/ANo interactions with the user are permitted during this process.
1056N/AOnce it has received this confirmation,
1056N/Athe session manager will feel free to terminate the client if that is what
1056N/Aif the user asked for the session to be put to sleep,
1056N/Athe session manager will ensure that the client does not
1056N/Areceive any mouse or keyboard events.
1056N/AAfter receiving a WM_SAVE_YOURSELF, saving its state, and updating WM_COMMAND,
1056N/Athe client should not change its state (in the sense of doing anything
1056N/Athat would require a change to WM_COMMAND) until it receives a mouse
1056N/Ait can assume that the danger is over.
1056N/AThe session manager will ensure that these events do not reach
1056N/Aclients until the danger is over or until the clients have been killed.
1056N/AIrrespective of how they are arranged in window groups,
1056N/Aclients with multiple top-level windows should ensure the following:
1276N/A</
p><
div class="itemizedlist"><
ul class="itemizedlist" type="disc"><
li class="listitem"><
p>
1056N/AOnly one of their top-level windows has a nonzero-length WM_COMMAND
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/AThey respond to a WM_SAVE_YOURSELF message by:
1276N/A </
p><
div class="itemizedlist"><
ul class="itemizedlist" type="circle"><
li class="listitem"><
p>
1056N/AFirst, updating the nonzero-length WM_COMMAND property, if necessary
1276N/A </
p></
li><
li class="listitem"><
p>
1056N/ASecond, updating the WM_COMMAND property on the window for which they received
1056N/Athe WM_SAVE_YOURSELF message if it was not updated in the first step
1056N/A </
p></
li></
ul></
div></
li></
ul></
div><
p>
1056N/AReceiving WM_SAVE_YOURSELF on a window is, conceptually, a command
1056N/Ato save the entire client state.
1276N/A</
p></
div><
div class="sect2"><
div class="titlepage"><
div><
div><
h3 class="title"><
a id="Window_Deletion_2"></
a>Window Deletion</
h3></
div></
div></
div><
p>
1056N/AWindows are deleted using the WM_DELETE_WINDOW protocol, which
1276N/A<
a class="xref" href="#Window_Deletion" title="Window Deletion">Window Deletion</
a>.
1276N/A</
p></
div></
div><
div class="sect1"><
div class="titlepage"><
div><
div><
h2 class="title" style="clear: both"><
a id="Summary_of_Session_Manager_Property_Types"></
a>Summary of Session Manager Property Types</
h2></
div></
div></
div><
p>
1056N/AThe session manager properties are listed in the following table:
1276N/A</
p><
div class="informaltable"><
table border="1"><
colgroup><
col align="left" class="c1" /><
col align="left" class="c2" /><
col align="left" class="c3" /><
col align="left" class="c4" /></
colgroup><
thead><
tr><
th align="left">Name</
th><
th align="left">Type</
th><
th align="left">Format</
th><
th align="left">See Section</
th></
tr></
thead><
tbody><
tr><
td align="left">WM_CLIENT_MACHINE</
td><
td align="left">TEXT</
td><
td align="left"> </
td><
td align="left">
1276N/A<
a class="xref" href="#WM_CLIENT_MACHINE_Property" title="WM_CLIENT_MACHINE Property">WM_CLIENT_MACHINE Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_COMMAND</
td><
td align="left">TEXT</
td><
td align="left"> </
td><
td align="left">
1276N/A<
a class="xref" href="#WM_COMMAND_Property" title="WM_COMMAND Property">WM_COMMAND Property</
a>
1056N/A </
td></
tr><
tr><
td align="left">WM_STATE</
td><
td align="left">WM_STATE</
td><
td align="left">32</
td><
td align="left">
1276N/A<
a class="xref" href="#WM_STATE_Property" title="WM_STATE Property">WM_STATE Property</
a>
1276N/A </
td></
tr></
tbody></
table></
div></
div><
div class="footnotes"><
br /><
hr width="100" align="left" /><
div class="footnote"><
p><
a id="ftn.id2604837" href="#id2604837" class="para"><
sup>[11] </
sup></
a>
1056N/AThis convention has changed since earlier drafts because of the
1056N/Aintroduction of the protocol in the next section.
1056N/Athere was ambiguity as to whether WM_SAVE_YOURSELF was a checkpoint
1056N/AIt is now unambiguously a checkpoint facility;
1056N/Aif a shutdown facility is judged to be necessary,
1056N/Aa separate WM_PROTOCOLS protocol will be developed and registered
1056N/A</
p></
div></
div></
div></
div></
body></
html>