Once the client has created one or more top-level windows but before it maps them, it must place properties on those windows to help the window manager manage them effectively. The following sections describe each property that must or should be set and how to set it.

It is important to remember that the version 1 conventions are the accepted X Consortium standard and will continue to be valid in R5 and later; there will be additions but not incompatible changes.

Some of the properties that a client sets for the window manager are mandatory (the standard properties), and some are optional. XSetWMProperties() which was introduced and used in basicwin in Chapter 3, “Basic Window Program” sets all the required properties. The purpose of XSetWMProperties() is to provide a simple interface for the programmer who wants to code an application quickly. Other functions are provided to communicate more optional information to the window manager.

In order to work well with most window managers, every program should call XSetWMProperties() for each top-level window. These provide the window manager with the following information:

The window manager, not Xlib, chooses its own default response when any of these properties are not set. Also, they are only hints. A window manager determines what to do with this information and is allowed to ignore it. They will, of course, be ignored if no window manager is running.

The following sections describe the properties set by the client that indicate its preferences to the window manager. Table 12-1 shows all the predefined properties that clients can set and the section in this chapter where they are described.

In addition to the functions mentioned above that set all of the standard properties, Xlib also provides separate functions for setting and getting each property. These are referenced in the sections below describing each property. See the relevant pages in Volume Two, for full details on each function. Applications set these properties and never read them, and the window manager gets them but never sets them. Therefore, if you are writing an application, you will only use the routines that set these properties.

typedef struct {
   long flags;                  /* Marks defined members in
                                 * structure */
   int x, y;                    /* Obsolete */
   int width, height;           /* Obsolete */
   int min_width, min_height;
   int max_width, max_height;
   int width_inc, height_inc;
   struct {
          int x;                /* Numerator */
          int y;                /* Denominator */
   } min_aspect, max_aspect;
   int base_width, base_height;
   int win_gravity;
} XSizeHints;

Additional Window Manager Hints - XA_WM_HINTS

The hints stored in the XA_WM_HINTS property provide an assortment of information to the window manager. Setting this property is required according to the ICCCM. Normally this is done by calling XSetWMProperties(). The XA_WM_HINTS property includes:

• Whether the program sets the keyboard focus window independently or only when assigned by the window manager.

• Whether the program desires to begin life as a window or as an icon.

• A window to be used by the window manager as an icon, or a pixmap and mask to be used by the window manager to draw on an icon window it creates.

• The initial position of the icon.

This property is normally set by the client with XSetWMProperties(). You should use the new XAllocWMHints() function to allocate an XWMHints structure, then set its fields, and then call XSetWMProperties(). An example doing this is shown in Chapter 3. The XWMHints structure is shown in Example 12-2.

Example 12-2. The XWMHints structure

typedef struct { long flags; /* Marks defined members in structure */ Bool input; /* Does application need window * manager for keyboard input */ int initial_state; /* See below */ Pixmap icon_pixmap; /* Pixmap to be used as icon */ Window icon_window; /* Window to be used as icon */ int icon_x, icon_y; /* Initial position of icon */ Pixmap icon_mask; /* Pixmap to be used as mask * for icon_pixmap */ XID window_group; /* ID of related window group */ /* This structure may be extended in the future */ } XWMHints;

The following sections describe each member of XWMHints and how it should be set.

Flags Field

The client must set the flags field to indicate which members of the XWMHints structure are to be read by the window manager. This is done by combining the symbols shown in Table 12-3 using bitwise OR (|).

Table 12-3. Flags for Window Manager Hints

Member	Flag	Bit
input	InputHint	0
initial_state	StateHint	1
icon_pixmap	IconPixmapHint	2
icon_window	IconWindowHint	3
icon_x, icon_y	IconPositionHint	4
icon_mask	IconMaskHint	5
window_group	WindowGroupHint	6
All of the above	AllHints	0-6

Input Field and the Keyboard Focus

The input member of XWMHints is used to communicate to the window manager the keyboard focus model used by the application. ^[51] For the input hint to be read by the window manager, the InputHint constant must be specified in the flags field of XWMHints.

