svn merge ^/branches/released .

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