diff options
Diffstat (limited to 'libXt/specs/CH08')
| -rw-r--r-- | libXt/specs/CH08 | 452 |
1 files changed, 452 insertions, 0 deletions
diff --git a/libXt/specs/CH08 b/libXt/specs/CH08 new file mode 100644 index 000000000..6dfb5290b --- /dev/null +++ b/libXt/specs/CH08 @@ -0,0 +1,452 @@ +.\" $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 |