There are four input models:

• No Input. The client never expects keyboard input. An example would be xload or another output-only client.

• Passive Input. The client expects keyboard input but never explicitly sets the keyboard focus. An example would be a simple client with no subwindows, which will accept input in PointerRoot mode, or when the window manager sets the keyboard focus to its top-level window (in click-to-type mode).

• Locally Active Input. The client expects keyboard input and explicitly sets the keyboard focus but only does so when one of its windows already has the focus.

  An example of a Locally Active style client would be a client with subwindows defining various data entry members. Such an application might use Next and Prev keys to move the keyboard focus between the members, once its top-level window has acquired the focus in pointer-following mode or when the window manager sets the keyboard focus to its top-level window (in click-to-type mode).

• Globally Active Input. The client expects keyboard input and explicitly sets the keyboard focus even when the focus is set to a window the client does not own. An example would be a client with a scrollbar that wants to allow users to scroll the window without disturbing the keyboard focus even if it is in some other window. The client wants to acquire the keyboard focus when the user clicks in the scrolled region, but not when the user clicks in the scrollbar itself, and then set the focus back to its original window. Thus, the client wants to prevent the window manager setting the keyboard focus to any of its windows.

Clients using the Globally Active and No Input models should set the input flag to False. Clients using the Passive and Locally Active models must set the input flag to True.

---

Note: If your application requires keyboard input and you neglect to set the input flag to True, you application will not get keyboard events under some window managers, such as olwm.

---

Under version 1 conventions, clients that use the Locally Active or Globally Active focus models must participate in one of the WM_PROTOCOLS called WM_TAKE_FOCUS, as described in “Window Manager Protocols - WM_PROTOCOLS”

Initial State Field

The initial_state member of XWMHints indicates to the window manager whether the application prefers to start off in iconified or normal state. initial_state specifies the state the client prefers to be in at the time the top-level window is mapped. The window manager does not reread this property so it is not useful for changing state after a window has been mapped. How to request a change of state is described in “Changing Application State” The initial_state flags are shown in Table 12-4.

Table 12-4. Initial State Hint Flags

Flag	Description
IconicState	Client wants to be iconified.
NormalState	Client wants top-level normal window visible.

When setting the initial_state member of XWMHints, you must OR the StateHint constant set into the flags member of XWMHints to indicate that the field is to be set.

Even though there is have no flag for an inactive state, a window manager might implement a concept of inactive state in which an infrequently used client's window would be represented as a string in a menu. But this state is invisible to the client, which would see itself merely as being in IconicState.

Icon Hints Fields

Under X, icons are by convention managed by the window manager, except that the client is allowed to provide a variety of pixmap patterns, names, and an icon window among which the window manager may pick and choose. The four members of XWMHints shown in Example 12-3 provide this information to the window manager.

Example 12-3. The icon hints elements of the XWMHints structure

typedef struct { . . Pixmap icon_pixmap; /* Pixmap for icon */ Pixmap icon_mask; /* Pixmap to be used as mask for * icon_pixmap */ Window icon_window; /* Window to be used as icon */ int icon_x, icon_y; /* Initial position of icon */ . . } XWMHints;

icon_pixmap is the pattern to be used to distinguish the icon from other clients. This pixmap should be:

• One of the sizes specified in the XA_WM_ICON_SIZE property on the root, as described in “XA_WM_ICON_SIZE”

• One bit deep. The window manager will select, through the resource database, suitable background (for the 0 bits) and foreground (for the 1 bits) colors. These resources can, of course, specify different colors for the icons of different clients.

The icon_mask is a one-bit-deep pixmap that determines which pixels in icon_pixmap are drawn on the icon window. This allows for icons that appear to be nonrectangular. Some window managers (including uwm) use the icon pixmap as a background tile for the icon window, a method which does not allow for the use of a mask.

