diff options
Diffstat (limited to 'libXt/specs/CH08')
| -rw-r--r-- | libXt/specs/CH08 | 452 |
1 files changed, 0 insertions, 452 deletions
diff --git a/libXt/specs/CH08 b/libXt/specs/CH08 deleted file mode 100644 index 6dfb5290b..000000000 --- a/libXt/specs/CH08 +++ /dev/null @@ -1,452 +0,0 @@ -.\" $Xorg: CH08,v 1.3 2000/08/17 19:42:46 cpqbld Exp $ -.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994 -.\" X Consortium -.\" -.\" Permission is hereby granted, free of charge, to any person obtaining -.\" a copy of this software and associated documentation files (the -.\" "Software"), to deal in the Software without restriction, including -.\" without limitation the rights to use, copy, modify, merge, publish, -.\" distribute, sublicense, and/or sell copies of the Software, and to -.\" permit persons to whom the Software is furnished to do so, subject to -.\" the following conditions: -.\" -.\" The above copyright notice and this permission notice shall be included -.\" in all copies or substantial portions of the Software. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR -.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -.\" OTHER DEALINGS IN THE SOFTWARE. -.\" -.\" Except as contained in this notice, the name of the X Consortium shall -.\" not be used in advertising or otherwise to promote the sale, use or -.\" other dealings in this Software without prior written authorization -.\" from the X Consortium. -.\" -.\" Copyright \(co 1985, 1986, 1987, 1988, 1991, 1994 -.\" Digital Equipment Corporation, Maynard, Massachusetts. -.\" -.\" Permission to use, copy, modify and distribute this documentation for any -.\" purpose and without fee is hereby granted, provided that the above copyright -.\" notice appears in all copies and that both that copyright notice and this -.\" permission notice appear in supporting documentation, and that the name of -.\" Digital not be used in in advertising or publicity pertaining -.\" to distribution of the software without specific, written prior permission. -.\" Digital makes no representations about the suitability of the -.\" software described herein for any purpose. -.\" It is provided ``as is'' without express or implied warranty. -.\" -\& -.sp 1 -.ce 3 -\s+1\fBChapter 8\fP\s-1 - -\s+1\fBCallbacks\fP\s-1 -.sp 2 -.nr H1 8 -.nr H2 0 -.nr H3 0 -.nr H4 0 -.nr H5 0 -.LP -.XS -Chapter 8 \(em Callbacks -.XE -.IN "Destroy Callbacks" -Applications and other widgets often need to register a procedure -with a widget that gets called under certain prespecified conditions. -For example, -when a widget is destroyed, -every procedure on the widget's \fIdestroy_callbacks\fP -list is called to notify clients of the widget's impending doom. -.LP -Every widget has an XtNdestroyCallbacks callback list resource. -Widgets can define additional callback lists as they see fit. -For example, the Pushbutton widget has a callback -list to notify clients when the button has been activated. -.LP -Except where otherwise noted, it is the intent that all Intrinsics -functions may be called at any time, including from within callback -procedures, action routines, and event handlers. - -.NH 2 -Using Callback Procedure and Callback List Definitions -.XS -\fB\*(SN Using Callback Procedure and Callback List Definitions\fP -.XE -.IN "XtCallbackList" -.IN "XtCallbackProc" -.LP -Callback procedure pointers for use in callback lists are of type -.PN XtCallbackProc . -.LP -.IN "XtCallbackProc" "" "@DEF@" -.sM -.FD 0 -typedef void (*XtCallbackProc)(Widget, XtPointer, XtPointer); -.br - Widget \fIw\fP; -.br - XtPointer \fIclient_data\fP; -.br - XtPointer \fIcall_data\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget owning the list in which the callback is registered. -.IP \fIclient_data\fP 1i -Specifies additional data supplied by the client when the procedure -was registered. -.IP \fIcall_data\fP 1i -Specifies any callback-specific data the widget wants to pass to the client. -For example, when Scrollbar executes its XtNthumbChanged callback list, -it passes the new position of the thumb. -.LP -.eM -The \fIclient_data\fP argument provides a way for the -client registering the callback procedure also to register client-specific data, -for example, a pointer to additional information about the widget, -a reason for invoking the callback, and so on. -The \fIclient_data\fP value may be NULL -if all necessary information is in the widget. -The \fIcall_data\fP argument is a convenience to avoid having simple -cases where the client could otherwise always call -.PN XtGetValues -or a widget-specific function to retrieve data from the widget. -Widgets should generally avoid putting complex state information -in \fIcall_data\fP. -The client can use the more general data retrieval methods, if necessary. -.LP -Whenever a client wants to pass a callback list as an argument in an -.PN XtCreateWidget , -.PN XtSetValues , -or -.PN XtGetValues -call, it should specify the address -of a NULL-terminated array of type -.PN XtCallbackList . -.IN "XtCallbackList" "" "@DEF@" -.IN "XtCallbackRec" "" "@DEF@" -.LP -.sM -.Ds 0 -.TA .5i 3i -.ta .5i 3i -typedef struct { - XtCallbackProc callback; - XtPointer closure; -} XtCallbackRec, *XtCallbackList; -.De -.LP -.eM -For example, the callback list for procedures A and B with client data -clientDataA and clientDataB, respectively, is -.LP -.KS -.Ds 5 -.TA .5i 3i -.ta .5i 3i -static XtCallbackRec callbacks[] = { - {A, (XtPointer) clientDataA}, - {B, (XtPointer) clientDataB}, - {(XtCallbackProc) NULL, (XtPointer) NULL} -}; -.De -.KE -.LP -Although callback lists are passed by address in arglists -and varargs lists, -the \*(xI recognize callback lists -through the widget resource list and will copy the contents -when necessary. -Widget initialize and set_values procedures -should not allocate memory for the callback list contents. -The \*(xI automatically do this, -potentially using a different structure for their -internal representation. - -.NH 2 -Identifying Callback Lists -.XS -\fB\*(SN Identifying Callback Lists\fP -.XE -.LP -Whenever a widget contains a callback list for use by clients, -it also exports in its public .h file the resource name of the callback list. -Applications and client widgets never access callback list fields directly. -Instead, they always identify the desired callback list by using the exported -resource name. -All the callback manipulation functions described in this chapter -except -.PN XtCallCallbackList -check -to see that the requested callback list is indeed implemented by the widget. -.LP -For the \*(xI to find and correctly handle callback lists, -they must be declared with a resource type of -.PN XtRCallback . -The internal representation of a callback list is -implementation-dependent; widgets may make no assumptions about the -value stored in this resource if it is non-NULL. Except to compare -the value to NULL (which is equivalent to -.PN XtCallbackStatus -.PN XtCallbackHasNone ), -access to callback list resources must be made -through other \*(xI procedures. - -.NH 2 -Adding Callback Procedures -.XS -\fB\*(SN Adding Callback Procedures\fP -.XE -.LP -To add a callback procedure to a widget's callback list, use -.PN XtAddCallback . -.LP -.IN "XtAddCallback" "" "@DEF@" -.sM -.FD 0 -void XtAddCallback(\fIw\fP, \fIcallback_name, \fP\fIcallback\fP, \ -\fIclient_data\fP) -.br - Widget \fIw\fP; -.br - String \fIcallback_name\fP; -.br - XtCallbackProc \fIcallback\fP; -.br - XtPointer \fIclient_data\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. \*(oI -.IP \fIcallback_name\fP 1i -Specifies the callback list to which the procedure is to be appended. -.IP \fIcallback\fP 1i -Specifies the callback procedure. -.IP \fIclient_data\fP 1i -Specifies additional data to be passed to the specified procedure -when it is invoked, -or NULL. -.LP -.eM -A callback will be invoked as many times as it occurs in the callback list. -.sp -.LP -To add a list of callback procedures to a given widget's callback list, use -.PN XtAddCallbacks . -.LP -.IN "XtAddCallbacks" "" "@DEF@" -.sM -.FD 0 -void XtAddCallbacks(\fIw\fP, \fIcallback_name, \fP\fIcallbacks\fP) -.br - Widget \fIw\fP; -.br - String \fIcallback_name\fP; -.br - XtCallbackList \fIcallbacks\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. \*(oI -.IP \fIcallback_name\fP 1i -Specifies the callback list to which the procedures are to be appended. -.IP \fIcallbacks\fP 1i -Specifies the null-terminated list of callback procedures and corresponding -client data. -.LP -.eM -.NH 2 -Removing Callback Procedures -.XS -\fB\*(SN Removing Callback Procedures\fP -.XE -.LP -To delete a callback procedure from a widget's callback list, use -.PN XtRemoveCallback . -.LP -.IN "XtRemoveCallback" "" "@DEF@" -.sM -.FD 0 -void XtRemoveCallback(\fIw\fP, \fIcallback_name\fP, \fIcallback\fP, \ -\fIclient_data\fP) -.br - Widget \fIw\fP; -.br - String \fIcallback_name\fP; -.br - XtCallbackProc \fIcallback\fP; -.br - XtPointer \fIclient_data\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. \*(oI -.IP \fIcallback_name\fP 1i -Specifies the callback list from which the procedure is to be deleted. -.IP \fIcallback\fP 1i -Specifies the callback procedure. -.IP \fIclient_data\fP 1i -Specifies the client data to match with the registered callback entry. -.LP -.eM -The -.PN XtRemoveCallback -function removes a callback only if both the procedure and the client -data match. -.sp -.LP -To delete a list of callback procedures from a given widget's callback list, use -.PN XtRemoveCallbacks . -.LP -.IN "XtRemoveCallbacks" "" "@DEF@" -.sM -.FD 0 -void XtRemoveCallbacks(\fIw\fP, \fIcallback_name\fP, \fIcallbacks\fP) -.br - Widget \fIw\fP; -.br - String \fIcallback_name\fP; -.br - XtCallbackList \fIcallbacks\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. \*(oI -.IP \fIcallback_name\fP 1i -Specifies the callback list from which the procedures are to be deleted. -.IP \fIcallbacks\fP 1i -Specifies the null-terminated list of callback procedures and corresponding -client data. -.LP -.eM -To delete all callback procedures from a given widget's callback list -and free all storage associated with the callback list, use -.PN XtRemoveAllCallbacks . -.LP -.IN "XtRemoveAllCallbacks" "" "@DEF@" -.sM -.FD 0 -void XtRemoveAllCallbacks(\fIw\fP, \fIcallback_name\fP) -.br - Widget \fIw\fP; -.br - String \fIcallback_name\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. \*(oI -.IP \fIcallback_name\fP 1i -Specifies the callback list to be cleared. -.LP -.eM -.NH 2 -Executing Callback Procedures -.XS -\*(SN Executing Callback Procedures -.XE -.LP -To execute the procedures in a given widget's callback list, -specifying the callback list by resource name, use -.PN XtCallCallbacks . -.LP -.IN "XtCallCallbacks" "" "@DEF@" -.sM -.FD 0 -void XtCallCallbacks(\fIw\fP, \fIcallback_name\fP, \fIcall_data\fP) -.br - Widget \fIw\fP; -.br - String \fIcallback_name\fP; -.br - XtPointer \fIcall_data\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. \*(oI -.IP \fIcallback_name\fP 1i -Specifies the callback list to be executed. -.IP \fIcall_data\fP 1i -Specifies a callback-list-specific data value to pass to each of the callback -procedure in the list, or NULL. -.LP -.eM -.LP -.PN XtCallCallbacks -calls each of the callback procedures in the list -named by \fIcallback_name\fP in the specified widget, passing the client -data registered with the procedure and \fIcall-data\fP. -.sp -.LP -To execute the procedures in a callback list, specifying the callback -list by address, use -.PN XtCallCallbackList . -.LP -.IN "XtCallCallbackList" "" "@DEF@" -.sM -.FD 0 -void XtCallCallbackList(\fIwidget\fP, \fIcallbacks\fP, \fIcall_data\fP) -.br - Widget \fIwidget\fP; -.br - XtCallbackList \fIcallbacks\fP; -.br - XtPointer \fIcall_data\fP; -.FN -.IP \fIwidget\fP 1i -Specifies the widget instance that contains the callback list. \*(oI -.IP \fIcallbacks\fP 1i -Specifies the callback list to be executed. -.IP \fIcall_data\fP 1i -Specifies a callback-list-specific data value to pass -to each of the callback procedures in the list, or NULL. -.LP -.eM -The \fIcallbacks\fP parameter must specify the contents of a widget or -object resource declared with representation type -.PN XtRCallback . -If \fIcallbacks\fP is NULL, -.PN XtCallCallbackList -returns immediately; otherwise it calls each of the callback -procedures in the list, passing the client data and \fIcall_data\fP. - -.NH 2 -Checking the Status of a Callback List -.XS -\*(SN Checking the Status of a Callback List -.XE -.LP -To find out the status of a given widget's callback list, use -.PN XtHasCallbacks . -.LP -.IN "XtHasCallbacks" "" "@DEF@" -.sp -.sM -.FD 0 -typedef enum {XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome} \ -XtCallbackStatus; -.sp -XtCallbackStatus XtHasCallbacks(\fIw\fP, \fIcallback_name\fP) -.br - Widget \fIw\fP; -.br - String \fIcallback_name\fP; -.FN -.IP \fIw\fP 1i -Specifies the widget. \*(oI -.IP \fIcallback_name\fP 1i -Specifies the callback list to be checked. -.LP -.eM -The -.PN XtHasCallbacks -function first checks to see if the widget has a callback list identified -by \fIcallback_name\fP. -If the callback list does not exist, -.PN XtHasCallbacks -returns -.PN XtCallbackNoList . -If the callback list exists but is empty, -it returns -.PN XtCallbackHasNone . -If the callback list exists and has at least one callback registered, -it returns -.PN XtCallbackHasSome . -.bp |