5539 lines
164 KiB
XML
5539 lines
164 KiB
XML
<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>
|