icon_window is a window created but not mapped by the client. Clients that need to know their icon's ID or want to draw more than a simple two-color bitmap on the icon should set this hint. For example, xbiff and xmh change their icon pixmap when mail arrives, and they need to know their icon's ID to do this. Therefore, they must supply an icon window.

The icon_window hint should not be used unless needed. When it is not specified, the window manager creates the icon window itself.

You do not know which of the hints the window manager will honor. With current window managers, you can be confident that if icon_window is set, the window it names will be visible. If not, if icon_pixmap is set, the pixmap it names is visible. Otherwise, the window's XA_WM_ICON_NAME string is visible.

The conventions specify that the window manager must use the specified icon window. Therefore the application can read events from that icon window if desired.

An application that sets an icon_window is responsible for redrawing the window in case of Expose events. One way to set the icon design to be displayed is to set the background pixmap attribute of the icon window. The advantage of this approach is that there is no need to handle Expose events for the icon, because the background is automatically redrawn by the server. The disadvantage is that there is no way to apply a mask to generate a nonrectangular icon.

The icon window:

• Must be an InputOutput child of the root window.

• Should be one of the sizes specified in the XA_WM_ICON_SIZE property on the root (described in “XA_WM_ICON_SIZE”).

• Must use the default visual and default colormap for the screen in question.

• Should not be mapped, unmapped, or configured by the client.

• Should not have the override_redirect window attribute set to True (should be left as the default).

The client must not:

• Select ResizeRedirectMask on the icon.

• Depend on being able to receive input events via their icon windows, although most window managers will allow some subset of key and button events through.

• Manipulate the borders of their icon windows.

To summarize the client procedures regarding icons:

• Use XSetWMIconName() to set a string in XA_WM_ICON_NAME. All clients should do this, since it provides a fallback for window managers whose ideas about icons differ widely from those of the client.

• Set a pixmap into the icon_pixmap member of the XA_WM_HINTS property and possibly another into the icon_mask member. The window manager is expected to display the pixmap masked by the mask. The pixmap should be one of the sizes found in the XA_WM_ICON_SIZE property on the root. Window managers will normally clip or tile pixmaps which do not match XA_WM_ICON_SIZE.

Or:

• Set a window into the icon_window member of the XA_WM_HINTS property. The window manager is expected to use that window instead of creating its own and to map that window whenever the client is in IconicState. In general, the size of the icon window should be one of those specified in XA_WM_ICON_SIZE on the root, if that property exists. Window managers may resize icon windows. If the client supplies an icon window, it is responsible for redrawing it when necessary.

Window Group Field

The window_group member of XWMHints lets the client specify that it has multiple top-level windows which should be iconified together or managed by the window manager as a group. For example, group leaders may have the full set of decorations and other group members a restricted set.

Applications with only one top-level window need not set this hint.

One of the top-level windows is known as the group leader. The window_group member of the hints for each of the other top-level windows should be set to the window ID of the group leader.

The group leader may be a window which exists only for that purpose and may never be mapped. Its window_group member should contain its own ID. The properties of the window group leader are those for the group as a whole (for example, the icon to be shown when the entire group is iconified). Every other top-level window may also have its own hints applicable only to itself.

Transient Window Field

All temporary subwindows of the root, such as pop-up menus and dialog boxes, should use XSetTransientForHint() to set the XA_WM_TRANSIENT_FOR property to the ID of the top-level window of the application that is creating the temporary window. This allows the window manager to process the temporary window accordingly (perhaps by decorating it differently than if it were a separate application). In particular, window managers will present newly mapped transient windows without requiring any user interaction, even if mapping top-level windows normally does require interaction.

It is important not to confuse XA_WM_TRANSIENT_FOR with the override_redirect window attribute. The override_redirect attribute specifies that the window manager does not get the chance to intercept the mapping request and thus no chance at all to decorate the window. This should be done only on the most temporary of windows, such as menus, or on windows that the programmer wants to be mapped without window manager intervention, such as automated demonstration programs. XA_WM_TRANSIENT_FOR should be used when other windows are allowed to be active while the transient window is visible, such as when the pointer is not grabbed while the window is popped up. If other windows must be frozen, use override_redirect and grab the pointer while the window is mapped.

