aboutsummaryrefslogtreecommitdiff
path: root/libXt/specs/CH08
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2012-04-10 15:05:45 +0200
committermarha <marha@users.sourceforge.net>2012-04-10 15:05:45 +0200
commit4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8 (patch)
tree3ddf28be6916dd5ea27837431b5be8c94017cd9a /libXt/specs/CH08
parent5564e91e3cf4ba5cb2fbebbc2d63d18f588016b8 (diff)
parent5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 (diff)
downloadvcxsrv-4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8.tar.gz
vcxsrv-4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8.tar.bz2
vcxsrv-4b35ef19b76849cbd854c3b6f92bbc1c2d50f2d8.zip
Merge remote-tracking branch 'origin/released'
Diffstat (limited to 'libXt/specs/CH08')
-rw-r--r--libXt/specs/CH08452
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