From 5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 10 Apr 2012 14:58:33 +0200 Subject: Updated following packages: bigreqsproto-1.1.2 fontsproto-2.1.2 recordproto-1.14.2 scrnsaverproto-1.2.2 xcmiscproto-1.2.2 libXt-1.1.3 xhost-1.0.5 kbproto-1.0.6 libXrender-0.9.7 libxkbfile-1.0.8 freetype-2.4.9 libXaw-1.0.10 libXpm-3.5.10 xproto-7.0.23 --- libXt/specs/CH11.xml | 5538 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 5538 insertions(+) create mode 100644 libXt/specs/CH11.xml (limited to 'libXt/specs/CH11.xml') diff --git a/libXt/specs/CH11.xml b/libXt/specs/CH11.xml new file mode 100644 index 000000000..92e46dc57 --- /dev/null +++ b/libXt/specs/CH11.xml @@ -0,0 +1,5538 @@ + +Utility Functions + +The Intrinsics provide a number of utility functions that you can use to + + + + +Determine the number of elements in an array. + + + + +Translate strings to widget instances. + + + + +Manage memory usage. + + + + +Share graphics contexts. + + + + +Manipulate selections. + + + + +Merge exposure events into a region. + + + + +Translate widget coordinates. + + + + +Locate a widget given a window id. + + + + +Handle errors. + + + + +Set the WM_COLORMAP_WINDOWS property. + + + + +Locate files by name with string substitutions. + + + + +Register callback functions for external agents. + + + + +Locate all the displays of an application context. + + + + + +Determining the Number of Elements in an Array + +To determine the number of elements in a fixed-size array, use +. + + + + +Cardinal XtNumber + ArrayType array + + + + + + + array + + + +Specifies a fixed-size array of arbitrary type. + + + + + + +The + +macro returns the number of elements allocated to the array. + + + + +Translating Strings to Widget Instances + +To translate a widget name to a widget instance, use +. + + + + +Widget XtNameToWidget + Widget reference + String names + + + + + + + reference + + + +Specifies the widget from which the search is to start. Must be of class Core or any subclass thereof. + + + + + + names + + + +Specifies the partially qualified name of the desired widget. + + + + + + +The + +function searches for a descendant of the reference +widget whose name matches the specified names. The names parameter +specifies a simple object name or a series of simple object name +components separated by periods or asterisks. + +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 : + + + + +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. + + + + +Return the first object in the enumeration that matches the +specified name, where each component of names matches exactly the +corresponding component of the qualified object name and asterisk +matches any series of components, including none. + + + + +If no match is found, return NULL. + + + + +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, + +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. + + + + +Managing Memory Usage + +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 +malloc, +calloc, +realloc, +and +free +with the following added functionality: + + + + +, +, +and + +give an error if there is not enough memory. + + + + + +simply returns if passed a NULL pointer. + + + + + +simply allocates new storage if passed a NULL pointer. + + + + +See the standard C library documentation on +malloc, +calloc, +realloc, +and +free +for more information. + + + +To allocate storage, use +. + + + + +char * XtMalloc + Cardinal size + + + + + + + size + + + +Specifies the number of bytes desired. + + + + + + +The + +function returns a pointer to a block of storage of at least +the specified size bytes. +If there is insufficient memory to allocate the new block, + +calls +. + + + +To allocate and initialize an array, use +. + + + + +char * XtCalloc + Cardinal num + Cardinal size + + + + + + + num + + + +Specifies the number of array elements to allocate. + + + + + + size + + + +Specifies the size of each array element in bytes. + + + + + + +The + +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, + +calls +. + +returns the address of the allocated storage. + + + +To change the size of an allocated block of storage, use +. + + + + +char *XtRealloc + char *ptr + Cardinal num + + + + + + + ptr + + + +Specifies a pointer to the old storage allocated with +, +, +or +, +or NULL. + + + + + + num + + + +Specifies number of bytes desired in new storage. + + + + + + +The + +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, + +calls +. +If ptr is NULL, + +simply calls +. + +then returns the address of the new block. + + + +To free an allocated block of storage, use +. + + + + +void XtFree + char *ptr + + + + + + + ptr + + + +Specifies a pointer to a block of storage allocated with +, +, +or +, +or NULL. + + + + + + +The + +function returns storage, allowing it to be reused. +If ptr is NULL, + +returns immediately. + + + +To allocate storage for a new instance of a type, use +. + + + + + +type XtNew + type t + + + + + + + type + + + +Specifies a previously declared type. + + + + + + + +returns a pointer to the allocated storage. +If there is insufficient memory to allocate the new block, + +calls +. + +is a convenience macro that calls + +with the following arguments specified: + + +((type *) XtMalloc((unsigned) sizeof(type))) + + +The storage allocated by + +should be freed using +. + + + +To copy an instance of a string, use +. + + + + +String XtNewString + String string + + + + + + + string + + + +Specifies a previously declared string. + + + + + + + +returns a pointer to the allocated storage. +If there is insufficient memory to allocate the new block, + +calls +. + +is a convenience macro that calls + +with the following arguments specified: + + +(strcpy(XtMalloc((unsigned)strlen(str) + 1), str)) + + +The storage allocated by + +should be freed using +. + + + + +Sharing Graphics Contexts + +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. + + + +To obtain a shareable GC with modifiable fields, use +. + + + + +GC XtAllocateGC + Widget object + Cardinal depth + XtGCMask value_mask + XGCValues *values + XtGCMask dynamic_mask + XtGCMask unused_mask + + + + + + + object + + + +Specifies an object, giving the screen for which the +returned GC is valid. Must be of class Object or any subclass thereof. + + + + + + depth + + + +Specifies the depth for which the returned GC is valid, or 0. + + + + + + value_mask + + + +Specifies fields of the GC that are initialized from values. + + + + + + values + + + +Specifies the values for the initialized fields. + + + + + + dynamic_mask + + + +Specifies fields of the GC that will be modified by the caller. + + + + + + unused_mask + + + +Specifies fields of the GC that will not be needed by the caller. + + + + + + +The + +function returns a shareable GC that may be +modified by the client. The screen field of the specified +widget or of the nearest widget ancestor of the specified +object and the specified depth argument supply +the root and drawable depths for which the GC is to be +valid. If depth is zero, the depth is taken from the +depth field of the specified widget or of the nearest +widget ancestor of the specified object. + + + +The value_mask argument specifies fields of the GC +that are initialized with the respective member of the +values structure. The dynamic_mask 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 unused_mask 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 unused_mask. The caller may assume +that at all times all fields not specified in either +dynamic_mask or unused_mask have their default value if not +specified in value_mask or the value specified by values. +If a field is specified in both value_mask and dynamic_mask, +the effect is as if it were specified only in dynamic_mask +and then immediately set to the value in values. If a field +is set in unused_mask and also in either value_mask or +dynamic_mask, the specification in unused_mask is ignored. + + + + +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. + +may modify and return an existing GC if it was allocated with a +nonzero unused_mask. + + + +To obtain a shareable GC with no modifiable fields, use +. + + + + +GC XtGetGC + Widget object + XtGCMask value_mask + XGCValues *values + + + + + + + object + + + +Specifies an object, giving the screen and depth for which the +returned GC is valid. Must be of class Object or any subclass thereof. + + + + + + value_mask + + + +Specifies which fields of the values structure are specified. + + + + + + values + + + +Specifies the actual values for this GC. + + + + + + +The + +function returns a shareable, read-only GC. +The parameters to this function are the same as those for +XCreateGC +except that an Object is passed instead of a Display. + +is equivalent to + +with depth, dynamic_mask, and unused_mask all zero. + + + + +shares only GCs in which all values in the GC returned by +XCreateGC +are the same. +In particular, it does not use the value_mask provided to +determine which fields of the GC a widget considers relevant. +The value_mask is used only to tell the server which fields should be +filled in from values and which it should fill in with default values. + + + +To deallocate a shared GC when it is no longer needed, use +. + + + + +void XtReleaseGC + Widget object + GC gc + + + + + + + object + + + +Specifies any object on the Display for which the GC was created. Must be of class Object or any subclass thereof. + + + + + + gc + + + +Specifies the shared GC obtained with either + +or +. + + + + + + +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. + + + + +Managing Selections + +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 Inter-Client Communication Conventions Manual.. +The Intrinsics supply functions for providing and receiving selection data in +one logical piece (atomic transfers) +or in smaller logical segments (incremental transfers). + + + +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. + + + +Setting and Getting the Selection Timeout Value + +To set the Intrinsics selection timeout, use +. + + + + +void XtAppSetSelectionTimeout + XtAppContext app_context + unsigned long timeout + + + + + + + app_context + + + +Specifies the application context. + + + + + + timeout + + + +Specifies the selection timeout in milliseconds. + + + + + + +To get the current selection timeout value, use +. + + + + +unsigned long XtAppGetSelectionTimeout + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context. + + + + + + +The + +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 +. +If +selectionTimeout +is not specified, +the default is five seconds. + + + + +Using Atomic Transfers + +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. + + + +Atomic Transfer Procedures + +The following procedures are used by the selection owner when +providing selection data in a single unit. + + + +The procedure pointer specified by the owner to supply the selection +data to the Intrinsics is of type +. + + + + +typedef Boolean (*XtConvertSelectionProc) + Widget w + Atom *selection + Atom *target + Atom *type_return + XtPointer *value_return + unsigned long *length_return + int *format_return + + + + + + + w + + + +Specifies the widget that currently owns this selection. + + + + + + selection + + + +Specifies the atom naming the selection requested +(for example, +XA_PRIMARY +or +XA_SECONDARY ). + + + + + + target + + + +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). + + + + + + type_return + + + +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 +XA_STRING. + + + + + + value_return + + + +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 + +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 + +when it is done with it. + + + + + + length_return + + + +Specifies a pointer into which the number of elements in value_return, +each of size indicated by format_return, is to be stored. + + + + + + format_return + + + +Specifies a pointer into which the size in bits of the data elements +of the selection value is to be stored. + + + + + + +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 +True +if the owner successfully converted the selection to the target type or +False +otherwise. +If the procedure returns +False, +the values of the return arguments are undefined. +Each + +should respond to target value +TARGETS +by returning a value containing the list of the targets +into which it is +prepared to convert the selection. +The value returned in +format_return must be one of 8, 16, or 32 to allow the server to +byte-swap the data if necessary. + + + +This procedure does not need to worry about responding to the +MULTIPLE or the TIMESTAMP target values (see + +in the Inter-Client Communication Conventions Manual.). +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 + +or +. + + + +To retrieve the +SelectionRequest +event that triggered the + +procedure, use +. + + + + +XSelectionRequestEvent *XtGetSelectionRequest + Widget w + Atom selection + XtRequestId request_id + + + + + + + w + + + +Specifies the widget that currently owns this selection. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the selection being processed. + + + + + + request_id + + + +Specifies the requestor id in the case of incremental +selections, or NULL in the case of atomic transfers. + + + + + + + +may be called only from within an + +procedure and returns a pointer to the +SelectionRequest +event that caused the conversion procedure to be invoked. +Request_id specifies a unique id for the individual request in the +case that multiple incremental transfers are outstanding. For atomic +transfers, request_id must be specified as NULL. If no +SelectionRequest +event is being processed for the specified +widget, selection, and request_id, + +returns NULL. + + + +The procedure pointer specified by the owner when it desires +notification upon losing ownership is of type +. + + + + +typedef void (*XtLoseSelectionProc) + Widget w + Atom *selection + + + + + + + w + + + +Specifies the widget that has lost selection ownership. + + + + + + selection + + + +Specifies the atom naming the selection. + + + + + + +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. + + + +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 +. + + + + +typedef void (*XtSelectionDoneProc) + Widget w + Atom *selection + Atom *target + + + + + + + w + + + +Specifies the widget that owns the converted selection. + + + + + + selection + + + +Specifies the atom naming the selection that was converted. + + + + + + target + + + +Specifies the target type to which the conversion was done. + + + + + + +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 +, +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 +, +it also owns the storage containing the converted +selection value. + + + +Getting the Selection Value + +The procedure pointer specified by the requestor to receive the +selection data from the Intrinsics is of type +. + + + + +typedef void (*XtSelectionCallbackPro) + Widget w + XtPointer client_data + Atom *selection + Atom *type + XtPointer value + unsigned long *length + int *format + + + + + + + w + + + +Specifies the widget that requested the selection value. + + + + + + client_data + + + +Specifies a value passed in by the widget when it requested the +selection. + + + + + + selection + + + +Specifies the name of the selection that was requested. + + + + + + type + + + +Specifies the representation type of the selection value (for example, +XA_STRING ). +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 +XT_CONVERT_FAIL +is used to indicate that the selection conversion failed because the +selection owner did not respond within the Intrinsics selection timeout +interval. + + + + + + value + + + +Specifies a pointer to the selection value. +The requesting client owns this storage and is responsible for freeing it +by calling + +when it is done with it. + + + + + + length + + + +Specifies the number of elements in value. + + + + + + format + + + +Specifies the size in bits of the data in each element of value. + + + + + + +This procedure is called by the Intrinsics selection mechanism to deliver the +requested selection to the requestor. + + + +If the +SelectionNotify +event returns a property of +None, +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. + + + +To obtain the selection value in a single logical unit, use + +or +. + + + + +void XtGetSelectionValue + Widget w + Atom selection + Atom target + XtSelectionCallbackProc callback + XtPointer client_data + Time time + + + + + + + w + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired; for example, +XA_PRIMARY. + + + + + + target + + + +Specifies the type of information needed about the selection. + + + + + + callback + + + +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. + + + + + + client_data + + + +Specifies additional data to be passed to the specified procedure +when it is called. + + + + + + time + + + +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 +CurrentTime +is not acceptable. + + + + + + +The + +function requests the value of the selection converted to +the target type. +The specified callback is called at some time after + +is called, when the selection value is received from the X server. +It may be called before or after + +returns. +For more information about selection, +target, and +time, see +Section 2.6 in the +Inter-Client Communication Conventions Manual.. + + + + +void XtGetSelectionValues + Widget w + Atom selection + Atom *targets + int count + XtSelectionCallbackProc callback + XtPointer *client_data + Time time + + + + + + + w + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired (that is, primary or secondary). + + + + + + targets + + + +Specifies the types of information needed about the selection. + + + + + + count + + + +Specifies the length of the targets and client_data lists. + + + + + + callback + + + +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. + + + + + + client_data + + + +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. + + + + + + time + + + +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 +CurrentTime +is not acceptable. + + + + + + +The + +function is similar to multiple calls to + +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 selection, target, and +time, see +section 2.6 +in the Inter-Client Communication Conventions Manual.. + + + +Setting the Selection Owner + +To set the selection owner and indicate that the selection value will +be provided in one piece, use +. + + + + +Boolean XtOwnSelection + Widget w + Atom selection + Time time + XtConvertSelectionProc convert_proc + XtLoseSelectionProc lose_selection + XtSelectionDoneProc done_proc + + + + + + + w + + + +Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the name of the selection (for example, +XA_PRIMARY ). + + + + + + time + + + +Specifies the timestamp that indicates when the ownership request was +initiated. +This should be the timestamp of the event that triggered ownership; +the value +CurrentTime +is not acceptable. + + + + + + convert_proc + + + +Specifies the procedure to be called whenever a client requests the +current value of the selection. + + + + + + lose_selection + + + +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. + + + + + + done_proc + + + +Specifies the procedure called +after the requestor has received the selection value, or NULL if the +owner is not +interested in being called back. + + + + + + +The + +function informs the Intrinsics selection mechanism that a +widget wishes to own a selection. +It returns +True +if the widget successfully becomes the owner and +False +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. + + + +If a done_proc is specified, the client owns the storage allocated +for passing the value to the Intrinsics. If done_proc is NULL, +the convert_proc must allocate storage using +, +, +or +, +and the value specified is freed by the +Intrinsics when the transfer is complete. + + + +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 + +that it no longer is to be the selection owner. + + + + +void XtDisownSelection + Widget w + Atom selection + Time time + + + + + + + w + + + +Specifies the widget that wishes to relinquish ownership. + + + + + + selection + + + +Specifies the atom naming the selection being given up. + + + + + + time + + + +Specifies the timestamp that indicates when the request to +relinquish selection ownership was initiated. + + + + + + +The + +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, + +does nothing. + + + +After a widget has called +, +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 + +finishes after the call to +. + + + + + +Using Incremental Transfers + +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 +request_id argument, which is an identifier that is guaranteed to be +unique among all incremental requests that are active concurrently. + + + +For example, consider the following: + + + + +Upon receiving a request for the selection value, the owner sends +the first segment. + + + + +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. + + + + +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. + + + + +Incremental Transfer Procedures + +The following procedures are used by selection owners who wish to +provide the selection data in multiple segments. + + + +The procedure pointer specified by the incremental owner to supply the +selection data to the Intrinsics is of type +. + + +typedef XtPointer XtRequestId; + + + + +typedef Boolean (*XtConvertSelectionIncrProc) + Widget w + Atom *selection + Atom *target + Atom *type_return + XtPointer *value_return + unsigned long *length_return + int *format_return + unsigned long *max_length + XtPointer client_data + XtRequestId *request_id + + + + + + + w + + + +Specifies the widget that currently owns this selection. + + + + + + selection + + + +Specifies the atom that names the selection requested. + + + + + + target + + + +Specifies the type of information required about the selection. + + + + + + type_return + + + +Specifies a pointer to an atom into which the property +type of the converted value of the selection is to be +stored. + + + + + + value_return + + + +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. + + + + + + length_return + + + +Specifies a pointer into which the number of elements +in value_return, each of size indicated by +format_return, is to be stored. + + + + + + format_return + + + +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. + + + + + + max_length + + + +Specifies the maximum number of bytes which may be +transferred at any one time. + + + + + + client_data + + + +Specifies the value passed in by the widget when it +took ownership of the selection. + + + + + + request_id + + + +Specifies an opaque identification for a specific request. + + + + + + +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 +. +It must return +True +if the procedure has succeeded in converting the selection data or +False +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 value_return +for each segment to be transferred. This procedure should store a +non-NULL value in value_return and zero in length_return 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. + + + +To retrieve the +SelectionRequest +event that triggered the selection conversion procedure, use +, +described in Section 11.5.2.1. + + + +The procedure pointer specified by the incremental selection owner +when it desires notification upon no longer having ownership is of +type +. + + + + +typedef void (*XtLoseSelectionIncrProc) + Widget w + Atom *selection + XtPointer client_data + + + + + + + w + + + +Specifies the widget that has lost the selection ownership. + + + + + + selection + + + +Specifies the atom that names the selection. + + + + + + client_data + + + +Specifies the value passed in by the widget when it +took ownership of the selection. + + + + + + +This procedure, which is optional, is called by the Intrinsics to +inform the selection owner that it no longer owns the selection. + + + +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 +. + + + + +typedef void (*XtSelectionDoneIncrProc) + Widget w + Atom *selection + Atom *target + XtRequestId *request_id + XtPointer client_data + + + + + + + w + + + +Specifies the widget that owns the selection. + + + + + + selection + + + +Specifies the atom that names the selection being transferred. + + + + + + target + + + +Specifies the target type to which the conversion was done. + + + + + + request_id + + + +Specifies an opaque identification for a specific request. + + + + + + client_data + + + +Specified the value passed in by the widget when it +took ownership of the selection. + + + + + + +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 +. + + + +The procedure pointer specified by the incremental selection owner to +notify it if a transfer should be terminated prematurely is of type +. + + + + +typedef void (*XtCancelConvertSelectionProc) + Widget w + Atom *selection + Atom *target + XtRequestId *request_id + XtPointer client_data + + + + + + + w + + + +Specifies the widget that owns the selection. + + + + + + selection + + + +Specifies the atom that names the selection being transferred. + + + + + + target + + + +Specifies the target type to which the conversion was done. + + + + + + request_id + + + +Specifies an opaque identification for a specific request. + + + + + + client_data + + + +Specifies the value passed in by the widget when it took ownership of +the selection. + + + + + + +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. + + + +Getting the Selection Value Incrementally + +To obtain the value of the selection using incremental transfers, use + +or +. + + + + +void XtGetSelectionValueIncremental + Widget w + Atom selection + Atom target + XtSelectionCallbackProc selection_callback + XtPointer client_data + Time time + + + + + + + w + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired. + + + + + + target + + + +Specifies the type of information needed +about the selection. + + + + + + selection_callback + + + +Specifies the callback procedure to be +called to receive each data segment. + + + + + + client_data + + + +Specifies client-specific data to be passed to +the specified callback procedure when it is invoked. + + + + + + time + + + +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 +CurrentTime +is not acceptable. + + + + + + +The + +function is similar to + +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 +selection_callback 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 +XT_CONVERT_FAIL +so that the requestor can dispose +of the partial selection value it has collected up until that point. +Upon receiving +XT_CONVERT_FAIL, +the requesting client must determine +for itself whether or not a partially completed data transfer is meaningful. +For more information about selection, +target, and +time, see + in the +Inter-Client Communication Conventions Manual. + + + + +void XtGetSelectionValuesIncremental + Widget w + Atom selection + Atom *targets + int count + XtSelectionCallbackProc selection_callback + XtPointer *client_data + Time time + + + + + + + w + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired. + + + + + + targets + + + +Specifies the types of information needed about +the selection. + + + + + + count + + + +Specifies the length of the targets and client_data lists. + + + + + + selection_callback + + + +Specifies the callback procedure to be called +to receive each selection value. + + + + + + client_data + + + +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. + + + + + + time + + + +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 +CurrentTime +is not acceptable. + + + + + + +The + +function is similar to + +except that it takes a list of targets and client data. + +is equivalent to calling + +successively for each target/client_data pair except that + +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 + +repeatedly. +For more information about selection, target, and +time, see +Section 2.6 in the +Inter-Client Communication Conventions Manual. + + + +Setting the Selection Owner for Incremental Transfers + +To set the selection owner when using incremental transfers, use +. + + + + +Boolean XtOwnSelectionIncremental + Widget w + Atom selection + Time time + XtConvertSelectionIncrProc convert_callback + XtLoseSelectionIncrProc lose_callback + XtSelectionDoneIncrProc done_callback + XtCancelConvertSelectionProc cancel_callback + XtPointer client_data + + + + + + + w + + + +Specifies the widget that wishes to become the owner. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the atom that names the selection. + + + + + + time + + + +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 +CurrentTime +is not acceptable. + + + + + + convert_callback + + + +Specifies the procedure to be called whenever +the current value of the selection is requested. + + + + + + lose_callback + + + +Specifies the procedure to be called whenever +the widget has lost selection ownership, or NULL if the +owner is not interested in being notified. + + + + + + done_callback + + + +Specifies the procedure called after the +requestor has received the entire selection, or NULL if +the owner is not interested in being notified. + + + + + + cancel_callback + + + +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. + + + + + + client_data + + + +Specifies the argument to be passed to each of +the callback procedures when they are called. + + + + + + +The + +procedure informs the Intrinsics +incremental selection mechanism that the specified widget wishes to +own the selection. It returns +True +if the specified widget successfully becomes the selection owner or +False +otherwise. +For more information about selection, target, and +time, see +Section 2.6 in the +Inter-Client Communication Conventions Manual. + + + +If a done_callback procedure is specified, the client owns the storage allocated +for passing the value to the Intrinsics. If done_callback is NULL, +the convert_callback procedure must allocate storage using +, +, +or +, +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. + + + +The lose_callback procedure does not indicate completion of any in-progress +transfers; it is invoked at the time a +SelectionClear +event is dispatched regardless of any active transfers, which are still +expected to continue. + + + +A widget that becomes the selection owner using + +may use + +to relinquish selection ownership. + + + + + +Setting and Retrieving Selection Target Parameters + +To specify target parameters for a selection request with a single target, +use +. + + + + +void XtSetSelectionParameters + Widget requestor + Atom selection + Atom type + XtPointer value + unsigned long length + int format + + + + + + + requestor + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the atom that names the selection. + + + + + + type + + + +Specifies the type of the property in which the parameters are passed. + + + + + + value + + + +Specifies a pointer to the parameters. + + + + + + length + + + +Specifies the number of elements containing data in value, +each element of a size indicated by format. + + + + + + format + + + +Specifies the size in bits of the data in the elements of value. + + + + + + +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 + +or to + +specifying the same requestor widget and selection atom will generate a +ConvertSelection +request referring to the property containing the parameters. If + +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. + + + +The possible values of format are 8, 16, or 32. If the format is 8, +the elements of value are assumed to be sizeof(char); +if 16, sizeof(short); if 32, sizeof(long). + + + +To generate a MULTIPLE +target request with parameters for any of the multiple targets of the +selection request, precede individual calls to + +and + +with corresponding individual calls to +, +and enclose these all within + +and +XtSendSelectionRequest. + +and + +cannot be used to make selection requests with parameterized targets. + + + +To retrieve any target parameters needed to perform a selection conversion, +the selection owner calls +. + + + + +void XtGetSelectionParameters + Widget owner + Atom selection + XtRequestId request_id + Atom *type_return + XtPointer *value_return + unsigned long *length_return + int *format_return + + + + + + + owner + + + +Specifies the widget that owns the specified selection. + + + + + + selection + + + +Specifies the selection being processed. + + + + + + request_id + + + +Specifies the requestor id in the case of incremental selections, +or NULL in the case of atomic transfers. + + + + + + type_return + + + +Specifies a pointer to an atom in which the property type +of the parameters is stored. + + + + + + value_return + + + +Specifies a pointer into which a pointer to the parameters is to be stored. +A NULL is stored if no parameters accompany the request. + + + + + + length_return + + + +Specifies a pointer into which the number of data elements +in value_return of size indicated by format_return are stored. + + + + + + format_return + + + +Specifies a pointer into which the size in bits of the parameter data +in the elements of value is stored. + + + + + + + +may be called only from within an + +or from within the first call to an + +with a new request_id. + + + +It is the responsibility of the caller to free the returned parameters using + +when the parameters are no longer needed. + + + + +Generating MULTIPLE Requests + +To have the Intrinsics bundle multiple calls to make selection requests into +a single request using a MULTIPLE target, use + +and +. + + + + +void XtCreateSelectionRequest + Widget requestor + Atom selection + + + + + + + requestor + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired. + + + + + + +When + +is called, subsequent calls to +, +, +, +and +, +with the requestor and selection as specified to +, +are bundled into a single selection request with +multiple targets. The request is made by calling +. + + + + +void XtSendSelectionRequest + Widget requestor + Atom selection + Time time + + + + + + + requestor + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired. + + + + + + time + + + +Specifies the timestamp that indicates when the selection request was +initiated. The value +CurrentTime +is not acceptable. + + + + + + +When + +is called with a value of requestor and selection matching +a previous call to +, +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 +, +, +, +and + +are invoked. + + + +Multi-threaded applications should lock the application context before +calling + +and release the lock after calling + +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. + + + +To relinquish the composition of a MULTIPLE request without sending it, use +. + + + + +void XtCancelSelectionRequest + Widget requestor + Atom selection + + + + + + + requestor + + + +Specifies the widget making the request. Must be of class Core or any subclass thereof. + + + + + + selection + + + +Specifies the particular selection desired. + + + + + + +When + +is called, any requests queued since the last call to + +for the same widget and selection are discarded +and any resources reserved are released. +A subsequent call to + +will not result in any request being made. +Subsequent calls to +, +, +, +or + +will not be deferred. + + + + +Auxiliary Selection Properties + +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. + + + +To acquire a temporary property name atom for use in a selection +request, the client may call +. + + + + +Atom XtReservePropertyAtom + Widget w + + + + + + + w + + + +Specifies the widget making a selection request. + + + + + + + +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. + + + +To return a temporary property name atom for reuse and to delete +the property named by that atom, use +. + + + + +void XtReleasePropertyAtom + Widget w + Atom atom + + + + + + + w + + + +Specifies the widget used to reserve the property name atom. + + + + + + atom + + + +Specifies the property name atom returned by + +that is to be released for reuse. + + + + + + + +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 atom does not +specify a value returned by + +for the specified widget, the results are undefined. + + + + +Retrieving the Most Recent Timestamp + +To retrieve the timestamp from the most recent call to + +that contained a timestamp, use +. + + + + +Time XtLastTimestampProcessed + Display *display + + + + + + + display + + + +Specifies an open display connection. + + + + + + +If no +KeyPress, +KeyRelease, +ButtonPress, +ButtonRelease, +MotionNotify, +EnterNotify, +LeaveNotify, +PropertyNotify, +or +SelectionClear +event has yet been passed to + +for the specified display, + +returns zero. + + + + +Retrieving the Most Recent Event + +To retrieve the event from the most recent call to + +for a specific display, use +. + + + + +XEvent *XtLastEventProcessed + Display *display + + + + + + + display + + + +Specifies the display connection from which to retrieve the event. + + + + + + +Returns the last event passed to + +for the specified display. Returns NULL if there is no such event. +The client must not modify the contents of the returned event. + + + + + +Merging Exposure Events into a Region + +The Intrinsics provide an + +utility function that merges +Expose +and +GraphicsExpose +events into a region for clients to process at once +rather than processing individual rectangles. +For further information about regions, +see +in +Xlib — C Language X Interface.. + + + +To merge +Expose +and +GraphicsExpose +events into a region, use +. + + + + +void XtAddExposureToRegion + XEvent *event + Region region + + + + + + + event + + + +Specifies a pointer to the +Expose +or +GraphicsExpose +event. + + + + + + region + + + +Specifies the region object (as defined in +<X11/Xutil.h>). + + + + + + +The + +function computes the union of the rectangle defined by the exposure +event and the specified region. +Then it stores the results back in region. +If the event argument is not an +Expose +or +GraphicsExpose +event, + +returns without an error and without modifying region. + + + +This function is used by the exposure compression mechanism; +see + + + + +Translating Widget Coordinates + +To translate an x-y coordinate pair from widget coordinates to root +window absolute coordinates, use +. + + + + +void XtTranslateCoords + Widget w + Position x + Position *rootx_return + + + + + + + w + + + +Specifies the widget. Must be of class RectObj or any subclass thereof. + + + + + + x + + + + + + + + y + + + +Specify the widget-relative x and y coordinates. + + + + + + rootx_return + + + + + + + + rooty_return + + + +Return the root-relative x and y coordinates. + + + + + + +While + +is similar to the Xlib +XTranslateCoordinates +function, it does not generate a server request because all the required +information already is in the widget's data structures. + + + + +Translating a Window to a Widget + +To translate a given window and display pointer into a widget instance, use +. + + + + +Widget XtWindowToWidget + Display *display + Window window + + + + + + + display + + + +Specifies the display on which the window is defined. + + + + + + window + + + +Specifies the drawable for which you want the widget. + + + + + + +If there is a realized widget whose window is the specified drawable on +the specified display, + +returns that widget. +If not and if the drawable has been associated with a widget through +, + +returns the widget associated with the drawable. In other cases it +returns NULL. + + + + +Handling Errors + +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. + + + +Two levels of interface are provided: + + + + +A high-level interface that takes an error +name and class and retrieves the error message text from +an error resource database. + + + + +A low-level interface that takes a simple string to display. + + + + +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. + + + +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. + + + + +To obtain the error database (for example, to merge with +an application- or widget-specific database), use +. + + + + XrmDatabase *XtAppGetErrorDatabase + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context. + + + + + + +The + +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 +. + + + +For a complete listing of all errors and warnings +that can be generated by the Intrinsics, see + + + +The high-level error and warning handler procedure pointers are of type +. + + + + +typedef void (*XtErrorMsgHandler) + String name + String type + String class + String defaultp + String *params + Cardinal *num_params + + + + + + + name + + + +Specifies the name to be concatenated with the specified type to form +the resource name of the error message. + + + + + + type + + + +Specifies the type to be concatenated with the name to form the +resource name of the error message. + + + + + + class + + + +Specifies the resource class of the error message. + + + + + + defaultp + + + +Specifies the default message to use if no error database entry is found. + + + + + + params + + + +Specifies a pointer to a list of parameters to be substituted in the message. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +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 +printf +notation is used to substitute the parameters into the message. + + + +An error message handler can obtain the error database text for an +error or a warning by calling +. + + + + +void XtAppGetErrorDatabaseText + XtAppContext app_context + String name + String default + String buffer_return + int nbytes + XrmDatabase database + + + + + + + app_context + + + +Specifies the application context. + + + + + + name + + + type + + + +Specify the name and type concatenated to form the resource name +of the error message. + + + + + + class + + + +Specifies the resource class of the error message. + + + + + + default + + + +Specifies the default message to use if an error database entry is not found. + + + + + + buffer_return + + + +Specifies the buffer into which the error message is to be returned. + + + + + + nbytes + + + +Specifies the size of the buffer in bytes. + + + + + + database + + + +Specifies the name of the alternative database to be used, +or NULL if the application context's error database is to be used. + + + + + + +The + +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 name and type are concatenated with a single "." +between them and the class is concatenated with itself with a +single "." if it does not already contain a ".". + + + +To return the application name and class as passed to + +for a particular Display, use +. + + + + +void XtGetApplicationNameAndClass + Display* display + String* name_return + String* class_return + + + + + + + display + + + +Specifies an open display connection that has been initialized with +. + + + + + + name_return + + + +Returns the application name. + + + + + + class_return + + + +Returns the application class. + + + + + + + +returns the application name and class passed to + +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. + + + +To register a procedure to be called on fatal error conditions, use +. + + + + +XtErrorMsgHandler XtAppSetErrorMsgHandler + XtAppContext app_context + XtErrorMsgHandler msg_handler + + + + + + + app_context + + + +Specifies the application context. + + + + + + msg_handler + + + +Specifies the new fatal error procedure, which should not return. + + + + + + + +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 +_XtDefaultErrorMsg +and constructs a string from the error resource database and calls +. +Fatal error message handlers should not return. +If one does, +subsequent Intrinsics behavior is undefined. + + + +To call the high-level error handler, use +. + + + + +void XtAppErrorMsg + XtAppContext app_context + String name + String type + String class + String default + String *params + Cardinal *num_params + + + + + + + app_context + + + +Specifies the application context. + + + + + + name + + + +Specifies the general kind of error. + + + + + + type + + + +Specifies the detailed name of the error. + + + + + + class + + + +Specifies the resource class. + + + + + + default + + + +Specifies the default message to use if an error database entry is not found. + + + + + + params + + + +Specifies a pointer to a list of values to be stored in the message. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +The Intrinsics internal errors all have class +"XtToolkitError". + + + +To register a procedure to be called on nonfatal error conditions, use +. + + + + +XtErrorMsgHandler XtAppSetWarningMsgHandler + XtAppContext app_context + XtErrorMsgHandler msg_handler + + + + + + + app_context + + + +Specifies the application context. + + + + + + msg_handler + + + +Specifies the new nonfatal error procedure, which usually returns. + + + + + + + +returns a pointer to the previously +installed high-level warning handler. +The default high-level warning handler provided by the Intrinsics is named +_XtDefaultWarningMsg +and constructs a string +from the error resource database and calls +. + + + +To call the installed high-level warning handler, use +. + + + + +void XtAppWarningMsg + XtAppContext app_context + String name + String type + String class + String default + String *params + Cardinal *num_params + + + + + + + app_context + + + +Specifies the application context. + + + + + + name + + + +Specifies the general kind of error. + + + + + + type + + + +Specifies the detailed name of the error. + + + + + + class + + + +Specifies the resource class. + + + + + + default + + + +Specifies the default message to use if an error database entry is not found. + + + + + + params + + + +Specifies a pointer to a list of values to be stored in the message. + + + + + + num_params + + + +Specifies the number of entries in params. + + + + + + +The Intrinsics internal warnings all have class +"XtToolkitError". + + + +The low-level error and warning handler procedure pointers are of type +. + + + + +typedef void (*XtErrorHandler) + String message + + + + + + + message + + + +Specifies the error message. + + + + + + +The error handler should display the message string in some appropriate fashion. + + + +To register a procedure to be called on fatal error conditions, use +. + + + + +XtErrorHandler XtAppSetErrorHandler + XtAppContext app_context + XtErrorHandler handler + + + + + + + app_context + + + +Specifies the application context. + + + + + + handler + + + +Specifies the new fatal error procedure, which should not return. + + + + + + + +returns a pointer to the previously installed +low-level fatal error handler. +The default low-level error handler provided by the Intrinsics is +_XtDefaultError. +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. + + + +To call the installed fatal error procedure, use +. + + + + +void XtAppError + XtAppContext app_context + String message + + + + + + + app_context + + + +Specifies the application context. + + + + + + message + + + +Specifies the message to be reported. + + + + + + +Most programs should use +, +not +, +to provide for customization and internationalization of error messages. + + + +To register a procedure to be called on nonfatal error conditions, use +. + + + + +XtErrorHandler XtAppSetWarningHandler + XtAppContext app_context + XtErrorHandler handler + + + + + + + app_context + + + +Specifies the application context. + + + + + + handler + + + +Specifies the new nonfatal error procedure, which usually returns. + + + + + + + +returns a pointer to the previously installed +low-level warning handler. +The default low-level warning handler provided by the Intrinsics is +_XtDefaultWarning. +On POSIX-based systems, +it prints the message to standard error and returns to the caller. + + + +To call the installed nonfatal error procedure, use +. + + + + +void XtAppWarning + XtAppContext app_context + String message + + + + + + + app_context + + + +Specifies the application context. + + + + + + message + + + +Specifies the nonfatal error message to be reported. + + + + + + +Most programs should use +, +not +, +to provide for customization and internationalization of warning messages. + + + + +Setting WM_COLORMAP_WINDOWS + +A client may set the value of the WM_COLORMAP_WINDOWS +property on a widget's window by calling +. + + + + +void XtSetWMColormapWindows + Widget widget + Widget* list + Cardinal count + + + + + + + widget + + + +Specifies the widget on whose window the WM_COLORMAP_WINDOWS +property is stored. Must be of class Core or any subclass thereof. + + + + + + list + + + +Specifies a list of widgets whose windows are potentially to be +listed in the WM_COLORMAP_WINDOWS property. + + + + + + count + + + +Specifies the number of widgets in list. + + + + + + + +returns immediately if widget is not realized or if count is 0. +Otherwise, + +constructs an ordered list of windows +by examining each widget in list 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. + + + +Finally, + +stores the resulting window list in the WM_COLORMAP_WINDOWS +property on the specified widget's window. +Refer to Section 4.1.8 in the Inter-Client Communication Conventions Manual. for details of +the semantics of the WM_COLORMAP_WINDOWS property. + + + + +Finding File Names + +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: + +and +. + +uses an arbitrary set of client-specified substitutions, and + +uses a set of standard substitutions corresponding +to the X/Open Portability Guide language localization conventions. +Most applications should use +. + + + +A string substitution is defined by a list of +Substitution +entries. + + +typedef struct { + char match; + String substitution; +} SubstitutionRec, *Substitution; + + +File name evaluation is handled in an operating-system-dependent +fashion by an + +procedure. + + + + +typedef Boolean (*XtFilePredicate) + String filename + + + + + + + filename + + + +Specifies a potential filename. + + + + + + +A file predicate procedure is called with a string that is +potentially a file name. It should return +True +if this string specifies a file that is appropriate for the intended use and +False +otherwise. + + + +To search for a file using substitutions in a path list, use +. + + + + +String XtFindFile + String path + Substitution substitutions + Cardinal num_substitutions + XtFilePredicate predicate + + + + + + + path + + + +Specifies a path of file names, including substitution characters. + + + + + + substitutions + + + +Specifies a list of substitutions to make into the path. + + + + + + num_substitutions + + + +Specifies the number of substitutions passed in. + + + + + + predicate + + + +Specifies a procedure called to judge each potential file name, or NULL. + + + + + + +The path 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, + +looks through the +specified substitutions for that character in the match field +and, if found, +replaces the percent and match characters with the string in the +corresponding substitution field. A substitution 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, + +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 + +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 +True; +this string is the return value for +. +If no string yields a +True +return from the predicate, + +returns NULL. + + + +If the predicate parameter is NULL, an internal procedure that checks +if the file exists, is readable, and is not a directory is used. + + + +It is the responsibility of the caller to free the returned string using + +when it is no longer needed. + + + +To search for a file using standard substitutions in a path list, use +. + + + + +String XtResolvePathname + Display *display + String type + Substitution substitutions + Cardinal num_substitutions + XtFilePredicate predicate + + + + + + + display + + + +Specifies the display to use to find the language for language substitutions. + + + + + + type + + + + + + + + + filename + + + + + + + + suffix + + + +Specify values to substitute into the path. + + + + + + path + + + +Specifies the list of file specifications, or NULL. + + + + + + substitutions + + + +Specifies a list of additional substitutions to make into the path, or NULL. + + + + + + num_substitutions + + + +Specifies the number of entries in substitutions. + + + + + + predicate + + + +Specifies a procedure called to judge each potential file name, or NULL. + + + + + + +The substitutions specified by + +are determined from the value of the language string retrieved by + +for the specified display. +To set the +language for all applications specify "*xnlLanguage: lang" 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. + + + + + +calls + +with the following substitutions +in addition to any passed by the caller and returns the value returned by +: + + + + + + + +%N + + + +The value of the filename parameter, or the application's +class name if filename is NULL. + + + + + +%T + + + +The value of the type parameter. + + + + + +%S + + + +The value of the suffix parameter. + + + + + +%L + + + +The language string associated with the specified display. + + + + + +%l + + + +The language part of the display's language string. + + + + + +%t + + + +The territory part of the display's language string. + + + + + +%c + + + +The codeset part of the display's language string. + + + + + +%C + + + +The customization string retrieved from the resource +database associated with display. + + + + + +%D + + + +The value of the implementation-specific default path. + + + + + + + + +If a path is passed to +, +it is passed along to +. +If the path argument is NULL, the value of the +XFILESEARCHPATH +environment variable is passed to +. +If XFILESEARCHPATH +is not defined, an implementation-specific default path is used +that contains at least six entries. These entries +must contain the following substitutions: + + + + + + +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 + + + +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, %N%S is inserted between them. + + + +The type 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". + + + +The suffix parameter is intended to be appended to the file name. +Possible values might include ".txt", ".dat", and ".bm". + + + +A suggested value for the default path on POSIX-based systems is + + + /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 + + + + +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 type +parameter is used as a subdirectory of the language directory or of +/usr/lib/X11, and suffix is appended to the file name. + + + +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 +XFILESEARCHPATH +to + + + %D:ourdir/%T/%N%C:ourdir/%T/%N + + + +The customization string is obtained by querying the resource database +currently associated with the display (the database returned by +XrmGetDatabase) +for the resource application_name.customization, class +application_class.Customization, where application_name +and application_class are the values returned by +. +If no value is specified in the database, the empty string is used. + + + +It is the responsibility of the caller to free the returned string using + +when it is no longer needed. + + + + + + +Hooks for External Agents + +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. + + + +To retrieve the hook registration widget, use +. + + + + +Widget XtHooksOfDisplay + Display *display + + + + + + + display + + + +Specifies the desired display. + + + + + + +The class of this object is a private, implementation-dependent +subclass of +Object. +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. + + + +The following procedures can be called with the hook registration object +as an argument: + + + + +, +, +, +, +, +, +, + + + + + +, +XtSuperclass, +, +, +XtIsObject, +XtIsRectObj, +XtIsWidget, +XtIsComposite, +XtIsConstraint, +XtIsShell, +XtIsOverrideShell, +XtIsWMShell, +XtIsVendorShell, +XtIsTransientShell, +XtIsToplevelShell, +XtIsApplicationShell, +XtIsSessionShell + + + + + + + + + +, +XtParent, +, + + + + + +, +, +, + + + + + + +Hook Object Resources + +The resource names, classes, and representation types that are specified +in the hook object resource list are: + + + + + + + + + Name + Class + Representation + + + + + XtNcreateHook + XtCCallback + XtRCallback + + + XtNchangeHook + XtCCallback + XtRCallback + + + XtNconfigureHook + XtCCallback + XtRCallback + + + XtNgeometryHook + XtCCallback + XtRCallback + + + XtNdestroyHook + XtCCallback + XtRCallback + + + XtNshells + XtCReadOnly + XtRWidgetList + + + XtNnumShells + XtCReadOnly + XtRCardinal + + + + + + + +Descriptions of each of these resources: + + + +The XtNcreateHook callback list is called from: +, +, +, +, +and their corresponding varargs versions. + + + +The call_data parameter in a createHook callback may be +cast to type +XtCreateHookData. + + +typedef struct { + String type; + Widget widget; + ArgList args; + Cardinal num_args; +} XtCreateHookDataRec, *XtCreateHookData; + + +The type is set to +XtHcreate, +widget is the newly created widget, and args and num_args +are the arguments passed to the create function. The callbacks are +called before returning from the create function. + + + +The XtNchangeHook callback list is called from: + + + + +, + + + + + +, +, +, + + + + + +, + + + + + +, +, +XtAddCallbacks, +, + + + + + +, +, + + + + + +, + + + + + +, +, + + + + + +, +, + + + + + + +The call_data parameter in a changeHook callback may +be cast to type +XtChangeHookData. + + +typedef struct { + String type; + Widget widget; + XtPointer event_data; + Cardinal num_event_data; +} XtChangeHookDataRec, *XtChangeHookData; + + +When the changeHook callbacks are called as a result of a call to + +or +, +type is set to +XtHsetValues, +widget is the new widget passed to the set_values procedure, and +event_data may be cast to type +XtChangeHookSetValuesData. + + +typedef struct { + Widget old, req; + ArgList args; + Cardinal num_args; +} XtChangeHookSetValuesDataRec, *XtChangeHookSetValuesData; + + +The old, req, args, and num_args 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. + + + +When the changeHook callbacks are called as a result of a call to + +or +, +type is set to +XtHmanageChildren, +widget is the parent, event_data may be cast to type +WidgetList and is the list of children being managed, and +num_event_data is the length of the widget list. +The callbacks are called after the children have been managed. + + + +When the changeHook callbacks are called as a result of a call to + +or +, +type is set to +XtHunmanageChildren, +widget is the parent, event_data may be cast to type +WidgetList and is a list of the children being unmanaged, and +num_event_data is the length of the widget list. +The callbacks are called after the children have been unmanaged. + + + +The changeHook callbacks are called twice as a result of a call to +, +once after unmanaging and again after managing. +When the callbacks are called the first time, type is set to +XtHunmanageSet, +widget is the parent, event_data may be cast to type +WidgetList and is a list of the children being unmanaged, and +num_event_data is the length of the widget list. +When the callbacks are called the second time, the type is set to +XtHmanageSet, +widget is the parent, event_data may be cast to type +WidgetList and is a list of the children being managed, and +num_event_data is the length of the widget list. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHrealizeWidget +and widget is the widget being realized. +The callbacks are called after the widget has been realized. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHunrealizeWidget, +and widget is the widget being unrealized. +The callbacks are called after the widget has been unrealized. + + + +When the changeHook callbacks are called as a result of a call to +, +type is set to +XtHaddCallback, +widget is the widget to which the callback is being added, and +event_data 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. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHaddCallbacks, +widget is the widget to which the callbacks are being added, and +event_data 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. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHremoveCallback, +widget is the widget from which the callback is being removed, and +event_data 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. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHremoveCallbacks, +widget is the widget from which the callbacks are being removed, and +event_data 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. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHremoveAllCallbacks +and widget is the widget from which the callbacks are being removed. +The callbacks are called after the callbacks have been removed from the +widget. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHaugmentTranslations +and widget is the widget whose translations are being modified. +The callbacks are called after the widget's translations have been +modified. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHoverrideTranslations +and widget is the widget whose translations are being modified. +The callbacks are called after the widget's translations have been +modified. + + + +When the changeHook callbacks are called as a result of a call to +, +The type is +XtHuninstallTranslations +and widget is the widget whose translations are being uninstalled. +The callbacks are called after the widget's translations have been +uninstalled. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHsetKeyboardFocus +and event_data may be cast to type Widget and is the value of +the descendant argument passed to . The +callbacks are called before returning from . + + + +When the changeHook callbacks are called as a result of a call to +, +type is set to +XtHsetWMColormapWindows, +event_data may be cast to type WidgetList and is the value of +the list argument passed to , and +num_event_data is the length of the list. The callbacks are +called before returning from . + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHsetMappedWhenManaged +and event_data may be cast to type Boolean and is the value of +the mapped_when_managed argument passed to . +The callbacks are called after setting the widget's mapped_when_managed +field and before realizing or unrealizing the widget. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHmapWidget +and widget is the widget being mapped. +The callbacks are called after mapping the widget. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHunmapWidget +and widget is the widget being unmapped. +The callbacks are called after unmapping the widget. + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHpopup, +widget is the widget being popped up, and event_data may +be cast to type XtGrabKind and is the value of the grab_kind argument +passed to . +The callbacks are called before returning from . + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHpopupSpringLoaded +and widget is the widget being popped up. +The callbacks are called +before returning from . + + + +When the changeHook callbacks are called as a result of a call to +, +the type is set to +XtHpopdown +and widget is the widget being popped down. +The callbacks are called +before returning from . + + + +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: + + + + XtCallCallbacks(XtHooksOfDisplay(dpy), XtNchangeHook, call_data); + + +The XtNconfigureHook callback list is called any time the Intrinsics +move, resize, or configure a widget and when + +is called. + + + +The call_data parameter may be cast to type +XtConfigureHookData. + + +typedef struct { + String type; + Widget widget; + XtGeometryMask changeMask; + XWindowChanges changes; +} XtConfigureHookDataRec, *XtConfigureHookData; + + +When the configureHook callbacks are called, the type is +XtHconfigure, +widget is the widget being configured, and changeMask and +changes reflect the changes made to the widget. The callbacks +are called after changes have been made to the widget. + + + +The XtNgeometryHook callback list is called from + +and + +once before and once after geometry negotiation occurs. + + + +The call_data parameter may be cast to type +XtGeometryHookData. + + + +typedef struct { + String type; + Widget widget; + XtWidgetGeometry* request; + XtWidgetGeometry* reply; + XtGeometryResult result; +} XtGeometryHookDataRec, *XtGeometryHookData; + + +When the geometryHook callbacks are called prior to geometry negotiation, +the type is +XtHpreGeometry, +widget is the widget for which the request is being made, and +request is the requested geometry. +When the geometryHook callbacks +are called after geometry negotiation, the type is +XtHpostGeometry, +widget is the widget for which the request was made, request +is the requested geometry, reply is the resulting geometry granted, +and result is the value returned from the geometry negotiation. + + + +The XtNdestroyHook callback list is called when a widget is destroyed. +The call_data parameter may be cast to type +XtDestroyHookData. + + +typedef struct { + String type; + Widget widget; +} XtDestroyHookDataRec, *XtDestroyHookData; + + +When the destroyHook callbacks are called as a result of a call to +, +the type is +XtHdestroy +and widget is the widget being destroyed. The callbacks are +called upon completion of phase one destroy for a widget. + + + +The XtNshells and XtnumShells are read-only resources that report a +list of all parentless shell widgets associated with a display. + + + +Clients who use these hooks must exercise caution in calling Intrinsics +functions in order to avoid recursion. + + + + +Querying Open Displays + +To retrieve a list of the Displays associated with an application context, +use +. + + + + +void XtGetDisplays + XtAppContext app_context + Display ***dpy_return + Cardinal *num_dpy_return + + + + + + + app_context + + + +Specifies the application context. + + + + + + dpy_return + + + +Returns a list of open Display connections in the specified application +context. + + + + + + num_dpy_return + + + +Returns the count of open Display connections in dpy_return. + + + + + + + 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 +. + + + + + -- cgit v1.2.3