Temporary windows that are popped up frequently should also set the save_under window attribute so that windows beneath the window may not need to redraw themselves quite so often.

To summarize, clients wishing to pop up a window should do one of three things:

• They can create and map another normal top-level window, which will get decorated and managed as a separate client by the window manager. See the discussion of window groups in “Window Group Field”

• If the window will be visible for a relatively short time and deserves a somewhat lighter treatment, they can set the XA_WM_TRANSIENT_FOR property. They can expect less decoration but should set all the normal window manager properties on the window. An example of an appropriate case would be a dialog box.

• If the window will be visible for a very short time and should not be decorated at all, the client can set the override_redirect window attribute. In general, this should be done only if the pointer is grabbed while the window is mapped. The window manager will never interfere with these windows, which should be used with caution. An example of an appropriate use is a pop-up menu.

typedef struct {
   char *res_name;
   char *res_class;
} XClassHint;

A session manager is in charge of starting and stopping applications in a controlled manner, so that a session made up of several running applications can be halted and restarted in its original state. This is useful, for example, when the user wants to log out without having to start from scratch when logging back in.

Note that session managers are rare or nonexistent at the present time. Nonetheless, these conventions should be honored because it is only a matter of time before session managers become available. And the session manager does not necessarily need to be a separate client from the window manager. A window manager may have session-management capabilities.

There are two properties that need setting for the benefit of session managers, WM_COMMAND and WM_CLIENT_MACHINE. These supply the command and arguments needed to invoke an application in its current state and the machine on which it should be run. Together they supply enough information to restart the application. These are described in the following sections.

The client will need to set one or more of the following properties if it uses multiple colormaps, if it takes the keyboard focus, if it has data that must be saved before the session manager kills it, or if it has multiple top-level windows and it would like to survive when the user deletes one of them.

The properties described above are those which the client is responsible for maintaining on its top-level windows. This section describes what the client can do with the properties that the window manager sets to give information to the client. There are currently two such properties. XA_WM_ICON_SIZE stores information about the sizes of icons that the window manager prefers. The application should use this information to create an icon pixmap or window of one of the right sizes.

The other property, WM_STATE, stores the current state (normal, iconic, or withdrawn) of the application. This is mostly for communication between the window manager and session manager but may also be used by some applications.

typedef struct {
   int min_width, min_height;
   int max_width, max_height;
   int width_inc, height_inc;
} XIconSize;

There are functions to set and read text properties that support encodings suitable for non-Western languages.

You will need to convert strings into XTextProperty structures before you can call XSetWMProperties(), XGetWMClientMachine(), XGetWMIconName(), XGetWMName(), XSetWMClientMachine(), XSetWMIconName(), or XSetWMName().

These routines use the XTextProperty structure, which contains enough information to read and write the property in any format (8-bit, 16-bit, or 32-bit). The XTextProperty structure is shown in Example 12-6.

typedef struct {
    unsigned char *value;   /* Property data */
    Atom encoding;          /* Type of property */
    int format;             /* 8, 16, or 32 */
    unsigned long nitems;   /* Number of items in value */
} XTextProperty;

You need to set the fields in two copies of this structure before calling XSetWMProperties(), in order to set the window name and icon name properties, as was done in basicwin in Chapter 3, “Basic Window Program” There are two ways to do this: one is to set the fields directly one at a time, and the other is to use XStringListToTextProperty(). The latter is easier and better, because it does not require hardcoding the format or encoding. See Example 3-9 for a demonstration of how to do this.

Four more routines are provided to manipulate the XTextProperty structure:

The window manager is allowed to change the border width, color, or pattern of an application's top-level window's border (usually to indicate which window has the keyboard focus), so this window must be an InputOutput window. This also means that the application should not try to use the border to indicate any application state.

The client may receive notification that its window has been reparented, moved, resized, raised, or lowered or that its border width has been changed by selecting StructureNotifyMask on its top-level window. It should not respond to these events by trying to change any of these characteristics, however.

