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/CH08.xml | 613 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 613 insertions(+) create mode 100644 libXt/specs/CH08.xml (limited to 'libXt/specs/CH08.xml') diff --git a/libXt/specs/CH08.xml b/libXt/specs/CH08.xml new file mode 100644 index 000000000..2f24e6555 --- /dev/null +++ b/libXt/specs/CH08.xml @@ -0,0 +1,613 @@ + +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 destroy_callbacks +list is called to notify clients of the widget's impending doom. + + + +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. + + + +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. + + +Using Callback Procedure and Callback List Definitions + +Callback procedure pointers for use in callback lists are of type +. + + + + +typedef void (*XtCallbackProc) + Widget w + XtPointer client_data + XtPointer call_data + + + + + + + w + + + +Specifies the widget owning the list in which the callback is registered. + + + + + + client_data + + + +Specifies additional data supplied by the client when the procedure +was registered. + + + + + + call_data + + + +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. + + + + + + +The client_data 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 client_data value may be NULL +if all necessary information is in the widget. +The call_data argument is a convenience to avoid having simple +cases where the client could otherwise always call + +or a widget-specific function to retrieve data from the widget. +Widgets should generally avoid putting complex state information +in call_data. +The client can use the more general data retrieval methods, if necessary. + + + +Whenever a client wants to pass a callback list as an argument in an +, +, +or + +call, it should specify the address +of a NULL-terminated array of type +XtCallbackList. + + +typedef struct { + XtCallbackProc callback; + XtPointer closure; +} XtCallbackRec, *XtCallbackList; + + +For example, the callback list for procedures A and B with client data +clientDataA and clientDataB, respectively, is + + +static XtCallbackRec callbacks[] = { + {A, (XtPointer) clientDataA}, + {B, (XtPointer) clientDataB}, + {(XtCallbackProc) NULL, (XtPointer) NULL} +}; + + +Although callback lists are passed by address in arglists +and varargs lists, +the Intrinsics 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 Intrinsics automatically do this, +potentially using a different structure for their +internal representation. + + + + +Identifying Callback Lists + +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 + +check +to see that the requested callback list is indeed implemented by the widget. + + + +For the Intrinsics to find and correctly handle callback lists, +they must be declared with a resource type of +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 +XtCallbackStatus +XtCallbackHasNone ), +access to callback list resources must be made +through other Intrinsics procedures. + + + + +Adding Callback Procedures + +To add a callback procedure to a widget's callback list, use +. + + + + +void XtAddCallback + Widget w + String callback_name + XtCallbackProc callback + XtPointer client_data + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list to which the procedure is to be appended. + + + + + + callback + + + +Specifies the callback procedure. + + + + + + client_data + + + +Specifies additional data to be passed to the specified procedure +when it is invoked, +or NULL. + + + + + + +A callback will be invoked as many times as it occurs in the callback list. + + + +To add a list of callback procedures to a given widget's callback list, use +. + + + + +void XtAddCallbacks + Widget w + String callback_name + XtCallbackList callbacks + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list to which the procedures are to be appended. + + + + + + callbacks + + + +Specifies the null-terminated list of callback procedures and corresponding +client data. + + + + + + + + + +Removing Callback Procedures + +To delete a callback procedure from a widget's callback list, use +. + + + + +void XtRemoveCallback + Widget w + String callback_name + XtCallbackProc callback + XtPointer client_data + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list from which the procedure is to be deleted. + + + + + + callback + + + +Specifies the callback procedure. + + + + + + client_data + + + +Specifies the client data to match with the registered callback entry. + + + + + + +The + +function removes a callback only if both the procedure and the client +data match. + + + +To delete a list of callback procedures from a given widget's callback list, use +. + + + + +void XtRemoveCallbacks + Widget w + String callback_name + XtCallbackList callbacks + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list from which the procedures are to be deleted. + + + + + + callbacks + + + +Specifies the null-terminated list of callback procedures and corresponding +client data. + + + + + + +To delete all callback procedures from a given widget's callback list +and free all storage associated with the callback list, use +. + + + + +void XtRemoveAllCallbacks + Widget w + String callback_name + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list to be cleared. + + + + + + + + + +Executing Callback Procedures + +To execute the procedures in a given widget's callback list, +specifying the callback list by resource name, use +. + + + + +void XtCallCallbacks + Widget w + String callback_name + XtPointer call_data + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list to be executed. + + + + + + call_data + + + +Specifies a callback-list-specific data value to pass to each of the callback +procedure in the list, or NULL. + + + + + + + + +calls each of the callback procedures in the list +named by callback_name in the specified widget, passing the client +data registered with the procedure and call-data. + + + +To execute the procedures in a callback list, specifying the callback +list by address, use +. + + + + +void XtCallCallbackList + Widget widget + XtCallbackList callbacks + XtPointer call_data + + + + + + + widget + + + +Specifies the widget instance that contains the callback list. Must be of class Object or any subclass thereof. + + + + + + callbacks + + + +Specifies the callback list to be executed. + + + + + + call_data + + + +Specifies a callback-list-specific data value to pass +to each of the callback procedures in the list, or NULL. + + + + + + +The callbacks parameter must specify the contents of a widget or +object resource declared with representation type +XtRCallback. +If callbacks is NULL, + +returns immediately; otherwise it calls each of the callback +procedures in the list, passing the client data and call_data. + + + + +Checking the Status of a Callback List + +To find out the status of a given widget's callback list, use +. + + + +typedef enum {XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome} XtCallbackStatus; + + + + +XtCallbackStatus XtHasCallbacks + Widget w + String callback_name + + + + + + + w + + + +Specifies the widget. Must be of class Object or any subclass thereof. + + + + + + callback_name + + + +Specifies the callback list to be checked. + + + + + + +The + +function first checks to see if the widget has a callback list identified +by callback_name. +If the callback list does not exist, + +returns +XtCallbackNoList. +If the callback list exists but is empty, +it returns +XtCallbackHasNone. +If the callback list exists and has at least one callback registered, +it returns +XtCallbackHasSome. + + + -- cgit v1.2.3