diff options
Diffstat (limited to 'specs/CH11.xml')
| -rw-r--r-- | specs/CH11.xml | 5538 |
1 files changed, 5538 insertions, 0 deletions
diff --git a/specs/CH11.xml b/specs/CH11.xml new file mode 100644 index 0000000..92e46dc --- /dev/null +++ b/specs/CH11.xml @@ -0,0 +1,5538 @@ +<chapter id='Utility_Functions'> +<title>Utility Functions</title> +<para> +The Intrinsics provide a number of utility functions that you can use to +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +Determine the number of elements in an array. + </para> + </listitem> + <listitem> + <para> +Translate strings to widget instances. + </para> + </listitem> + <listitem> + <para> +Manage memory usage. + </para> + </listitem> + <listitem> + <para> +Share graphics contexts. + </para> + </listitem> + <listitem> + <para> +Manipulate selections. + </para> + </listitem> + <listitem> + <para> +Merge exposure events into a region. + </para> + </listitem> + <listitem> + <para> +Translate widget coordinates. + </para> + </listitem> + <listitem> + <para> +Locate a widget given a window id. + </para> + </listitem> + <listitem> + <para> +Handle errors. + </para> + </listitem> + <listitem> + <para> +Set the WM_COLORMAP_WINDOWS property. + </para> + </listitem> + <listitem> + <para> +Locate files by name with string substitutions. + </para> + </listitem> + <listitem> + <para> +Register callback functions for external agents. + </para> + </listitem> + <listitem> + <para> +Locate all the displays of an application context. + </para> + </listitem> +</itemizedlist> + +<sect1 id="Determining_the_Number_of_Elements_in_an_Array"> +<title>Determining the Number of Elements in an Array</title> +<para> +To determine the number of elements in a fixed-size array, use +<xref linkend='XtNumber' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtNumber'> +<funcprototype> +<funcdef>Cardinal <function>XtNumber</function></funcdef> + <paramdef>ArrayType <parameter>array</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>array</emphasis> + </term> + <listitem> + <para> +Specifies a fixed-size array of arbitrary type. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtNumber' xrefstyle='select: title'/> +macro returns the number of elements allocated to the array. +</para> +</sect1> + +<sect1 id="Translating_Strings_to_Widget_Instances"> +<title>Translating Strings to Widget Instances</title> +<para> +To translate a widget name to a widget instance, use +<xref linkend='XtNameToWidget' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtNameToWidget'> +<funcprototype> +<funcdef>Widget <function>XtNameToWidget</function></funcdef> + <paramdef>Widget <parameter>reference</parameter></paramdef> + <paramdef>String <parameter>names</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>reference</emphasis> + </term> + <listitem> + <para> +Specifies the widget from which the search is to start. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>names</emphasis> + </term> + <listitem> + <para> +Specifies the partially qualified name of the desired widget. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtNameToWidget' xrefstyle='select: title'/> +function searches for a descendant of the <emphasis remap='I'>reference</emphasis> +widget whose name matches the specified names. The <emphasis remap='I'>names</emphasis> parameter +specifies a simple object name or a series of simple object name +components separated by periods or asterisks. +<xref linkend='XtNameToWidget' xrefstyle='select: title'/> +returns the descendant with the shortest name matching the specification +according to the following rules, where child is either a pop-up child +or a normal child if the widget's class is a subclass of +Composite : +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +Enumerate the object subtree rooted at the reference widget in +breadth-first order, qualifying the name of each object with the +names of all its ancestors up to, but not including, the reference +widget. The ordering between children of a common parent is +not defined. + </para> + </listitem> + <listitem> + <para> +Return the first object in the enumeration that matches the +specified name, where each component of <emphasis remap='I'>names</emphasis> matches exactly the +corresponding component of the qualified object name and asterisk +matches any series of components, including none. + </para> + </listitem> + <listitem> + <para> +If no match is found, return NULL. + </para> + </listitem> +</itemizedlist> +<para> +Since breadth-first traversal is specified, the descendant with the +shortest matching name (i.e., the fewest number of components), if any, +will always be returned. However, since the order of enumeration of +children is undefined and since the Intrinsics do not require that all +children of a widget have unique names, +<xref linkend='XtNameToWidget' xrefstyle='select: title'/> +may return any +child that matches if there are multiple objects in the subtree with +the same name. Consecutive separators (periods or asterisks) +including at least one asterisk are treated as a single asterisk. +Consecutive periods are treated as a single period. +</para> +</sect1> + +<sect1 id="Managing_Memory_Usage"> +<title>Managing Memory Usage</title> +<para> +The Intrinsics memory management functions provide uniform checking for +null pointers and error reporting on memory allocation errors. +These functions are completely compatible with their standard C language +runtime counterparts +<function>malloc</function>, +<function>calloc</function>, +<function>realloc</function>, +and +<function>free</function> +with the following added functionality: +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +<xref linkend='XtMalloc' xrefstyle='select: title'/>, +<xref linkend='XtCalloc' xrefstyle='select: title'/>, +and +<xref linkend='XtRealloc' xrefstyle='select: title'/> +give an error if there is not enough memory. + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtFree' xrefstyle='select: title'/> +simply returns if passed a NULL pointer. + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtRealloc' xrefstyle='select: title'/> +simply allocates new storage if passed a NULL pointer. + </para> + </listitem> +</itemizedlist> +<para> +See the standard C library documentation on +<function>malloc</function>, +<function>calloc</function>, +<function>realloc</function>, +and +<function>free</function> +for more information. +</para> + +<para> +To allocate storage, use +<xref linkend='XtMalloc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtMalloc'> +<funcprototype> +<funcdef>char * <function>XtMalloc</function></funcdef> + <paramdef>Cardinal <parameter>size</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>size</emphasis> + </term> + <listitem> + <para> +Specifies the number of bytes desired. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtMalloc' xrefstyle='select: title'/> +function returns a pointer to a block of storage of at least +the specified <emphasis remap='I'>size</emphasis> bytes. +If there is insufficient memory to allocate the new block, +<xref linkend='XtMalloc' xrefstyle='select: title'/> +calls +<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. +</para> + +<para> +To allocate and initialize an array, use +<xref linkend='XtCalloc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtCalloc'> +<funcprototype> +<funcdef>char * <function>XtCalloc</function></funcdef> + <paramdef>Cardinal <parameter>num</parameter></paramdef> + <paramdef>Cardinal <parameter>size</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>num</emphasis> + </term> + <listitem> + <para> +Specifies the number of array elements to allocate. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>size</emphasis> + </term> + <listitem> + <para> +Specifies the size of each array element in bytes. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtCalloc' xrefstyle='select: title'/> +function allocates space for the specified number of array elements +of the specified size and initializes the space to zero. +If there is insufficient memory to allocate the new block, +<xref linkend='XtCalloc' xrefstyle='select: title'/> +calls +<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. +<xref linkend='XtCalloc' xrefstyle='select: title'/> +returns the address of the allocated storage. +</para> + +<para> +To change the size of an allocated block of storage, use +<xref linkend='XtRealloc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtRealloc'> +<funcprototype> +<funcdef>char *<function>XtRealloc</function></funcdef> + <paramdef>char *<parameter>ptr</parameter></paramdef> + <paramdef>Cardinal <parameter>num</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ptr</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the old storage allocated with +<xref linkend='XtMalloc' xrefstyle='select: title'/>, +<xref linkend='XtCalloc' xrefstyle='select: title'/>, +or +<xref linkend='XtRealloc' xrefstyle='select: title'/>, +or NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num</emphasis> + </term> + <listitem> + <para> +Specifies number of bytes desired in new storage. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtRealloc' xrefstyle='select: title'/> +function changes the size of a block of storage, possibly moving it. +Then it copies the old contents (or as much as will fit) into the new block +and frees the old block. +If there is insufficient memory to allocate the new block, +<xref linkend='XtRealloc' xrefstyle='select: title'/> +calls +<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. +If <emphasis remap='I'>ptr</emphasis> is NULL, +<xref linkend='XtRealloc' xrefstyle='select: title'/> +simply calls +<xref linkend='XtMalloc' xrefstyle='select: title'/>. +<xref linkend='XtRealloc' xrefstyle='select: title'/> +then returns the address of the new block. +</para> + +<para> +To free an allocated block of storage, use +<xref linkend='XtFree' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtFree'> +<funcprototype> +<funcdef>void <function>XtFree</function></funcdef> + <paramdef>char *<parameter>ptr</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>ptr</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to a block of storage allocated with +<xref linkend='XtMalloc' xrefstyle='select: title'/>, +<xref linkend='XtCalloc' xrefstyle='select: title'/>, +or +<xref linkend='XtRealloc' xrefstyle='select: title'/>, +or NULL. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtFree' xrefstyle='select: title'/> +function returns storage, allowing it to be reused. +If <emphasis remap='I'>ptr</emphasis> is NULL, +<xref linkend='XtFree' xrefstyle='select: title'/> +returns immediately. +</para> + +<para> +To allocate storage for a new instance of a type, use +<xref linkend='XtNew' xrefstyle='select: title'/>. +</para> + + +<funcsynopsis id='XtNew'> +<funcprototype> +<funcdef>type <function>XtNew</function></funcdef> + <paramdef>type <parameter>t</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>type</emphasis> + </term> + <listitem> + <para> +Specifies a previously declared type. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtNew' xrefstyle='select: title'/> +returns a pointer to the allocated storage. +If there is insufficient memory to allocate the new block, +<xref linkend='XtNew' xrefstyle='select: title'/> +calls +<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. +<xref linkend='XtNew' xrefstyle='select: title'/> +is a convenience macro that calls +<xref linkend='XtMalloc' xrefstyle='select: title'/> +with the following arguments specified: +</para> +<literallayout > +((type *) XtMalloc((unsigned) sizeof(type))) +</literallayout> +<para> +The storage allocated by +<xref linkend='XtNew' xrefstyle='select: title'/> +should be freed using +<xref linkend='XtFree' xrefstyle='select: title'/>. +</para> + +<para> +To copy an instance of a string, use +<xref linkend='XtNewString' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtNewString'> +<funcprototype> +<funcdef>String <function>XtNewString</function></funcdef> + <paramdef>String <parameter>string</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>string</emphasis> + </term> + <listitem> + <para> +Specifies a previously declared string. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtNewString' xrefstyle='select: title'/> +returns a pointer to the allocated storage. +If there is insufficient memory to allocate the new block, +<xref linkend='XtNewString' xrefstyle='select: title'/> +calls +<xref linkend='XtErrorMsg' xrefstyle='select: title'/>. +<xref linkend='XtNewString' xrefstyle='select: title'/> +is a convenience macro that calls +<xref linkend='XtMalloc' xrefstyle='select: title'/> +with the following arguments specified: +</para> +<literallayout > +(strcpy(XtMalloc((unsigned)strlen(str) + 1), str)) +</literallayout> +<para> +The storage allocated by +<xref linkend='XtNewString' xrefstyle='select: title'/> +should be freed using +<xref linkend='XtFree' xrefstyle='select: title'/>. +</para> +</sect1> + +<sect1 id="Sharing_Graphics_Contexts"> +<title>Sharing Graphics Contexts</title> +<para> +The Intrinsics provide a mechanism whereby cooperating objects can share a +graphics context (GC), thereby reducing both the number of GCs +created and the total number of server calls in any given application. +The mechanism is a simple caching scheme +and allows for clients to declare both modifiable and nonmodifiable +fields of the shared GCs. +</para> + +<para> +To obtain a shareable GC with modifiable fields, use +<xref linkend='XtAllocateGC' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAllocateGC'> +<funcprototype> +<funcdef>GC <function>XtAllocateGC</function></funcdef> + <paramdef>Widget <parameter>object</parameter></paramdef> + <paramdef>Cardinal <parameter>depth</parameter></paramdef> + <paramdef>XtGCMask <parameter>value_mask</parameter></paramdef> + <paramdef>XGCValues *<parameter>values</parameter></paramdef> + <paramdef>XtGCMask <parameter>dynamic_mask</parameter></paramdef> + <paramdef>XtGCMask <parameter>unused_mask</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>object</emphasis> + </term> + <listitem> + <para> +Specifies an object, giving the screen for which the +returned GC is valid. Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>depth</emphasis> + </term> + <listitem> + <para> +Specifies the depth for which the returned GC is valid, or 0. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value_mask</emphasis> + </term> + <listitem> + <para> +Specifies fields of the GC that are initialized from <emphasis remap='I'>values</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>values</emphasis> + </term> + <listitem> + <para> +Specifies the values for the initialized fields. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dynamic_mask</emphasis> + </term> + <listitem> + <para> +Specifies fields of the GC that will be modified by the caller. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>unused_mask</emphasis> + </term> + <listitem> + <para> +Specifies fields of the GC that will not be needed by the caller. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtAllocateGC' xrefstyle='select: title'/> +function returns a shareable GC that may be +modified by the client. The <emphasis remap='I'>screen</emphasis> field of the specified +widget or of the nearest widget ancestor of the specified +object and the specified <emphasis remap='I'>depth</emphasis> argument supply +the root and drawable depths for which the GC is to be +valid. If <emphasis remap='I'>depth</emphasis> is zero, the depth is taken from the +<emphasis remap='I'>depth</emphasis> field of the specified widget or of the nearest +widget ancestor of the specified object. +</para> + +<para> +The <emphasis remap='I'>value_mask</emphasis> argument specifies fields of the GC +that are initialized with the respective member of the +<emphasis remap='I'>values</emphasis> structure. The <emphasis remap='I'>dynamic_mask</emphasis> argument specifies fields +that the caller intends to modify during program execution. +The caller must ensure that the corresponding GC field is set +prior to each use of the GC. The <emphasis remap='I'>unused_mask</emphasis> argument +specifies fields of the GC that are of no interest to the +caller. The caller may make no assumptions about the contents +of any fields specified in <emphasis remap='I'>unused_mask</emphasis>. The caller may assume +that at all times all fields not specified in either +<emphasis remap='I'>dynamic_mask</emphasis> or <emphasis remap='I'>unused_mask</emphasis> have their default value if not +specified in <emphasis remap='I'>value_mask</emphasis> or the value specified by <emphasis remap='I'>values</emphasis>. +If a field is specified in both <emphasis remap='I'>value_mask</emphasis> and <emphasis remap='I'>dynamic_mask</emphasis>, +the effect is as if it were specified only in <emphasis remap='I'>dynamic_mask</emphasis> +and then immediately set to the value in <emphasis remap='I'>values</emphasis>. If a field +is set in <emphasis remap='I'>unused_mask</emphasis> and also in either <emphasis remap='I'>value_mask</emphasis> or +<emphasis remap='I'>dynamic_mask</emphasis>, the specification in <emphasis remap='I'>unused_mask</emphasis> is ignored. +</para> + +<para> +<xref linkend='XtAllocateGC' xrefstyle='select: title'/> +tries to minimize the number of unique GCs +created by comparing the arguments with those of previous +calls and returning an existing GC when there are no +conflicts. +<xref linkend='XtAllocateGC' xrefstyle='select: title'/> +may modify and return an existing GC if it was allocated with a +nonzero <emphasis remap='I'>unused_mask</emphasis>. +</para> + +<para> +To obtain a shareable GC with no modifiable fields, use +<xref linkend='XtGetGC' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtGetGC'> +<funcprototype> +<funcdef>GC <function>XtGetGC</function></funcdef> + <paramdef>Widget <parameter>object</parameter></paramdef> + <paramdef>XtGCMask <parameter>value_mask</parameter></paramdef> + <paramdef>XGCValues *<parameter>values</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>object</emphasis> + </term> + <listitem> + <para> +Specifies an object, giving the screen and depth for which the +returned GC is valid. Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value_mask</emphasis> + </term> + <listitem> + <para> +Specifies which fields of the <emphasis remap='I'>values</emphasis> structure are specified. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>values</emphasis> + </term> + <listitem> + <para> +Specifies the actual values for this GC. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtGetGC' xrefstyle='select: title'/> +function returns a shareable, read-only GC. +The parameters to this function are the same as those for +<function>XCreateGC</function> +except that an Object is passed instead of a Display. +<xref linkend='XtGetGC' xrefstyle='select: title'/> +is equivalent to +<xref linkend='XtAllocateGC' xrefstyle='select: title'/> +with <emphasis remap='I'>depth</emphasis>, <emphasis remap='I'>dynamic_mask</emphasis>, and <emphasis remap='I'>unused_mask</emphasis> all zero. +</para> + +<para> +<xref linkend='XtGetGC' xrefstyle='select: title'/> +shares only GCs in which all values in the GC returned by +<function>XCreateGC</function> +are the same. +In particular, it does not use the <emphasis remap='I'>value_mask</emphasis> provided to +determine which fields of the GC a widget considers relevant. +The <emphasis remap='I'>value_mask</emphasis> is used only to tell the server which fields should be +filled in from <emphasis remap='I'>values</emphasis> and which it should fill in with default values. +</para> + +<para> +To deallocate a shared GC when it is no longer needed, use +<xref linkend='XtReleaseGC' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtReleaseGC'> +<funcprototype> +<funcdef>void <function>XtReleaseGC</function></funcdef> + <paramdef>Widget <parameter>object</parameter></paramdef> + <paramdef>GC <parameter>gc</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>object</emphasis> + </term> + <listitem> + <para> +Specifies any object on the Display for which the GC was created. Must be of class Object or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>gc</emphasis> + </term> + <listitem> + <para> +Specifies the shared GC obtained with either +<xref linkend='XtAllocateGC' xrefstyle='select: title'/> +or +<xref linkend='XtGetGC' xrefstyle='select: title'/>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +References to shareable GCs are counted and a free request is generated to the +server when the last user of a given GC releases it. +</para> +</sect1> + +<sect1 id="Managing_Selections"> +<title>Managing Selections</title> +<para> +Arbitrary widgets in multiple applications can communicate +with each other by means of the Intrinsics global selection mechanism, +which conforms to the specifications in the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis>. +The Intrinsics supply functions for providing and receiving selection data in +one logical piece (atomic transfers) +or in smaller logical segments (incremental transfers). +</para> + +<para> +The incremental interface is provided for a selection owner or +selection requestor that cannot or prefers not to pass the selection +value to and from the Intrinsics in a single call. For instance, +either an application that is running on a machine with limited memory +may not be able to store the entire selection value in memory or a +selection owner may already have the selection value available in +discrete chunks, and it would be more efficient not to have to +allocate additional storage to copy the pieces contiguously. Any +owner or requestor that prefers to deal with the selection value in +segments can use the incremental interfaces to do so. +The transfer between the selection owner or requestor and the Intrinsics is not +required to match the underlying +transport protocol between the application and the X server; +the Intrinsics will break too large a selection +into smaller pieces for transport if necessary +and will coalesce a selection transmitted incrementally if the value +was requested atomically. +</para> + +<sect2 id='Setting_and_Getting_the_Selection_Timeout_Value'> +<title>Setting and Getting the Selection Timeout Value</title> +<para> +To set the Intrinsics selection timeout, use +<xref linkend='XtAppSetSelectionTimeout' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppSetSelectionTimeout'> +<funcprototype> +<funcdef>void <function>XtAppSetSelectionTimeout</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>unsigned long <parameter>timeout</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>timeout</emphasis> + </term> + <listitem> + <para> +Specifies the selection timeout in milliseconds. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +To get the current selection timeout value, use +<xref linkend='XtAppGetSelectionTimeout' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppGetSelectionTimeout'> +<funcprototype> +<funcdef>unsigned long <function>XtAppGetSelectionTimeout</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtAppGetSelectionTimeout' xrefstyle='select: title'/> +function returns the current selection timeout value in milliseconds. +The selection timeout is the time within which the two communicating +applications must respond to one another. +The initial timeout value is set by the +selectionTimeout +application resource as retrieved by +<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>. +If +selectionTimeout +is not specified, +the default is five seconds. +</para> +</sect2> + +<sect2 id="Using_Atomic_Transfers"> +<title>Using Atomic Transfers</title> +<para> +When using atomic transfers, the owner will completely +process one selection request at a time. +The owner may consider each request individually, +since there is no possibility for overlap +between evaluation of two requests. +</para> + +<sect3 id="Atomic_Transfer_Procedures"> +<title>Atomic Transfer Procedures</title> +<para> +The following procedures are used by the selection owner when +providing selection data in a single unit. +</para> + +<para> +The procedure pointer specified by the owner to supply the selection +data to the Intrinsics is of type +<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtConvertSelectionProc'> +<funcprototype> +<funcdef>typedef Boolean <function>(*XtConvertSelectionProc)</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom *<parameter>selection</parameter></paramdef> + <paramdef>Atom *<parameter>target</parameter></paramdef> + <paramdef>Atom *<parameter>type_return</parameter></paramdef> + <paramdef>XtPointer *<parameter>value_return</parameter></paramdef> + <paramdef>unsigned long *<parameter>length_return</parameter></paramdef> + <paramdef>int *<parameter>format_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that currently owns this selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the atom naming the selection requested +(for example, +<function>XA_PRIMARY</function> +or +<function>XA_SECONDARY ).</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>target</emphasis> + </term> + <listitem> + <para> +Specifies the target type of the selection that has been requested, +which indicates the desired information about the selection +(for example, File Name, Text, Window). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>type_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to an atom into which the property type of the +converted value of the selection is to be stored. +For instance, either File Name or Text might have property type +<function>XA_STRING</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer into which a pointer to the converted value of the +selection is to be stored. +The selection owner is responsible for allocating this storage. +If the selection owner has provided an +<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/> +for the selection, +this storage is owned by the selection owner; +otherwise, it is owned by the Intrinsics selection mechanism, +which frees it by calling +<xref linkend='XtFree' xrefstyle='select: title'/> +when it is done with it. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer into which the number of elements in <emphasis remap='I'>value_return</emphasis>, +each of size indicated by <emphasis remap='I'>format_return</emphasis>, is to be stored. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>format_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer into which the size in bits of the data elements +of the selection value is to be stored. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This procedure is called by the Intrinsics selection mechanism +to get the value of a selection as a given type +from the current selection owner. +It returns +<function>True</function> +if the owner successfully converted the selection to the target type or +<function>False</function> +otherwise. +If the procedure returns +<function>False</function>, +the values of the return arguments are undefined. +Each +<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/> +should respond to target value +<function>TARGETS</function> +by returning a value containing the list of the targets +into which it is +prepared to convert the selection. +The value returned in +<emphasis remap='I'>format_return</emphasis> must be one of 8, 16, or 32 to allow the server to +byte-swap the data if necessary. +</para> + +<para> +This procedure does not need to worry about responding to the +MULTIPLE or the TIMESTAMP target values (see +<xref linkend='Window_Creation_Convenience_Routine' /> +in the <olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink>). +A selection request with +the MULTIPLE target type is transparently transformed into a +series of calls to this procedure, one for each target type, and a +selection request with the TIMESTAMP target value is answered +automatically by the Intrinsics using the time specified in the +call to +<xref linkend='XtOwnSelection' xrefstyle='select: title'/> +or +<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>. +</para> + +<para> +To retrieve the +<function>SelectionRequest</function> +event that triggered the +<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/> +procedure, use +<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtGetSelectionRequest'> +<funcprototype> +<funcdef>XSelectionRequestEvent *<function>XtGetSelectionRequest</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> + <paramdef>XtRequestId <parameter>request_id</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that currently owns this selection. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the selection being processed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>request_id</emphasis> + </term> + <listitem> + <para> +Specifies the requestor id in the case of incremental +selections, or NULL in the case of atomic transfers. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/> +may be called only from within an +<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/> +procedure and returns a pointer to the +<function>SelectionRequest</function> +event that caused the conversion procedure to be invoked. +<emphasis remap='I'>Request_id</emphasis> specifies a unique id for the individual request in the +case that multiple incremental transfers are outstanding. For atomic +transfers, <emphasis remap='I'>request_id</emphasis> must be specified as NULL. If no +<function>SelectionRequest</function> +event is being processed for the specified +<emphasis remap='I'>widget</emphasis>, <emphasis remap='I'>selection</emphasis>, and <emphasis remap='I'>request_id</emphasis>, +<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/> +returns NULL. +</para> + +<para> +The procedure pointer specified by the owner when it desires +notification upon losing ownership is of type +<xref linkend='XtLoseSelectionProc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtLoseSelectionProc'> +<funcprototype> +<funcdef>typedef void <function>(*XtLoseSelectionProc)</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom *<parameter>selection</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that has lost selection ownership. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the atom naming the selection. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This procedure is called by the Intrinsics selection mechanism +to inform the specified widget that it has lost the given selection. +Note that this procedure does not ask the widget to relinquish the +selection ownership; it is merely informative. +</para> + +<para> +The procedure pointer specified by the owner when it desires +notification of receipt of the data or when it manages the storage +containing the data is of type +<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtSelectionDoneProc'> +<funcprototype> +<funcdef>typedef void <function>(*XtSelectionDoneProc)</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom *<parameter>selection</parameter></paramdef> + <paramdef>Atom *<parameter>target</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that owns the converted selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the atom naming the selection that was converted. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>target</emphasis> + </term> + <listitem> + <para> +Specifies the target type to which the conversion was done. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This procedure is called by the Intrinsics selection mechanism +to inform the selection owner that a selection requestor has successfully +retrieved a selection value. +If the selection owner has registered an +<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>, +it should expect it to be called once for each conversion that it performs, +after the converted value has been successfully transferred +to the requestor. +If the selection owner has registered an +<xref linkend='XtSelectionDoneProc' xrefstyle='select: title'/>, +it also owns the storage containing the converted +selection value. +</para> +</sect3> +<sect3 id="Getting_the_Selection_Value"> +<title>Getting the Selection Value</title> +<para> +The procedure pointer specified by the requestor to receive the +selection data from the Intrinsics is of type +<xref linkend='XtSelectionCallbackProc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtSelectionCallbackProc'> +<funcprototype> +<funcdef>typedef void <function>(*XtSelectionCallbackPro)</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> + <paramdef>Atom *<parameter>selection</parameter></paramdef> + <paramdef>Atom *<parameter>type</parameter></paramdef> + <paramdef>XtPointer <parameter>value</parameter></paramdef> + <paramdef>unsigned long *<parameter>length</parameter></paramdef> + <paramdef>int *<parameter>format</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that requested the selection value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies a value passed in by the widget when it requested the +selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the name of the selection that was requested. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>type</emphasis> + </term> + <listitem> + <para> +Specifies the representation type of the selection value (for example, +<function>XA_STRING ).</function> +Note that it is not the target that was requested (which the client +must remember for itself), but the type that +is used to represent the target. +The special symbolic constant +<function>XT_CONVERT_FAIL</function> +is used to indicate that the selection conversion failed because the +selection owner did not respond within the Intrinsics selection timeout +interval. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the selection value. +The requesting client owns this storage and is responsible for freeing it +by calling +<xref linkend='XtFree' xrefstyle='select: title'/> +when it is done with it. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length</emphasis> + </term> + <listitem> + <para> +Specifies the number of elements in <emphasis remap='I'>value</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>format</emphasis> + </term> + <listitem> + <para> +Specifies the size in bits of the data in each element of <emphasis remap='I'>value</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This procedure is called by the Intrinsics selection mechanism to deliver the +requested selection to the requestor. +</para> + +<para> +If the +<function>SelectionNotify</function> +event returns a property of +<function>None</function>, +meaning the conversion has been refused because there is no owner for the +specified selection or the owner cannot convert the selection to the +requested target for any reason, the procedure is called with a value +of NULL and a length of zero. +</para> + +<para> +To obtain the selection value in a single logical unit, use +<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> +or +<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtGetSelectionValue'> +<funcprototype> +<funcdef>void <function>XtGetSelectionValue</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> + <paramdef>Atom <parameter>target</parameter></paramdef> + <paramdef>XtSelectionCallbackProc <parameter>callback</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> + <paramdef>Time <parameter>time</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget making the request. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the particular selection desired; for example, +<function>XA_PRIMARY</function>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>target</emphasis> + </term> + <listitem> + <para> +Specifies the type of information needed about the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>callback</emphasis> + </term> + <listitem> + <para> +Specifies the procedure to be called when the selection value +has been obtained. +Note that this is how the selection value is communicated back to the client. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies additional data to be passed to the specified procedure +when it is called. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the timestamp that indicates when the selection request was +initiated. +This should be the timestamp of the event that triggered this request; +the value +<function>CurrentTime</function> +is not acceptable. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> +function requests the value of the selection converted to +the target type. +The specified callback is called at some time after +<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> +is called, when the selection value is received from the X server. +It may be called before or after +<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> +returns. +For more information about <emphasis remap='I'>selection</emphasis>, +<emphasis remap='I'>target</emphasis>, and +<emphasis remap='I'>time</emphasis>, see +<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>Section 2.6</olink> in the +<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink>. +</para> + +<funcsynopsis id='XtGetSelectionValues'> +<funcprototype> +<funcdef>void <function>XtGetSelectionValues</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> + <paramdef>Atom *<parameter>targets</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>XtSelectionCallbackProc <parameter>callback</parameter></paramdef> + <paramdef>XtPointer *<parameter>client_data</parameter></paramdef> + <paramdef>Time <parameter>time</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget making the request. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the particular selection desired (that is, primary or secondary). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>targets</emphasis> + </term> + <listitem> + <para> +Specifies the types of information needed about the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>count</emphasis> + </term> + <listitem> + <para> +Specifies the length of the <emphasis remap='I'>targets</emphasis> and <emphasis remap='I'>client_data</emphasis> lists. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>callback</emphasis> + </term> + <listitem> + <para> +Specifies the callback procedure +to be called with each selection value obtained. +Note that this is how the selection values are communicated back to the +client. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies a list of additional data values, one for each target type, +that are passed to the callback procedure when it is called for that target. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the timestamp that indicates when the selection request was +initiated. +This should be the timestamp of the event that triggered this request; +the value +<function>CurrentTime</function> +is not acceptable. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/> +function is similar to multiple calls to +<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> +except that it guarantees that no other client can assert ownership +between requests and therefore that all the conversions will refer to +the same selection value. The callback is invoked once for each +target value with the corresponding client data. +For more information about <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and +<emphasis remap='I'>time</emphasis>, see +<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>section 2.6</olink> +in the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis>. +</para> +</sect3> +<sect3 id="Setting_the_Selection_Owner"> +<title>Setting the Selection Owner</title> +<para> +To set the selection owner and indicate that the selection value will +be provided in one piece, use +<xref linkend='XtOwnSelection' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtOwnSelection'> +<funcprototype> +<funcdef>Boolean <function>XtOwnSelection</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> + <paramdef>Time <parameter>time</parameter></paramdef> + <paramdef>XtConvertSelectionProc <parameter>convert_proc</parameter></paramdef> + <paramdef>XtLoseSelectionProc <parameter>lose_selection</parameter></paramdef> + <paramdef>XtSelectionDoneProc <parameter>done_proc</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the name of the selection (for example, +<function>XA_PRIMARY ).</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the timestamp that indicates when the ownership request was +initiated. +This should be the timestamp of the event that triggered ownership; +the value +<function>CurrentTime</function> +is not acceptable. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>convert_proc</emphasis> + </term> + <listitem> + <para> +Specifies the procedure to be called whenever a client requests the +current value of the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>lose_selection</emphasis> + </term> + <listitem> + <para> +Specifies the procedure to be called whenever the widget has +lost selection ownership, or NULL if the owner is not interested in being +called back. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>done_proc</emphasis> + </term> + <listitem> + <para> +Specifies the procedure called +after the requestor has received the selection value, or NULL if the +owner is not +interested in being called back. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtOwnSelection' xrefstyle='select: title'/> +function informs the Intrinsics selection mechanism that a +widget wishes to own a selection. +It returns +<function>True</function> +if the widget successfully becomes the owner and +<function>False</function> +otherwise. +The widget may fail to become the owner if some other widget +has asserted ownership at a time later than this widget. +The widget can lose selection ownership either +because some other widget asserted later ownership of the selection +or because the widget voluntarily gave up ownership of the selection. +The lose_selection procedure is not called +if the widget fails to obtain selection ownership in the first place. +</para> + +<para> +If a done_proc is specified, the client owns the storage allocated +for passing the value to the Intrinsics. If <emphasis remap='I'>done_proc</emphasis> is NULL, +the convert_proc must allocate storage using +<xref linkend='XtMalloc' xrefstyle='select: title'/>, +<xref linkend='XtRealloc' xrefstyle='select: title'/>, +or +<xref linkend='XtCalloc' xrefstyle='select: title'/>, +and the value specified is freed by the +Intrinsics when the transfer is complete. +</para> + +<para> +Usually, a selection owner maintains ownership indefinitely until some +other widget requests ownership, at which time +the Intrinsics selection mechanism informs the previous owner that it +has lost ownership of the selection. +However, in response to some user actions +(for example, when a user deletes the information selected), +the application may wish to explicitly inform the Intrinsics +by using +<xref linkend='XtDisownSelection' xrefstyle='select: title'/> +that it no longer is to be the selection owner. +</para> + +<funcsynopsis id='XtDisownSelection'> +<funcprototype> +<funcdef>void <function>XtDisownSelection</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> + <paramdef>Time <parameter>time</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that wishes to relinquish ownership. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the atom naming the selection being given up. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the timestamp that indicates when the request to +relinquish selection ownership was initiated. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtDisownSelection' xrefstyle='select: title'/> +function informs the Intrinsics selection mechanism that +the specified widget is to lose ownership of the selection. +If the widget does not currently own the selection, either +because it lost the selection +or because it never had the selection to begin with, +<xref linkend='XtDisownSelection' xrefstyle='select: title'/> +does nothing. +</para> + +<para> +After a widget has called +<xref linkend='XtDisownSelection' xrefstyle='select: title'/>, +its convert procedure is not called even if a request arrives later +with a timestamp during the period that this widget owned the selection. +However, its done procedure is called if a conversion that started +before the call to +<xref linkend='XtDisownSelection' xrefstyle='select: title'/> +finishes after the call to +<xref linkend='XtDisownSelection' xrefstyle='select: title'/>. +</para> +</sect3> +</sect2> + +<sect2 id="Using_Incremental_Transfers"> +<title>Using Incremental Transfers</title> +<para> +When using the incremental interface, an owner may have to process +more than one selection request for the same selection, converted to +the same target, at the same time. The incremental functions take a +<emphasis remap='I'>request_id</emphasis> argument, which is an identifier that is guaranteed to be +unique among all incremental requests that are active concurrently. +</para> + +<para> +For example, consider the following: +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +Upon receiving a request for the selection value, the owner sends +the first segment. + </para> + </listitem> + <listitem> + <para> +While waiting to be called to provide the next segment value but +before sending it, the owner receives another request from a +different requestor for the same selection value. + </para> + </listitem> + <listitem> + <para> +To distinguish between the requests, the owner uses the request_id +value. This allows the owner to distinguish between the first +requestor, which is asking for the second segment, and the second +requestor, which is asking for the first segment. + </para> + </listitem> +</itemizedlist> +<sect3 id="Incremental_Transfer_Procedures"> +<title>Incremental Transfer Procedures</title> +<para> +The following procedures are used by selection owners who wish to +provide the selection data in multiple segments. +</para> + +<para> +The procedure pointer specified by the incremental owner to supply the +selection data to the Intrinsics is of type +<xref linkend='XtConvertSelectionIncrProc' xrefstyle='select: title'/>. +</para> +<literallayout > +typedef XtPointer XtRequestId; +</literallayout> + +<funcsynopsis id='XtConvertSelectionIncrProc'> +<funcprototype> +<funcdef>typedef Boolean <function>(*XtConvertSelectionIncrProc)</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom *<parameter>selection</parameter></paramdef> + <paramdef>Atom *<parameter>target</parameter></paramdef> + <paramdef>Atom *<parameter>type_return</parameter></paramdef> + <paramdef>XtPointer *<parameter>value_return</parameter></paramdef> + <paramdef>unsigned long *<parameter>length_return</parameter></paramdef> + <paramdef>int *<parameter>format_return</parameter></paramdef> + <paramdef>unsigned long *<parameter>max_length</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> + <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that currently owns this selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the atom that names the selection requested. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>target</emphasis> + </term> + <listitem> + <para> +Specifies the type of information required about the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>type_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to an atom into which the property +type of the converted value of the selection is to be +stored. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer into which a pointer to the +converted value of the selection is to be stored. +The selection owner is responsible for allocating this storage. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer into which the number of elements +in <emphasis remap='I'>value_return</emphasis>, each of size indicated by +<emphasis remap='I'>format_return</emphasis>, is to be stored. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>format_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer into which the size in bits of the +data elements of the selection value is to be stored so that the +server may byte-swap the data if necessary. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>max_length</emphasis> + </term> + <listitem> + <para> +Specifies the maximum number of bytes which may be +transferred at any one time. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the value passed in by the widget when it +took ownership of the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>request_id</emphasis> + </term> + <listitem> + <para> +Specifies an opaque identification for a specific request. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This procedure is called repeatedly by the Intrinsics selection mechanism to get +the next incremental chunk of data from a selection owner who has +called +<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>. +It must return +<function>True</function> +if the procedure has succeeded in converting the selection data or +<function>False</function> +otherwise. +On the first call with a particular request id, the owner must begin +a new incremental transfer for the requested selection and target. On +subsequent calls with the same request id, the owner may assume that +the previously supplied value is no longer needed by the Intrinsics; +that is, a fixed transfer area may be allocated and returned in <emphasis remap='I'>value_return</emphasis> +for each segment to be transferred. This procedure should store a +non-NULL value in <emphasis remap='I'>value_return</emphasis> and zero in <emphasis remap='I'>length_return</emphasis> to indicate that the +entire selection has been delivered. After returning this final +segment, the request id may be reused by the Intrinsics to begin a +new transfer. +</para> + +<para> +To retrieve the +<function>SelectionRequest</function> +event that triggered the selection conversion procedure, use +<xref linkend='XtGetSelectionRequest' xrefstyle='select: title'/>, +described in Section 11.5.2.1. +</para> + +<para> +The procedure pointer specified by the incremental selection owner +when it desires notification upon no longer having ownership is of +type +<xref linkend='XtLoseSelectionIncrProc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtLoseSelectionIncrProc'> +<funcprototype> +<funcdef>typedef void <function>(*XtLoseSelectionIncrProc)</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom *<parameter>selection</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that has lost the selection ownership. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the atom that names the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the value passed in by the widget when it +took ownership of the selection. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This procedure, which is optional, is called by the Intrinsics to +inform the selection owner that it no longer owns the selection. +</para> + +<para> +The procedure pointer specified by the incremental selection owner +when it desires notification of receipt of the data or when it manages +the storage containing the data is of type +<xref linkend='XtSelectionDoneIncrProc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtSelectionDoneIncrProc'> +<funcprototype> +<funcdef>typedef void <function>(*XtSelectionDoneIncrProc)</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom *<parameter>selection</parameter></paramdef> + <paramdef>Atom *<parameter>target</parameter></paramdef> + <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that owns the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the atom that names the selection being transferred. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>target</emphasis> + </term> + <listitem> + <para> +Specifies the target type to which the conversion was done. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>request_id</emphasis> + </term> + <listitem> + <para> +Specifies an opaque identification for a specific request. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specified the value passed in by the widget when it +took ownership of the selection. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This procedure, which is optional, is called by the Intrinsics after +the requestor has retrieved the final (zero-length) segment of the +incremental transfer to indicate that the entire transfer is complete. +If this procedure is not specified, the Intrinsics will free only the +final value returned by the selection owner using +<xref linkend='XtFree' xrefstyle='select: title'/>. +</para> + +<para> +The procedure pointer specified by the incremental selection owner to +notify it if a transfer should be terminated prematurely is of type +<xref linkend='XtCancelConvertSelectionProc' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtCancelConvertSelectionProc'> +<funcprototype> +<funcdef>typedef void <function>(*XtCancelConvertSelectionProc)</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom *<parameter>selection</parameter></paramdef> + <paramdef>Atom *<parameter>target</parameter></paramdef> + <paramdef>XtRequestId *<parameter>request_id</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that owns the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the atom that names the selection being transferred. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>target</emphasis> + </term> + <listitem> + <para> +Specifies the target type to which the conversion was done. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>request_id</emphasis> + </term> + <listitem> + <para> +Specifies an opaque identification for a specific request. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the value passed in by the widget when it took ownership of +the selection. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +This procedure is called by the Intrinsics when it has been determined +by means of a timeout or other mechanism that any remaining segments +of the selection no longer need to be transferred. Upon receiving +this callback, the selection request is considered complete and the +owner can free the memory and any other resources that have been +allocated for the transfer. +</para> +</sect3> +<sect3 id="Getting_the_Selection_Value_Incrementally"> +<title>Getting the Selection Value Incrementally</title> +<para> +To obtain the value of the selection using incremental transfers, use +<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> +or +<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtGetSelectionValueIncremental'> +<funcprototype> +<funcdef>void <function>XtGetSelectionValueIncremental</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> + <paramdef>Atom <parameter>target</parameter></paramdef> + <paramdef>XtSelectionCallbackProc <parameter>selection_callback</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> + <paramdef>Time <parameter>time</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget making the request. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the particular selection desired. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>target</emphasis> + </term> + <listitem> + <para> +Specifies the type of information needed +about the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection_callback</emphasis> + </term> + <listitem> + <para> +Specifies the callback procedure to be +called to receive each data segment. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies client-specific data to be passed to +the specified callback procedure when it is invoked. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the timestamp that indicates when the +selection request was initiated. This should be the +timestamp of the event that triggered this request; +the value +<function>CurrentTime</function> +is not acceptable. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> +function is similar to +<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> +except that the selection_callback procedure will +be called repeatedly upon delivery of multiple segments of the +selection value. The end of the selection value is indicated when +<emphasis remap='I'>selection_callback</emphasis> is called with a non-NULL value of length zero, +which must still be freed by the client. If the +transfer of the selection is aborted in the middle of a transfer +(for example, because of a timeout), the selection_callback procedure is +called with a type value equal to the symbolic constant +<function>XT_CONVERT_FAIL</function> +so that the requestor can dispose +of the partial selection value it has collected up until that point. +Upon receiving +<function>XT_CONVERT_FAIL</function>, +the requesting client must determine +for itself whether or not a partially completed data transfer is meaningful. +For more information about <emphasis remap='I'>selection</emphasis>, +<emphasis remap='I'>target</emphasis>, and +<emphasis remap='I'>time</emphasis>, see +<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms' /> in the +<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink> +</para> + +<funcsynopsis id='XtGetSelectionValuesIncremental'> +<funcprototype> +<funcdef>void <function>XtGetSelectionValuesIncremental</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> + <paramdef>Atom *<parameter>targets</parameter></paramdef> + <paramdef>int <parameter>count</parameter></paramdef> + <paramdef>XtSelectionCallbackProc <parameter>selection_callback</parameter></paramdef> + <paramdef>XtPointer *<parameter>client_data</parameter></paramdef> + <paramdef>Time <parameter>time</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget making the request. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the particular selection desired. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>targets</emphasis> + </term> + <listitem> + <para> +Specifies the types of information needed about +the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>count</emphasis> + </term> + <listitem> + <para> +Specifies the length of the <emphasis remap='I'>targets</emphasis> and <emphasis remap='I'>client_data</emphasis> lists. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection_callback</emphasis> + </term> + <listitem> + <para> +Specifies the callback procedure to be called +to receive each selection value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies a list of client data (one for each target +type) values that are passed to the callback procedure when +it is invoked for the corresponding target. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the timestamp that indicates when the +selection request was initiated. This should be the +timestamp of the event that triggered this request; +the value +<function>CurrentTime</function> +is not acceptable. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/> +function is similar to +<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> +except that it takes a list of targets and client data. +<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/> +is equivalent to calling +<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> +successively for each <emphasis remap='I'>target/client_data</emphasis> pair except that +<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/> +does guarantee that all the conversions will use the same selection +value because the ownership of the selection cannot change in the +middle of the list, as would be possible when calling +<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> +repeatedly. +For more information about <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and +<emphasis remap='I'>time</emphasis>, see +<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>Section 2.6</olink> in the +<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink> +</para> +</sect3> +<sect3 id="Setting_the_Selection_Owner_for_Incremental_Transfers"> +<title>Setting the Selection Owner for Incremental Transfers</title> +<para> +To set the selection owner when using incremental transfers, use +<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtOwnSelectionIncremental'> +<funcprototype> +<funcdef>Boolean <function>XtOwnSelectionIncremental</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> + <paramdef>Time <parameter>time</parameter></paramdef> + <paramdef>XtConvertSelectionIncrProc <parameter>convert_callback</parameter></paramdef> + <paramdef>XtLoseSelectionIncrProc <parameter>lose_callback</parameter></paramdef> + <paramdef>XtSelectionDoneIncrProc <parameter>done_callback</parameter></paramdef> + <paramdef>XtCancelConvertSelectionProc <parameter>cancel_callback</parameter></paramdef> + <paramdef>XtPointer <parameter>client_data</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the atom that names the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the timestamp that indicates when the +selection ownership request was initiated. This should be +the timestamp of the event that triggered ownership; the value +<function>CurrentTime</function> +is not acceptable. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>convert_callback</emphasis> + </term> + <listitem> + <para> +Specifies the procedure to be called whenever +the current value of the selection is requested. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>lose_callback</emphasis> + </term> + <listitem> + <para> +Specifies the procedure to be called whenever +the widget has lost selection ownership, or NULL if the +owner is not interested in being notified. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>done_callback</emphasis> + </term> + <listitem> + <para> +Specifies the procedure called after the +requestor has received the entire selection, or NULL if +the owner is not interested in being notified. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>cancel_callback</emphasis> + </term> + <listitem> + <para> +Specifies the callback procedure to be called +when a selection request aborts because a timeout expires, +or NULL if the owner is not interested in being notified. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>client_data</emphasis> + </term> + <listitem> + <para> +Specifies the argument to be passed to each of +the callback procedures when they are called. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/> +procedure informs the Intrinsics +incremental selection mechanism that the specified widget wishes to +own the selection. It returns +<function>True</function> +if the specified widget successfully becomes the selection owner or +<function>False</function> +otherwise. +For more information about <emphasis remap='I'>selection</emphasis>, <emphasis remap='I'>target</emphasis>, and +<emphasis remap='I'>time</emphasis>, see +<olink targetdoc='icccm' targetptr='Use_of_Selection_Atoms'>Section 2.6</olink> in the +<olink targetdoc='icccm' targetptr='icccm'>Inter-Client Communication Conventions Manual.</olink> +</para> + +<para> +If a done_callback procedure is specified, the client owns the storage allocated +for passing the value to the Intrinsics. If <emphasis remap='I'>done_callback</emphasis> is NULL, +the convert_callback procedure must allocate storage using +<xref linkend='XtMalloc' xrefstyle='select: title'/>, +<xref linkend='XtRealloc' xrefstyle='select: title'/>, +or +<xref linkend='XtCalloc' xrefstyle='select: title'/>, +and the final value specified is freed by the +Intrinsics when the transfer is complete. After a selection transfer +has started, only one of the done_callback or cancel_callback +procedures is invoked to indicate completion of the transfer. +</para> + +<para> +The lose_callback procedure does not indicate completion of any in-progress +transfers; it is invoked at the time a +<function>SelectionClear</function> +event is dispatched regardless of any active transfers, which are still +expected to continue. +</para> + +<para> +A widget that becomes the selection owner using +<xref linkend='XtOwnSelectionIncremental' xrefstyle='select: title'/> +may use +<xref linkend='XtDisownSelection' xrefstyle='select: title'/> +to relinquish selection ownership. +</para> +</sect3> +</sect2> + +<sect2 id="Setting_and_Retrieving_Selection_Target_Parameters"> +<title>Setting and Retrieving Selection Target Parameters</title> +<para> +To specify target parameters for a selection request with a single target, +use +<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtSetSelectionParameters'> +<funcprototype> +<funcdef>void <function>XtSetSelectionParameters</function></funcdef> + <paramdef>Widget <parameter>requestor</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> + <paramdef>Atom <parameter>type</parameter></paramdef> + <paramdef>XtPointer <parameter>value</parameter></paramdef> + <paramdef>unsigned long <parameter>length</parameter></paramdef> + <paramdef>int <parameter>format</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>requestor</emphasis> + </term> + <listitem> + <para> +Specifies the widget making the request. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the atom that names the selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>type</emphasis> + </term> + <listitem> + <para> +Specifies the type of the property in which the parameters are passed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the parameters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length</emphasis> + </term> + <listitem> + <para> +Specifies the number of elements containing data in <emphasis remap='I'>value</emphasis>, +each element of a size indicated by <emphasis remap='I'>format</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>format</emphasis> + </term> + <listitem> + <para> +Specifies the size in bits of the data in the elements of <emphasis remap='I'>value</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The specified parameters are copied and stored in a new property +of the specified type and format on the requestor's window. To initiate +a selection request with a target and these parameters, a subsequent +call to +<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> +or to +<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> +specifying the same requestor widget and selection atom will generate a +<function>ConvertSelection</function> +request referring to the property containing the parameters. If +<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/> +is called more than once with the same widget and selection without +a call to specify a request, the most recently specified parameters +are used in the subsequent request. +</para> + +<para> +The possible values of <emphasis remap='I'>format</emphasis> are 8, 16, or 32. If the format is 8, +the elements of <emphasis remap='I'>value</emphasis> are assumed to be sizeof(char); +if 16, sizeof(short); if 32, sizeof(long). +</para> + +<para> +To generate a MULTIPLE +target request with parameters for any of the multiple targets of the +selection request, precede individual calls to +<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/> +and +<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> +with corresponding individual calls to +<xref linkend='XtSetSelectionParameters' xrefstyle='select: title'/>, +and enclose these all within +<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/> +and +<function>XtSendSelectionRequest.</function> +<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/> +and +<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/> +cannot be used to make selection requests with parameterized targets. +</para> + +<para> +To retrieve any target parameters needed to perform a selection conversion, +the selection owner calls +<xref linkend='XtGetSelectionParameters' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtGetSelectionParameters'> +<funcprototype> +<funcdef>void <function>XtGetSelectionParameters</function></funcdef> + <paramdef>Widget <parameter>owner</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> + <paramdef>XtRequestId <parameter>request_id</parameter></paramdef> + <paramdef>Atom *<parameter>type_return</parameter></paramdef> + <paramdef>XtPointer *<parameter>value_return</parameter></paramdef> + <paramdef>unsigned long *<parameter>length_return</parameter></paramdef> + <paramdef>int *<parameter>format_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>owner</emphasis> + </term> + <listitem> + <para> +Specifies the widget that owns the specified selection. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the selection being processed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>request_id</emphasis> + </term> + <listitem> + <para> +Specifies the requestor id in the case of incremental selections, +or NULL in the case of atomic transfers. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>type_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to an atom in which the property type +of the parameters is stored. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer into which a pointer to the parameters is to be stored. +A NULL is stored if no parameters accompany the request. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>length_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer into which the number of data elements +in <emphasis remap='I'>value_return</emphasis> of size indicated by <emphasis remap='I'>format_return</emphasis> are stored. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>format_return</emphasis> + </term> + <listitem> + <para> +Specifies a pointer into which the size in bits of the parameter data +in the elements of <emphasis remap='I'>value</emphasis> is stored. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtGetSelectionParameters' xrefstyle='select: title'/> +may be called only from within an +<xref linkend='XtConvertSelectionProc' xrefstyle='select: title'/> +or from within the first call to an +<xref linkend='XtConvertSelectionIncrProc' xrefstyle='select: title'/> +with a new request_id. +</para> + +<para> +It is the responsibility of the caller to free the returned parameters using +<xref linkend='XtFree' xrefstyle='select: title'/> +when the parameters are no longer needed. +</para> +</sect2> + +<sect2 id="Generating_MULTIPLE_Requests"> +<title>Generating MULTIPLE Requests</title> +<para> +To have the Intrinsics bundle multiple calls to make selection requests into +a single request using a <emphasis role='strong'>MULTIPLE</emphasis> target, use +<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/> +and +<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtCreateSelectionRequest'> +<funcprototype> +<funcdef>void <function>XtCreateSelectionRequest</function></funcdef> + <paramdef>Widget <parameter>requestor</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>requestor</emphasis> + </term> + <listitem> + <para> +Specifies the widget making the request. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the particular selection desired. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +When +<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/> +is called, subsequent calls to +<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>, +<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>, +<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>, +and +<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/>, +with the requestor and selection as specified to +<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>, +are bundled into a single selection request with +multiple targets. The request is made by calling +<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtSendSelectionRequest'> +<funcprototype> +<funcdef>void <function>XtSendSelectionRequest</function></funcdef> + <paramdef>Widget <parameter>requestor</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> + <paramdef>Time <parameter>time</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>requestor</emphasis> + </term> + <listitem> + <para> +Specifies the widget making the request. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the particular selection desired. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the timestamp that indicates when the selection request was +initiated. The value +<function>CurrentTime</function> +is not acceptable. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +When +<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/> +is called with a value of <emphasis remap='I'>requestor</emphasis> and <emphasis remap='I'>selection</emphasis> matching +a previous call to +<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/>, +a selection request is sent to the selection owner. +If a single target request is queued, that request is made. +If multiple targets are queued, they are bundled into a single request +with a target of MULTIPLE using the specified timestamp. +As the values are returned, the callbacks specified in +<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>, +<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>, +<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>, +and +<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/> +are invoked. +</para> + +<para> +Multi-threaded applications should lock the application context before +calling +<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/> +and release the lock after calling +<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/> +to ensure that the thread assembling the request is safe from interference +by another thread assembling a different request naming the same widget +and selection. +</para> + +<para> +To relinquish the composition of a MULTIPLE request without sending it, use +<xref linkend='XtCancelSelectionRequest' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtCancelSelectionRequest'> +<funcprototype> +<funcdef>void <function>XtCancelSelectionRequest</function></funcdef> + <paramdef>Widget <parameter>requestor</parameter></paramdef> + <paramdef>Atom <parameter>selection</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>requestor</emphasis> + </term> + <listitem> + <para> +Specifies the widget making the request. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>selection</emphasis> + </term> + <listitem> + <para> +Specifies the particular selection desired. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +When +<xref linkend='XtCancelSelectionRequest' xrefstyle='select: title'/> +is called, any requests queued since the last call to +<xref linkend='XtCreateSelectionRequest' xrefstyle='select: title'/> +for the same widget and selection are discarded +and any resources reserved are released. +A subsequent call to +<xref linkend='XtSendSelectionRequest' xrefstyle='select: title'/> +will not result in any request being made. +Subsequent calls to +<xref linkend='XtGetSelectionValue' xrefstyle='select: title'/>, +<xref linkend='XtGetSelectionValues' xrefstyle='select: title'/>, +<xref linkend='XtGetSelectionValueIncremental' xrefstyle='select: title'/>, +or +<xref linkend='XtGetSelectionValuesIncremental' xrefstyle='select: title'/> +will not be deferred. +</para> +</sect2> + +<sect2 id="Auxiliary_Selection_Properties"> +<title>Auxiliary Selection Properties</title> +<para> +Certain uses of parameterized selections require clients to name +other window properties within a selection parameter. To permit +reuse of temporary property names in these circumstances and +thereby reduce the number of unique atoms created in the server, +the Intrinsics provides two interfaces for acquiring temporary property names. +</para> + +<para> +To acquire a temporary property name atom for use in a selection +request, the client may call +<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtReservePropertyAtom'> +<funcprototype> +<funcdef>Atom <function>XtReservePropertyAtom</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget making a selection request. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/> +returns an atom that may be used as a property name during selection +requests involving the specified widget. +As long as the atom remains reserved, it is unique with respect to all +other reserved atoms for the widget. +</para> + +<para> +To return a temporary property name atom for reuse and to delete +the property named by that atom, use +<xref linkend='XtReleasePropertyAtom' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtReleasePropertyAtom'> +<funcprototype> +<funcdef>void <function>XtReleasePropertyAtom</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Atom <parameter>atom</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget used to reserve the property name atom. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>atom</emphasis> + </term> + <listitem> + <para> +Specifies the property name atom returned by +<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/> +that is to be released for reuse. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtReleasePropertyAtom' xrefstyle='select: title'/> +marks the specified property name atom as +no longer in use and ensures that any property having that name +on the specified widget's window is deleted. If <emphasis remap='I'>atom</emphasis> does not +specify a value returned by +<xref linkend='XtReservePropertyAtom' xrefstyle='select: title'/> +for the specified widget, the results are undefined. +</para> +</sect2> + +<sect2 id="Retrieving_the_Most_Recent_Timestamp"> +<title>Retrieving the Most Recent Timestamp</title> +<para> +To retrieve the timestamp from the most recent call to +<xref linkend='XtDispatchEvent' xrefstyle='select: title'/> +that contained a timestamp, use +<xref linkend='XtLastTimestampProcessed' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtLastTimestampProcessed'> +<funcprototype> +<funcdef>Time <function>XtLastTimestampProcessed</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies an open display connection. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If no +<function>KeyPress</function>, +<function>KeyRelease</function>, +<function>ButtonPress</function>, +<function>ButtonRelease</function>, +<function>MotionNotify</function>, +<function>EnterNotify</function>, +<function>LeaveNotify</function>, +<function>PropertyNotify</function>, +or +<function>SelectionClear</function> +event has yet been passed to +<xref linkend='XtDispatchEvent' xrefstyle='select: title'/> +for the specified display, +<xref linkend='XtLastTimestampProcessed' xrefstyle='select: title'/> +returns zero. +</para> +</sect2> + +<sect2 id="Retrieving_the_Most_Recent_Event"> +<title>Retrieving the Most Recent Event</title> +<para> +To retrieve the event from the most recent call to +<xref linkend='XtDispatchEvent' xrefstyle='select: title'/> +for a specific display, use +<xref linkend='XtLastEventProcessed' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtLastEventProcessed'> +<funcprototype> +<funcdef>XEvent *<function>XtLastEventProcessed</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the display connection from which to retrieve the event. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +Returns the last event passed to +<xref linkend='XtDispatchEvent' xrefstyle='select: title'/> +for the specified display. Returns NULL if there is no such event. +The client must not modify the contents of the returned event. +</para> +</sect2> +</sect1> + +<sect1 id="Merging_Exposure_Events_into_a_Region"> +<title>Merging Exposure Events into a Region</title> +<para> +The Intrinsics provide an +<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/> +utility function that merges +<function>Expose</function> +and +<function>GraphicsExpose</function> +events into a region for clients to process at once +rather than processing individual rectangles. +For further information about regions, +see <olink targetdoc='libX11' targetptr='Manipulating_Regions' /> +in <olink targetdoc='libX11' targetptr='libX11'> +Xlib — C Language X Interface.</olink>. +</para> + +<para> +To merge +<function>Expose</function> +and +<function>GraphicsExpose</function> +events into a region, use +<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAddExposureToRegion'> +<funcprototype> +<funcdef>void <function>XtAddExposureToRegion</function></funcdef> + <paramdef>XEvent *<parameter>event</parameter></paramdef> + <paramdef>Region <parameter>region</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>event</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the +<function>Expose</function> +or +<function>GraphicsExpose</function> +event. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>region</emphasis> + </term> + <listitem> + <para> +Specifies the region object (as defined in +<function><X11/Xutil.h></function>). + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/> +function computes the union of the rectangle defined by the exposure +event and the specified region. +Then it stores the results back in <emphasis remap='I'>region</emphasis>. +If the event argument is not an +<function>Expose</function> +or +<function>GraphicsExpose</function> +event, +<xref linkend='XtAddExposureToRegion' xrefstyle='select: title'/> +returns without an error and without modifying <emphasis remap='I'>region</emphasis>. +</para> + +<para> +This function is used by the exposure compression mechanism; +see <xref linkend='Exposure_Compression' /> +</para> +</sect1> + +<sect1 id="Translating_Widget_Coordinates"> +<title>Translating Widget Coordinates</title> +<para> +To translate an x-y coordinate pair from widget coordinates to root +window absolute coordinates, use +<xref linkend='XtTranslateCoords' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtTranslateCoords'> +<funcprototype> +<funcdef>void <function>XtTranslateCoords</function></funcdef> + <paramdef>Widget <parameter>w</parameter></paramdef> + <paramdef>Position <parameter>x</parameter></paramdef> + <paramdef>Position *<parameter>rootx_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>w</emphasis> + </term> + <listitem> + <para> +Specifies the widget. Must be of class RectObj or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>x</emphasis> + </term> + <listitem> + <para></para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>y</emphasis> + </term> + <listitem> + <para> +Specify the widget-relative x and y coordinates. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>rootx_return</emphasis> + </term> + <listitem> + <para></para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>rooty_return</emphasis> + </term> + <listitem> + <para> +Return the root-relative x and y coordinates. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +While +<xref linkend='XtTranslateCoords' xrefstyle='select: title'/> +is similar to the Xlib +<function>XTranslateCoordinates</function> +function, it does not generate a server request because all the required +information already is in the widget's data structures. +</para> +</sect1> + +<sect1 id="Translating_a_Window_to_a_Widget"> +<title>Translating a Window to a Widget</title> +<para> +To translate a given window and display pointer into a widget instance, use +<xref linkend='XtWindowToWidget' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtWindowToWidget'> +<funcprototype> +<funcdef>Widget <function>XtWindowToWidget</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>Window <parameter>window</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the display on which the window is defined. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>window</emphasis> + </term> + <listitem> + <para> +Specifies the drawable for which you want the widget. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +If there is a realized widget whose window is the specified drawable on +the specified <emphasis remap='I'>display</emphasis>, +<xref linkend='XtWindowToWidget' xrefstyle='select: title'/> +returns that widget. +If not and if the drawable has been associated with a widget through +<xref linkend='XtRegisterDrawable' xrefstyle='select: title'/>, +<xref linkend='XtWindowToWidget' xrefstyle='select: title'/> +returns the widget associated with the drawable. In other cases it +returns NULL. +</para> +</sect1> + +<sect1 id="Handling_Errors"> +<title>Handling Errors</title> +<para> +The Intrinsics allow a client to register procedures that are called +whenever a fatal or nonfatal error occurs. +These facilities are intended for both error reporting and logging +and for error correction or recovery. +</para> + +<para> +Two levels of interface are provided: +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +A high-level interface that takes an error +name and class and retrieves the error message text from +an error resource database. + </para> + </listitem> + <listitem> + <para> +A low-level interface that takes a simple string to display. + </para> + </listitem> +</itemizedlist> +<para> +The high-level functions construct a string to pass to the lower-level +interface. +The strings may be specified in application code and are +overridden by the contents of an external systemwide file, +the "error database file". The location and name of this file are +implementation-dependent. +</para> +<note> +<para> +The application-context-specific error handling is not +implemented on many systems, although the interfaces are +always present. +Most implementations will have just one set of error handlers +for all application contexts within a process. +If they are set for different application contexts, +the ones registered last will prevail. +</para> +</note> + +<para> +To obtain the error database (for example, to merge with +an application- or widget-specific database), use +<xref linkend='XtAppGetErrorDatabase' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppGetErrorDatabase'> +<funcprototype> <funcdef>XrmDatabase *<function>XtAppGetErrorDatabase</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtAppGetErrorDatabase' xrefstyle='select: title'/> +function returns the address of the error database. +The Intrinsics do a lazy binding of the error database and do not merge in the +database file until the first call to +<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>. +</para> + +<para> +For a complete listing of all errors and warnings +that can be generated by the Intrinsics, see <xref linkend='Intrinsics_Error_Messages' /> +</para> + +<para> +The high-level error and warning handler procedure pointers are of type +<xref linkend='XtErrorMsgHandler' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtErrorMsgHandler'> +<funcprototype> +<funcdef>typedef void <function>(*XtErrorMsgHandler)</function></funcdef> + <paramdef>String <parameter>name</parameter></paramdef> + <paramdef>String <parameter>type</parameter></paramdef> + <paramdef>String <parameter>class</parameter></paramdef> + <paramdef>String <parameter>defaultp</parameter></paramdef> + <paramdef>String *<parameter>params</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_params</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <listitem> + <para> +Specifies the name to be concatenated with the specified type to form +the resource name of the error message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>type</emphasis> + </term> + <listitem> + <para> +Specifies the type to be concatenated with the name to form the +resource name of the error message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>class</emphasis> + </term> + <listitem> + <para> +Specifies the resource class of the error message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>defaultp</emphasis> + </term> + <listitem> + <para> +Specifies the default message to use if no error database entry is found. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>params</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to a list of parameters to be substituted in the message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_params</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in <emphasis remap='I'>params</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The specified name can be a general kind of error, +like "invalidParameters" or "invalidWindow", +and the specified type gives extra information +such as the name of the routine in which the error was detected. +Standard +<function>printf</function> +notation is used to substitute the parameters into the message. +</para> + +<para> +An error message handler can obtain the error database text for an +error or a warning by calling +<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppGetErrorDatabaseText'> +<funcprototype> +<funcdef>void <function>XtAppGetErrorDatabaseText</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>String <parameter>name</parameter></paramdef> + <paramdef>String <parameter>default</parameter></paramdef> + <paramdef>String <parameter>buffer_return</parameter></paramdef> + <paramdef>int <parameter>nbytes</parameter></paramdef> + <paramdef>XrmDatabase <parameter>database</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <term> + <emphasis remap='I'>type</emphasis> + </term> + <listitem> + <para> +Specify the name and type concatenated to form the resource name +of the error message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>class</emphasis> + </term> + <listitem> + <para> +Specifies the resource class of the error message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>default</emphasis> + </term> + <listitem> + <para> +Specifies the default message to use if an error database entry is not found. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>buffer_return</emphasis> + </term> + <listitem> + <para> +Specifies the buffer into which the error message is to be returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nbytes</emphasis> + </term> + <listitem> + <para> +Specifies the size of the buffer in bytes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>database</emphasis> + </term> + <listitem> + <para> +Specifies the name of the alternative database to be used, +or NULL if the application context's error database is to be used. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The +<xref linkend='XtAppGetErrorDatabaseText' xrefstyle='select: title'/> +returns the appropriate message from the error database +or returns the specified default message if one is not found in the +error database. +To form the full resource name and class when querying the database, +the <emphasis remap='I'>name</emphasis> and <emphasis remap='I'>type</emphasis> are concatenated with a single "." +between them and the <emphasis remap='I'>class</emphasis> is concatenated with itself with a +single "." if it does not already contain a ".". +</para> + +<para> +To return the application name and class as passed to +<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/> +for a particular Display, use +<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtGetApplicationNameAndClass'> +<funcprototype> +<funcdef>void <function>XtGetApplicationNameAndClass</function></funcdef> + <paramdef>Display* <parameter>display</parameter></paramdef> + <paramdef>String* <parameter>name_return</parameter></paramdef> + <paramdef>String* <parameter>class_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies an open display connection that has been initialized with +<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>name_return</emphasis> + </term> + <listitem> + <para> +Returns the application name. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>class_return</emphasis> + </term> + <listitem> + <para> +Returns the application class. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/> +returns the application name and class passed to +<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/> +for the specified display. If the display was +never initialized or has been closed, the result is undefined. The +returned strings are owned by the Intrinsics and must not be modified +or freed by the caller. +</para> + +<para> +To register a procedure to be called on fatal error conditions, use +<xref linkend='XtAppSetErrorMsgHandler' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppSetErrorMsgHandler'> +<funcprototype> +<funcdef>XtErrorMsgHandler <function>XtAppSetErrorMsgHandler</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>msg_handler</emphasis> + </term> + <listitem> + <para> +Specifies the new fatal error procedure, which should not return. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtAppSetErrorMsgHandler' xrefstyle='select: title'/> +returns a pointer to the previously +installed high-level fatal error handler. +The default high-level fatal error handler provided by the Intrinsics is named +<function>_XtDefaultErrorMsg</function> +and constructs a string from the error resource database and calls +<xref linkend='XtError' xrefstyle='select: title'/>. +Fatal error message handlers should not return. +If one does, +subsequent Intrinsics behavior is undefined. +</para> + +<para> +To call the high-level error handler, use +<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppErrorMsg'> +<funcprototype> +<funcdef>void <function>XtAppErrorMsg</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>String <parameter>name</parameter></paramdef> + <paramdef>String <parameter>type</parameter></paramdef> + <paramdef>String <parameter>class</parameter></paramdef> + <paramdef>String <parameter>default</parameter></paramdef> + <paramdef>String *<parameter>params</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_params</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <listitem> + <para> +Specifies the general kind of error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>type</emphasis> + </term> + <listitem> + <para> +Specifies the detailed name of the error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>class</emphasis> + </term> + <listitem> + <para> +Specifies the resource class. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>default</emphasis> + </term> + <listitem> + <para> +Specifies the default message to use if an error database entry is not found. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>params</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to a list of values to be stored in the message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_params</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in <emphasis remap='I'>params</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The Intrinsics internal errors all have class +"XtToolkitError". +</para> + +<para> +To register a procedure to be called on nonfatal error conditions, use +<xref linkend='XtAppSetWarningMsgHandler' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppSetWarningMsgHandler'> +<funcprototype> +<funcdef>XtErrorMsgHandler <function>XtAppSetWarningMsgHandler</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>XtErrorMsgHandler <parameter>msg_handler</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>msg_handler</emphasis> + </term> + <listitem> + <para> +Specifies the new nonfatal error procedure, which usually returns. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtAppSetWarningMsgHandler' xrefstyle='select: title'/> +returns a pointer to the previously +installed high-level warning handler. +The default high-level warning handler provided by the Intrinsics is named +<function>_XtDefaultWarningMsg</function> +and constructs a string +from the error resource database and calls +<xref linkend='XtWarning' xrefstyle='select: title'/>. +</para> + +<para> +To call the installed high-level warning handler, use +<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppWarningMsg'> +<funcprototype> +<funcdef>void <function>XtAppWarningMsg</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>String <parameter>name</parameter></paramdef> + <paramdef>String <parameter>type</parameter></paramdef> + <paramdef>String <parameter>class</parameter></paramdef> + <paramdef>String <parameter>default</parameter></paramdef> + <paramdef>String *<parameter>params</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_params</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <listitem> + <para> +Specifies the general kind of error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>type</emphasis> + </term> + <listitem> + <para> +Specifies the detailed name of the error. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>class</emphasis> + </term> + <listitem> + <para> +Specifies the resource class. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>default</emphasis> + </term> + <listitem> + <para> +Specifies the default message to use if an error database entry is not found. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>params</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to a list of values to be stored in the message. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_params</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in <emphasis remap='I'>params</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The Intrinsics internal warnings all have class +"XtToolkitError". +</para> + +<para> +The low-level error and warning handler procedure pointers are of type +<xref linkend='XtErrorHandler' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtErrorHandler'> +<funcprototype> +<funcdef>typedef void <function>(*XtErrorHandler)</function></funcdef> + <paramdef>String <parameter>message</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>message</emphasis> + </term> + <listitem> + <para> +Specifies the error message. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The error handler should display the message string in some appropriate fashion. +</para> + +<para> +To register a procedure to be called on fatal error conditions, use +<xref linkend='XtAppSetErrorHandler' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppSetErrorHandler'> +<funcprototype> +<funcdef>XtErrorHandler <function>XtAppSetErrorHandler</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>handler</emphasis> + </term> + <listitem> + <para> +Specifies the new fatal error procedure, which should not return. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtAppSetErrorHandler' xrefstyle='select: title'/> +returns a pointer to the previously installed +low-level fatal error handler. +The default low-level error handler provided by the Intrinsics is +<function>_XtDefaultError</function>. +On POSIX-based systems, +it prints the message to standard error and terminates the application. +Fatal error message handlers should not return. +If one does, +subsequent Intrinsics behavior is undefined. +</para> + +<para> +To call the installed fatal error procedure, use +<xref linkend='XtAppError' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppError'> +<funcprototype> +<funcdef>void <function>XtAppError</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>String <parameter>message</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>message</emphasis> + </term> + <listitem> + <para> +Specifies the message to be reported. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +Most programs should use +<xref linkend='XtAppErrorMsg' xrefstyle='select: title'/>, +not +<xref linkend='XtAppError' xrefstyle='select: title'/>, +to provide for customization and internationalization of error messages. +</para> + +<para> +To register a procedure to be called on nonfatal error conditions, use +<xref linkend='XtAppSetWarningHandler' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppSetWarningHandler'> +<funcprototype> +<funcdef>XtErrorHandler <function>XtAppSetWarningHandler</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>XtErrorHandler <parameter>handler</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>handler</emphasis> + </term> + <listitem> + <para> +Specifies the new nonfatal error procedure, which usually returns. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtAppSetWarningHandler' xrefstyle='select: title'/> +returns a pointer to the previously installed +low-level warning handler. +The default low-level warning handler provided by the Intrinsics is +<function>_XtDefaultWarning</function>. +On POSIX-based systems, +it prints the message to standard error and returns to the caller. +</para> + +<para> +To call the installed nonfatal error procedure, use +<xref linkend='XtAppWarning' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtAppWarning'> +<funcprototype> +<funcdef>void <function>XtAppWarning</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>String <parameter>message</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>message</emphasis> + </term> + <listitem> + <para> +Specifies the nonfatal error message to be reported. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +Most programs should use +<xref linkend='XtAppWarningMsg' xrefstyle='select: title'/>, +not +<xref linkend='XtAppWarning' xrefstyle='select: title'/>, +to provide for customization and internationalization of warning messages. +</para> +</sect1> + +<sect1 id="Setting_WM_COLORMAP_WINDOWS"> +<title>Setting WM_COLORMAP_WINDOWS</title> +<para> +A client may set the value of the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> +property on a widget's window by calling +<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtSetWMColormapWindows'> +<funcprototype> +<funcdef>void <function>XtSetWMColormapWindows</function></funcdef> + <paramdef>Widget <parameter>widget</parameter></paramdef> + <paramdef>Widget* <parameter>list</parameter></paramdef> + <paramdef>Cardinal <parameter>count</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>widget</emphasis> + </term> + <listitem> + <para> +Specifies the widget on whose window the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> +property is stored. Must be of class Core or any subclass thereof. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>list</emphasis> + </term> + <listitem> + <para> +Specifies a list of widgets whose windows are potentially to be +listed in the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> property. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>count</emphasis> + </term> + <listitem> + <para> +Specifies the number of widgets in <emphasis remap='I'>list</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/> +returns immediately if <emphasis remap='I'>widget</emphasis> is not realized or if <emphasis remap='I'>count</emphasis> is 0. +Otherwise, +<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/> +constructs an ordered list of windows +by examining each widget in <emphasis remap='I'>list</emphasis> in turn and +ignoring the widget if it is not realized, or +adding the widget's window to the window list if the widget is realized +and if its colormap resource is different from the colormap +resources of all widgets whose windows are already on the window list. +</para> + +<para> +Finally, +<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/> +stores the resulting window list in the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> +property on the specified widget's window. +Refer to Section 4.1.8 in the <emphasis remap='I'>Inter-Client Communication Conventions Manual.</emphasis> for details of +the semantics of the <emphasis role='strong'>WM_COLORMAP_WINDOWS</emphasis> property. +</para> +</sect1> +<!-- FIXME: --> +<sect1 id="Finding_File_Names"> +<title>Finding File Names</title> +<para> +The Intrinsics provide procedures to look for a file by name, allowing +string substitutions in a list of file specifications. Two +routines are provided for this: +<xref linkend='XtFindFile' xrefstyle='select: title'/> +and +<xref linkend='XtResolvePathname' xrefstyle='select: title'/>. +<xref linkend='XtFindFile' xrefstyle='select: title'/> +uses an arbitrary set of client-specified substitutions, and +<xref linkend='XtResolvePathname' xrefstyle='select: title'/> +uses a set of standard substitutions corresponding +to the <emphasis remap='I'>X/Open Portability Guide</emphasis> language localization conventions. +Most applications should use +<xref linkend='XtResolvePathname' xrefstyle='select: title'/>. +</para> + +<para> +A string substitution is defined by a list of +<function>Substitution</function> +entries. +</para> +<literallayout > +typedef struct { + char match; + String substitution; +} SubstitutionRec, *Substitution; +</literallayout> +<para> +File name evaluation is handled in an operating-system-dependent +fashion by an +<xref linkend='XtFilePredicate' xrefstyle='select: title'/> +procedure. +</para> + +<funcsynopsis id='XtFilePredicate'> +<funcprototype> +<funcdef>typedef Boolean <function>(*XtFilePredicate)</function></funcdef> + <paramdef>String <parameter>filename</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>filename</emphasis> + </term> + <listitem> + <para> +Specifies a potential filename. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +A file predicate procedure is called with a string that is +potentially a file name. It should return +<function>True</function> +if this string specifies a file that is appropriate for the intended use and +<function>False</function> +otherwise. +</para> + +<para> +To search for a file using substitutions in a path list, use +<xref linkend='XtFindFile' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtFindFile'> +<funcprototype> +<funcdef>String <function>XtFindFile</function></funcdef> + <paramdef>String <parameter>path</parameter></paramdef> + <paramdef>Substitution <parameter>substitutions</parameter></paramdef> + <paramdef>Cardinal <parameter>num_substitutions</parameter></paramdef> + <paramdef>XtFilePredicate <parameter>predicate</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>path</emphasis> + </term> + <listitem> + <para> +Specifies a path of file names, including substitution characters. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>substitutions</emphasis> + </term> + <listitem> + <para> +Specifies a list of substitutions to make into the path. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_substitutions</emphasis> + </term> + <listitem> + <para> +Specifies the number of substitutions passed in. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>predicate</emphasis> + </term> + <listitem> + <para> +Specifies a procedure called to judge each potential file name, or NULL. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The <emphasis remap='I'>path</emphasis> parameter specifies a string that consists of a series of +potential file names delimited by colons. Within each name, the +percent character specifies a string substitution selected by the +following character. The character sequence "%:" specifies an +embedded colon that is not a delimiter; the sequence is replaced by a +single colon. The character sequence "%%" specifies a percent +character that does not introduce a substitution; the sequence is +replaced by a single percent character. If a percent character is +followed by any other character, +<xref linkend='XtFindFile' xrefstyle='select: title'/> +looks through the +specified <emphasis remap='I'>substitutions</emphasis> for that character in the <emphasis remap='I'>match</emphasis> field +and, if found, +replaces the percent and match characters with the string in the +corresponding <emphasis remap='I'>substitution</emphasis> field. A <emphasis remap='I'>substitution</emphasis> field entry of NULL +is equivalent to a pointer to an empty string. If the operating +system does not interpret multiple embedded name separators in the +path (i.e., "/" in POSIX) the same way as a single separator, +<xref linkend='XtFindFile' xrefstyle='select: title'/> +will collapse multiple separators into a single one after performing +all string substitutions. Except for collapsing embedded separators, +the contents of the string substitutions are not interpreted by +<xref linkend='XtFindFile' xrefstyle='select: title'/> +and may therefore contain any operating-system-dependent +characters, including additional name separators. Each resulting +string is passed to the predicate procedure until a string is found for +which the procedure returns +<function>True</function>; +this string is the return value for +<xref linkend='XtFindFile' xrefstyle='select: title'/>. +If no string yields a +<function>True</function> +return from the predicate, +<xref linkend='XtFindFile' xrefstyle='select: title'/> +returns NULL. +</para> + +<para> +If the <emphasis remap='I'>predicate</emphasis> parameter is NULL, an internal procedure that checks +if the file exists, is readable, and is not a directory is used. +</para> + +<para> +It is the responsibility of the caller to free the returned string using +<xref linkend='XtFree' xrefstyle='select: title'/> +when it is no longer needed. +</para> + +<para> +To search for a file using standard substitutions in a path list, use +<xref linkend='XtResolvePathname' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtResolvePathname'> +<funcprototype> +<funcdef>String <function>XtResolvePathname</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> + <paramdef>String <parameter>type</parameter></paramdef> + <paramdef>Substitution <parameter>substitutions</parameter></paramdef> + <paramdef>Cardinal <parameter>num_substitutions</parameter></paramdef> + <paramdef>XtFilePredicate <parameter>predicate</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the display to use to find the language for language substitutions. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>type</emphasis> + </term> + <listitem> + <para></para> + + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>filename</emphasis> + </term> + <listitem> + <para></para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>suffix</emphasis> + </term> + <listitem> + <para> +Specify values to substitute into the path. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>path</emphasis> + </term> + <listitem> + <para> +Specifies the list of file specifications, or NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>substitutions</emphasis> + </term> + <listitem> + <para> +Specifies a list of additional substitutions to make into the path, or NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_substitutions</emphasis> + </term> + <listitem> + <para> +Specifies the number of entries in <emphasis remap='I'>substitutions</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>predicate</emphasis> + </term> + <listitem> + <para> +Specifies a procedure called to judge each potential file name, or NULL. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The substitutions specified by +<xref linkend='XtResolvePathname' xrefstyle='select: title'/> +are determined from the value of the language string retrieved by +<xref linkend='XtDisplayInitialize' xrefstyle='select: title'/> +for the specified display. +To set the +language for all applications specify "*xnlLanguage: <emphasis remap='I'>lang</emphasis>" in the +resource database. +The format and content of the language string are +implementation-defined. One suggested syntax is to compose +the language string of three parts; a "language part", a +"territory part" and a "codeset part". The manner in which +this composition is accomplished is implementation-defined, +and the Intrinsics make no interpretation of the parts other +than to use them in substitutions as described below. +</para> + + +<para> +<xref linkend='XtResolvePathname' xrefstyle='select: title'/> +calls +<xref linkend='XtFindFile' xrefstyle='select: title'/> +with the following substitutions +in addition to any passed by the caller and returns the value returned by +<xref linkend='XtFindFile' xrefstyle='select: title'/>: +</para> +<!-- PROBLEM BELOW HERE --> + + +<variablelist> + <varlistentry> + <term> +%N + </term> + <listitem> + <para> +The value of the <emphasis remap='I'>filename</emphasis> parameter, or the application's +class name if <emphasis remap='I'>filename</emphasis> is NULL. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> +%T + </term> + <listitem> + <para> +The value of the <emphasis remap='I'>type</emphasis> parameter. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> +%S + </term> + <listitem> + <para> +The value of the <emphasis remap='I'>suffix</emphasis> parameter. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> +%L + </term> + <listitem> + <para> +The language string associated with the specified display. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> +%l + </term> + <listitem> + <para> +The language part of the display's language string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> +%t + </term> + <listitem> + <para> +The territory part of the display's language string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> +%c + </term> + <listitem> + <para> +The codeset part of the display's language string. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> +%C + </term> + <listitem> + <para> +The customization string retrieved from the resource +database associated with <emphasis remap='I'>display</emphasis>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> +%D + </term> + <listitem> + <para> +The value of the implementation-specific default path. + </para> + </listitem> + </varlistentry> +</variablelist> + + +<!-- PROBLEM ABOVE HERE --> +<para> +If a path is passed to +<xref linkend='XtResolvePathname' xrefstyle='select: title'/>, +it is passed along to +<xref linkend='XtFindFile' xrefstyle='select: title'/>. +If the <emphasis remap='I'>path</emphasis> argument is NULL, the value of the +<emphasis role='strong'>XFILESEARCHPATH</emphasis> +environment variable is passed to +<xref linkend='XtFindFile' xrefstyle='select: title'/>. +If <emphasis role='strong'>XFILESEARCHPATH</emphasis> +is not defined, an implementation-specific default path is used +that contains at least six entries. These entries +must contain the following substitutions: +</para> + + +<!-- OK PAST HERE --> + +<literallayout> +1. %C, %N, %S, %T, %L or %C, %N, %S, %T, %l, %t, %c +2. %C, %N, %S, %T, %l +3. %C, %N, %S, %T +4. %N, %S, %T, %L or %N, %S, %T, %l, %t, %c +5. %N, %S, %T, %l +6. %N, %S, %T +</literallayout> + +<para> +The order of these six entries within the path must be as given above. +The order and use of substitutions within a given entry +are implementation-dependent. +If the path begins +with a colon, it is preceded by %N%S. If the path includes two +adjacent colons, <function>%N%S</function> is inserted between them. +</para> + +<para> +The <emphasis remap='I'>type</emphasis> parameter is intended to be a category of files, usually +being translated into a directory in the pathname. Possible values +might include "app-defaults", "help", and "bitmap". +</para> + +<para> +The <emphasis remap='I'>suffix</emphasis> parameter is intended to be appended to the file name. +Possible values might include ".txt", ".dat", and ".bm". +</para> + +<para> +A suggested value for the default path on POSIX-based systems is +</para> +<literallayout> + /usr/lib/X11/%L/%T/%N%C%S:/usr/lib/X11/%l/%T/%N%C%S:\ + /usr/lib/X11/%T/%N%C%S:/usr/lib/X11/%L/%T/%N%S:\ + /usr/lib/X11/%l/%T/%N%S:/usr/lib/X11/%T/%N%S +</literallayout> + + +<para> +Using this example, if the user has specified a language, it is +used as a subdirectory of /usr/lib/X11 that is searched for other +files. If the desired file is not found there, the lookup is +tried again using just the language part of the specification. If the +file is not there, it is looked for in /usr/lib/X11. The <emphasis remap='I'>type</emphasis> +parameter is used as a subdirectory of the language directory or of +/usr/lib/X11, and <emphasis remap='I'>suffix</emphasis> is appended to the file name. +</para> + +<para> +The %D substitution allows the addition of path +elements to the implementation-specific default path, typically to +allow additional directories to be searched without preventing +resources in the system directories from being found. For example, a +user installing resource files under a directory called "ourdir" +might set +<emphasis role='strong'>XFILESEARCHPATH</emphasis> +to +</para> +<literallayout> + %D:ourdir/%T/%N%C:ourdir/%T/%N +</literallayout> + +<para> +The customization string is obtained by querying the resource database +currently associated with the display (the database returned by +<function>XrmGetDatabase</function>) +for the resource <emphasis remap='I'>application_name</emphasis>.customization, class +<emphasis remap='I'>application_class</emphasis>.Customization, where <emphasis remap='I'>application_name</emphasis> +and <emphasis remap='I'>application_class</emphasis> are the values returned by +<xref linkend='XtGetApplicationNameAndClass' xrefstyle='select: title'/>. +If no value is specified in the database, the empty string is used. +</para> + +<para> +It is the responsibility of the caller to free the returned string using +<xref linkend='XtFree' xrefstyle='select: title'/> +when it is no longer needed. +</para> + + +</sect1> +<!-- END OF FIXME --> +<sect1 id="Hooks_for_External_Agents"> +<title>Hooks for External Agents</title> +<para> +Applications may register +functions that are called at a particular control points in the Intrinsics. +These functions are intended to be used to provide notification +of an "X Toolkit event", such as widget creation, to an external agent, +such as an interactive resource editor, drag-and-drop server, or +an aid for physically challenged users. +The control points containing such registration hooks are identified +in a "hook registration" object. +</para> + +<para> +To retrieve the hook registration widget, use +<xref linkend='XtHooksOfDisplay' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtHooksOfDisplay'> +<funcprototype> +<funcdef>Widget <function>XtHooksOfDisplay</function></funcdef> + <paramdef>Display *<parameter>display</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the desired display. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +The class of this object is a private, implementation-dependent +subclass of +<function>Object</function>. +The hook object has no parent. The resources of this object are +the callback lists for hooks and the read-only resources for getting +a list of parentless shells. All of the callback lists are initially +empty. When a display is closed, the hook object associated with it +is destroyed. +</para> + +<para> +The following procedures can be called with the hook registration object +as an argument: +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +<xref linkend='XtAddCallback' xrefstyle='select: title'/>, +<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>, +<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>, +<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>, +<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>, +<xref linkend='XtCallCallbacks' xrefstyle='select: title'/>, +<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>, +<xref linkend='XtCallCallbackList' xrefstyle='select: title'/> + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtClass' xrefstyle='select: title'/>, +<function>XtSuperclass</function>, +<xref linkend='XtIsSubclass' xrefstyle='select: title'/>, +<xref linkend='XtCheckSubclass' xrefstyle='select: title'/>, +<function>XtIsObject</function>, +<function>XtIsRectObj</function>, +<function>XtIsWidget</function>, +<function>XtIsComposite</function>, +<function>XtIsConstraint</function>, +<function>XtIsShell</function>, +<function>XtIsOverrideShell</function>, +<function>XtIsWMShell</function>, +<function>XtIsVendorShell</function>, +<function>XtIsTransientShell</function>, +<function>XtIsToplevelShell</function>, +<function>XtIsApplicationShell</function>, +<function>XtIsSessionShell</function> + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtWidgetToApplicationContext' xrefstyle='select: title'/> + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtName' xrefstyle='select: title'/>, +<function>XtParent</function>, +<xref linkend='XtDisplayOfObject' xrefstyle='select: title'/>, +<xref linkend='XtScreenOfObject' xrefstyle='select: title'/> + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtSetValues' xrefstyle='select: title'/>, +<xref linkend='XtGetValues' xrefstyle='select: title'/>, +<xref linkend='XtVaSetValues' xrefstyle='select: title'/>, +<xref linkend='XtVaGetValues' xrefstyle='select: title'/> + </para> + </listitem> +</itemizedlist> + +<sect2 id="Hook_Object_Resources"> +<title>Hook Object Resources</title> +<para> +The resource names, classes, and representation types that are specified +in the hook object resource list are: +<informaltable frame='topbot'> + <?dbfo keep-together="always" ?> + <tgroup cols='3' align='left' colsep='0' rowsep='0'> + <colspec colwidth='1.0*' colname='c1'/> + <colspec colwidth='1.0*' colname='c2'/> + <colspec colwidth='1.0*' colname='c3'/> + <thead> + <row rowsep='1'> + <entry>Name</entry> + <entry>Class</entry> + <entry>Representation</entry> + </row> + </thead> + <tbody> + <row> + <entry>XtNcreateHook</entry> + <entry>XtCCallback</entry> + <entry>XtRCallback</entry> + </row> + <row> + <entry>XtNchangeHook</entry> + <entry>XtCCallback</entry> + <entry>XtRCallback</entry> + </row> + <row> + <entry>XtNconfigureHook</entry> + <entry>XtCCallback</entry> + <entry>XtRCallback</entry> + </row> + <row> + <entry>XtNgeometryHook</entry> + <entry>XtCCallback</entry> + <entry>XtRCallback</entry> + </row> + <row> + <entry>XtNdestroyHook</entry> + <entry>XtCCallback</entry> + <entry>XtRCallback</entry> + </row> + <row> + <entry>XtNshells</entry> + <entry>XtCReadOnly</entry> + <entry>XtRWidgetList</entry> + </row> + <row> + <entry>XtNnumShells</entry> + <entry>XtCReadOnly</entry> + <entry>XtRCardinal</entry> + </row> + </tbody> + </tgroup> +</informaltable> +</para> + +<para> +Descriptions of each of these resources: +</para> + +<para> +The XtNcreateHook callback list is called from: +<xref linkend='XtCreateWidget' xrefstyle='select: title'/>, +<xref linkend='XtCreateManagedWidget' xrefstyle='select: title'/>, +<xref linkend='XtCreatePopupShell' xrefstyle='select: title'/>, +<xref linkend='XtAppCreateShell' xrefstyle='select: title'/>, +and their corresponding varargs versions. +</para> + +<para> +The <emphasis remap='I'>call_data</emphasis> parameter in a createHook callback may be +cast to type +<function>XtCreateHookData</function>. +</para> +<literallayout > +typedef struct { + String type; + Widget widget; + ArgList args; + Cardinal num_args; +} XtCreateHookDataRec, *XtCreateHookData; +</literallayout> +<para> +The <emphasis remap='I'>type</emphasis> is set to +<function>XtHcreate</function>, +<emphasis remap='I'>widget</emphasis> is the newly created widget, and <emphasis remap='I'>args</emphasis> and <emphasis remap='I'>num_args</emphasis> +are the arguments passed to the create function. The callbacks are +called before returning from the create function. +</para> + +<para> +The XtNchangeHook callback list is called from: +</para> +<itemizedlist spacing='compact'> + <listitem> + <para> +<xref linkend='XtSetValues' xrefstyle='select: title'/>, +<xref linkend='XtVaSetValues' xrefstyle='select: title'/> + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtManageChild' xrefstyle='select: title'/>, +<xref linkend='XtManageChildren' xrefstyle='select: title'/>, +<xref linkend='XtUnmanageChild' xrefstyle='select: title'/>, +<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/> + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>, +<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/> + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtAddCallback' xrefstyle='select: title'/>, +<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>, +<function>XtAddCallbacks,</function> +<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>, +<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/> + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>, +<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>, +<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/> + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>, +<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/> + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>, +<xref linkend='XtMapWidget' xrefstyle='select: title'/>, +<xref linkend='XtUnmapWidget' xrefstyle='select: title'/> + </para> + </listitem> + <listitem> + <para> +<xref linkend='XtPopup' xrefstyle='select: title'/>, +<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>, +<xref linkend='XtPopdown' xrefstyle='select: title'/> + </para> + </listitem> +</itemizedlist> + +<para> +The <emphasis remap='I'>call_data</emphasis> parameter in a changeHook callback may +be cast to type +<function>XtChangeHookData</function>. +</para> +<literallayout > +typedef struct { + String type; + Widget widget; + XtPointer event_data; + Cardinal num_event_data; +} XtChangeHookDataRec, *XtChangeHookData; +</literallayout> +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtSetValues' xrefstyle='select: title'/> +or +<xref linkend='XtVaSetValues' xrefstyle='select: title'/>, +<emphasis remap='I'>type</emphasis> is set to +<function>XtHsetValues</function>, +<emphasis remap='I'>widget</emphasis> is the new widget passed to the set_values procedure, and +<emphasis remap='I'>event_data</emphasis> may be cast to type +<function>XtChangeHookSetValuesData</function>. +</para> +<literallayout > +typedef struct { + Widget old, req; + ArgList args; + Cardinal num_args; +} XtChangeHookSetValuesDataRec, *XtChangeHookSetValuesData; +</literallayout> +<para> +The <emphasis remap='I'>old</emphasis>, <emphasis remap='I'>req</emphasis>, <emphasis remap='I'>args</emphasis>, and <emphasis remap='I'>num_args</emphasis> are the +parameters passed to the set_values procedure. The callbacks are called +after the set_values and constraint set_values procedures have been called. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtManageChild' xrefstyle='select: title'/> +or +<xref linkend='XtManageChildren' xrefstyle='select: title'/>, +<emphasis remap='I'>type</emphasis> is set to +<function>XtHmanageChildren</function>, +<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type +WidgetList and is the list of children being managed, and +<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list. +The callbacks are called after the children have been managed. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtUnmanageChild' xrefstyle='select: title'/> +or +<xref linkend='XtUnmanageChildren' xrefstyle='select: title'/>, +<emphasis remap='I'>type</emphasis> is set to +<function>XtHunmanageChildren</function>, +<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type +WidgetList and is a list of the children being unmanaged, and +<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list. +The callbacks are called after the children have been unmanaged. +</para> + +<para> +The changeHook callbacks are called twice as a result of a call to +<xref linkend='XtChangeManagedSet' xrefstyle='select: title'/>, +once after unmanaging and again after managing. +When the callbacks are called the first time, <emphasis remap='I'>type</emphasis> is set to +<function>XtHunmanageSet</function>, +<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type +WidgetList and is a list of the children being unmanaged, and +<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list. +When the callbacks are called the second time, the <emphasis remap='I'>type</emphasis> is set to +<function>XtHmanageSet</function>, +<emphasis remap='I'>widget</emphasis> is the parent, <emphasis remap='I'>event_data</emphasis> may be cast to type +WidgetList and is a list of the children being managed, and +<emphasis remap='I'>num_event_data</emphasis> is the length of the widget list. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtRealizeWidget' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHrealizeWidget</function> +and <emphasis remap='I'>widget</emphasis> is the widget being realized. +The callbacks are called after the widget has been realized. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtUnrealizeWidget' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHunrealizeWidget</function>, +and <emphasis remap='I'>widget</emphasis> is the widget being unrealized. +The callbacks are called after the widget has been unrealized. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtAddCallback' xrefstyle='select: title'/>, +<emphasis remap='I'>type</emphasis> is set to +<function>XtHaddCallback</function>, +<emphasis remap='I'>widget</emphasis> is the widget to which the callback is being added, and +<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of the +callback being added. +The callbacks are called after the callback has been added to the widget. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHaddCallbacks</function>, +<emphasis remap='I'>widget</emphasis> is the widget to which the callbacks are being added, and +<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of the +callbacks being added. +The callbacks are called after the callbacks have been added to the widget. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHremoveCallback</function>, +<emphasis remap='I'>widget</emphasis> is the widget from which the callback is being removed, and +<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of +the callback being removed. The callbacks are called after the callback +has been removed from the widget. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHremoveCallbacks</function>, +<emphasis remap='I'>widget</emphasis> is the widget from which the callbacks are being removed, and +<emphasis remap='I'>event_data</emphasis> may be cast to type String and is the name of the +callbacks being removed. The callbacks are called after the callbacks +have been removed from the widget. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHremoveAllCallbacks</function> +and <emphasis remap='I'>widget</emphasis> is the widget from which the callbacks are being removed. +The callbacks are called after the callbacks have been removed from the +widget. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtAugmentTranslations' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHaugmentTranslations</function> +and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being modified. +The callbacks are called after the widget's translations have been +modified. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtOverrideTranslations' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHoverrideTranslations</function> +and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being modified. +The callbacks are called after the widget's translations have been +modified. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtUninstallTranslations' xrefstyle='select: title'/>, +The <emphasis remap='I'>type</emphasis> is +<function>XtHuninstallTranslations</function> +and <emphasis remap='I'>widget</emphasis> is the widget whose translations are being uninstalled. +The callbacks are called after the widget's translations have been +uninstalled. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHsetKeyboardFocus</function> +and <emphasis remap='I'>event_data</emphasis> may be cast to type Widget and is the value of +the descendant argument passed to <xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>. The +callbacks are called before returning from <xref linkend='XtSetKeyboardFocus' xrefstyle='select: title'/>. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>, +<emphasis remap='I'>type</emphasis> is set to +<function>XtHsetWMColormapWindows</function>, +<emphasis remap='I'>event_data</emphasis> may be cast to type WidgetList and is the value of +the list argument passed to <xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>, and +<emphasis remap='I'>num_event_data</emphasis> is the length of the list. The callbacks are +called before returning from <xref linkend='XtSetWMColormapWindows' xrefstyle='select: title'/>. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHsetMappedWhenManaged</function> +and <emphasis remap='I'>event_data</emphasis> may be cast to type Boolean and is the value of +the mapped_when_managed argument passed to <xref linkend='XtSetMappedWhenManaged' xrefstyle='select: title'/>. +The callbacks are called after setting the widget's mapped_when_managed +field and before realizing or unrealizing the widget. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtMapWidget' xrefstyle='select: title'/>, +the <emphasis remap='I'>type </emphasis> is set to +<function>XtHmapWidget</function> +and <emphasis remap='I'>widget</emphasis> is the widget being mapped. +The callbacks are called after mapping the widget. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtUnmapWidget' xrefstyle='select: title'/>, +the <emphasis remap='I'>type </emphasis> is set to +<function>XtHunmapWidget</function> +and <emphasis remap='I'>widget</emphasis> is the widget being unmapped. +The callbacks are called after unmapping the widget. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtPopup' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHpopup</function>, +<emphasis remap='I'>widget</emphasis> is the widget being popped up, and <emphasis remap='I'>event_data</emphasis> may +be cast to type XtGrabKind and is the value of the grab_kind argument +passed to <xref linkend='XtPopup' xrefstyle='select: title'/>. +The callbacks are called before returning from <xref linkend='XtPopup' xrefstyle='select: title'/>. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHpopupSpringLoaded</function> +and <emphasis remap='I'>widget</emphasis> is the widget being popped up. +The callbacks are called +before returning from <xref linkend='XtPopupSpringLoaded' xrefstyle='select: title'/>. +</para> + +<para> +When the changeHook callbacks are called as a result of a call to +<xref linkend='XtPopdown' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is set to +<function>XtHpopdown</function> +and <emphasis remap='I'>widget</emphasis> is the widget being popped down. +The callbacks are called +before returning from <xref linkend='XtPopdown' xrefstyle='select: title'/>. +</para> + +<para> +A widget set that exports interfaces that change application state +without employing the Intrinsics library should invoke the change hook +itself. This is done by: +</para> + +<literallayout > + XtCallCallbacks(XtHooksOfDisplay(dpy), XtNchangeHook, call_data); +</literallayout> +<para> +The XtNconfigureHook callback list is called any time the Intrinsics +move, resize, or configure a widget and when +<xref linkend='XtResizeWindow' xrefstyle='select: title'/> +is called. +</para> + +<para> +The <emphasis remap='I'>call_data</emphasis> parameter may be cast to type +<function>XtConfigureHookData.</function> +</para> +<literallayout > +typedef struct { + String type; + Widget widget; + XtGeometryMask changeMask; + XWindowChanges changes; +} XtConfigureHookDataRec, *XtConfigureHookData; +</literallayout> +<para> +When the configureHook callbacks are called, the <emphasis remap='I'>type</emphasis> is +<function>XtHconfigure</function>, +<emphasis remap='I'>widget</emphasis> is the widget being configured, and <emphasis remap='I'>changeMask</emphasis> and +<emphasis remap='I'>changes</emphasis> reflect the changes made to the widget. The callbacks +are called after changes have been made to the widget. +</para> + +<para> +The XtNgeometryHook callback list is called from +<xref linkend='XtMakeGeometryRequest' xrefstyle='select: title'/> +and +<xref linkend='XtMakeResizeRequest' xrefstyle='select: title'/> +once before and once after geometry negotiation occurs. +</para> + +<para> +The <emphasis remap='I'>call_data</emphasis> parameter may be cast to type +<function>XtGeometryHookData</function>. +</para> + +<literallayout > +typedef struct { + String type; + Widget widget; + XtWidgetGeometry* request; + XtWidgetGeometry* reply; + XtGeometryResult result; +} XtGeometryHookDataRec, *XtGeometryHookData; +</literallayout> +<para> +When the geometryHook callbacks are called prior to geometry negotiation, +the <emphasis remap='I'>type</emphasis> is +<function>XtHpreGeometry</function>, +<emphasis remap='I'>widget</emphasis> is the widget for which the request is being made, and +<emphasis remap='I'>request</emphasis> is the requested geometry. +When the geometryHook callbacks +are called after geometry negotiation, the <emphasis remap='I'>type</emphasis> is +<function>XtHpostGeometry</function>, +<emphasis remap='I'>widget</emphasis> is the widget for which the request was made, <emphasis remap='I'>request</emphasis> +is the requested geometry, <emphasis remap='I'>reply</emphasis> is the resulting geometry granted, +and <emphasis remap='I'>result</emphasis> is the value returned from the geometry negotiation. +</para> + +<para> +The XtNdestroyHook callback list is called when a widget is destroyed. +The <emphasis remap='I'>call_data parameter</emphasis> may be cast to type +<function>XtDestroyHookData</function>. +</para> +<literallayout > +typedef struct { + String type; + Widget widget; +} XtDestroyHookDataRec, *XtDestroyHookData; +</literallayout> +<para> +When the destroyHook callbacks are called as a result of a call to +<xref linkend='XtDestroyWidget' xrefstyle='select: title'/>, +the <emphasis remap='I'>type</emphasis> is +<function>XtHdestroy</function> +and <emphasis remap='I'>widget</emphasis> is the widget being destroyed. The callbacks are +called upon completion of phase one destroy for a widget. +</para> + +<para> +The XtNshells and XtnumShells are read-only resources that report a +list of all parentless shell widgets associated with a display. +</para> + +<para> +Clients who use these hooks must exercise caution in calling Intrinsics +functions in order to avoid recursion. +</para> +</sect2> + +<sect2 id="Querying_Open_Displays"> +<title>Querying Open Displays</title> +<para> +To retrieve a list of the Displays associated with an application context, +use +<xref linkend='XtGetDisplays' xrefstyle='select: title'/>. +</para> + +<funcsynopsis id='XtGetDisplays'> +<funcprototype> +<funcdef>void <function>XtGetDisplays</function></funcdef> + <paramdef>XtAppContext <parameter>app_context</parameter></paramdef> + <paramdef>Display ***<parameter>dpy_return</parameter></paramdef> + <paramdef>Cardinal *<parameter>num_dpy_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> + +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>app_context</emphasis> + </term> + <listitem> + <para> +Specifies the application context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>dpy_return</emphasis> + </term> + <listitem> + <para> +Returns a list of open Display connections in the specified application +context. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_dpy_return</emphasis> + </term> + <listitem> + <para> +Returns the count of open Display connections in <emphasis remap='I'>dpy_return</emphasis>. + </para> + </listitem> + </varlistentry> +</variablelist> + +<para> +<xref linkend='XtGetDisplays' xrefstyle='select: title'/> may be used by an external agent to query the +list of open displays that belong to an application context. To free +the list of displays, use +<xref linkend='XtFree' xrefstyle='select: title'/>. +</para> +</sect2> +</sect1> + +</chapter> |