Let's look how a typical selection transaction occurs and then go into all the details of how to make it happen. From the user's point of view, it works like this:

The desired result is that the text or graphics should appear in the application in which it was pasted. Now how do two applications actually make this happen?

The application in which the text or graphics is being selected must first of all figure out what information is being selected and be able to convert it into a format that can be transferred to other applications. If the selection is text (usually the selection is a string) and the selected area is highlighted, by having the user drag the pointer over the area, then this application has to become the owner of a selection atom.

There are two built-in selection atoms: XA_PRIMARY and XA_SECONDARY. Unless the client foresees needing two simultaneous selections, it should use XA_PRIMARY. It calls XSetSelectionOwner(), specifying the selection atom, any window that it created (this window is used by other applications to identify the owner), and the time. The time used should be from the event that triggered the bid to own the selection (not CurrentTime) because of race conditions that can otherwise occur. If the client does not already own the selection atom, then this call will generate a SelectionClear event for the old owner, telling it to unhighlight the old selection.

Each client that wants to be able to have a selection pasted into it must set aside a key or button combination to indicate that the user wishes to paste in the current selection. In response to the event that occurs when that key or button combination is pressed, the client calls XConvertSelection(). This call specifies which selection the application wants (XA_PRIMARY until other conventions are established), the property to place the data in, the window on which to set this property, and the time. These arguments are quite clear. But the XConvertSelection() call also specifies a target type that the application wants the data in. You need to understand what happens after the XConvertSelection() call to understand the purpose of the target type property.

The server places all the arguments of the XConvertSelection() call into an XSelectionRequestEvent and sends the event to the selection owner. The owner then tries to convert the selection data into the format specified in the target type property. If the selection owner knows how to convert the data into the requested type, it puts the data in the property specified in the event and returns the atom of this property in the property member of a SelectionNotify event. If the selection owner cannot convert the selection into the requested type, it returns None as the property member in the SelectionNotify event. The owner sends this SelectionNotify event using XSendEvent().

When the requestor receives the SelectionNotify event, it either reads the property if it is set, repeats the request with a different target type if the owner returned None, or gives up on pasting data from that selection owner. It could be that the user is trying to do something like paste graphics into a text-only application.

Now you should understand the selection mechanism in general, so let's look at a more tangible example of how it takes place.

Let's say a text editor is the owner of the selection XA_PRIMARY. The user is editing a C program and debugging the same C program in another window. The user would like to select a line in the source code and instruct the debugger to stop at that same line without having to type in the line number. Perhaps the debugger would have a button labeled “stop at,” which, when pressed, would tell the debugger to request a value for the primary selection. The text editor would allow the user to select text on a line and would be able to convert that selection into a string if it were pasted into another text editor or into a line number if it were pasted into the debugger. Which type the text editor would choose would depend on the target type of the selection request.

Assuming the text editor already uses the selection mechanism to transfer text to other applications, adding the line number capability should be easy. It would simply need to look for a new target type that indicated to it to figure out what line number the selected text is on. It might choose the first line, if more than one line were selected, or simply display an error message telling the user to select a single line.

The debugger application would then make the call shown in Example 12-7.

Display display;
Atom target;
Window debugger_window;
Time time;
Bool only_if_exists;
Atom data_prop;
/* We create atom for data to be put into */
data_prop = XInternAtom(display, "STOP_LINE_NUM",
      only_if_exists = False);
/* Target type atom must have been created by owner */
target_type = XInternAtom(display, "LINE_NUMBER",
      only_if_exists = True);
if (target_type == None) {
   fprintf(stderr, "%s: selection owner did not create \
         LINE_NUMBER atom", argv[0]);
   return(False);
}
XConvertSelection(display, XA_PRIMARY, target_type,
      data_prop, debugger_window, time = triggering_event_time)
/* Wait for a SelectionNotify event and, if the property
 * member is the same as data_prop, the conversion went fine;
 * if the property member is None, the conversion failed */

