453 lines
13 KiB
Plaintext
453 lines
13 KiB
Plaintext
.\" $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
|