3556 lines
94 KiB
Plaintext
3556 lines
94 KiB
Plaintext
.\" $Xorg: CH07,v 1.4 2000/08/17 19:42:45 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 7\fP\s-1
|
|
|
|
\s+1\fBEvent Management\fP\s-1
|
|
.sp 2
|
|
.nr H1 7
|
|
.nr H2 0
|
|
.nr H3 0
|
|
.nr H4 0
|
|
.nr H5 0
|
|
.LP
|
|
.XS
|
|
Chapter 7 \(em Event Management
|
|
.XE
|
|
While Xlib allows the reading and processing of events anywhere in an application,
|
|
widgets in the \*(tk neither directly read events
|
|
nor grab the server or pointer.
|
|
Widgets register procedures that are to be called
|
|
when an event or class of events occurs in that widget.
|
|
.LP
|
|
A typical application consists of startup code followed by an event loop
|
|
that reads events and dispatches them by calling
|
|
the procedures that widgets have registered.
|
|
The default event loop provided by the \*(xI is
|
|
.PN XtAppMainLoop .
|
|
.LP
|
|
The event manager is a collection of functions to perform the following tasks:
|
|
.IP \(bu 5
|
|
Add or remove event sources other than X server events (in particular,
|
|
timer interrupts, file input, or POSIX signals).
|
|
.IP \(bu 5
|
|
Query the status of event sources.
|
|
.IP \(bu 5
|
|
Add or remove procedures to be called when an event occurs for a particular
|
|
widget.
|
|
.IP \(bu 5
|
|
Enable and
|
|
disable the dispatching of user-initiated events (keyboard and pointer events)
|
|
for a particular widget.
|
|
.IP \(bu 5
|
|
Constrain the dispatching of events to a cascade of pop-up widgets.
|
|
.IP \(bu 5
|
|
Register procedures to be called when specific events arrive.
|
|
.IP \(bu 5
|
|
Register procedures to be called when the \*(xI will block.
|
|
.IP \(bu 5
|
|
Enable safe operation in a multi-threaded environment.
|
|
.LP
|
|
Most widgets do not need to call any of the event handler functions explicitly.
|
|
The normal interface to X events is through the higher-level
|
|
translation manager,
|
|
which maps sequences of X events, with modifiers, into procedure calls.
|
|
Applications rarely use any of the event manager routines besides
|
|
.PN XtAppMainLoop .
|
|
|
|
.NH 2
|
|
Adding and Deleting Additional Event Sources
|
|
.XS
|
|
\fB\*(SN Adding and Deleting Additional Event Sources\fP
|
|
.XE
|
|
.LP
|
|
While most applications are driven only by X events,
|
|
some applications need to incorporate other sources of input
|
|
into the \*(xI event-handling mechanism.
|
|
The event manager provides routines to integrate notification of timer events
|
|
and file data pending into this mechanism.
|
|
.LP
|
|
The next section describes functions that provide input gathering from files.
|
|
The application registers the files with the \*(xI read routine.
|
|
When input is pending on one of the files,
|
|
the registered callback procedures are invoked.
|
|
|
|
.NH 3
|
|
Adding and Removing Input Sources
|
|
.XS
|
|
\fB\*(SN Adding and Removing Input Sources\fP
|
|
.XE
|
|
.LP
|
|
To register a new file as an input source for a given application context, use
|
|
.PN XtAppAddInput .
|
|
.LP
|
|
.IN "XtAppAddInput" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtInputId XtAppAddInput(\fIapp_context\fP, \fIsource\fP, \fIcondition\fP, \
|
|
\fIproc\fP, \fIclient_data\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.br
|
|
int \fIsource\fP;
|
|
.br
|
|
XtPointer \fIcondition\fP;
|
|
.br
|
|
XtInputCallbackProc \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context that identifies the application.
|
|
.IP \fIsource\fP 1i
|
|
Specifies the source file descriptor on a POSIX-based system
|
|
or other operating-system-dependent device specification.
|
|
.IP \fIcondition\fP 1i
|
|
Specifies the mask that indicates a read, write, or exception condition
|
|
or some other operating-system-dependent condition.
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to be called when the condition is found.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies an argument passed to the specified procedure
|
|
when it is called.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtAppAddInput
|
|
function registers with the \*(xI read routine a new source of events,
|
|
which is usually file input but can also be file output.
|
|
Note that \fIfile\fP should be loosely interpreted to mean any sink
|
|
or source of data.
|
|
.PN XtAppAddInput
|
|
also specifies the conditions under which the source can generate events.
|
|
When an event is pending on this source,
|
|
the callback procedure is called.
|
|
.LP
|
|
The legal values for the \fIcondition\fP argument are operating-system-dependent.
|
|
On a POSIX-based system,
|
|
\fIsource\fP is a file number and the condition is some union of the following:
|
|
.IN "XtInputReadMask" "" "@DEF@"
|
|
.IP \fBXtInputReadMask\fR 1.5i
|
|
Specifies that \fIproc\fP is to be called when \fIsource\fP has data to be read.
|
|
.IN "XtInputWriteMask" "" "@DEF@"
|
|
.IP \fBXtInputWriteMask\fR 1.5i
|
|
Specifies that \fIproc\fP is to be called when \fIsource\fP is ready
|
|
for writing.
|
|
.IN "XtInputExceptMask" "" "@DEF@"
|
|
.IP \fBXtInputExceptMask\fR 1.5i
|
|
Specifies that \fIproc\fP is to be called when \fIsource\fP has
|
|
exception data.
|
|
.LP
|
|
Callback procedure pointers used to handle file events are of
|
|
type
|
|
.PN XtInputCallbackProc .
|
|
.LP
|
|
.IN "XtInputCallbackProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtInputCallbackProc)(XtPointer, int*, XtInputId*);
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.br
|
|
int *\fIsource\fP;
|
|
.br
|
|
XtInputId *\fIid\fP;
|
|
.FN
|
|
.IP \fIclient_data\fP 1i
|
|
Passes the client data argument that was registered for this procedure in
|
|
.PN XtApp\%AddInput .
|
|
.IP \fIsource\fP 1i
|
|
Passes the source file descriptor generating the event.
|
|
.IP \fIid\fP 1i
|
|
Passes the id returned from the corresponding
|
|
.PN XtAppAddInput
|
|
call.
|
|
.LP
|
|
.eM
|
|
See Section 7.12 for information regarding the use of
|
|
.PN XtAppAddInput
|
|
in multiple threads.
|
|
.sp
|
|
.LP
|
|
To discontinue a source of input, use
|
|
.PN XtRemoveInput .
|
|
.LP
|
|
.IN "XtRemoveInput" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRemoveInput(\fIid\fP)
|
|
.br
|
|
XtInputId \fIid\fP;
|
|
.FN
|
|
.IP \fIid\fP 1i
|
|
Specifies the id returned from the corresponding
|
|
.PN XtAppAddInput
|
|
call.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtRemoveInput
|
|
function causes the \*(xI read routine to stop watching for events
|
|
from the file source specified by \fIid\fP.
|
|
.LP
|
|
See Section 7.12 for information regarding the use of
|
|
.PN XtRemoveInput
|
|
in multiple threads.
|
|
|
|
.NH 3
|
|
Adding and Removing Blocking Notifications
|
|
.XS
|
|
\fB\*(SN Adding and Removing Blocking Notifications\fP
|
|
.XE
|
|
.LP
|
|
Occasionally it is desirable for an application to receive notification
|
|
when the \*(xI event manager detects no pending input from file sources
|
|
and no pending input from X server event sources and is about to block
|
|
in an operating system call.
|
|
.sp
|
|
.LP
|
|
To register a hook that is called immediately prior to event blocking, use
|
|
.PN XtAppAddBlockHook .
|
|
.LP
|
|
.IN "XtAppAddBlockHook" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtBlockHookId XtAppAddBlockHook(\fIapp_context\fP, \fIproc\fP, \
|
|
\fIclient_data\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.br
|
|
XtBlockHookProc \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context that identifies the application.
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to be called before blocking.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies an argument passed to the specified procedure when it is called.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtAppAddBlockHook
|
|
function registers the specified procedure and returns an identifier for it.
|
|
The hook procedure \fIproc\fP is called at any time in the future when
|
|
the \*(xI are about to block pending some input.
|
|
.LP
|
|
The procedure pointers used to provide notification of event blocking
|
|
are of type
|
|
.PN XtBlockHookProc .
|
|
.LP
|
|
.IN "XtBlockHookProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtBlockHookProc)(XtPointer);
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIclient_data\fP 1i
|
|
Passes the client data argument that was registered for this procedure in
|
|
.PN XtApp\%AddBlockHook .
|
|
.LP
|
|
.eM
|
|
To discontinue the use of a procedure for blocking notification, use
|
|
.PN XtRemoveBlockHook .
|
|
.LP
|
|
.IN "XtRemoveBlockHook" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRemoveBlockHook(\fIid\fP)
|
|
.br
|
|
XtBlockHookId \fIid\fP;
|
|
.FN
|
|
.IP \fIid\fP 1i
|
|
Specifies the identifier returned from the corresponding call to
|
|
.PN XtAppAddBlockHook .
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtRemoveBlockHook
|
|
function removes the specified procedure from the list of procedures
|
|
that are called by the \*(xI read routine before blocking on event sources.
|
|
|
|
.NH 3
|
|
Adding and Removing Timeouts
|
|
.XS
|
|
\fB\*(SN Adding and Removing Timeouts\fP
|
|
.XE
|
|
.LP
|
|
The timeout facility notifies the application or the widget
|
|
through a callback procedure that a specified time interval has elapsed.
|
|
Timeout values are uniquely identified by an interval id.
|
|
.sp
|
|
.LP
|
|
To register a timeout callback, use
|
|
.PN XtAppAddTimeOut .
|
|
.LP
|
|
.IN "XtAppAddTimeOut" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtIntervalId XtAppAddTimeOut(\fIapp_context\fP, \fIinterval\fP, \fIproc\fP, \
|
|
\fIclient_data\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.br
|
|
unsigned long \fIinterval\fP;
|
|
.br
|
|
XtTimerCallbackProc \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context for which the timer is to be set.
|
|
.IP \fIinterval\fP 1i
|
|
Specifies the time interval in milliseconds.
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to be called when the time expires.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies an argument passed to the specified procedure
|
|
when it is called.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtAppAddTimeOut
|
|
function creates a timeout and returns an identifier for it.
|
|
The timeout value is set to \fIinterval\fP.
|
|
The callback procedure \fIproc\fP is called when
|
|
.PN XtAppNextEvent
|
|
or
|
|
.PN XtAppProcessEvent
|
|
is next called after the time interval elapses,
|
|
and then the timeout is removed.
|
|
.LP
|
|
Callback procedure pointers used with timeouts are of
|
|
type
|
|
.PN XtTimerCallbackProc .
|
|
.LP
|
|
.IN "XtTimerCallbackProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtTimerCallbackProc)(XtPointer, XtIntervalId*);
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.br
|
|
XtIntervalId *\fItimer\fP;
|
|
.FN
|
|
.IP \fIclient_data\fP 1i
|
|
Passes the client data argument that was registered for this procedure in
|
|
.PN XtApp\%AddTimeOut .
|
|
.IP \fItimer\fP 1i
|
|
Passes the id returned from the corresponding
|
|
.PN XtAppAddTimeOut
|
|
call.
|
|
.LP
|
|
.eM
|
|
See Section 7.12 for information regarding the use of
|
|
.PN XtAppAddTimeOut
|
|
in multiple threads.
|
|
.sp
|
|
.LP
|
|
To clear a timeout value, use
|
|
.PN XtRemoveTimeOut .
|
|
.LP
|
|
.IN "XtRemoveTimeOut" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRemoveTimeOut(\fItimer\fP)
|
|
.br
|
|
XtIntervalId \fItimer\fP;
|
|
.FN
|
|
.IP \fItimer\fP 1i
|
|
Specifies the id for the timeout request to be cleared.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtRemoveTimeOut
|
|
function removes the pending timeout.
|
|
Note that timeouts are automatically removed once they trigger.
|
|
.LP
|
|
Please refer to Section 7.12 for information regarding the use of
|
|
.PN XtRemoveTimeOut
|
|
in multiple threads.
|
|
|
|
.NH 3
|
|
Adding and Removing Signal Callbacks
|
|
.XS
|
|
\fB\*(SN Adding and Removing Signal Callbacks\fP
|
|
.XE
|
|
.LP
|
|
The signal facility notifies the application or the widget through a
|
|
callback procedure that a signal or other external asynchronous event
|
|
has occurred. The registered callback procedures are uniquely identified
|
|
by a signal id.
|
|
.sp
|
|
.LP
|
|
Prior to establishing a signal handler, the application or widget should
|
|
call
|
|
.PN XtAppAddSignal
|
|
and store the resulting identifier in a place accessible to the signal
|
|
handler. When a signal arrives, the signal handler should call
|
|
.PN XtNoticeSignal
|
|
to notify the \*(xI that a signal has occured. To register a signal
|
|
callback use
|
|
.PN XtAppAddSignal .
|
|
.LP
|
|
.IN "XtAppAddSignal" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtSignalId XtAppAddSignal(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.br
|
|
XtSignalCallbackProc \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context that identifies the application.
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to be called when the signal is noticed.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies an argument passed to the specified procedure when it is called.
|
|
.LP
|
|
.eM
|
|
The callback procedure pointers used to handle signal events are of type
|
|
.PN XtSignalCallbackProc .
|
|
.LP
|
|
.IN "XtSignalCallbackProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtSignalCallbackProc)(XtPointer, XtSignalId*);
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.br
|
|
XtSignalId *\fIid\fP;
|
|
.FN
|
|
.IP \fIclient_data\fP 1i
|
|
Passes the client data argument that was registered for this procedure in
|
|
.PN XtAppAddSignal .
|
|
.IP \fIid\fP 1i
|
|
Passes the id returned from the corresponding
|
|
.PN XtAppAddSignal
|
|
call.
|
|
.LP
|
|
.eM
|
|
To notify the \*(xI that a signal has occured, use
|
|
.PN XtNoticeSignal .
|
|
.LP
|
|
.IN "XtNoticeSignal" "" "@DEF@"
|
|
.sp
|
|
.sM
|
|
.FD 0
|
|
void XtNoticeSignal(\fIid\fP)
|
|
.br
|
|
XtSignalId \fIid\fP;
|
|
.FN
|
|
.IP \fIid\fP 1i
|
|
Specifies the id returned from the corresponding
|
|
.PN XtAppAddSignal
|
|
call.
|
|
.LP
|
|
.eM
|
|
On a POSIX-based system,
|
|
.PN XtNoticeSignal
|
|
is the only \*(xI function that can safely be called from a signal handler.
|
|
If
|
|
.PN XtNoticeSignal
|
|
is invoked multiple times before the \*(xI are able to invoke the
|
|
registered callback, the callback is only called once.
|
|
Logically, the \*(xI maintain ``pending'' flag for each registered callback.
|
|
This flag is initially
|
|
.PN False
|
|
and is set to
|
|
.PN True
|
|
by
|
|
.PN XtNoticeSignal .
|
|
When
|
|
.PN XtAppNextEvent
|
|
or
|
|
.PN XtAppProcessEvent
|
|
(with a mask including
|
|
.PN XtIMSignal )
|
|
is called, all registered callbacks with ``pending''
|
|
.PN True
|
|
are invoked and the flags are reset to
|
|
.PN False .
|
|
.LP
|
|
If the signal handler wants to track how many times the signal has been
|
|
raised, it can keep its own private counter. Typically the handler would
|
|
not do any other work; the callback does the actual processing for the
|
|
signal. The \*(xI never block signals from being raised, so if a given
|
|
signal can be raised multiple times before the \*(xI can invoke the
|
|
callback for that signal, the callback must be designed to deal with
|
|
this. In another case, a signal might be raised just after the \*(xI
|
|
sets the pending flag to
|
|
.PN False
|
|
but before the callback can get control, in which case the pending flag
|
|
will still be
|
|
.PN True
|
|
after the callback returns, and the \*(xI will invoke the callback
|
|
again, even though all of the signal raises have been handled. The
|
|
callback must also be prepared to handle this case.
|
|
.LP
|
|
To remove a registered signal callback, call
|
|
.PN XtRemoveSignal .
|
|
.LP
|
|
.IN "XtRemoveSignal" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRemoveSignal(\fIid\fP)
|
|
.br
|
|
XtSignalId \fIid\fP;
|
|
.FN
|
|
.IP \fIid\fP 1i
|
|
Specifies the id returned by the corresponding call to
|
|
.PN XtAppAddSignal .
|
|
.LP
|
|
.eM
|
|
The client should typically disable the source of the signal before calling
|
|
.PN XtRemoveSignal .
|
|
If the signal could have been raised again before the source was disabled
|
|
and the client wants to process it, then after disabling the source but
|
|
before calling
|
|
.PN XtRemoveSignal
|
|
the client can test for signals with
|
|
.PN XtAppPending
|
|
and process them by calling
|
|
.PN XtAppProcessEvent
|
|
with the mask
|
|
.PN XtIMSignal .
|
|
|
|
.NH 2
|
|
Constraining Events to a Cascade of Widgets
|
|
.XS
|
|
\fB\*(SN Constraining Events to a Cascade of Widgets\fP
|
|
.XE
|
|
.LP
|
|
.IN "Grabbing Input"
|
|
.IN "Input Grabbing"
|
|
Modal widgets are widgets that, except for the input directed to them,
|
|
lock out user input to the application.
|
|
.LP
|
|
When a modal menu or modal dialog box is popped up using
|
|
.PN XtPopup ,
|
|
user events (keyboard and pointer events) that occur outside the modal
|
|
widget should be delivered to the modal widget or ignored.
|
|
In no case will user events be delivered to a widget outside
|
|
the modal widget.
|
|
.LP
|
|
Menus can pop up submenus, and dialog boxes can pop up further dialog
|
|
boxes to create a pop-up cascade.
|
|
In this case,
|
|
user events may be delivered to one of several modal widgets in the cascade.
|
|
.LP
|
|
Display-related events should be delivered outside the modal cascade so that
|
|
exposure events and the like keep the application's display up-to-date.
|
|
Any event that occurs within the cascade is delivered as usual.
|
|
The user events delivered to the most recent spring-loaded shell
|
|
in the cascade when they occur outside the cascade are called remap events
|
|
and are
|
|
.PN KeyPress ,
|
|
.PN KeyRelease ,
|
|
.PN ButtonPress ,
|
|
and
|
|
.PN ButtonRelease .
|
|
The user events ignored when they occur outside the cascade are
|
|
.PN MotionNotify
|
|
and
|
|
.PN EnterNotify .
|
|
All other events are delivered normally.
|
|
In particular, note that this is one
|
|
way in which widgets can receive
|
|
.PN LeaveNotify
|
|
events without first receiving
|
|
.PN EnterNotify
|
|
events; they should be prepared to deal with
|
|
this, typically by ignoring any unmatched
|
|
.PN LeaveNotify
|
|
events.
|
|
.LP
|
|
.PN XtPopup
|
|
uses the
|
|
.PN XtAddGrab
|
|
and
|
|
.PN XtRemoveGrab
|
|
functions to constrain user events to a modal cascade
|
|
and subsequently to remove a grab when the modal widget is popped down.
|
|
|
|
.sp
|
|
.LP
|
|
To constrain or redirect user input to a modal widget, use
|
|
.PN XtAddGrab .
|
|
.LP
|
|
.IN "XtAddGrab" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtAddGrab(\fIw\fP, \fIexclusive\fP, \fIspring_loaded\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
Boolean \fIexclusive\fP;
|
|
.br
|
|
Boolean \fIspring_loaded\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget to add to the modal cascade. \*(cI
|
|
.IP \fIexclusive\fP 1i
|
|
Specifies whether user events should be dispatched exclusively to this widget
|
|
or also to previous widgets in the cascade.
|
|
.IP \fIspring_loaded\fP 1i
|
|
Specifies whether this widget was popped up because the user pressed
|
|
a pointer button.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtAddGrab
|
|
function appends the widget to the modal cascade
|
|
and checks that \fIexclusive\fP is
|
|
.PN True
|
|
if \fIspring_loaded\fP is
|
|
.PN True .
|
|
If this condition is not met,
|
|
.PN XtAddGrab
|
|
generates a warning message.
|
|
.LP
|
|
The modal cascade is used by
|
|
.PN XtDispatchEvent
|
|
when it tries to dispatch a user event.
|
|
When at least one modal widget is in the widget cascade,
|
|
.PN XtDispatchEvent
|
|
first determines if the event should be delivered.
|
|
It starts at the most recent cascade entry and follows the cascade up to and
|
|
including the most recent cascade entry added with the \fIexclusive\fP parameter
|
|
.PN True .
|
|
.LP
|
|
This subset of the modal cascade along with all descendants of these widgets
|
|
comprise the active subset.
|
|
User events that occur outside the widgets in this subset are ignored
|
|
or remapped.
|
|
Modal menus with submenus generally add a submenu widget to the cascade
|
|
with \fIexclusive\fP
|
|
.PN False .
|
|
Modal dialog boxes that need to restrict user input to the most deeply nested
|
|
dialog box add a subdialog widget to the cascade with \fIexclusive\fP
|
|
.PN True .
|
|
User events that occur within the active subset are delivered to the
|
|
appropriate widget, which is usually a child or further descendant of the modal
|
|
widget.
|
|
.LP
|
|
Regardless of where in the application they occur,
|
|
remap events are always delivered to the most recent widget in the active
|
|
subset of the cascade registered with \fIspring_loaded\fP
|
|
.PN True ,
|
|
if any such widget exists.
|
|
If the event
|
|
occurred in the active subset of the cascade but outside the
|
|
spring-loaded widget, it is delivered normally before being
|
|
delivered also to the spring-loaded widget.
|
|
Regardless of where it is dispatched, the \*(xI do not modify
|
|
the contents of the event.
|
|
.sp
|
|
.LP
|
|
To remove the redirection of user input to a modal widget, use
|
|
.PN XtRemoveGrab .
|
|
.LP
|
|
.IN "XtRemoveGrab" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRemoveGrab(\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget to remove from the modal cascade.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtRemoveGrab
|
|
function removes widgets from the modal cascade starting
|
|
at the most recent widget up to and including the specified widget.
|
|
It issues a warning if the specified widget is not on the modal cascade.
|
|
|
|
.NH 3
|
|
Requesting Key and Button Grabs
|
|
.XS
|
|
\fB\*(SN Requesting Key and Button Grabs\fP
|
|
.XE
|
|
.LP
|
|
The \*(xI provide a set of key and button grab interfaces that
|
|
are parallel to those provided by Xlib and that allow the \*(xI
|
|
to modify event dispatching when necessary. \*(tk applications and
|
|
widgets that need to passively grab keys or buttons or actively grab
|
|
the keyboard or pointer should use the
|
|
following \*(xI routines rather than the corresponding Xlib
|
|
routines.
|
|
.sp
|
|
.LP
|
|
To passively grab a single key of the keyboard, use
|
|
.PN XtGrabKey .
|
|
.LP
|
|
.IN "XtGrabKey" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtGrabKey(\fIwidget\fP, \fIkeycode\fP, \fImodifiers\fP, \
|
|
\fIowner_events\fP, \fIpointer_mode\fP, \fIkeyboard_mode\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
KeyCode \fIkeycode\fP;
|
|
.br
|
|
Modifiers \fImodifiers\fP;
|
|
.br
|
|
Boolean \fIowner_events\fP;
|
|
.br
|
|
int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget in whose window the key is to be grabbed. \*(cI
|
|
.sp 6p
|
|
.IP \fIkeycode\fP
|
|
.br
|
|
.ns
|
|
.IP \fImodifiers\fP
|
|
.br
|
|
.ns
|
|
.IP \fIowner_events\fP
|
|
.br
|
|
.ns
|
|
.IP \fIpointer_mode\fP
|
|
.br
|
|
.ns
|
|
.IP \fIkeyboard_mode\fP 1i
|
|
Specify arguments to
|
|
.PN XGrabKey ;
|
|
see Section 12.2 in \fI\*(xL\fP.
|
|
.LP
|
|
.eM
|
|
.PN XtGrabKey
|
|
calls
|
|
.PN XGrabKey
|
|
specifying the widget's window as the grab
|
|
window if the widget is realized. The remaining arguments are exactly
|
|
as for
|
|
.PN XGrabKey .
|
|
If the widget is not realized, or is later unrealized, the call to
|
|
.PN XGrabKey
|
|
is performed (again) when
|
|
the widget is realized and its window becomes mapped. In the future,
|
|
if
|
|
.PN XtDispatchEvent
|
|
is called with a
|
|
.PN KeyPress
|
|
event matching the specified keycode and modifiers (which may be
|
|
.PN AnyKey
|
|
or
|
|
.PN AnyModifier ,
|
|
respectively) for the
|
|
widget's window, the \*(xI will call
|
|
.PN XtUngrabKeyboard
|
|
with the timestamp from the
|
|
.PN KeyPress
|
|
event if either of the following conditions is true:
|
|
.IP \(bu 3
|
|
There is a modal cascade and the widget is not in
|
|
the active subset of the cascade and the keyboard was not previously
|
|
grabbed, or
|
|
.IP \(bu 3
|
|
.PN XFilterEvent
|
|
returns
|
|
.PN True .
|
|
|
|
.sp
|
|
.LP
|
|
To cancel a passive key grab, use
|
|
.PN XtUngrabKey .
|
|
.LP
|
|
.IN "XtUngrabKey" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtUngrabKey(\fIwidget\fP, \fIkeycode\fP\fI, modifiers\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
KeyCode \fIkeycode\fP;
|
|
.br
|
|
Modifiers \fImodifiers\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget in whose window the key was grabbed.
|
|
.sp 6p
|
|
.IP \fIkeycode\fP
|
|
.br
|
|
.ns
|
|
.IP \fImodifiers\fP 1i
|
|
Specify arguments to
|
|
.PN XUngrabKey ;
|
|
see Section 12.2 in \fI\*(xL\fP.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtUngrabKey
|
|
procedure calls
|
|
.PN XUngrabKey
|
|
specifying the widget's
|
|
window as the ungrab window if the widget is realized. The remaining
|
|
arguments are exactly as for
|
|
.PN XUngrabKey .
|
|
If the widget is not realized,
|
|
.PN XtUngrabKey
|
|
removes a deferred
|
|
.PN XtGrabKey
|
|
request, if any, for the specified widget, keycode, and modifiers.
|
|
.sp
|
|
.LP
|
|
To actively grab the keyboard, use
|
|
.PN XtGrabKeyboard .
|
|
.LP
|
|
.IN "XtGrabKeyboard" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XtGrabKeyboard(\fIwidget\fP, \fIowner_events\fP, \fIpointer_mode\fP, \
|
|
\fIkeyboard_mode\fP, \fItime\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
Boolean \fIowner_events\fP;
|
|
.br
|
|
int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
|
|
.br
|
|
Time \fItime\fP;
|
|
.br
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget for whose window the keyboard is to be grabbed.
|
|
\*(cI
|
|
.sp 6p
|
|
.IP \fIowner_events\fP
|
|
.br
|
|
.ns
|
|
.IP \fIpointer_mode\fP
|
|
.br
|
|
.ns
|
|
.IP \fIkeyboard_mode\fP
|
|
.br
|
|
.ns
|
|
.IP \fItime\fP 1i
|
|
Specify arguments to
|
|
.PN XGrabKeyboard ;
|
|
see Section 12.2 in \fI\*(xL\fP.
|
|
.LP
|
|
.eM
|
|
If the specified widget is realized,
|
|
.PN XtGrabKeyboard
|
|
calls
|
|
.PN XGrabKeyboard
|
|
specifying the widget's window as the grab window. The remaining
|
|
arguments and return value are exactly as for
|
|
.PN XGrabKeyboard .
|
|
If the widget is not realized,
|
|
.PN XtGrabKeyboard
|
|
immediately returns
|
|
.PN GrabNotViewable .
|
|
No future automatic ungrab is implied by
|
|
.PN XtGrabKeyboard .
|
|
.sp
|
|
.LP
|
|
To cancel an active keyboard grab, use
|
|
.PN XtUngrabKeyboard .
|
|
.LP
|
|
.IN "XtUngrabKeyboard" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtUngrabKeyboard(\fIwidget\fP, \fItime\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
Time \fItime\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget that has the active keyboard grab.
|
|
.IP \fItime\fP 1i
|
|
Specifies the additional argument to
|
|
.PN XUngrabKeyboard ;
|
|
see Section 12.2 in \fI\*(xL\fP.
|
|
.LP
|
|
.eM
|
|
.PN XtUngrabKeyboard
|
|
calls
|
|
.PN XUngrabKeyboard
|
|
with the specified time.
|
|
.sp
|
|
.LP
|
|
To passively grab a single pointer button, use
|
|
.PN XtGrabButton .
|
|
.LP
|
|
.IN "XtGrabButton" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtGrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP, \
|
|
\fIowner_events\fP, \fIevent_mask\fP, \fIpointer_mode\fP,
|
|
\fIkeyboard_mode\fP, \fIconfine_to\fP, \fIcursor\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
int \fIbutton\fP;
|
|
.br
|
|
Modifiers \fImodifiers\fP;
|
|
.br
|
|
Boolean \fIowner_events\fP;
|
|
.br
|
|
unsigned int \fIevent_mask\fP;
|
|
.br
|
|
int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
|
|
.br
|
|
Window \fIconfine_to\fP;
|
|
.br
|
|
Cursor \fIcursor\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget in whose window the button is to be grabbed. \*(cI
|
|
.sp 6p
|
|
.IP \fIbutton\fP
|
|
.br
|
|
.ns
|
|
.IP \fImodifiers\fP
|
|
.br
|
|
.ns
|
|
.IP \fIowner_events\fP
|
|
.br
|
|
.ns
|
|
.IP \fIevent_mask\fP
|
|
.br
|
|
.ns
|
|
.IP \fIpointer_mode\fP
|
|
.br
|
|
.ns
|
|
.IP \fIkeyboard_mode\fP
|
|
.br
|
|
.ns
|
|
.IP \fIconfine_to\fP
|
|
.br
|
|
.ns
|
|
.IP \fIcursor\fP 1i
|
|
Specify arguments to
|
|
.PN XGrabButton ;
|
|
see Section 12.1 in \fI\*(xL\fP.
|
|
.LP
|
|
.eM
|
|
.PN XtGrabButton
|
|
calls
|
|
.PN XGrabButton
|
|
specifying the widget's window as the
|
|
grab window if the widget is realized. The remaining arguments are
|
|
exactly as for
|
|
.PN XGrabButton .
|
|
If the widget is not realized, or is later unrealized, the call to
|
|
.PN XGrabButton
|
|
is performed (again)
|
|
when the widget is realized and its window becomes mapped. In the
|
|
future, if
|
|
.PN XtDispatchEvent
|
|
is called with a
|
|
.PN ButtonPress
|
|
event matching the specified button and modifiers (which may be
|
|
.PN AnyButton
|
|
or
|
|
.PN AnyModifier ,
|
|
respectively)
|
|
for the widget's window, the \*(xI will call
|
|
.PN XtUngrabPointer
|
|
with the timestamp from the
|
|
.PN ButtonPress
|
|
event if either of the following conditions is true:
|
|
.IP \(bu 3
|
|
There is a modal cascade and the
|
|
widget is not in the active subset of the cascade and the pointer was
|
|
not previously grabbed, or
|
|
.IP \(bu 3
|
|
.PN XFilterEvent
|
|
returns
|
|
.PN True .
|
|
|
|
.sp
|
|
.LP
|
|
To cancel a passive button grab, use
|
|
.PN XtUngrabButton .
|
|
.LP
|
|
.IN "XtUngrabButton" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtUngrabButton(\fIwidget\fP, \fIbutton\fP, \fImodifiers\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
unsigned int \fIbutton\fP;
|
|
.br
|
|
Modifiers \fImodifiers\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget in whose window the button was grabbed.
|
|
.IP \fIbutton\fP
|
|
.br
|
|
.ns
|
|
.IP \fImodifiers\fP 1i
|
|
Specify arguments to
|
|
.PN XUngrabButton ;
|
|
see Section 12.1 in \fI\*(xL\fP.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtUngrabButton
|
|
procedure calls
|
|
.PN XUngrabButton
|
|
specifying the
|
|
widget's window as the ungrab window if the widget is realized. The
|
|
remaining arguments are exactly as for
|
|
.PN XUngrabButton .
|
|
If the widget is not realized,
|
|
.PN XtUngrabButton
|
|
removes a deferred
|
|
.PN XtGrabButton
|
|
request, if any, for the specified widget, button, and modifiers.
|
|
.sp
|
|
.LP
|
|
To actively grab the pointer, use
|
|
.PN XtGrabPointer .
|
|
.LP
|
|
.IN "XtGrabPointer" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
int XtGrabPointer(\fIwidget\fP, \fIowner_events\fP, \fIevent_mask\fP, \
|
|
\fIpointer_mode\fP, \fIkeyboard_mode\fP,
|
|
\fIconfine_to\fP, \fIcursor\fP, \fItime\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
Boolean \fIowner_events\fP;
|
|
.br
|
|
unsigned int \fIevent_mask\fP;
|
|
.br
|
|
int \fIpointer_mode\fP, \fIkeyboard_mode\fP;
|
|
.br
|
|
Window \fIconfine_to\fP;
|
|
.br
|
|
Cursor \fIcursor\fP;
|
|
.br
|
|
Time \fItime\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget for whose window the pointer is to be grabbed. \*(cI
|
|
.sp 6p
|
|
.IP \fIowner_events\fP
|
|
.br
|
|
.ns
|
|
.IP \fIevent_mask\fP
|
|
.br
|
|
.ns
|
|
.IP \fIpointer_mode\fP
|
|
.br
|
|
.ns
|
|
.IP \fIkeyboard_mode\fP
|
|
.br
|
|
.ns
|
|
.IP \fIconfine_to\fP
|
|
.br
|
|
.ns
|
|
.IP \fIcursor\fP
|
|
.br
|
|
.ns
|
|
.IP \fItime\fP 1i
|
|
Specify arguments to
|
|
.PN XGrabPointer ;
|
|
see Section 12.1 in \fI\*(xL\fP.
|
|
.LP
|
|
.eM
|
|
If the specified widget is realized,
|
|
.PN XtGrabPointer
|
|
calls
|
|
.PN XGrabPointer ,
|
|
specifying the widget's window as the grab window. The remaining
|
|
arguments and return value are exactly as for
|
|
.PN XGrabPointer .
|
|
If the widget is not realized,
|
|
.PN XtGrabPointer
|
|
immediately returns
|
|
.PN GrabNotViewable .
|
|
No future automatic ungrab is implied by
|
|
.PN XtGrabPointer .
|
|
.sp
|
|
.LP
|
|
To cancel an active pointer grab, use
|
|
.PN XtUngrabPointer .
|
|
.LP
|
|
.IN "XtUngrabPointer" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtUngrabPointer(\fIwidget\fP, \fItime\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
Time \fItime\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget that has the active pointer grab.
|
|
.IP \fItime\fP 1i
|
|
Specifies the time argument to
|
|
.PN XUngrabPointer ;
|
|
see Section 12.1 in \fI\*(xL\fP.
|
|
.LP
|
|
.eM
|
|
.PN XtUngrabPointer
|
|
calls
|
|
.PN XUngrabPointer
|
|
with the specified time.
|
|
|
|
.NH 2
|
|
Focusing Events on a Child
|
|
.XS
|
|
\fB\*(SN Focusing Events on a Child\fP
|
|
.XE
|
|
.LP
|
|
To redirect keyboard input to a normal descendant of a
|
|
widget without calling
|
|
.PN XSetInputFocus ,
|
|
use
|
|
.PN XtSetKeyboardFocus .
|
|
.LP
|
|
.IN "XtSetKeyboardFocus" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtSetKeyboardFocus(\fIsubtree\fP\, \fIdescendant\fP)
|
|
.br
|
|
Widget \fIsubtree\fP, \fIdescendant\fP;
|
|
.FN
|
|
.IP \fIsubtree\fP 1i
|
|
Specifies the subtree of the hierarchy for which the keyboard focus is
|
|
to be set. \*(cI
|
|
.IP \fIdescendant\fP 1i
|
|
Specifies either the normal (non-pop-up) descendant of \fIsubtree\fP to which
|
|
keyboard events are logically directed, or
|
|
.PN None .
|
|
It is not an error to specify
|
|
.PN None
|
|
when no input focus was previously set. \*(oI
|
|
.LP
|
|
.eM
|
|
.PN XtSetKeyboardFocus
|
|
causes
|
|
.PN XtDispatchEvent
|
|
to remap keyboard events occurring within the specified subtree
|
|
and dispatch them to the specified descendant widget or to an ancestor.
|
|
If the descendant's class is not a subclass of Core, the descendant is
|
|
replaced by its closest windowed ancestor.
|
|
.LP
|
|
When there is no modal cascade, keyboard events can be dispatched
|
|
to a widget in one of five ways. Assume the server delivered the
|
|
event to the window for widget E (because of X input focus, key or
|
|
keyboard grabs, or pointer position).
|
|
.IP \(bu 3
|
|
If neither E nor any of E's ancestors have redirected the keyboard
|
|
focus, or if the event activated a grab for E as specified by a call
|
|
to
|
|
.PN XtGrabKey
|
|
with any value of \fIowner_events\fP, or
|
|
if the keyboard is actively grabbed by E with \fIowner_events\fP
|
|
.PN False
|
|
via
|
|
.PN XtGrabKeyboard
|
|
or
|
|
.PN XtGrabKey
|
|
on a previous key press, the event is dispatched to E.
|
|
.IP \(bu 3
|
|
Beginning with the ancestor of E closest to the root that has
|
|
redirected the keyboard focus or E if no such ancestor exists, if
|
|
the target of that focus redirection has in turn redirected the
|
|
keyboard focus, recursively follow this focus chain to find a widget
|
|
F that has not redirected focus.
|
|
.RS
|
|
.IP \- 3
|
|
If E is the final focus target widget F or a descendant of F, the
|
|
event is dispatched to E.
|
|
.IP \- 3
|
|
If E is not F, an ancestor of F, or a descendant of F, and the event
|
|
activated a grab for E as specified by a call to
|
|
.PN XtGrabKey
|
|
for E,
|
|
.PN XtUngrabKeyboard
|
|
is called.
|
|
.IP \- 3
|
|
If E is an ancestor of F, and the event is a key press, and either
|
|
.RS
|
|
.IP + 3
|
|
E has grabbed the key with
|
|
.PN XtGrabKey
|
|
and \fIowner_events\fP
|
|
.PN False ,
|
|
or
|
|
.IP + 3
|
|
E has grabbed the key with
|
|
.PN XtGrabKey
|
|
and \fIowner_events\fP
|
|
.PN True ,
|
|
and the coordinates of the event are outside the rectangle specified
|
|
by E's geometry,
|
|
.RE
|
|
then the event is dispatched to E.
|
|
.IP \- 3
|
|
Otherwise, define A as the closest common ancestor of E and F:
|
|
.RS
|
|
.IP + 3
|
|
If there is an active keyboard grab for any widget via either
|
|
.PN XtGrabKeyboard
|
|
or
|
|
.PN XtGrabKey
|
|
on a previous key press, or
|
|
if no widget between F and A (noninclusive) has grabbed
|
|
the key and modifier combination with
|
|
.PN XtGrabKey
|
|
and any value of \fIowner_events\fP, the event is dispatched to F.
|
|
.IP + 3
|
|
Else, the event is dispatched to the ancestor of F closest to A
|
|
that has grabbed the key and modifier combination with
|
|
.PN XtGrabKey .
|
|
.RE
|
|
.RE
|
|
.LP
|
|
When there is a modal cascade, if the final destination widget as
|
|
identified above is in the active subset of the cascade, the event is
|
|
dispatched; otherwise the event is remapped to a spring-loaded shell
|
|
or discarded.
|
|
Regardless of where it is dispatched, the \*(xI do not modify
|
|
the contents of the event.
|
|
.LP
|
|
When \fIsubtree\fP or one of its descendants acquires the X input focus
|
|
or the pointer moves into the subtree such that keyboard events would
|
|
now be delivered to the subtree, a
|
|
.PN FocusIn
|
|
event is generated for the descendant if
|
|
.PN FocusChange
|
|
events have been selected by the descendant.
|
|
Similarly, when \fIsubtree\fP loses the X input focus
|
|
or the keyboard focus for one of its ancestors, a
|
|
.PN FocusOut
|
|
event is generated for descendant if
|
|
.PN FocusChange
|
|
events have been selected by the descendant.
|
|
.sp
|
|
.LP
|
|
A widget tree may also actively manage the X server input focus. To
|
|
do so, a widget class specifies an accept_focus procedure.
|
|
.LP
|
|
.IN "accept_focus procedure"
|
|
The accept_focus procedure pointer is of type
|
|
.PN XtAcceptFocusProc .
|
|
.LP
|
|
.IN "XtAcceptFocusProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef Boolean (*XtAcceptFocusProc)(Widget, Time*);
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
Time *\fItime\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget.
|
|
.IP \fItime\fP 1i
|
|
Specifies the X time of the event causing the accept focus.
|
|
.LP
|
|
.eM
|
|
Widgets that need the input focus can call
|
|
.PN XSetInputFocus
|
|
explicitly, pursuant to the restrictions of the \fI\*(xC\fP.
|
|
To allow outside agents, such as the parent,
|
|
to cause a widget to take the input focus,
|
|
every widget exports an accept_focus procedure.
|
|
The widget returns a value indicating
|
|
whether it actually took the focus or not,
|
|
so that the parent can give the focus to another widget.
|
|
Widgets that need to know when they lose the input focus must use
|
|
the Xlib focus notification mechanism explicitly
|
|
(typically by specifying translations for
|
|
.PN FocusIn
|
|
and
|
|
.PN FocusOut
|
|
events).
|
|
Widgets classes that never want the input focus should set the
|
|
\fIaccept_focus\fP field to NULL.
|
|
.sp
|
|
.LP
|
|
To call a widget's accept_focus procedure, use
|
|
.PN XtCallAcceptFocus .
|
|
.LP
|
|
.IN "XtCallAcceptFocus" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Boolean XtCallAcceptFocus(\fIw\fP, \fItime\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
Time *\fItime\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget. \*(cI
|
|
.IP \fItime\fP 1i
|
|
Specifies the X time of the event that is causing the focus change.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtCallAcceptFocus
|
|
function calls the specified widget's accept_focus procedure,
|
|
passing it the specified widget and time, and returns what the accept_focus
|
|
procedure returns.
|
|
If \fIaccept_focus\fP is NULL,
|
|
.PN XtCallAcceptFocus
|
|
returns
|
|
.PN False .
|
|
|
|
.NH 3
|
|
Events for Drawables That Are Not a Widget's Window
|
|
.XS
|
|
\fB\*(SN Events for Drawables That Are Not a Widget's Window\fP
|
|
.XE
|
|
.LP
|
|
Sometimes an application must handle events for drawables that are not
|
|
associated with widgets in its widget tree. Examples include handling
|
|
.PN GraphicsExpose
|
|
and
|
|
.PN NoExpose
|
|
events on Pixmaps, and handling
|
|
.PN PropertyNotify
|
|
events on the root window.
|
|
.LP
|
|
To register a drawable with the \*(xI event dispatching, use
|
|
.PN XtRegisterDrawable .
|
|
.LP
|
|
.IN "XtRegisterDrawable" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRegisterDrawable(\fIdisplay\fP, \fIdrawable\fP, \fIwidget\fP)
|
|
.br
|
|
Display *\fIdisplay\fP;
|
|
.br
|
|
Drawable \fIdrawable\fP;
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the drawable's display.
|
|
.IP \fIdrawable\fP 1i
|
|
Specifies the drawable to register.
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget to register the drawable for.
|
|
.LP
|
|
.eM
|
|
.PN XtRegisterDrawable
|
|
associates the specified drawable with the specified widget
|
|
so that future calls to
|
|
.PN XtWindowToWidget
|
|
with the drawable will return the widget.
|
|
The default event dispatcher will dispatch future events that
|
|
arrive for the drawable to the widget in the same manner as
|
|
events that contain the widget's window.
|
|
.LP
|
|
If the drawable is already registered with another widget, or if the
|
|
drawable is the window of a widget in the client's widget tree, the
|
|
results of calling
|
|
.PN XtRegisterDrawable
|
|
are undefined.
|
|
|
|
.LP
|
|
To unregister a drawable with the Intrinsics event dispatching, use
|
|
.PN XtUnregisterDrawable .
|
|
.LP
|
|
.IN "XtUnregisterDrawable" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtUnregisterDrawable(\fIdisplay\fP, \fIdrawable\fP)
|
|
.br
|
|
Display *\fIdisplay\fP;
|
|
.br
|
|
Drawable \fIdrawable\fP;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the drawable's display.
|
|
.IP \fIdrawable\fP 1i
|
|
Specifies the drawable to unregister.
|
|
.LP
|
|
.eM
|
|
.PN XtUnregisterDrawable
|
|
removes an association created with
|
|
.PN XtRegisterDrawable .
|
|
If the drawable is the window of a widget in the client's widget tree
|
|
the results of calling
|
|
.PN XtUnregisterDrawable
|
|
are undefined.
|
|
|
|
.NH 2
|
|
Querying Event Sources
|
|
.XS
|
|
\fB\*(SN Querying Event Sources\fP
|
|
.XE
|
|
.LP
|
|
The event manager provides several functions to examine and read events
|
|
(including file and timer events) that are in the queue.
|
|
The next three functions are \*(xI equivalents of the
|
|
.PN XPending ,
|
|
.PN XPeekEvent ,
|
|
and
|
|
.PN XNextEvent
|
|
Xlib calls.
|
|
.sp
|
|
.LP
|
|
.IN "Events"
|
|
To determine if there are any events on the input queue for a given application,
|
|
use
|
|
.PN XtAppPending .
|
|
.LP
|
|
.IN "XtAppPending" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtInputMask XtAppPending(\fIapp_context\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context that identifies the application to check.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtAppPending
|
|
function returns a nonzero value if there are
|
|
events pending from the X server, timer pending, other input sources
|
|
pending, or signal sources pending. The
|
|
value returned is a bit mask that is the OR of
|
|
.PN XtIMXEvent ,
|
|
.PN XtIMTimer ,
|
|
.PN XtIMAlternateInput ,
|
|
and
|
|
.PN XtIMSignal
|
|
(see
|
|
.PN XtAppProcessEvent ).
|
|
If there are no events pending,
|
|
.PN XtAppPending
|
|
flushes the output buffers of each Display in the application context
|
|
and returns zero.
|
|
.sp
|
|
.LP
|
|
To return the event from the head of a given application's input queue
|
|
without removing input from the queue, use
|
|
.PN XtAppPeekEvent .
|
|
.LP
|
|
.IN "XtAppPeekEvent" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Boolean XtAppPeekEvent(\fIapp_context\fP, \fIevent_return\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.br
|
|
XEvent *\fIevent_return\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context that identifies the application.
|
|
.IP \fIevent_return\fP 1i
|
|
Returns the event information to the specified event structure.
|
|
.LP
|
|
.eM
|
|
If there is an X event in the queue,
|
|
.PN XtAppPeekEvent
|
|
copies it into \fIevent_return\fP and returns
|
|
.PN True .
|
|
If no X input is on the queue,
|
|
.PN XtAppPeekEvent
|
|
flushes the output buffers of each Display in the application context
|
|
and blocks until some input is available
|
|
(possibly calling some timeout callbacks in the interim).
|
|
If the next available input is an X event,
|
|
.PN XtAppPeekEvent
|
|
fills in \fIevent_return\fP and returns
|
|
.PN True .
|
|
Otherwise, the input is for an input source
|
|
registered with
|
|
.PN XtAppAddInput ,
|
|
and
|
|
.PN XtAppPeekEvent
|
|
returns
|
|
.PN False .
|
|
.FS
|
|
The sample implementations provides XtAppPeekEvent as described. Timeout callbacks
|
|
are called while blocking for input. If some input for an input source is
|
|
available,
|
|
.PN XtAppPeekEvent
|
|
will return
|
|
.PN True
|
|
without returning an event.
|
|
.FE
|
|
.sp
|
|
.LP
|
|
To remove and return the event
|
|
from the head of a given application's X event queue,
|
|
use
|
|
.PN XtAppNextEvent .
|
|
.LP
|
|
.IN "XtAppNextEvent" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtAppNextEvent(\fIapp_context\fP, \fIevent_return\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.br
|
|
XEvent *\fIevent_return\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context that identifies the application.
|
|
.IP \fIevent_return\fP 1i
|
|
Returns the event information to the specified event structure.
|
|
.LP
|
|
.eM
|
|
If the X event queue is empty,
|
|
.PN XtAppNextEvent
|
|
flushes the X output buffers of each Display in the application context
|
|
and waits for an X event while looking at the other input sources
|
|
and timeout values and calling any callback procedures triggered by them.
|
|
This wait time can be used for background processing;
|
|
see Section 7.8.
|
|
|
|
.NH 2
|
|
Dispatching Events
|
|
.XS
|
|
\fB\*(SN Dispatching Events\fP
|
|
.XE
|
|
.LP
|
|
The \*(xI provide functions that dispatch events
|
|
to widgets or other application code.
|
|
Every client interested in X events on a widget uses
|
|
.PN XtAddEventHandler
|
|
to register which events it is
|
|
interested in and a procedure (event handler) to be called
|
|
when the event happens in that window.
|
|
The translation manager automatically registers event handlers for widgets
|
|
that use translation tables; see Chapter 10.
|
|
.sp
|
|
.LP
|
|
Applications that need direct control of the processing of different types
|
|
of input should use
|
|
.PN XtAppProcessEvent .
|
|
.LP
|
|
.IN "XtAppProcessEvent" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtAppProcessEvent(\fIapp_context\fP, \fImask\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.br
|
|
XtInputMask \fImask\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context that identifies the
|
|
application for which to process input.
|
|
.IP \fImask\fP 1i
|
|
Specifies what types of events to process.
|
|
The mask is the bitwise inclusive OR of any combination of
|
|
.PN XtIMXEvent ,
|
|
.PN XtIMTimer ,
|
|
.PN XtIMAlternateInput ,
|
|
and
|
|
.PN XtIMSignal .
|
|
As a convenience,
|
|
.PN Intrinsic.h
|
|
defines the symbolic name
|
|
.PN XtIMAll
|
|
to be the bitwise inclusive OR of these four event types.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtAppProcessEvent
|
|
function processes one timer, input source, signal source, or X event.
|
|
If there is no event or input of the appropriate type to process, then
|
|
.PN XtAppProcessEvent
|
|
blocks until there is.
|
|
If there is more than one type of input available to process,
|
|
it is undefined which will get processed.
|
|
Usually, this procedure is not called by client applications; see
|
|
.PN XtAppMainLoop .
|
|
.PN XtAppProcessEvent
|
|
processes timer events by calling any appropriate timer callbacks,
|
|
input sources by calling any appropriate input callbacks,
|
|
signal source by calling any appropriate signal callbacks,
|
|
and X events by
|
|
calling
|
|
.PN XtDispatchEvent .
|
|
.LP
|
|
When an X event is received,
|
|
it is passed to
|
|
.PN XtDispatchEvent ,
|
|
which calls the appropriate event handlers
|
|
and passes them the widget, the event, and client-specific data
|
|
registered with each procedure.
|
|
If no handlers for that event are registered,
|
|
the event is ignored and the dispatcher simply returns.
|
|
|
|
.sp
|
|
.LP
|
|
To dispatch an event returned by
|
|
.PN XtAppNextEvent ,
|
|
retrieved directly from the Xlib queue, or synthetically constructed,
|
|
to any registered event filters or event handlers, call
|
|
.PN XtDispatchEvent .
|
|
.LP
|
|
.IN "XtDispatchEvent" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Boolean XtDispatchEvent(\fIevent\fP)
|
|
.br
|
|
XEvent *\fIevent\fP;
|
|
.FN
|
|
.IP \fIevent\fP 1i
|
|
Specifies a pointer to the event structure to be dispatched
|
|
to the appropriate event handlers.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtDispatchEvent
|
|
function first calls
|
|
.PN XFilterEvent
|
|
with the \fIevent\fP and the window of the widget to which the
|
|
\*(xI intend to dispatch the event, or the event window if
|
|
the \*(xI would not dispatch the event to any handlers.
|
|
If
|
|
.PN XFilterEvent
|
|
returns
|
|
.PN True
|
|
and the event activated a server grab as identified
|
|
by a previous call to
|
|
.PN XtGrabKey
|
|
or
|
|
.PN XtGrabButton ,
|
|
.PN XtDispatchEvent
|
|
calls
|
|
.PN XtUngrabKeyboard
|
|
or
|
|
.PN XtUngrabPointer
|
|
with the timestamp from the event and immediately returns
|
|
.PN True .
|
|
If
|
|
.PN XFilterEvent
|
|
returns
|
|
.PN True
|
|
and a grab was not activated,
|
|
.PN XtDispatchEvent
|
|
just immediately returns
|
|
.PN True .
|
|
Otherwise,
|
|
.PN XtDispatchEvent
|
|
sends the event to the event handler functions that
|
|
have been previously registered with the dispatch routine.
|
|
.PN XtDispatchEvent
|
|
returns
|
|
.PN True
|
|
if
|
|
.PN XFilterEvent
|
|
returned
|
|
.PN True ,
|
|
or if the event was dispatched to some handler, and
|
|
.PN False
|
|
if it found no handler to which to dispatch the event.
|
|
.PN XtDispatchEvent
|
|
records the last timestamp in any event that
|
|
contains a timestamp (see
|
|
.PN XtLastTimestampProcessed ),
|
|
regardless of whether it was filtered or dispatched.
|
|
If a modal cascade is active with \fIspring_loaded\fP
|
|
.PN True ,
|
|
and if the event is a remap event as defined by
|
|
.PN XtAddGrab ,
|
|
.PN XtDispatchEvent
|
|
may dispatch the event a second time. If it does so,
|
|
.PN XtDispatchEvent
|
|
will call
|
|
.PN XFilterEvent
|
|
again with the window of the spring-loaded widget prior to the second
|
|
dispatch, and if
|
|
.PN XFilterEvent
|
|
returns
|
|
.PN True ,
|
|
the second dispatch will not be performed.
|
|
|
|
.NH 2
|
|
The Application Input Loop
|
|
.XS
|
|
\fB\*(SN The Application Input Loop\fP
|
|
.XE
|
|
.LP
|
|
To process all input from a given application in a continuous loop,
|
|
use the convenience procedure
|
|
.PN XtAppMainLoop .
|
|
.LP
|
|
.IN "XtAppMainLoop" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtAppMainLoop(\fIapp_context\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context that identifies the application.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtAppMainLoop
|
|
function first reads the next incoming X event by calling
|
|
.PN XtAppNextEvent
|
|
and then dispatches the event to the appropriate registered procedure
|
|
by calling
|
|
.PN XtDispatchEvent .
|
|
This constitutes the main loop of \*(tk applications.
|
|
There is nothing special about
|
|
.PN XtAppMainLoop ;
|
|
it simply calls
|
|
.PN XtAppNextEvent
|
|
and then
|
|
.PN XtDispatchEvent
|
|
in a conditional loop.
|
|
At the bottom of the loop, it checks to see if the specified
|
|
application context's destroy flag is set.
|
|
If the flag is set, the loop breaks.
|
|
The whole loop is enclosed between a matching
|
|
.PN XtAppLock
|
|
and
|
|
.PN XtAppUnlock .
|
|
.LP
|
|
Applications can provide their own version of this loop,
|
|
which tests some global termination flag or tests that the number
|
|
of top-level widgets is larger than zero before circling back to the call to
|
|
.PN XtAppNextEvent .
|
|
|
|
.NH 2
|
|
Setting and Checking the Sensitivity State of a Widget
|
|
.XS
|
|
\fB\*(SN Setting and Checking the Sensitivity State of a Widget\fP
|
|
.XE
|
|
.LP
|
|
Many widgets have a mode in which they assume a different appearance
|
|
(for example, are grayed out or stippled), do not respond to user events,
|
|
and become dormant.
|
|
.LP
|
|
When dormant,
|
|
a widget is considered to be insensitive.
|
|
If a widget is insensitive,
|
|
the event manager does not dispatch any events to the widget
|
|
with an event type of
|
|
.PN KeyPress ,
|
|
.PN KeyRelease ,
|
|
.PN ButtonPress ,
|
|
.PN ButtonRelease ,
|
|
.PN MotionNotify ,
|
|
.PN EnterNotify ,
|
|
.PN LeaveNotify ,
|
|
.PN FocusIn ,
|
|
or
|
|
.PN FocusOut .
|
|
.LP
|
|
A widget can be insensitive because its \fIsensitive\fP field is
|
|
.PN False
|
|
or because one of its ancestors is insensitive and thus the widget's
|
|
\fIancestor_sensitive\fP field also is
|
|
.PN False .
|
|
A widget can but does not need to distinguish these two cases visually.
|
|
.NT
|
|
Pop-up shells will have
|
|
\fIancestor_sensitive\fP
|
|
.PN False
|
|
if the parent was insensitive when the shell
|
|
was created. Since
|
|
.PN XtSetSensitive
|
|
on the parent will not
|
|
modify the resource of the pop-up child, clients are advised to include
|
|
a resource specification of the form
|
|
``*TransientShell.ancestorSensitive: True''
|
|
in the application defaults resource file or to
|
|
otherwise ensure that the parent is
|
|
sensitive when creating pop-up shells.
|
|
.NE
|
|
.sp
|
|
.LP
|
|
To set the sensitivity state of a widget, use
|
|
.PN XtSetSensitive .
|
|
.LP
|
|
.IN "XtSetSensitive" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtSetSensitive(\fIw\fP, \fIsensitive\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
Boolean \fIsensitive\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget. \*(rI
|
|
.IP \fIsensitive\fP 1i
|
|
Specifies whether the widget should receive
|
|
keyboard, pointer, and focus events.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtSetSensitive
|
|
function first calls
|
|
.PN XtSetValues
|
|
on the current widget with an argument list specifying the
|
|
XtNsensitive resource and the new value.
|
|
If \fIsensitive\fP is
|
|
.PN False
|
|
and the widget's class is a subclass of
|
|
Composite,
|
|
.PN XtSetSensitive
|
|
recursively propagates the new value
|
|
down the child tree by calling
|
|
.PN XtSetValues
|
|
on each child to set \fIancestor_sensitive\fP to
|
|
.PN False .
|
|
If \fIsensitive\fP is
|
|
.PN True
|
|
and the widget's class is a subclass of
|
|
Composite
|
|
and the widget's \fIancestor_sensitive\fP field is
|
|
.PN True ,
|
|
.PN XtSetSensitive
|
|
sets the \fIancestor_sensitive\fP of each child to
|
|
.PN True
|
|
and then recursively calls
|
|
.PN XtSetValues
|
|
on each normal descendant that is now sensitive to set
|
|
\fIancestor_sensitive\fP to
|
|
.PN True .
|
|
.LP
|
|
.PN XtSetSensitive
|
|
calls
|
|
.PN XtSetValues
|
|
to change the \fIsensitive\fP and \fIancestor_sensitive\fP fields
|
|
of each affected widget.
|
|
Therefore, when one of these changes,
|
|
the widget's set_values procedure should
|
|
take whatever display actions are needed
|
|
(for example, graying out or stippling the widget).
|
|
.LP
|
|
.PN XtSetSensitive
|
|
maintains the invariant that, if the parent has either \fIsensitive\fP
|
|
or \fIancestor_sensitive\fP
|
|
.PN False ,
|
|
then all children have \fIancestor_sensitive\fP
|
|
.PN False .
|
|
.sp
|
|
.LP
|
|
To check the current sensitivity state of a widget,
|
|
use
|
|
.PN XtIsSensitive .
|
|
.LP
|
|
.IN "XtIsSensitive" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Boolean XtIsSensitive(\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the object. \*(oI
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtIsSensitive
|
|
function returns
|
|
.PN True
|
|
or
|
|
.PN False
|
|
to indicate whether user input events are being dispatched.
|
|
If object's class is a subclass of RectObj and
|
|
both \fIsensitive\fP and \fIancestor_sensitive\fP are
|
|
.PN True ,
|
|
.PN XtIsSensitive
|
|
returns
|
|
.PN True ;
|
|
otherwise, it returns
|
|
.PN False .
|
|
|
|
.NH 2
|
|
Adding Background Work Procedures
|
|
.XS
|
|
\fB\*(SN Adding Background Work Procedures\fP
|
|
.XE
|
|
.LP
|
|
The \*(xI have some limited support for background processing.
|
|
Because most applications spend most of their time waiting for input,
|
|
you can register an idle-time work procedure
|
|
that is called when the toolkit would otherwise block in
|
|
.PN XtAppNextEvent
|
|
or
|
|
.PN XtAppProcessEvent .
|
|
Work procedure pointers are of type
|
|
.PN XtWorkProc .
|
|
.LP
|
|
.IN "XtWorkProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef Boolean (*XtWorkProc)(XtPointer);
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIclient_data\fP 1i
|
|
Passes the client data specified when the work procedure was registered.
|
|
.LP
|
|
.eM
|
|
This procedure should return
|
|
.PN True
|
|
when it is done to indicate that it
|
|
should be removed.
|
|
If the procedure returns
|
|
.PN False ,
|
|
it will remain registered and called again when the
|
|
application is next idle.
|
|
Work procedures should be very judicious about how much they do.
|
|
If they run for more than a small part of a second,
|
|
interactive feel is likely to suffer.
|
|
.sp
|
|
.LP
|
|
To register a work procedure for a given application, use
|
|
.PN XtAppAddWorkProc .
|
|
.LP
|
|
.IN "XtAppAddWorkProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtWorkProcId XtAppAddWorkProc(\fIapp_context\fP, \fIproc\fP, \fIclient_data\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.br
|
|
XtWorkProc \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context that identifies the application.
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to be called when the application is idle.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies the argument passed to the specified procedure
|
|
when it is called.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtAppAddWorkProc
|
|
function adds the specified work procedure for the application identified
|
|
by \fIapp_context\fP
|
|
and returns an opaque unique identifier for this work procedure.
|
|
Multiple work procedures can be registered,
|
|
and the most recently added one is always the one that is called.
|
|
However, if a work procedure adds another work procedure,
|
|
the newly added one has lower priority than the current one.
|
|
.sp
|
|
.LP
|
|
To remove a work procedure, either return
|
|
.PN True
|
|
from the procedure when it is called or use
|
|
.PN XtRemoveWorkProc
|
|
outside of the procedure.
|
|
.LP
|
|
.IN "XtRemoveWorkProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRemoveWorkProc(\fIid\fP)
|
|
.br
|
|
XtWorkProcId \fIid\fP;
|
|
.FN
|
|
.IP \fIid\fP 1i
|
|
Specifies which work procedure to remove.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtRemoveWorkProc
|
|
function explicitly removes the specified background work procedure.
|
|
|
|
.NH 2
|
|
X Event Filters
|
|
.XS
|
|
\*(SN X Event Filters
|
|
.XE
|
|
.LP
|
|
The event manager provides filters that can be applied to
|
|
specific X events.
|
|
The filters, which screen out events that are redundant or are temporarily
|
|
unwanted, handle
|
|
pointer motion compression,
|
|
enter/leave compression, and
|
|
exposure compression.
|
|
|
|
.NH 3
|
|
Pointer Motion Compression
|
|
.XS
|
|
\*(SN Pointer Motion Compression
|
|
.XE
|
|
.LP
|
|
Widgets can have a hard time keeping up with a rapid stream of
|
|
pointer motion events. Furthermore,
|
|
they usually do not care about every motion event. To throw out
|
|
redundant motion events, the widget class field \fIcompress_motion\fP should be
|
|
.PN True .
|
|
.IN "compress_motion field"
|
|
When a request for an event would return a motion event,
|
|
the \*(xI check if there are any other motion events
|
|
for the same widget immediately
|
|
following the current one and, if so, skip all but the last of them.
|
|
|
|
.NH 3
|
|
Enter/Leave Compression
|
|
.XS
|
|
\*(SN Enter/Leave Compression
|
|
.XE
|
|
.LP
|
|
To throw out pairs of enter and leave events that have no intervening events,
|
|
as can happen when the user moves the pointer across a widget
|
|
without stopping in it,
|
|
the widget class field \fIcompress_enterleave\fP should be
|
|
.PN True .
|
|
.IN "compress_enterleave field"
|
|
These enter and leave events are not delivered to the client
|
|
if they are found together in the input queue.
|
|
|
|
.NH 3
|
|
Exposure Compression
|
|
.XS
|
|
\*(SN Exposure Compression
|
|
.XE
|
|
.LP
|
|
.IN "compress_expose field"
|
|
Many widgets prefer to process a series of exposure events as a
|
|
single expose region rather than as individual rectangles. Widgets
|
|
with complex displays might use the expose region as a clip list
|
|
in a graphics context, and widgets with simple displays might
|
|
ignore the region entirely and redisplay their whole window or
|
|
might get the bounding box from the region and redisplay only that
|
|
rectangle.
|
|
.LP
|
|
In either case, these widgets do not care about getting partial exposure events.
|
|
The \fIcompress_exposure\fP field in the widget class
|
|
structure specifies the type and number of exposure events that are
|
|
dispatched to the widget's expose procedure. This field must be
|
|
initialized to one of the following values:
|
|
.sp
|
|
.sM
|
|
.Ds 0
|
|
.TA 3i
|
|
.ta 3i
|
|
#define XtExposeNoCompress ((XtEnum)False)
|
|
#define XtExposeCompressSeries ((XtEnum)True)
|
|
#define XtExposeCompressMultiple <implementation-defined>
|
|
#define XtExposeCompressMaximal <implementation-defined>
|
|
.De
|
|
.LP
|
|
.eM
|
|
optionally ORed with any combination of the following flags (all with
|
|
implementation-defined values):
|
|
.PN XtExposeGraphicsExpose ,
|
|
.PN XtExposeGraphicsExposeMerged ,
|
|
.PN XtExposeNoExpose ,
|
|
and
|
|
.PN XtExposeNoRegion .
|
|
|
|
.LP
|
|
If the \fIcompress_exposure\fP field in the widget class structure does not
|
|
specify
|
|
.PN XtExposeNoCompress ,
|
|
the event manager calls the widget's expose procedure only
|
|
once for a series of exposure events.
|
|
In this case, all
|
|
.PN Expose
|
|
or
|
|
.PN GraphicsExpose
|
|
events are accumulated into a region.
|
|
When the final event is received,
|
|
the event manager replaces the rectangle in the event with the
|
|
bounding box for the region
|
|
and calls the widget's expose procedure,
|
|
passing the modified exposure event and (unless
|
|
.PN XtExposeNoRegion
|
|
is specified) the region.
|
|
For more information on regions, see Section 16.5 in \fI\*(xL\fP.)
|
|
.LP
|
|
The values have the following interpretation:
|
|
.sp
|
|
.LP
|
|
.PN XtExposeNoCompress
|
|
.IN "XtExposeNoCompress" "" "@DEF@"
|
|
.IP
|
|
No exposure compression is performed; every selected event is
|
|
individually dispatched to the expose procedure with a \fIregion\fP
|
|
argument of NULL.
|
|
.sp
|
|
.LP
|
|
.PN XtExposeCompressSeries
|
|
.IN "XtExposeCompressSeries" "" "@DEF@"
|
|
.IP
|
|
Each series of exposure events is coalesced into a single event,
|
|
which is dispatched
|
|
when an exposure event with count equal to zero is reached.
|
|
.sp
|
|
.LP
|
|
.PN XtExposeCompressMultiple
|
|
.IN "XtExposeCompressMultiple" "" "@DEF@"
|
|
.IP
|
|
Consecutive series of exposure events are coalesced into a single
|
|
event, which is dispatched
|
|
when an exposure event with count equal to zero is reached and either
|
|
the event queue is empty or the next event is not an exposure event
|
|
for the same widget.
|
|
.sp
|
|
.LP
|
|
.PN XtExposeCompressMaximal
|
|
.IN "XtExposeCompressMaximal" "" "@DEF"
|
|
.IP
|
|
All expose series currently in the queue for the widget
|
|
are coalesced into a single
|
|
event without regard to intervening nonexposure events. If a
|
|
partial series is in the end of the queue, the \*(xI will
|
|
block until the end of the series is received.
|
|
.sp
|
|
.LP
|
|
The additional flags have the following meaning:
|
|
.sp
|
|
.LP
|
|
.PN XtExposeGraphicsExpose
|
|
.IN "XtExposeGraphicsExpose" "" "@DEF@"
|
|
.IP
|
|
Specifies that
|
|
.PN GraphicsExpose
|
|
events are also to be dispatched to
|
|
the expose procedure.
|
|
.PN GraphicsExpose
|
|
events are compressed, if specified, in the same manner as
|
|
.PN Expose
|
|
events.
|
|
.sp
|
|
.LP
|
|
.PN XtExposeGraphicsExposeMerged
|
|
.IN "XtExposeGraphicsExposeMerged" "" "@DEF@"
|
|
.IP
|
|
Specifies in the case of
|
|
.PN XtExposeCompressMultiple
|
|
and
|
|
.PN XtExposeCompressMaximal
|
|
that series of
|
|
.PN GraphicsExpose
|
|
and
|
|
.PN Expose
|
|
events are to be compressed together, with the final event type
|
|
determining the type of the event passed to the expose procedure.
|
|
If this flag is not set, then only series of the same event type
|
|
as the event at the head of the queue are coalesced. This flag
|
|
also implies
|
|
.PN XtExposeGraphicsExpose .
|
|
.sp
|
|
.LP
|
|
.PN XtExposeNoExpose
|
|
.IN "XtExposeNoExpose" "" "@DEF@"
|
|
.IP
|
|
Specifies that
|
|
.PN NoExpose
|
|
events are also to be dispatched to the expose procedure.
|
|
.PN NoExpose
|
|
events are never coalesced with
|
|
other exposure events or with each other.
|
|
.sp
|
|
.LP
|
|
.PN XtExposeNoRegion
|
|
.IN "XtExposeNoRegion" "" "@DEF"
|
|
.IP
|
|
Specifies that the final region argument passed to the expose
|
|
procedure is NULL. The rectangle in the event will still
|
|
contain bounding box information for the entire series of
|
|
compressed exposure events. This option saves processing time when the
|
|
region is not needed by the widget.
|
|
|
|
.NH 2
|
|
Widget Exposure and Visibility
|
|
.XS
|
|
\*(SN Widget Exposure and Visibility
|
|
.XE
|
|
.LP
|
|
Every primitive widget and some composite widgets display data on the screen
|
|
by means of direct Xlib calls.
|
|
Widgets cannot simply write to the screen and forget what they have done.
|
|
They must keep enough state to redisplay the window or parts
|
|
of it if a portion is obscured and then reexposed.
|
|
|
|
.NH 3
|
|
Redisplay of a Widget: The expose Procedure
|
|
.XS
|
|
\*(SN Redisplay of a Widget: The expose Procedure
|
|
.XE
|
|
.IN "expose procedure"
|
|
.LP
|
|
The expose procedure pointer in a widget class is of type
|
|
.PN XtExposeProc .
|
|
.LP
|
|
.IN "XtExposeProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtExposeProc)(Widget, XEvent*, Region);
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
XEvent *\fIevent\fP;
|
|
.br
|
|
Region \fIregion\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget instance requiring redisplay.
|
|
.IP \fIevent\fP 1i
|
|
Specifies the exposure event giving the rectangle requiring redisplay.
|
|
.IP \fIregion\fP 1i
|
|
Specifies the union of all rectangles in this exposure sequence.
|
|
.LP
|
|
.eM
|
|
The redisplay of a widget upon exposure is the responsibility of the
|
|
expose procedure in the widget's class record.
|
|
If a widget has no display semantics,
|
|
it can specify NULL for the \fIexpose\fP field.
|
|
Many composite widgets serve only as containers for their children
|
|
and have no expose procedure.
|
|
.NT
|
|
If the \fIexpose\fP procedure is NULL,
|
|
.PN XtRealizeWidget
|
|
fills in a default bit gravity of
|
|
.PN NorthWestGravity
|
|
before it calls the widget's realize procedure.
|
|
.NE
|
|
.LP
|
|
If the widget's \fIcompress_exposure\fP class field specifies
|
|
.PN XtExposeNoCompress
|
|
or
|
|
.PN XtExposeNoRegion ,
|
|
or if the event type is
|
|
.PN NoExpose
|
|
(see Section 7.9.3),
|
|
\fIregion\fP is NULL. If
|
|
.PN XtExposeNoCompress
|
|
is not specified and the event type is not
|
|
.PN NoExpose ,
|
|
the event is the final event in the compressed series
|
|
but \fIx\fP, \fIy\fP, \fIwidth\fP, and \fIheight\fP contain
|
|
the bounding box for all the compressed events.
|
|
The region is created and destroyed by the \*(xI, but
|
|
the widget is permitted to modify the region contents.
|
|
.LP
|
|
A small simple widget (for example, Label) can ignore the bounding box
|
|
information in the event and redisplay the entire window.
|
|
A more complicated widget (for example, Text) can use the bounding box
|
|
information to minimize the amount of calculation and redisplay it does.
|
|
A very complex widget uses the region as a clip list in a GC and
|
|
ignores the event information.
|
|
The expose procedure is not chained and is therefore
|
|
responsible for exposure of all superclass data
|
|
as well as its own.
|
|
.LP
|
|
However,
|
|
it often is possible to anticipate the display needs of several levels
|
|
of subclassing.
|
|
For example, rather than implement separate display procedures for
|
|
the widgets Label, Pushbutton, and Toggle,
|
|
you could write a single display routine in Label that uses display state
|
|
fields like
|
|
.LP
|
|
.DS
|
|
Boolean invert;
|
|
Boolean highlight;
|
|
Dimension highlight_width;
|
|
.DE
|
|
Label would have \fIinvert\fP and \fIhighlight\fP always
|
|
.PN False
|
|
and \fIhighlight_width\fP zero.
|
|
Pushbutton would dynamically set \fIhighlight\fP and \fIhighlight_width\fP,
|
|
but it would leave \fIinvert\fP always
|
|
.PN False .
|
|
Finally, Toggle would dynamically set all three.
|
|
In this case,
|
|
the expose procedures for Pushbutton and Toggle inherit
|
|
their superclass's expose procedure;
|
|
see Section 1.6.10.
|
|
|
|
.NH 3
|
|
Widget Visibility
|
|
.XS
|
|
\*(SN Widget Visibility
|
|
.XE
|
|
.LP
|
|
Some widgets may use substantial computing resources to produce the
|
|
data they will display.
|
|
However, this effort is wasted if the widget is not actually visible
|
|
on the screen, that is, if the widget is obscured by another application
|
|
or is iconified.
|
|
.LP
|
|
.IN "Visibility"
|
|
The \fIvisible\fP field in the
|
|
core
|
|
widget structure provides a hint to the widget that it need not compute
|
|
display data.
|
|
This field is guaranteed to be
|
|
.PN True
|
|
by the time an
|
|
exposure
|
|
event is processed if any part of the widget is visible,
|
|
but is
|
|
.PN False
|
|
if the widget is fully obscured.
|
|
.LP
|
|
Widgets can use or ignore the \fIvisible\fP hint.
|
|
If they ignore it,
|
|
they should have \fIvisible_interest\fP in their widget class record set
|
|
.PN False .
|
|
In such cases,
|
|
the \fIvisible\fP field is initialized
|
|
.PN True
|
|
and never changes.
|
|
If \fIvisible_interest\fP is
|
|
.PN True ,
|
|
the event manager asks for
|
|
.PN VisibilityNotify
|
|
events for the widget and sets \fIvisible\fP to
|
|
.PN True
|
|
on
|
|
.PN VisibilityUnobscured
|
|
or
|
|
.PN VisibilityPartiallyObscured
|
|
.IN VisibilityNotify
|
|
events and
|
|
.PN False
|
|
on
|
|
.PN VisibilityFullyObscured
|
|
events.
|
|
|
|
.NH 2
|
|
X Event Handlers
|
|
.XS
|
|
\*(SN X Event Handlers
|
|
.XE
|
|
.LP
|
|
Event handlers are procedures called when specified events
|
|
occur in a widget.
|
|
Most widgets need not use event handlers explicitly.
|
|
Instead, they use the \*(xI translation manager.
|
|
Event handler procedure pointers are of the type
|
|
.PN XtEventHandler .
|
|
.LP
|
|
.IN "XtEventHandler" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtEventHandler)(Widget, XtPointer, XEvent*, Boolean*);
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.br
|
|
XEvent *\fIevent\fP;
|
|
.br
|
|
Boolean *\fIcontinue_to_dispatch\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget for which the event arrived.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies any client-specific information registered with the event handler.
|
|
.IP \fIevent\fP 1i
|
|
Specifies the triggering event.
|
|
.IP \fIcontinue_to_dispatch\fP 1i
|
|
Specifies whether the remaining event
|
|
handlers registered for the current event
|
|
should be called.
|
|
.LP
|
|
.eM
|
|
After receiving an event and before calling any event handlers, the
|
|
Boolean pointed to by \fIcontinue_to_dispatch\fP is initialized to
|
|
.PN True .
|
|
When an event handler is called, it may decide that further processing
|
|
of the event is not desirable and may store
|
|
.PN False
|
|
in this Boolean, in
|
|
which case any handlers remaining to be called for the event are
|
|
ignored.
|
|
.LP
|
|
The circumstances under which the \*(xI may add event handlers
|
|
to a widget are currently implementation-dependent. Clients must
|
|
therefore be aware that storing
|
|
.PN False
|
|
into the \fIcontinue_to_dispatch\fP argument can lead to portability problems.
|
|
|
|
.NH 3
|
|
Event Handlers That Select Events
|
|
.XS
|
|
\*(SN Event Handlers That Select Events
|
|
.XE
|
|
.LP
|
|
To register an event handler procedure with the dispatch mechanism, use
|
|
.PN XtAddEventHandler .
|
|
.LP
|
|
.IN "XtAddEventHandler" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtAddEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
|
|
\fIproc\fP, \fIclient_data\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
EventMask \fIevent_mask\fP;
|
|
.br
|
|
Boolean \fInonmaskable\fP;
|
|
.br
|
|
XtEventHandler \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget for which this event handler is being registered. \*(cI
|
|
.IP \fIevent_mask\fP 1i
|
|
Specifies the event mask for which to call this procedure.
|
|
.IP \fInonmaskable\fP 1i
|
|
Specifies whether this procedure should be
|
|
called on the nonmaskable events
|
|
.Pn ( GraphicsExpose ,
|
|
.PN NoExpose ,
|
|
.PN SelectionClear ,
|
|
.PN SelectionRequest ,
|
|
.PN SelectionNotify ,
|
|
.PN ClientMessage ,
|
|
and
|
|
.PN MappingNotify ).
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to be called.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies additional data to be passed to the event handler.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtAddEventHandler
|
|
function registers a procedure with the dispatch mechanism that is
|
|
to be called when an event that matches the mask occurs on the specified
|
|
widget.
|
|
Each widget has a single registered event handler list, which will
|
|
contain any procedure/client_data pair exactly once regardless of
|
|
the manner in which it is registered.
|
|
If the procedure is already registered with the same \fIclient_data\fP
|
|
value,
|
|
the specified mask augments the existing mask.
|
|
If the widget is realized,
|
|
.PN XtAddEventHandler
|
|
calls
|
|
.PN XSelectInput ,
|
|
if necessary.
|
|
The order in which this procedure is called relative to other handlers
|
|
registered for the same event is not defined.
|
|
.sp
|
|
.LP
|
|
To remove a previously registered event handler, use
|
|
.PN XtRemoveEventHandler .
|
|
.LP
|
|
.IN "XtRemoveEventHandler" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRemoveEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
|
|
\fIproc\fP, \fIclient_data\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
EventMask \fIevent_mask\fP;
|
|
.br
|
|
Boolean \fInonmaskable\fP;
|
|
.br
|
|
XtEventHandler \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget for which this procedure is registered. \*(cI
|
|
.IP \fIevent_mask\fP 1i
|
|
Specifies the event mask for which to unregister this procedure.
|
|
.IP \fInonmaskable\fP 1i
|
|
Specifies whether this procedure should be
|
|
removed on the nonmaskable events
|
|
.Pn ( GraphicsExpose ,
|
|
.PN NoExpose ,
|
|
.PN SelectionClear ,
|
|
.PN SelectionRequest ,
|
|
.PN SelectionNotify ,
|
|
.PN ClientMessage ,
|
|
and
|
|
.PN MappingNotify ).
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to be removed.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies the registered client data.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtRemoveEventHandler
|
|
function unregisters an event handler registered with
|
|
.PN XtAddEventHandler
|
|
or
|
|
.PN XtInsertEventHandler
|
|
for the specified events.
|
|
The request is ignored if \fIclient_data\fP does not match the value given
|
|
when the handler was registered.
|
|
If the widget is realized and no other event handler requires the event,
|
|
.PN XtRemoveEventHandler
|
|
calls
|
|
.PN XSelectInput .
|
|
If the specified procedure has not been registered
|
|
or if it has been registered with a different value of \fIclient_data\fP,
|
|
.PN XtRemoveEventHandler
|
|
returns without reporting an error.
|
|
.LP
|
|
To stop a procedure registered with
|
|
.PN XtAddEventHandler
|
|
or
|
|
.PN XtInsertEventHandler
|
|
from receiving all selected events, call
|
|
.PN XtRemoveEventHandler
|
|
with an \fIevent_mask\fP of
|
|
.PN XtAllEvents
|
|
and \fInonmaskable\fP
|
|
.PN True .
|
|
The procedure will continue to receive any events
|
|
that have been specified in calls to
|
|
.PN XtAddRawEventHandler
|
|
or
|
|
.PN XtInsertRawEventHandler .
|
|
.sp
|
|
.LP
|
|
To register an event handler procedure that receives events before or
|
|
after all previously registered event handlers, use
|
|
.PN XtInsertEventHandler .
|
|
.LP
|
|
.IN "XtListPosition" "" "@DEF@"
|
|
.IN "XtInsertEventHandler" "" "@DEF@"
|
|
.sM
|
|
.Ds 0
|
|
typedef enum {XtListHead, XtListTail} XtListPosition;
|
|
.De
|
|
.LP
|
|
.FD 0
|
|
void XtInsertEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
|
|
\fIproc\fP, \fIclient_data\fP, \fIposition\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
EventMask \fIevent_mask\fP;
|
|
.br
|
|
Boolean \fInonmaskable\fP;
|
|
.br
|
|
XtEventHandler \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.br
|
|
XtListPosition \fIposition\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget for which this event handler is being registered. \*(cI
|
|
.IP \fIevent_mask\fP 1i
|
|
Specifies the event mask for which to call this procedure.
|
|
.IP \fInonmaskable\fP 1i
|
|
Specifies whether this procedure should be
|
|
called on the nonmaskable events
|
|
.Pn ( GraphicsExpose ,
|
|
.PN NoExpose ,
|
|
.PN SelectionClear ,
|
|
.PN SelectionRequest ,
|
|
.PN SelectionNotify ,
|
|
.PN ClientMessage ,
|
|
and
|
|
.PN MappingNotify ).
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to be called.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies additional data to be passed to the client's event handler.
|
|
.IP \fIposition\fP 1i
|
|
Specifies when the event handler is to be called
|
|
relative to other previously registered handlers.
|
|
.LP
|
|
.eM
|
|
.PN XtInsertEventHandler
|
|
is identical to
|
|
.PN XtAddEventHandler
|
|
with the additional \fIposition\fP argument. If \fIposition\fP is
|
|
.PN XtListHead ,
|
|
the event
|
|
handler is registered so that it is called before any event
|
|
handlers that were previously registered for the same widget. If
|
|
\fIposition\fP is
|
|
.PN XtListTail ,
|
|
the event handler is registered to be called
|
|
after any previously registered event handlers. If the procedure is
|
|
already registered with the same \fIclient_data\fP value, the specified mask
|
|
augments the existing mask and the procedure is repositioned in
|
|
the list.
|
|
|
|
.NH 3
|
|
Event Handlers That Do Not Select Events
|
|
.XS
|
|
\*(SN Event Handlers That Do Not Select Events
|
|
.XE
|
|
.LP
|
|
On occasion,
|
|
clients need to register an event handler procedure with the
|
|
dispatch mechanism without explicitly
|
|
causing the X server to select for that event.
|
|
To do this, use
|
|
.PN XtAddRawEventHandler .
|
|
.LP
|
|
.IN "XtAddRawEventHandler" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtAddRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
|
|
\fIproc\fP, \fIclient_data\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
EventMask \fIevent_mask\fP;
|
|
.br
|
|
Boolean \fInonmaskable\fP;
|
|
.br
|
|
XtEventHandler \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget for which this event handler is being registered. \*(cI
|
|
.IP \fIevent_mask\fP 1i
|
|
Specifies the event mask for which to call this procedure.
|
|
.IP \fInonmaskable\fP 1i
|
|
Specifies whether this procedure should be
|
|
called on the nonmaskable events
|
|
.Pn ( GraphicsExpose ,
|
|
.PN NoExpose ,
|
|
.PN SelectionClear ,
|
|
.PN SelectionRequest ,
|
|
.PN SelectionNotify ,
|
|
.PN ClientMessage ,
|
|
and
|
|
.PN MappingNotify ).
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to be called.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies additional data to be passed to the client's event handler.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtAddRawEventHandler
|
|
function is similar to
|
|
.PN XtAddEventHandler
|
|
except that it does not affect the widget's event mask and never causes an
|
|
.PN XSelectInput
|
|
for its events.
|
|
Note that the widget might already have those mask bits set
|
|
because of other nonraw event handlers registered on it.
|
|
If the procedure is already registered with the same \fIclient_data\fP,
|
|
the specified mask augments the existing mask.
|
|
The order in which this procedure is called relative to other handlers
|
|
registered for the same event is not defined.
|
|
.sp
|
|
.LP
|
|
To remove a previously registered raw event handler, use
|
|
.PN XtRemoveRawEventHandler .
|
|
.LP
|
|
.IN "XtRemoveRawEventHandler" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRemoveRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
|
|
\fIproc\fP, \fIclient_data\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
EventMask \fIevent_mask\fP;
|
|
.br
|
|
Boolean \fInonmaskable\fP;
|
|
.br
|
|
XtEventHandler \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget for which this procedure is registered. \*(cI
|
|
.IP \fIevent_mask\fP 1i
|
|
Specifies the event mask for which to unregister this procedure.
|
|
.IP \fInonmaskable\fP 1i
|
|
Specifies whether this procedure should be
|
|
removed on the nonmaskable events
|
|
.Pn ( GraphicsExpose ,
|
|
.PN NoExpose ,
|
|
.PN SelectionClear ,
|
|
.PN SelectionRequest ,
|
|
.PN SelectionNotify ,
|
|
.PN ClientMessage ,
|
|
and
|
|
.PN MappingNotify ).
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to be registered.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies the registered client data.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtRemoveRawEventHandler
|
|
function unregisters an event handler registered with
|
|
.PN XtAddRawEventHandler
|
|
or
|
|
.PN XtInsertRawEventHandler
|
|
for the specified events without changing
|
|
the window event mask.
|
|
The request is ignored if \fIclient_data\fP does not match the value given
|
|
when the handler was registered.
|
|
If the specified procedure has not been registered
|
|
or if it has been registered with a different value of \fIclient_data\fP,
|
|
.PN XtRemoveRawEventHandler
|
|
returns without reporting an error.
|
|
.LP
|
|
To stop a procedure
|
|
registered with
|
|
.PN XtAddRawEventHandler
|
|
or
|
|
.PN XtInsertRawEventHandler
|
|
from receiving all nonselected events, call
|
|
.PN XtRemoveRawEventHandler
|
|
with an \fIevent_mask\fP of
|
|
.PN XtAllEvents
|
|
and \fInonmaskable\fP
|
|
.PN True .
|
|
The procedure
|
|
will continue to receive any events that have been specified in calls to
|
|
.PN XtAddEventHandler
|
|
or
|
|
.PN XtInsertEventHandler .
|
|
.sp
|
|
.LP
|
|
To register an event handler procedure that receives events before or
|
|
after all previously registered event handlers without selecting for
|
|
the events, use
|
|
.PN XtInsertRawEventHandler .
|
|
.LP
|
|
.IN "XtInsertRawEventHandler" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtInsertRawEventHandler(\fIw\fP, \fIevent_mask\fP, \fInonmaskable\fP, \
|
|
\fIproc\fP, \fIclient_data\fP, \fIposition\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.br
|
|
EventMask \fIevent_mask\fP;
|
|
.br
|
|
Boolean \fInonmaskable\fP;
|
|
.br
|
|
XtEventHandler \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.br
|
|
XtListPosition \fIposition\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget for which this event handler is being registered. \*(cI
|
|
.IP \fIevent_mask\fP 1i
|
|
Specifies the event mask for which to call this procedure.
|
|
.IP \fInonmaskable\fP 1i
|
|
Specifies whether this procedure should be
|
|
called on the nonmaskable events
|
|
.Pn ( GraphicsExpose ,
|
|
.PN NoExpose ,
|
|
.PN SelectionClear ,
|
|
.PN SelectionRequest ,
|
|
.PN SelectionNotify ,
|
|
.PN ClientMessage ,
|
|
and
|
|
.PN MappingNotify ).
|
|
.IP \fIproc\fP 1i
|
|
Specifies the procedure to be registered.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies additional data to be passed to the client's event handler.
|
|
.IP \fIposition\fP 1i
|
|
Specifies when the event handler is to be called
|
|
relative to other previously registered handlers.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtInsertRawEventHandler
|
|
function is similar to
|
|
.PN XtInsertEventHandler
|
|
except that it does not modify the widget's event
|
|
mask and never causes an
|
|
.PN XSelectInput
|
|
for the specified events. If
|
|
the procedure is already registered with the same \fIclient_data\fP
|
|
value, the
|
|
specified mask augments the existing mask and the procedure is
|
|
repositioned in the list.
|
|
|
|
.NH 3
|
|
Current Event Mask
|
|
.XS
|
|
\*(SN Current Event Mask
|
|
.XE
|
|
.LP
|
|
To retrieve the event mask for a given widget, use
|
|
.PN XtBuildEventMask .
|
|
.LP
|
|
.IN "XtBuildEventMask" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
EventMask XtBuildEventMask(\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget. \*(cI
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtBuildEventMask
|
|
function returns the event mask representing the logical OR
|
|
of all event masks for event handlers registered on the widget with
|
|
.PN XtAddEventHandler
|
|
and
|
|
.PN XtInsertEventHandler
|
|
and all event translations, including accelerators,
|
|
installed on the widget.
|
|
This is the same event mask stored into the
|
|
.PN XSetWindowAttributes
|
|
structure by
|
|
.PN XtRealizeWidget
|
|
and sent to the server when event handlers and translations are installed or
|
|
removed on the realized widget.
|
|
|
|
.NH 3
|
|
Event Handlers for X11 Protocol Extensions
|
|
.XS
|
|
\fB\*(SN Event Handlers for X11 Protocol Extensions\fP
|
|
.XE
|
|
.LP
|
|
To register an event handler procedure with the \*(xI dispatch
|
|
mechanism according to an event type, use
|
|
.PN XtInsertEventTypeHandler .
|
|
.LP
|
|
.IN "XtInsertEventTypeHandler" "" "@DEF"
|
|
.sM
|
|
.FD 0
|
|
void XtInsertEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
|
|
\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP, \fIposition\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
int \fIevent_type\fP;
|
|
.br
|
|
XtPointer \fIselect_data\fP;
|
|
.br
|
|
XtEventHandler \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.br
|
|
XtListPosition \fIposition\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget for which this event handler is being registered. \*(cI
|
|
.IP \fIevent_type\fP 1i
|
|
Specifies the event type for which to call this event handler.
|
|
.IP \fIselect_data\fP 1i
|
|
Specifies data used to request events of the specified type from the server,
|
|
or NULL.
|
|
.IP \fIproc\fP 1i
|
|
Specifies the event handler to be called.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies additional data to be passed to the event handler.
|
|
.IP \fIposition\fP 1i
|
|
Specifies when the event handler is to be called relative to other
|
|
previously registered handlers.
|
|
.LP
|
|
.eM
|
|
.PN XtInsertEventTypeHandler
|
|
registers a procedure with the
|
|
dispatch mechanism that is to be called when an event that matches the
|
|
specified \fIevent_type\fP is dispatched to the specified \fIwidget\fP.
|
|
.LP
|
|
If \fIevent_type\fP specifies one of the core X protocol events, then
|
|
\fIselect_data\fP must be a pointer to a value of type
|
|
.PN EventMask ,
|
|
indicating
|
|
the event mask to be used to select for the desired event. This event
|
|
mask is included in the value returned by
|
|
.PN XtBuildEventMask .
|
|
If the widget is realized,
|
|
.PN XtInsertEventTypeHandler
|
|
calls
|
|
.PN XSelectInput
|
|
if necessary. Specifying NULL for \fIselect_data\fP is equivalent to
|
|
specifying a pointer to an event mask containing 0. This is similar
|
|
to the
|
|
.PN XtInsertRawEventHandler
|
|
function.
|
|
.LP
|
|
If \fIevent_type\fP specifies an extension event type, then the semantics of
|
|
the data pointed to by \fIselect_data\fP are defined by the extension
|
|
selector registered for the specified event type.
|
|
.LP
|
|
In either case the \*(xI are not required to copy the data
|
|
pointed to by \fIselect_data\fP, so the caller must ensure that it remains
|
|
valid as long as the event handler remains registered with this value
|
|
of \fIselect_data\fP.
|
|
.LP
|
|
The \fIposition\fP argument allows the client to control the order of
|
|
invocation of event handlers registered for the same event type. If
|
|
the client does not care about the order, it should normally specify
|
|
.PN XtListTail ,
|
|
which registers this event handler after any previously
|
|
registered handlers for this event type.
|
|
.LP
|
|
Each widget has a single registered event handler list, which will
|
|
contain any procedure/client_data pair exactly once if it is
|
|
registered with
|
|
.PN XtInsertEventTypeHandler ,
|
|
regardless of the manner
|
|
in which it is registered and regardless of the value(s)
|
|
of \fIselect_data\fP. If the procedure is already registered with the
|
|
same \fIclient_data\fP value, the specified mask augments the existing
|
|
mask and the procedure is repositioned in the list.
|
|
.sp
|
|
.LP
|
|
To remove an event handler registered with
|
|
.PN XtInsertEventTypeHandler ,
|
|
use
|
|
.PN XtRemoveEventTypeHandler .
|
|
.LP
|
|
.IN "XtRemoveEventTypeHandler" "" "@DEF"
|
|
.sM
|
|
.FD 0
|
|
void XtRemoveEventTypeHandler(\fIwidget\fP, \fIevent_type\fP, \
|
|
\fIselect_data\fP, \fIproc\fP, \fIclient_data\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
int \fIevent_type\fP;
|
|
.br
|
|
XtPointer \fIselect_data\fP;
|
|
.br
|
|
XtEventHandler \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget for which the event handler was registered. \*(cI
|
|
.IP \fIevent_type\fP 1i
|
|
Specifies the event type for which the handler was registered.
|
|
.IP \fIselect_data\fP 1i
|
|
Specifies data used to deselect events of the specified type
|
|
from the server, or NULL.
|
|
.IP \fIproc\fP 1i
|
|
Specifies the event handler to be removed.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies the additional client data with which the procedure was registered.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtRemoveEventTypeHandler
|
|
function unregisters an event handler
|
|
registered with
|
|
.PN XtInsertEventTypeHandler
|
|
for the specified event type.
|
|
The request is ignored if \fIclient_data\fP does not match the value given
|
|
when the handler was registered.
|
|
.LP
|
|
If \fIevent_type\fP specifies one of the core X protocol events,
|
|
\fIselect_data\fP must be a pointer to a value of type
|
|
.PN EventMask, indicating the event
|
|
mask to be used to deselect for the appropriate event. If the widget
|
|
is realized,
|
|
.PN XtRemoveEventTypeHandler
|
|
calls
|
|
.PN XSelectInput
|
|
if necessary.
|
|
Specifying NULL for \fIselect_data\fP is equivalent to specifying a pointer
|
|
to an event mask containing 0. This is similar to the
|
|
.PN XtRemoveRawEventHandler
|
|
function.
|
|
.LP
|
|
If \fIevent_type\fP specifies an extension event type, then the semantics of
|
|
the data pointed to by \fIselect_data\fP are defined by the extension
|
|
selector registered for the specified event type.
|
|
.sp
|
|
.LP
|
|
To register a procedure to select extension events for a widget, use
|
|
.PN XtRegisterExtensionSelector .
|
|
.LP
|
|
.IN "XtRegisterExtensionSelector" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtRegisterExtensionSelector(\fIdisplay\fP, \fImin_event_type\fP, \
|
|
\fImax_event_type\fP, \fIproc\fP,
|
|
\fIclient_data\fP)
|
|
.br
|
|
Display \fI*display\fP;
|
|
.br
|
|
int \fImin_event_type\fP;
|
|
.br
|
|
int \fImax_event_type\fP;
|
|
.br
|
|
XtExtensionSelectProc \fIproc\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIdisplay\fP 1.5i
|
|
Specifies the display for which the extension selector is to be registered.
|
|
.IP \fImin_event_type\fP
|
|
.IP \fImax_event_type\fP 1.5i
|
|
Specifies the range of event types for the extension.
|
|
.IP \fIproc\fP 1.5i
|
|
Specifies the extension selector procedure.
|
|
.IP \fIclient_data\fP 1.5i
|
|
Specifies additional data to be passed to the extension selector.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtRegisterExtensionSelector
|
|
function registers a procedure to arrange
|
|
for the delivery of extension events to widgets.
|
|
.LP
|
|
If \fImin_event_type\fP and \fImax_event_type\fP match the parameters
|
|
to a previous call to
|
|
.PN XtRegisterExtensionSelector
|
|
for the same \fIdisplay\fP, then \fIproc\fP and \fIclient_data\fP
|
|
replace the previously
|
|
registered values. If the range specified by \fImin_event_type\fP
|
|
and \fImax_event_type\fP overlaps the range of the parameters to a
|
|
previous call for the same display in any other way, an error results.
|
|
.LP
|
|
When a widget is realized,
|
|
after the \fIcore.realize\fP method is called,
|
|
the \*(xI check to see if any event
|
|
handler specifies an event type within the range of a registered
|
|
extension selector. If so, the \*(xI call each such selector.
|
|
If an event type handler is added or removed, the \*(xI check to
|
|
see if the event type falls within the range of a registered extension
|
|
selector, and if it does, calls the selector. In either case the \*(xI
|
|
pass a list of all the widget's event types that are within the
|
|
selector's range. The corresponding select data are also passed. The
|
|
selector is responsible for enabling the delivery of extension events
|
|
required by the widget.
|
|
.sp
|
|
.LP
|
|
An extension selector is of type
|
|
.PN XtExtensionSelectProc .
|
|
.LP
|
|
.IN "XtExtensionSelectProc" "" "@DEF"
|
|
.sM
|
|
.FD 0
|
|
typedef void (*XtExtensionSelectProc)(Widget, int *, XtPointer *, int, \
|
|
XtPointer);
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
int *\fIevent_types\fP;
|
|
.br
|
|
XtPointer *\fIselect_data\fP;
|
|
.br
|
|
int \fIcount\fP;
|
|
.br
|
|
XtPointer \fIclient_data\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget that is being realized or is having
|
|
an event handler added or removed.
|
|
.IP \fIevent_types\fP 1i
|
|
Specifies a list of event types that the widget has
|
|
registered event handlers for.
|
|
.IP \fIselect_data\fP 1i
|
|
Specifies a list of the select_data parameters specified in
|
|
.PN XtInsertEventTypeHandler .
|
|
.IP \fIcount\fP 1i
|
|
Specifies the number of entries in the \fIevent_types\fP and \fIselect_data\fP
|
|
lists.
|
|
.IP \fIclient_data\fP 1i
|
|
Specifies the additional client data with which the procedure was registered.
|
|
.LP
|
|
.eM
|
|
The \fIevent_types\fP and \fIselect_data\fP lists will always have the
|
|
same number of elements, specified by \fIcount\fP.
|
|
Each event type/select data pair represents one call to
|
|
.PN XtInsertEventTypeHandler .
|
|
.sp
|
|
.LP
|
|
To register a procedure to dispatch events of a specific type within
|
|
.PN XtDispatchEvent ,
|
|
use
|
|
.PN XtSetEventDispatcher .
|
|
.LP
|
|
.IN "XtSetEventDispatcher" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
XtEventDispatchProc XtSetEventDispatcher(\fIdisplay\fP, \fIevent_type\fP, \
|
|
\fIproc\fP)
|
|
.br
|
|
Display *\fIdisplay\fP;
|
|
.br
|
|
int \fIevent_type\fP;
|
|
.br
|
|
XtEventDispatchProc \fIproc\fP;
|
|
.FN
|
|
.IP \fIdisplay\fP 1i
|
|
Specifies the display for which the event dispatcher is to be registered.
|
|
.IP \fIevent_type\fP 1i
|
|
Specifies the event type for which the dispatcher should be invoked.
|
|
.IP \fIproc\fP 1i
|
|
Specifies the event dispatcher procedure.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtSetEventDispatcher
|
|
function registers the event dispatcher procedure specified by \fIproc\fP
|
|
for events with the type \fIevent_type\fP. The previously registered
|
|
dispatcher (or the default dispatcher if there was no previously registered
|
|
dispatcher) is returned. If \fIproc\fP is NULL, the default procedure is
|
|
restored for the specified type.
|
|
.LP
|
|
In the future, when
|
|
.PN XtDispatchEvent
|
|
is called with an event type of \fIevent_type\fP, the specified \fIproc\fP
|
|
(or the default dispatcher) is invoked to determine a widget
|
|
to which to dispatch the event.
|
|
.LP
|
|
The default dispatcher handles the \*(xI modal cascade and keyboard
|
|
focus mechanisms, handles the semantics of \fIcompress_enterleave\fP
|
|
and \fIcompress_motion\fP, and discards all extension events.
|
|
.sp
|
|
.LP
|
|
An event dispatcher procedure pointer is of type
|
|
.PN XtEventDispatchProc .
|
|
.LP
|
|
.IN "XtEventDispatchProc" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
typedef Boolean (*XtEventDispatchProc)(XEvent*)
|
|
.br
|
|
XEvent *\fIevent\fP;
|
|
.FN
|
|
.IP \fIevent\fP 1i
|
|
Passes the event to be dispatched.
|
|
.LP
|
|
.eM
|
|
The event dispatcher procedure should determine whether this event is of
|
|
a type that should be dispatched to a widget.
|
|
.LP
|
|
If the event should be dispatched to a widget, the event dispatcher
|
|
procedure should determine the appropriate widget to receive the
|
|
event, call
|
|
.PN XFilterEvent
|
|
with the window of this widget, or
|
|
.PN None
|
|
if the event is to be discarded, and if
|
|
.PN XFilterEvent
|
|
returns
|
|
.PN False ,
|
|
dispatch the event to the widget using
|
|
.PN XtDispatchEventToWidget .
|
|
The procedure should return
|
|
.PN True
|
|
if either
|
|
.PN XFilterEvent
|
|
or
|
|
.PN XtDispatchEventToWidget
|
|
returned
|
|
.PN True
|
|
and
|
|
.PN False
|
|
otherwise.
|
|
.LP
|
|
If the event should not be dispatched to a widget, the event
|
|
dispatcher procedure should attempt to dispatch the event elsewhere as
|
|
appropriate and return
|
|
.PN True
|
|
if it successfully dispatched the event and
|
|
.PN False
|
|
otherwise.
|
|
.sp
|
|
.LP
|
|
Some dispatchers for extension events may wish to forward events
|
|
according to the Intrinsics' keyboard focus mechanism. To determine
|
|
which widget is the end result of keyboard event forwarding, use
|
|
.PN XtGetKeyboardFocusWidget .
|
|
.LP
|
|
.IN "XtGetKeyboardFocusWidget" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Widget XtGetKeyboardFocusWidget(\fIwidget\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget to get forwarding information for.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtGetKeyboardFocusWidget
|
|
function returns the widget that would be the end result of keyboard
|
|
event forwarding for a keyboard event for the specified widget.
|
|
.sp
|
|
.LP
|
|
To dispatch an event to a specified widget, use
|
|
.PN XtDispatchEventToWidget .
|
|
.LP
|
|
.IN "XtDispatchEventToWidget" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Boolean XtDispatchEventToWidget(\fIwidget\fP, \fIevent\fP)
|
|
.br
|
|
Widget \fIwidget\fP;
|
|
.br
|
|
XEvent *\fIevent\fP;
|
|
.FN
|
|
.IP \fIwidget\fP 1i
|
|
Specifies the widget to which to dispatch the event.
|
|
.IP \fIevent\fP 1i
|
|
Specifies a pointer to the event to be dispatched.
|
|
.LP
|
|
.eM
|
|
The
|
|
.PN XtDispatchEventToWidget
|
|
function scans the list of registered event handlers for the
|
|
specified widget and calls each handler that has been registered
|
|
for the specified event type, subject to the \fIcontinue_to_dispatch\fP
|
|
value returned by each handler.
|
|
The \*(xI behave as if event handlers were registered at the head
|
|
of the list for
|
|
.PN Expose ,
|
|
.PN NoExpose ,
|
|
.PN GraphicsExpose ,
|
|
and
|
|
.PN VisibilityNotify
|
|
events to invoke the widget's expose procedure according to the exposure
|
|
compression rules and to update the widget's \fIvisible\fP field
|
|
if \fIvisible_interest\fP is
|
|
.PN True .
|
|
These internal event handlers never set \fIcontinue_to_dispatch\fP to
|
|
.PN False .
|
|
.LP
|
|
.PN XtDispatchEventToWidget
|
|
returns
|
|
.PN True
|
|
if any event handler was called and
|
|
.PN False
|
|
otherwise.
|
|
|
|
.NH 2
|
|
Using the \*(xI in a Multi-Threaded Environment
|
|
.XS
|
|
\*(SN Using the \*(xI in a Multi-Threaded Environment
|
|
.XE
|
|
.LP
|
|
The \*(xI may be used in environments that offer multiple threads
|
|
of execution within the context of a single process. A multi-threaded
|
|
application using the \*(xI must explicitly initialize the toolkit
|
|
for mutually exclusive access by calling
|
|
.PN XtToolkitThreadInitialize .
|
|
|
|
.NH 3
|
|
Initializing a Multi-Threaded \*(xI Application
|
|
.XS
|
|
\fB\*(SN Initializing a Multi-Threaded \*(xI Application\fP
|
|
.XE
|
|
.LP
|
|
To test and initialize \*(xI support for mutually exclusive thread
|
|
access, call
|
|
.PN XtToolkitThreadInitialize .
|
|
.LP
|
|
.IN "XtToolkitThreadInitialize" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Boolean XtToolkitThreadInitialize()
|
|
.FN
|
|
.LP
|
|
.eM
|
|
.PN XtToolkitThreadInitialize
|
|
returns \fBTrue\fP if the \*(xI support mutually exclusive thread
|
|
access, otherwise it returns \fBFalse\fP. \fBXtToolkitThreadInitialize\fP
|
|
must be called before
|
|
.PN XtCreateApplicationContext ,
|
|
.PN XtAppInitialize ,
|
|
.PN XtOpenApplication ,
|
|
or
|
|
.PN XtSetLanguageProc
|
|
is called. \fBXtToolkitThreadInitialize\fP may be called more than once;
|
|
however, the application writer must ensure that it is not called
|
|
simultaneously by two or more threads.
|
|
|
|
.NH 3
|
|
Locking \*(tk Data Structures
|
|
.XS
|
|
\fB\*(SN Locking \*(tk Data Structures\fP
|
|
.XE
|
|
.LP
|
|
The \*(xI employs two levels of locking: application context and
|
|
process. Locking an application context ensures mutually exclusive
|
|
access by a thread to the state associated with the application context,
|
|
including all displays and widgets associated with it. Locking a
|
|
process ensures mutually exclusive access by a thread to \*(xI process
|
|
global data.
|
|
.LP
|
|
A client may acquire a lock multiple times and the effect is cumulative.
|
|
The client must ensure that the lock is released an equal number of times in
|
|
order for the lock to be acquired by another thread.
|
|
.LP
|
|
Most application writers will have little need to use locking as the
|
|
\*(xI performs the necessary locking internally.
|
|
Resource converters are an exception.
|
|
They require the application context or process to be locked
|
|
before the application can safely call them directly, for example:
|
|
.LP
|
|
.KS
|
|
.Ds
|
|
.TA .5i 2i
|
|
.ta .5i 2i
|
|
...
|
|
XtAppLock(app_context);
|
|
XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret);
|
|
XtAppUnlock(app_context);
|
|
...
|
|
.De
|
|
.KE
|
|
.LP
|
|
When the application relies upon
|
|
.PN XtConvertAndStore
|
|
or a converter to provide the storage for the results of a
|
|
conversion, the application should acquire the process lock before
|
|
calling out and hold the lock until the results have been copied.
|
|
.LP
|
|
Application writers who write their own
|
|
utility functions, such as one which retrieves the being_destroyed field from
|
|
a widget instance, must lock the application context before accessing
|
|
widget internal data. For example:
|
|
.LP
|
|
.KS
|
|
.Ds
|
|
.TA .5i 2i
|
|
.ta .5i 2i
|
|
#include <X11/CoreP.h>
|
|
Boolean BeingDestroyed (widget)
|
|
Widget widget;
|
|
{
|
|
Boolean ret;
|
|
XtAppLock(XtWidgetToApplicationContext(widget));
|
|
ret = widget->core.being_destroyed;
|
|
XtAppUnlock(XtWidgetToApplicationContext(widget));
|
|
return ret;
|
|
}
|
|
.De
|
|
.KE
|
|
A client that wishes to atomically call two or more \*(xI functions
|
|
must lock the application context. For example:
|
|
.LP
|
|
.KS
|
|
.Ds
|
|
.TA .5i 2i
|
|
.ta .5i 2i
|
|
...
|
|
XtAppLock(XtWidgetToApplicationContext(widget));
|
|
XtUnmanageChild (widget1);
|
|
XtManageChild (widget2);
|
|
XtAppUnlock(XtWidgetToApplicationContext(widget));
|
|
...
|
|
.De
|
|
.KE
|
|
|
|
.NH 4
|
|
Locking the Application Context
|
|
.XS
|
|
\fB\*(SN Locking the Application Context\fP
|
|
.XE
|
|
.LP
|
|
To ensure mutual exclusion of application context, display, or
|
|
widget internal state, use
|
|
.PN XtAppLock.
|
|
.LP
|
|
.IN "XtAppLock" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtAppLock(\fIapp_context\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context to lock.
|
|
.LP
|
|
.eM
|
|
\fBXtAppLock\fP blocks until it is able to acquire the lock. Locking the
|
|
application context also ensures that only the thread holding the lock
|
|
makes Xlib calls from within Xt. An application that makes its own
|
|
direct Xlib calls must either lock the application context around every
|
|
call or enable thread locking in Xlib.
|
|
.LP
|
|
To unlock a locked application context, use
|
|
.PN XtAppUnlock.
|
|
.LP
|
|
.IN "XtAppUnlock" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtAppUnlock(\fIapp_context\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context that was previously locked.
|
|
.LP
|
|
.eM
|
|
|
|
.NH 4
|
|
Locking the Process
|
|
.XS
|
|
\*(SN Locking the Process
|
|
.XE
|
|
.LP
|
|
To ensure mutual exclusion of \*(tk process global data, a
|
|
widget writer must use
|
|
.PN XtProcessLock.
|
|
.LP
|
|
.IN "XtProcessLock" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtProcessLock()
|
|
.FN
|
|
.LP
|
|
.eM
|
|
\fBXtProcessLock\fP blocks until it is able to acquire the lock.
|
|
Widget writers may use XtProcessLock to guarantee mutually exclusive
|
|
access to widget static data.
|
|
.LP
|
|
To unlock a locked process, use
|
|
.PN XtProcessUnlock .
|
|
.LP
|
|
.IN "XtProcessUnlock" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtProcessUnlock()
|
|
.FN
|
|
.LP
|
|
.eM
|
|
To lock both an application context and the process at the same
|
|
time, call
|
|
.PN XtAppLock
|
|
first and then
|
|
.PN XtProcessLock .
|
|
To release both locks, call
|
|
.PN XtProcessUnlock
|
|
first and then
|
|
.PN XtAppUnlock .
|
|
The order is important to avoid deadlock.
|
|
|
|
.NH 3
|
|
Event Management in a Multi-Threaded Environment
|
|
.XS
|
|
\fB\*(SN Event Management in a Multi-Threaded Environment\fP
|
|
.XE
|
|
.LP
|
|
In a nonthreaded environment an application writer could reasonably
|
|
assume that it is safe to exit the application from a quit callback.
|
|
This assumption may no longer hold true in a multi-threaded environment;
|
|
therefore it is desirable to provide a mechanism to terminate an
|
|
event-processing loop without necessarily terminating its thread.
|
|
.LP
|
|
To indicate that the event loop should terminate after the current
|
|
event dispatch has completed, use
|
|
.PN XtAppSetExitFlag .
|
|
.LP
|
|
.IN "XtAppSetExitFlag" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
void XtAppSetExitFlag(\fIapp_context\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context.
|
|
.LP
|
|
.eM
|
|
.PN XtAppMainLoop
|
|
tests the value of the flag and will return if the flag is \fBTrue\fP.
|
|
.LP
|
|
Application writers who implement their own main loop may test the
|
|
value of the exit flag with
|
|
.PN XtAppGetExitFlag .
|
|
.LP
|
|
.IN "XtAppGetExitFlag" "" "@DEF@"
|
|
.sM
|
|
.FD 0
|
|
Boolean XtAppGetExitFlag(\fIapp_context\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context.
|
|
.LP
|
|
.eM
|
|
.PN XtAppGetExitFlag
|
|
will normally return \fBFalse\fP, indicating that event processing
|
|
may continue. When
|
|
.PN XtAppGetExitFlag
|
|
returns \fBTrue\fP, the loop must terminate and return to the caller,
|
|
which might then destroy the application context.
|
|
.LP
|
|
Application writers should be aware that, if a thread is blocked in
|
|
.PN XtAppNextEvent ,
|
|
.PN XtAppPeekEvent ,
|
|
or
|
|
.PN XtAppProcessEvent
|
|
and another thread in the same application context opens a new display,
|
|
adds an alternate input, or a timeout, any new source(s) will not
|
|
normally be "noticed" by the blocked thread. Any new sources are
|
|
"noticed" the next time one of these functions is called.
|
|
.LP
|
|
The \*(xI manage access to events on a last-in, first-out basis. If
|
|
multiple threads in the same application context block in
|
|
.PN XtAppNextEvent ,
|
|
.PN XtAppPeekEvent ,
|
|
or
|
|
.PN XtAppProcessEvent ,
|
|
the last thread to call one of these functions is the first
|
|
thread to return.
|
|
.bp
|