The server sends all of the above information in a SelectionRequest event to the text editor client (which had previously made itself the owner of the selection with XSetSelectionOwner()).

The text editor stores the data in the property specified in the SelectionRequest event on debugger_window, then sends a SelectionNotify event (using XSendEvent()) to the requesting application. Upon receiving this event, the debugger reads this property and uses its value to place a break point in the C program.

Now that you have seen a more practical application of selections, we'll move on to a more precise description of each step in the selection transfer process.

When the user decides to select something in an application, the application needs to become the selection owner. Being the selection owner means that when any other application requests the value of the selection with XConvertSelection(), the owner gets the resulting XSelectionRequest event. The transfer of selection ownership also makes sure that only one application at a time is attempting to set the properties. The previous application to call XSetSelectionOwner(), if it was another application, receives a SelectionClear event, which indicates to it that it should clear any area it has highlighted.

Note that if the time in the XSetSelectionOwner() request is in the future relative to the server's current time or if it is in the past relative to the last time the selection concerned changed hands, the XSetSelectionOwner() request appears to the client to succeed, but ownership is not actually transferred. To ensure that ownership has been transferred, a client must perform the sequence shown in Example 12-8.

XSetSelectionOwner(display, selection_atom, owner, time);
if (XGetSelectionOwner(display, selection_atom) != owner) {
    /* We didn't get the selection */
}

If XGetSelectionOwner() returns a window ID rather than None, then the selection ownership was successfully transferred.

When a requestor wants the value of a selection, the owner receives a SelectionRequest event. Example 12-9 shows the XSelectionRequestEvent structure.

typedef struct {
   int type;
   unsigned long serial;   /* # of last request processed by
                            * server */
   Bool send_event;        /* True if this came from SendEvent
                            * request */
   Display *display;       /* Display the event was read from */
   Window owner;
   Window requestor;
   Atom selection;
   Atom target;
   Atom property;
   Time time;
} XSelectionRequestEvent;

The owner and the selection members will be the values specified in the XSetSelectionOwner() request, and therefore, the selection owner is interested in them only if it owns more than one selection.

The owner should convert the selection into the type specified by the target member and set the property specified by the property member of the SelectionRequest event. Current conventions hold that all properties used to reply to SelectionRequest events should be placed on the requestor window. If the data comprising the selection cannot be stored on the requestor window (for example, because the server cannot provide sufficient memory), the owner must refuse the selection request as above.

The owner should also send the requestor a SelectionNotify event using XSendEvent() with an event_mask of 0. The members of the SelectionNotify event should be set to the same values received in the SelectionRequest event, except that if the selection could not be converted to the requested type, the property member should be set to None. Example 12-10 shows the XSelectionEvent structure which is used for SelectionNotify events.

typedef struct {
   int type;
   unsigned long serial;   /* # of last request processed by
                            * server */
   Bool send_event;        /* True if this came from SendEvent
                            * request */
   Display *display;       /* Display the event was read from */
   Window requestor;
   Atom selection;
   Atom target;
   Atom property;          /* Atom or None */
   Time time;
} XSelectionEvent;

The selection, target, and property members should be set to the values received in the SelectionRequest event. Setting the property member to None indicates that the conversion requested could not be made.

The data stored in the property must eventually be deleted. According to the current conventions, selection requestors are responsible for deleting the converted properties whose names they receive in SelectionNotify events. Owners are responsible for deleting all other properties involved in communicating selections.

A selection owner may need confirmation that the data comprising the selection has actually been transferred. They should express interest in PropertyNotify events for the requestor window and wait until the property in the SelectionNotify event has been deleted before assuming that the selection data has been transferred.

When some other client becomes the owner of a particular selection, the previous owner receives a SelectionClear event. The XSelectionClearEvent structure is shown in Example 12-11.

typedef struct {
   int type;
   unsigned long serial;   /* # of last request processed by
                            * server */
   Bool send_event;        /* True if from a SendEvent request */
   Display *display;       /* Display the event was read from */
   Window window;
   Atom selection;
   Time time;
} XSelectionClearEvent;

The time member is the time at which the ownership changed hands, and the owner member is the window the new owner specified in its XSetSelectionOwner() request.

If an owner loses ownership while it has a transfer in progress, that is to say before it receives notification that the requestor has received all the data, it must continue to service the ongoing transfer to completion.

To relinquish ownership of a selection voluntarily, a client should execute a XSetSelectionOwner() call for that selection atom, with owner specified as None and time specified as CurrentTime. Alternatively, the client may destroy the window used as the owner argument of the XSetSelectionOwner() call, or it may exit. In both cases, the ownership of the selection involved will revert to None.

A client wishing to obtain the value of a selection in a particular form issues an XConvertSelection() call. The arguments of the call are three atoms, a window, and the time. The first atom is the selection, usually XA_PRIMARY. The second atom is the target type, the type in which the requestor wants the data. The conventions will specify a standard list of target type atoms. The third atom specifies the property that the owner should set to the converted data. The window argument is the window on which the property containing the data is to be set. The time member should be set to the timestamp on the event triggering the request for the selection value. Note that the requestor of a selection does not need to know the owner of the selection or the window it specified in the XSetSelectionOwner() call.

The client that calls XConvertSelection() call will get a SelectionNotify event sent to it from the selection owner. The requestor, selection, time, and target arguments of this event will be the same as those on the XConvertSelection() request.

If the property member is None, the conversion has been refused. This can mean that there is no owner for the selection, that the owner does not support the conversion implied by target, or that the server did not have sufficient space to accommodate the data.

If the property member is not None, then that property will exist on the requestor window. The value of the selection can be retrieved from this property using XGetWindowProperty(). When using XGetWindowProperty() to retrieve the value of a selection, the property argument should be set to the property member in the SelectionNotify event. The type member should be set to AnyPropertyType, because the requestor has no way of knowing beforehand what type the selection owner will use.

The property in the SelectionNotify should be deleted by invoking XGetWindowProperty() with the delete argument set to True. As discussed above, the owner has no way of knowing when the data has been transferred to the requestor unless the property is removed.

Selections can get large, and this poses two problems:

The proposed conventions for dealing with these problems are given in Appendix L, Interclient Communcation Conventions, of Volume Zero (as of the second printing).

A given selection has a type associated with it. Built-in property types that might apply to selections are XA_BITMAP, XA_CARDINAL, XA_INTEGER, XA_PIXMAP, XA_POINT, XA_RECTANGLE, and XA_STRING. Other types that clients could define might be XA_FILE_NAME or XA_PICTURE (a sequence of graphics primitives to reproduce a picture--the Macintosh uses this type of selection to cut and paste graphics into text applications and vice versa).

It is important to observe that defining a new atom consumes resources in the server, and they are not released until the server reinitializes. Thus, it must be a goal to reduce the need for newly minted atoms.

The selection named by XA_PRIMARY is used for all commands which take only a single argument. It is the principal means of communication between clients which use the selection mechanism.

It is suggested that the selection named by XA_SECONDARY be used:

The CLIPBOARD selection can be used to hold deleted data (it has no predefined atom). There is a client called xclipboard that will display the contents of the CLIPBOARD, even if the client where the data was selected has already been killed.

The atom that a requestor supplies as the target argument of XConvertSelection() determines the form of the data supplied. The set of such atoms is extensible, but a generally accepted base set of target atoms is needed. The set specified in the conventions is shown in Appendix L, Interclient Communcation Conventions, of Volume Zero (as of the second printing). However, some types are already predefined properties, and these can safely be used.

Target properties describe types of data. They contain the C language types of the structures that are used for many of the Xlib functions. The predefined target atoms are shown in Table 12-6.

The owner should not translate the selection into some arbitrary fallback target type (such as XA_STRING) and return the fallback target to the requestor in the SelectionNotify event, because this might confuse the requestor. The conversion should simply fail. The requestor then has the option of requesting another type. The requestor can supply the target TARGETS to get a list of target types the owner supports.