From 5f8448ef6b85a9ff72c5af4cec99183c8bb60dc6 Mon Sep 17 00:00:00 2001 From: marha Date: Tue, 10 Apr 2012 14:58:33 +0200 Subject: Updated following packages: bigreqsproto-1.1.2 fontsproto-2.1.2 recordproto-1.14.2 scrnsaverproto-1.2.2 xcmiscproto-1.2.2 libXt-1.1.3 xhost-1.0.5 kbproto-1.0.6 libXrender-0.9.7 libxkbfile-1.0.8 freetype-2.4.9 libXaw-1.0.10 libXpm-3.5.10 xproto-7.0.23 --- libXt/specs/CH07.xml | 4989 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 4989 insertions(+) create mode 100644 libXt/specs/CH07.xml (limited to 'libXt/specs/CH07.xml') diff --git a/libXt/specs/CH07.xml b/libXt/specs/CH07.xml new file mode 100644 index 000000000..7ea72596e --- /dev/null +++ b/libXt/specs/CH07.xml @@ -0,0 +1,4989 @@ + +Event Management + +While Xlib allows the reading and processing of events anywhere in an application, +widgets in the X Toolkit 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. + + + +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 Intrinsics is +. + + + +The event manager is a collection of functions to perform the following tasks: + + + + +Add or remove event sources other than X server events (in particular, +timer interrupts, file input, or POSIX signals). + + + + +Query the status of event sources. + + + + +Add or remove procedures to be called when an event occurs for a particular +widget. + + + + +Enable and +disable the dispatching of user-initiated events (keyboard and pointer events) +for a particular widget. + + + + +Constrain the dispatching of events to a cascade of pop-up widgets. + + + + +Register procedures to be called when specific events arrive. + + + + +Register procedures to be called when the Intrinsics will block. + + + + +Enable safe operation in a multi-threaded environment. + + + + +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 +. + + +Adding and Deleting Additional Event Sources + +While most applications are driven only by X events, +some applications need to incorporate other sources of input +into the Intrinsics event-handling mechanism. +The event manager provides routines to integrate notification of timer events +and file data pending into this mechanism. + + + +The next section describes functions that provide input gathering from files. +The application registers the files with the Intrinsics read routine. +When input is pending on one of the files, +the registered callback procedures are invoked. + + +Adding and Removing Input Sources + +To register a new file as an input source for a given application context, use +. + + + + +XtInputId XtAppAddInput + XtAppContext app_context + int source + XtPointer condition + XtInputCallbackProc proc + XtPointer client_data + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + source + + + +Specifies the source file descriptor on a POSIX-based system +or other operating-system-dependent device specification. + + + + + + condition + + + +Specifies the mask that indicates a read, write, or exception condition +or some other operating-system-dependent condition. + + + + + + proc + + + +Specifies the procedure to be called when the condition is found. + + + + + + client_data + + + +Specifies an argument passed to the specified procedure +when it is called. + + + + + + +The + +function registers with the Intrinsics read routine a new source of events, +which is usually file input but can also be file output. +Note that file should be loosely interpreted to mean any sink +or source of data. + +also specifies the conditions under which the source can generate events. +When an event is pending on this source, +the callback procedure is called. + + + +The legal values for the condition argument are operating-system-dependent. +On a POSIX-based system, +source is a file number and the condition is some union of the following: + + + + XtInputReadMask + + + +Specifies that proc is to be called when source has data to be read. + + + + + + XtInputWriteMask + + + +Specifies that proc is to be called when source is ready +for writing. + + + + + + XtInputExceptMask + + + +Specifies that proc is to be called when source has +exception data. + + + + + + + +Callback procedure pointers used to handle file events are of +type +. + + + + +typedef void (*XtInputCallbackProc) + XtPointer client_data + int *source + XtInputId *id + + + + + + + client_data + + + +Passes the client data argument that was registered for this procedure in +XtApp\%AddInput. + + + + + + source + + + +Passes the source file descriptor generating the event. + + + + + + id + + + +Passes the id returned from the corresponding + +call. + + + + + + +See +for information regarding the use of + +in multiple threads. + + + +To discontinue a source of input, use +. + + + + +void XtRemoveInput + XtInputId id + + + + + + + id + + + +Specifies the id returned from the corresponding + +call. + + + + + + +The + +function causes the Intrinsics read routine to stop watching for events +from the file source specified by id. + + + +See +for information regarding the use of + +in multiple threads. + + + + +Adding and Removing Blocking Notifications + +Occasionally it is desirable for an application to receive notification +when the Intrinsics 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. + + + +To register a hook that is called immediately prior to event blocking, use +. + + + + +XtBlockHookId XtAppAddBlockHook + XtAppContext app_context + XtBlockHookProc proc + XtPointer client_data + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + proc + + + +Specifies the procedure to be called before blocking. + + + + + + client_data + + + +Specifies an argument passed to the specified procedure when it is called. + + + + + + +The + +function registers the specified procedure and returns an identifier for it. +The hook procedure proc is called at any time in the future when +the Intrinsics are about to block pending some input. + + + +The procedure pointers used to provide notification of event blocking +are of type +. + + + + +void *XtBlockHookProc + XtPointer client_data + + + + + + + client_data + + + +Passes the client data argument that was registered for this procedure in +XtApp\%AddBlockHook. + + + + + + +To discontinue the use of a procedure for blocking notification, use +. + + + + +void XtRemoveBlockHook + XtBlockHookId id + + + + + + + id + + + +Specifies the identifier returned from the corresponding call to +. + + + + + + +The + +function removes the specified procedure from the list of procedures +that are called by the Intrinsics read routine before blocking on event sources. + + + + +Adding and Removing Timeouts + +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. + + + +To register a timeout callback, use +. + + + + +XtIntervalId XtAppAddTimeOut + XtAppContext app_context + unsigned long interval + XtTimerCallbackProc proc + XtPointer client_data + + + + + + + app_context + + + +Specifies the application context for which the timer is to be set. + + + + + + interval + + + +Specifies the time interval in milliseconds. + + + + + + proc + + + +Specifies the procedure to be called when the time expires. + + + + + + client_data + + + +Specifies an argument passed to the specified procedure +when it is called. + + + + + + +The + +function creates a timeout and returns an identifier for it. +The timeout value is set to interval. +The callback procedure proc is called when + +or + +is next called after the time interval elapses, +and then the timeout is removed. + + + +Callback procedure pointers used with timeouts are of +type +. + + + + +void *XtTimerCallbackProc + XtPointer client_data + XtIntervalId *timer + + + + + + + client_data + + + +Passes the client data argument that was registered for this procedure in +XtApp\%AddTimeOut. + + + + + + timer + + + +Passes the id returned from the corresponding + +call. + + + + + + +See +for information regarding the use of + +in multiple threads. + + + +To clear a timeout value, use +. + + + + +void XtRemoveTimeOut + XtIntervalId timer + + + + + + + timer + + + +Specifies the id for the timeout request to be cleared. + + + + + + +The + +function removes the pending timeout. +Note that timeouts are automatically removed once they trigger. + + + +Please refer to Section 7.12 for information regarding the use of + +in multiple threads. + + + + +Adding and Removing Signal Callbacks + +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. + + + +Prior to establishing a signal handler, the application or widget should +call + +and store the resulting identifier in a place accessible to the signal +handler. When a signal arrives, the signal handler should call + +to notify the Intrinsics that a signal has occured. To register a signal +callback use +. + + + + +XtSignalId XtAppAddSignal + XtAppContext app_context + XtSignalCallbackProc proc + XtPointer client_data + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + proc + + + +Specifies the procedure to be called when the signal is noticed. + + + + + + client_data + + + +Specifies an argument passed to the specified procedure when it is called. + + + + + + +The callback procedure pointers used to handle signal events are of type +. + + + + +typedef void (*XtSignalCallbackProc) + XtPointer client_data + XtSignalId *id + + + + + + + client_data + + + +Passes the client data argument that was registered for this procedure in +. + + + + + + id + + + +Passes the id returned from the corresponding + +call. + + + + + + +To notify the Intrinsics that a signal has occured, use +. + + + + +void XtNoticeSignal + XtSignalId id + + + + + + + id + + + +Specifies the id returned from the corresponding + +call. + + + + + + +On a POSIX-based system, + +is the only Intrinsics function that can safely be called from a signal handler. +If + +is invoked multiple times before the Intrinsics are able to invoke the +registered callback, the callback is only called once. +Logically, the Intrinsics maintain ``pending'' flag for each registered callback. +This flag is initially +False +and is set to +True +by +. +When + +or + +(with a mask including +XtIMSignal) +is called, all registered callbacks with ``pending'' +True +are invoked and the flags are reset to +False. + + + +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 Intrinsics never block signals from being raised, so if a given +signal can be raised multiple times before the Intrinsics 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 Intrinsics +sets the pending flag to +False +but before the callback can get control, in which case the pending flag +will still be +True +after the callback returns, and the Intrinsics 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. + + + +To remove a registered signal callback, call +. + + + + +void XtRemoveSignal + XtSignalId id + + + + + + + id + + + +Specifies the id returned by the corresponding call to +. + + + + + + +The client should typically disable the source of the signal before calling +. +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 + +the client can test for signals with + +and process them by calling + +with the mask +XtIMSignal. + + + + + +Constraining Events to a Cascade of Widgets + +Modal widgets are widgets that, except for the input directed to them, +lock out user input to the application. + + + +When a modal menu or modal dialog box is popped up using +, +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. + + + +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. + + + +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 +KeyPress, +KeyRelease, +ButtonPress, +and +ButtonRelease. +The user events ignored when they occur outside the cascade are +MotionNotify +and +EnterNotify. +All other events are delivered normally. +In particular, note that this is one +way in which widgets can receive +LeaveNotify +events without first receiving +EnterNotify +events; they should be prepared to deal with +this, typically by ignoring any unmatched +LeaveNotify +events. + + + + +uses the + +and + +functions to constrain user events to a modal cascade +and subsequently to remove a grab when the modal widget is popped down. + + + +To constrain or redirect user input to a modal widget, use +. + + + + +void XtAddGrab + Widget w + Boolean exclusive + Boolean spring_loaded + + + + + + + w + + + +Specifies the widget to add to the modal cascade. Must be of class Core or any subclass thereof. + + + + + + exclusive + + + +Specifies whether user events should be dispatched exclusively to this widget +or also to previous widgets in the cascade. + + + + + + spring_loaded + + + +Specifies whether this widget was popped up because the user pressed +a pointer button. + + + + + + +The + +function appends the widget to the modal cascade +and checks that exclusive is +True +if spring_loaded is +True. +If this condition is not met, + +generates a warning message. + + + +The modal cascade is used by + +when it tries to dispatch a user event. +When at least one modal widget is in the widget cascade, + +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 exclusive parameter +True. + + + +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 exclusive +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 exclusive +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. + + + +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 spring_loaded +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 Intrinsics do not modify +the contents of the event. + + + +To remove the redirection of user input to a modal widget, use +. + + + + +void XtRemoveGrab + Widget w + + + + + + + w + + + +Specifies the widget to remove from the modal cascade. + + + + + + +The + +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. + + +Requesting Key and Button Grabs + +The Intrinsics provide a set of key and button grab interfaces that +are parallel to those provided by Xlib and that allow the Intrinsics +to modify event dispatching when necessary. X Toolkit applications and +widgets that need to passively grab keys or buttons or actively grab +the keyboard or pointer should use the +following Intrinsics routines rather than the corresponding Xlib +routines. + + + +To passively grab a single key of the keyboard, use +. + + + + +void XtGrabKey + Widget widget + KeyCode keycode + Modifiers modifiers + Boolean owner_events + int pointer_mode + + + + + + + widget + + + +Specifies the widget in whose window the key is to be grabbed. Must be of class Core or any subclass thereof. + + + + + + keycode + + + modifiers + + + owner_events + + + pointer_mode + + + keyboard_mode + + + +Specify arguments to +XGrabKey; +see Section 12.2 +in Xlib — C Language X Interface. + + + + + + + + +calls +XGrabKey +specifying the widget's window as the grab +window if the widget is realized. The remaining arguments are exactly +as for +XGrabKey. +If the widget is not realized, or is later unrealized, the call to +XGrabKey +is performed (again) when +the widget is realized and its window becomes mapped. In the future, +if + +is called with a +KeyPress +event matching the specified keycode and modifiers (which may be +AnyKey +or +AnyModifier, +respectively) for the +widget's window, the Intrinsics will call + +with the timestamp from the +KeyPress +event if either of the following conditions is true: + + + + +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 + + + + +XFilterEvent +returns +True. + + + + +To cancel a passive key grab, use +. + + + + +void XtUngrabKey + Widget widget + KeyCode keycode + Modifiers modifiers + + + + + + + widget + + + +Specifies the widget in whose window the key was grabbed. + + + + + + keycode + + + modifiers + + + +Specify arguments to +XUngrabKey; +see Section 12.2 +in Xlib — C Language X Interface. + + + + + + +The + +procedure calls +XUngrabKey +specifying the widget's +window as the ungrab window if the widget is realized. The remaining +arguments are exactly as for +XUngrabKey. +If the widget is not realized, + +removes a deferred + +request, if any, for the specified widget, keycode, and modifiers. + + + +To actively grab the keyboard, use +. + + + + +int XtGrabKeyboard + Widget widget + Boolean owner_events + int pointer_mode + Time time + + + + + + + widget + + + +Specifies the widget for whose window the keyboard is to be grabbed. +Must be of class Core or any subclass thereof. + + + + + + owner_events + + + pointer_mode + + + keyboard_mode + + + time + + + +Specify arguments to +XGrabKeyboard; +see Section 12.2 +in Xlib — C Language X Interface. + + + + + + +If the specified widget is realized, + +calls +XGrabKeyboard +specifying the widget's window as the grab window. The remaining +arguments and return value are exactly as for +XGrabKeyboard. +If the widget is not realized, + +immediately returns +GrabNotViewable. +No future automatic ungrab is implied by +. + + + +To cancel an active keyboard grab, use +. + + + + +void XtUngrabKeyboard + Widget widget + Time time + + + + + + + widget + + + +Specifies the widget that has the active keyboard grab. + + + + + + time + + + +Specifies the additional argument to +XUngrabKeyboard; +see Section 12.2 +in Xlib — C Language X Interface. + + + + + + + +calls +XUngrabKeyboard +with the specified time. + + + +To passively grab a single pointer button, use +. + + + + +void XtGrabButton + Widget widget + int button + Modifiers modifiers + Boolean owner_events + unsigned int event_mask + int pointer_mode + Window confine_to + Cursor cursor + + + + + + + widget + + + +Specifies the widget in whose window the button is to be grabbed. Must be of class Core or any subclass thereof. + + + + + + button + + + modifiers + + + owner_events + + + event_mask + + + pointer_mode + + + keyboard_mode + + + confine_to + + + cursor + + + +Specify arguments to +XGrabButton; +see Section 12.1 +in Xlib — C Language X Interface. + + + + + + + +calls +XGrabButton +specifying the widget's window as the +grab window if the widget is realized. The remaining arguments are +exactly as for +XGrabButton. +If the widget is not realized, or is later unrealized, the call to +XGrabButton +is performed (again) +when the widget is realized and its window becomes mapped. In the +future, if + +is called with a +ButtonPress +event matching the specified button and modifiers (which may be +AnyButton +or +AnyModifier, +respectively) +for the widget's window, the Intrinsics will call + +with the timestamp from the +ButtonPress +event if either of the following conditions is true: + + + + +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 + + + + +XFilterEvent +returns +True. + + + + +To cancel a passive button grab, use +. + + + + +void XtUngrabButton + Widget widget + unsigned int button + Modifiers modifiers + + + + + + + widget + + + +Specifies the widget in whose window the button was grabbed. + + + + + + button + + + modifiers + + + +Specify arguments to +XUngrabButton; +see Section 12.1 +in Xlib — C Language X Interface. + + + + + + +The + +procedure calls +XUngrabButton +specifying the +widget's window as the ungrab window if the widget is realized. The +remaining arguments are exactly as for +XUngrabButton. +If the widget is not realized, + +removes a deferred + +request, if any, for the specified widget, button, and modifiers. + + + +To actively grab the pointer, use +. + + + + +int XtGrabPointer + Widget widget + Boolean owner_events + unsigned int event_mask + int pointer_mode + Window confine_to + Cursor cursor + Time time + + + + + + + widget + + + +Specifies the widget for whose window the pointer is to be grabbed. Must be of class Core or any subclass thereof. + + + + + + owner_events + + + event_mask + + + pointer_mode + + + keyboard_mode + + + confine_to + + + cursor + + + time + + + +Specify arguments to +XGrabPointer; +see Section 12.1 +in Xlib — C Language X Interface. + + + + + + +If the specified widget is realized, + +calls +XGrabPointer, +specifying the widget's window as the grab window. The remaining +arguments and return value are exactly as for +XGrabPointer. +If the widget is not realized, + +immediately returns +GrabNotViewable. +No future automatic ungrab is implied by +. + + + +To cancel an active pointer grab, use +. + + + + +void XtUngrabPointer + Widget widget + Time time + + + + + + + widget + + + +Specifies the widget that has the active pointer grab. + + + + + + time + + + +Specifies the time argument to +XUngrabPointer; +see Section 12.1 +in Xlib — C Language X Interface. + + + + + + + +calls +XUngrabPointer +with the specified time. + + + + + +Focusing Events on a Child + +To redirect keyboard input to a normal descendant of a +widget without calling +XSetInputFocus, +use +. + + + + +void XtSetKeyboardFocus + Widget subtree + + + + + + + subtree + + + +Specifies the subtree of the hierarchy for which the keyboard focus is +to be set. Must be of class Core or any subclass thereof. + + + + + + descendant + + + +Specifies either the normal (non-pop-up) descendant of subtree to which +keyboard events are logically directed, or +None. +It is not an error to specify +None +when no input focus was previously set. Must be of class Object or any subclass thereof. + + + + + + + +causes + +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. + + + +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). + + + + +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 + +with any value of owner_events, or +if the keyboard is actively grabbed by E with owner_events +False +via + +or + +on a previous key press, the event is dispatched to E. + + + + +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. + + + + + + +If E is the final focus target widget F or a descendant of F, the +event is dispatched to E. + + + + +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 + +for E, + +is called. + + + + +If E is an ancestor of F, and the event is a key press, and either + + + + + + +E has grabbed the key with + +and owner_events +False, +or + + + + +E has grabbed the key with + +and owner_events +True, +and the coordinates of the event are outside the rectangle specified +by E's geometry, +then the event is dispatched to E. + + + + + + +Otherwise, define A as the closest common ancestor of E and F: + + + + + + +If there is an active keyboard grab for any widget via either + +or + +on a previous key press, or +if no widget between F and A (noninclusive) has grabbed +the key and modifier combination with + +and any value of owner_events, the event is dispatched to F. + + + + +Else, the event is dispatched to the ancestor of F closest to A +that has grabbed the key and modifier combination with +. + + + + + + + + +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 Intrinsics do not modify +the contents of the event. + + + +When subtree 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 +FocusIn +event is generated for the descendant if +FocusChange +events have been selected by the descendant. +Similarly, when subtree loses the X input focus +or the keyboard focus for one of its ancestors, a +FocusOut +event is generated for descendant if +FocusChange +events have been selected by the descendant. + + + +A widget tree may also actively manage the X server input focus. To +do so, a widget class specifies an accept_focus procedure. + + + +The accept_focus procedure pointer is of type +. + + + + +Boolean *XtAcceptFocusProc + + Widget w + Time *time + + + + + + + w + + + +Specifies the widget. + + + + + + time + + + +Specifies the X time of the event causing the accept focus. + + + + + + +Widgets that need the input focus can call +XSetInputFocus +explicitly, pursuant to the restrictions of the Inter-Client Communication Conventions Manual.. +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 +FocusIn +and +FocusOut +events). +Widgets classes that never want the input focus should set the +accept_focus field to NULL. + + + +To call a widget's accept_focus procedure, use +. + + + + +Boolean XtCallAcceptFocus + Widget w + Time *time + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + time + + + +Specifies the X time of the event that is causing the focus change. + + + + + + +The + +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 accept_focus is NULL, + +returns +False. + + +Events for Drawables That Are Not a Widget's Window + +Sometimes an application must handle events for drawables that are not +associated with widgets in its widget tree. Examples include handling +GraphicsExpose +and +NoExpose +events on Pixmaps, and handling +PropertyNotify +events on the root window. + + + +To register a drawable with the Intrinsics event dispatching, use +. + + + + +void XtRegisterDrawable + Display *display + Drawable drawable + Widget widget + + + + + + + display + + + +Specifies the drawable's display. + + + + + + drawable + + + +Specifies the drawable to register. + + + + + + widget + + + +Specifies the widget to register the drawable for. + + + + + + + +associates the specified drawable with the specified widget +so that future calls to + +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. + + + +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 + +are undefined. + + + +To unregister a drawable with the Intrinsics event dispatching, use +. + + + + +void XtUnregisterDrawable + Display *display + Drawable drawable + + + + + + + display + + + +Specifies the drawable's display. + + + + + + drawable + + + +Specifies the drawable to unregister. + + + + + + + +removes an association created with +. +If the drawable is the window of a widget in the client's widget tree +the results of calling + +are undefined. + + + + + +Querying Event Sources + +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 Intrinsics equivalents of the +XPending, +XPeekEvent, +and +XNextEvent +Xlib calls. + + + +To determine if there are any events on the input queue for a given application, +use +. + + + + +XtInputMask XtAppPending + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context that identifies the application to check. + + + + + + +The + +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 +XtIMXEvent, +XtIMTimer, +XtIMAlternateInput, +and +XtIMSignal +(see +XtAppProcessEvent ). +If there are no events pending, + +flushes the output buffers of each Display in the application context +and returns zero. + + + +To return the event from the head of a given application's input queue +without removing input from the queue, use +. + + + + +Boolean XtAppPeekEvent + XtAppContext app_context + XEvent *event_return + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + event_return + + + +Returns the event information to the specified event structure. + + + + + + +If there is an X event in the queue, + +copies it into event_return and returns +True. +If no X input is on the queue, + +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, + +fills in event_return and returns +True. +Otherwise, the input is for an input source +registered with +, +and + +returns +False. +The sample implementations provides XtAppPeekEvent as described. Timeout callbacks +are called while blocking for input. If some input for an input source is +available, + +will return +True +without returning an event. + + + +To remove and return the event +from the head of a given application's X event queue, +use +. + + + + +void XtAppNextEvent + XtAppContext app_context + XEvent *event_return + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + event_return + + + +Returns the event information to the specified event structure. + + + + + + +If the X event queue is empty, + +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 . + + + + +Dispatching Events + +The Intrinsics provide functions that dispatch events +to widgets or other application code. +Every client interested in X events on a widget uses + +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 . + + + +Applications that need direct control of the processing of different types +of input should use +. + + + + +void XtAppProcessEvent + XtAppContext app_context + XtInputMask mask + + + + + + + app_context + + + +Specifies the application context that identifies the +application for which to process input. + + + + + + mask + + + +Specifies what types of events to process. +The mask is the bitwise inclusive OR of any combination of +XtIMXEvent, +XtIMTimer, +XtIMAlternateInput, +and +XtIMSignal. +As a convenience, +Intrinsic.h +defines the symbolic name +XtIMAll +to be the bitwise inclusive OR of these four event types. + + + + + + +The + +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 + +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 +. + +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 +. + + + +When an X event is received, +it is passed to +, +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. + + + +To dispatch an event returned by +, +retrieved directly from the Xlib queue, or synthetically constructed, +to any registered event filters or event handlers, call +. + + + + +Boolean XtDispatchEvent + XEvent *event + + + + + + + event + + + +Specifies a pointer to the event structure to be dispatched +to the appropriate event handlers. + + + + + + +The + +function first calls +XFilterEvent +with the event and the window of the widget to which the +Intrinsics intend to dispatch the event, or the event window if +the Intrinsics would not dispatch the event to any handlers. +If +XFilterEvent +returns +True +and the event activated a server grab as identified +by a previous call to + +or +, + +calls + +or + +with the timestamp from the event and immediately returns +True. +If +XFilterEvent +returns +True +and a grab was not activated, + +just immediately returns +True. +Otherwise, + +sends the event to the event handler functions that +have been previously registered with the dispatch routine. + +returns +True +if +XFilterEvent +returned +True, +or if the event was dispatched to some handler, and +False +if it found no handler to which to dispatch the event. + +records the last timestamp in any event that +contains a timestamp (see +XtLastTimestampProcessed ), +regardless of whether it was filtered or dispatched. +If a modal cascade is active with spring_loaded +True, +and if the event is a remap event as defined by +, + +may dispatch the event a second time. If it does so, + +will call +XFilterEvent +again with the window of the spring-loaded widget prior to the second +dispatch, and if +XFilterEvent +returns +True, +the second dispatch will not be performed. + + + + +The Application Input Loop + +To process all input from a given application in a continuous loop, +use the convenience procedure +. + + + + +void XtAppMainLoop + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + +The + +function first reads the next incoming X event by calling + +and then dispatches the event to the appropriate registered procedure +by calling +. +This constitutes the main loop of X Toolkit applications. +There is nothing special about +; +it simply calls + +and then + +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 + +and +. + + + +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 +. + + + + +Setting and Checking the Sensitivity State of a Widget + +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. + + + +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 +KeyPress, +KeyRelease, +ButtonPress, +ButtonRelease, +MotionNotify, +EnterNotify, +LeaveNotify, +FocusIn, +or +FocusOut. + + + +A widget can be insensitive because its sensitive field is +False +or because one of its ancestors is insensitive and thus the widget's +ancestor_sensitive field also is +False. +A widget can but does not need to distinguish these two cases visually. + + + + +Pop-up shells will have +ancestor_sensitive +False +if the parent was insensitive when the shell +was created. Since + +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. + + + + +To set the sensitivity state of a widget, use +. + + + + +void XtSetSensitive + Widget w + Boolean sensitive + + + + + + + w + + + +Specifies the widget. Must be of class RectObj or any subclass thereof. + + + + + + sensitive + + + +Specifies whether the widget should receive +keyboard, pointer, and focus events. + + + + + + +The + +function first calls + +on the current widget with an argument list specifying the +XtNsensitive resource and the new value. +If sensitive is +False +and the widget's class is a subclass of +Composite, + +recursively propagates the new value +down the child tree by calling + +on each child to set ancestor_sensitive to +False. +If sensitive is +True +and the widget's class is a subclass of +Composite +and the widget's ancestor_sensitive field is +True, + +sets the ancestor_sensitive of each child to +True +and then recursively calls + +on each normal descendant that is now sensitive to set +ancestor_sensitive to +True. + + + + +calls + +to change the sensitive and ancestor_sensitive 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). + + + + +maintains the invariant that, if the parent has either sensitive +or ancestor_sensitive +False, +then all children have ancestor_sensitive +False. + + + +To check the current sensitivity state of a widget, +use +. + + + + +Boolean XtIsSensitive + Widget w + + + + + + + w + + + +Specifies the object. Must be of class Object or any subclass thereof. + + + + + + +The + +function returns +True +or +False +to indicate whether user input events are being dispatched. +If object's class is a subclass of RectObj and +both sensitive and ancestor_sensitive are +True, + +returns +True; +otherwise, it returns +False. + + + + +Adding Background Work Procedures + +The Intrinsics 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 + +or +. +Work procedure pointers are of type +. + + + + +typedef Boolean (*XtWorkProc) + + XtPointer client_data + + + + + + + client_data + + + +Passes the client data specified when the work procedure was registered. + + + + + + +This procedure should return +True +when it is done to indicate that it +should be removed. +If the procedure returns +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. + + + +To register a work procedure for a given application, use +. + + + + +XtWorkProcId XtAppAddWorkProc + XtAppContext app_context + XtWorkProc proc + XtPointer client_data + + + + + + + app_context + + + +Specifies the application context that identifies the application. + + + + + + proc + + + +Specifies the procedure to be called when the application is idle. + + + + + + client_data + + + +Specifies the argument passed to the specified procedure +when it is called. + + + + + + +The + +function adds the specified work procedure for the application identified +by app_context +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. + + + +To remove a work procedure, either return +True +from the procedure when it is called or use + +outside of the procedure. + + + + +void XtRemoveWorkProc + XtWorkProcId id + + + + + + + id + + + +Specifies which work procedure to remove. + + + + + + +The + +function explicitly removes the specified background work procedure. + + + + +X Event Filters + +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. + + +Pointer Motion Compression + +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 compress_motion should be +True. +When a request for an event would return a motion event, +the Intrinsics 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. + + + + +Enter/Leave Compression + +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 compress_enterleave should be +True. +These enter and leave events are not delivered to the client +if they are found together in the input queue. + + + + +Exposure Compression + +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. + + + +In either case, these widgets do not care about getting partial exposure events. +The compress_exposure 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: + + + +#define XtExposeNoCompress ((XtEnum)False) +#define XtExposeCompressSeries ((XtEnum)True) +#define XtExposeCompressMultiple <implementation-defined> +#define XtExposeCompressMaximal <implementation-defined> + + + +optionally ORed with any combination of the following flags (all with +implementation-defined values): +XtExposeGraphicsExpose, +XtExposeGraphicsExposeMerged, +XtExposeNoExpose, +and +XtExposeNoRegion. + + + +If the compress_exposure field in the widget class structure does not +specify +XtExposeNoCompress, +the event manager calls the widget's expose procedure only +once for a series of exposure events. +In this case, all +Expose +or +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 +XtExposeNoRegion +is specified) the region. +For more information on regions, see +Section 16.5 in +Xlib — C Language X Interface..) + + + +The values have the following interpretation: + + + +XtExposeNoCompress + + + + +No exposure compression is performed; every selected event is +individually dispatched to the expose procedure with a region +argument of NULL. + + + + +XtExposeCompressSeries + + + + +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. + + + + +XtExposeCompressMultiple + + + + +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. + + + + +XtExposeCompressMaximal + + + + +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 Intrinsics will +block until the end of the series is received. + + + + +The additional flags have the following meaning: + + + +XtExposeGraphicsExpose + + + + +Specifies that +GraphicsExpose +events are also to be dispatched to +the expose procedure. +GraphicsExpose +events are compressed, if specified, in the same manner as +Expose +events. + + + + +XtExposeGraphicsExposeMerged + + + + +Specifies in the case of +XtExposeCompressMultiple +and +XtExposeCompressMaximal +that series of +GraphicsExpose +and +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 +XtExposeGraphicsExpose. + + + + +XtExposeNoExpose + + + + +Specifies that +NoExpose +events are also to be dispatched to the expose procedure. +NoExpose +events are never coalesced with +other exposure events or with each other. + + + + +XtExposeNoRegion + + + + +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. + + + + + + + +Widget Exposure and Visibility + +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. + + + +Redisplay of a Widget: The expose Procedure + +The expose procedure pointer in a widget class is of type +. + + + + +typedef void (*XtExposeProc) + Widget w + XEvent *event + Region region + + + + + + + w + + + +Specifies the widget instance requiring redisplay. + + + + + + event + + + +Specifies the exposure event giving the rectangle requiring redisplay. + + + + + + region + + + +Specifies the union of all rectangles in this exposure sequence. + + + + + + +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 expose field. +Many composite widgets serve only as containers for their children +and have no expose procedure. + + + + +If the expose procedure is NULL, + +fills in a default bit gravity of +NorthWestGravity +before it calls the widget's realize procedure. + + + + +If the widget's compress_exposure class field specifies +XtExposeNoCompress +or +XtExposeNoRegion, +or if the event type is +NoExpose +(see ), +region is NULL. If +XtExposeNoCompress +is not specified and the event type is not +NoExpose, +the event is the final event in the compressed series +but x, y, width, and height contain +the bounding box for all the compressed events. +The region is created and destroyed by the Intrinsics, but +the widget is permitted to modify the region contents. + + + +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. + + + +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 + + +Boolean invert; +Boolean highlight; +Dimension highlight_width; + + +Label would have invert and highlight always +False +and highlight_width zero. +Pushbutton would dynamically set highlight and highlight_width, +but it would leave invert always +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 . + + + + +Widget Visibility + +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. + + + +The visible 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 +True +by the time an +exposure +event is processed if any part of the widget is visible, +but is +False +if the widget is fully obscured. + + + +Widgets can use or ignore the visible hint. +If they ignore it, +they should have visible_interest in their widget class record set +False. +In such cases, +the visible field is initialized +True +and never changes. +If visible_interest is +True, +the event manager asks for +VisibilityNotify +events for the widget and sets visible to +True +on +VisibilityUnobscured +or +VisibilityPartiallyObscured +events and +False +on +VisibilityFullyObscured +events. + + + + + +X Event Handlers + +Event handlers are procedures called when specified events +occur in a widget. +Most widgets need not use event handlers explicitly. +Instead, they use the Intrinsics translation manager. +Event handler procedure pointers are of the type +. + + + + +typedef void (*XtEventHandler) + + Widget w + XtPointer client_data + XEvent *event + Boolean *continue_to_dispatch + + + + + + + w + + + +Specifies the widget for which the event arrived. + + + + + + client_data + + + +Specifies any client-specific information registered with the event handler. + + + + + + event + + + +Specifies the triggering event. + + + + + + continue_to_dispatch + + + +Specifies whether the remaining event +handlers registered for the current event +should be called. + + + + + + +After receiving an event and before calling any event handlers, the +Boolean pointed to by continue_to_dispatch is initialized to +True. +When an event handler is called, it may decide that further processing +of the event is not desirable and may store +False +in this Boolean, in +which case any handlers remaining to be called for the event are +ignored. + + + +The circumstances under which the Intrinsics may add event handlers +to a widget are currently implementation-dependent. Clients must +therefore be aware that storing +False +into the continue_to_dispatch argument can lead to portability problems. + + +Event Handlers That Select Events + +To register an event handler procedure with the dispatch mechanism, use +. + + + + +void XtAddEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + + + + + + + w + + + +Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to call this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +called on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be called. + + + + + + client_data + + + +Specifies additional data to be passed to the event handler. + + + + + + +The + +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 client_data +value, +the specified mask augments the existing mask. +If the widget is realized, + +calls +XSelectInput, +if necessary. +The order in which this procedure is called relative to other handlers +registered for the same event is not defined. + + + +To remove a previously registered event handler, use +. + + + + +void XtRemoveEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + + + + + + + w + + + +Specifies the widget for which this procedure is registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to unregister this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +removed on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be removed. + + + + + + client_data + + + +Specifies the registered client data. + + + + + + +The + +function unregisters an event handler registered with + +or + +for the specified events. +The request is ignored if client_data does not match the value given +when the handler was registered. +If the widget is realized and no other event handler requires the event, + +calls +XSelectInput. +If the specified procedure has not been registered +or if it has been registered with a different value of client_data, + +returns without reporting an error. + + + +To stop a procedure registered with + +or + +from receiving all selected events, call + +with an event_mask of +XtAllEvents +and nonmaskable +True. +The procedure will continue to receive any events +that have been specified in calls to + +or +. + + + +To register an event handler procedure that receives events before or +after all previously registered event handlers, use +. + + +typedef enum {XtListHead, XtListTail} XtListPosition; + + + + +void XtInsertEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + XtListPosition position + + + + + + + w + + + +Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to call this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +called on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be called. + + + + + + client_data + + + +Specifies additional data to be passed to the client's event handler. + + + + + + position + + + +Specifies when the event handler is to be called +relative to other previously registered handlers. + + + + + + + +is identical to + +with the additional position argument. If position is +XtListHead, +the event +handler is registered so that it is called before any event +handlers that were previously registered for the same widget. If +position is +XtListTail, +the event handler is registered to be called +after any previously registered event handlers. If the procedure is +already registered with the same client_data value, the specified mask +augments the existing mask and the procedure is repositioned in +the list. + + + + +Event Handlers That Do Not Select Events + +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 +. + + + + +void XtAddRawEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + + + + + + + w + + + +Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to call this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +called on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be called. + + + + + + client_data + + + +Specifies additional data to be passed to the client's event handler. + + + + + + +The + +function is similar to + +except that it does not affect the widget's event mask and never causes an +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 client_data, +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. + + + +To remove a previously registered raw event handler, use +. + + + + +void XtRemoveRawEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + + + + + + + w + + + +Specifies the widget for which this procedure is registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to unregister this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +removed on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be registered. + + + + + + client_data + + + +Specifies the registered client data. + + + + + + +The + +function unregisters an event handler registered with + +or + +for the specified events without changing +the window event mask. +The request is ignored if client_data 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 client_data, + +returns without reporting an error. + + + +To stop a procedure +registered with + +or + +from receiving all nonselected events, call + +with an event_mask of +XtAllEvents +and nonmaskable +True. +The procedure +will continue to receive any events that have been specified in calls to + +or +. + + + +To register an event handler procedure that receives events before or +after all previously registered event handlers without selecting for +the events, use +. + + + + +void XtInsertRawEventHandler + Widget w + EventMask event_mask + Boolean nonmaskable + XtEventHandler proc + XtPointer client_data + XtListPosition position + + + + + + + w + + + +Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. + + + + + + event_mask + + + +Specifies the event mask for which to call this procedure. + + + + + + nonmaskable + + + +Specifies whether this procedure should be +called on the nonmaskable events +( GraphicsExpose, +NoExpose, +SelectionClear, +SelectionRequest, +SelectionNotify, +ClientMessage, +and +MappingNotify ). + + + + + + proc + + + +Specifies the procedure to be registered. + + + + + + client_data + + + +Specifies additional data to be passed to the client's event handler. + + + + + + position + + + +Specifies when the event handler is to be called +relative to other previously registered handlers. + + + + + + +The + +function is similar to + +except that it does not modify the widget's event +mask and never causes an +XSelectInput +for the specified events. If +the procedure is already registered with the same client_data +value, the +specified mask augments the existing mask and the procedure is +repositioned in the list. + + + + +Current Event Mask + +To retrieve the event mask for a given widget, use +. + + + + +EventMask XtBuildEventMask + Widget w + + + + + + + w + + + +Specifies the widget. Must be of class Core or any subclass thereof. + + + + + + +The + +function returns the event mask representing the logical OR +of all event masks for event handlers registered on the widget with + +and + +and all event translations, including accelerators, +installed on the widget. +This is the same event mask stored into the +XSetWindowAttributes +structure by + +and sent to the server when event handlers and translations are installed or +removed on the realized widget. + + + + +Event Handlers for X11 Protocol Extensions + +To register an event handler procedure with the Intrinsics dispatch +mechanism according to an event type, use +. + + + + +void XtInsertEventTypeHandler + Widget widget + int event_type + XtPointer select_data + XtEventHandler proc + XtPointer client_data + XtListPosition position + + + + + + + widget + + + +Specifies the widget for which this event handler is being registered. Must be of class Core or any subclass thereof. + + + + + + event_type + + + +Specifies the event type for which to call this event handler. + + + + + + select_data + + + +Specifies data used to request events of the specified type from the server, +or NULL. + + + + + + proc + + + +Specifies the event handler to be called. + + + + + + client_data + + + +Specifies additional data to be passed to the event handler. + + + + + + position + + + +Specifies when the event handler is to be called relative to other +previously registered handlers. + + + + + + + +registers a procedure with the +dispatch mechanism that is to be called when an event that matches the +specified event_type is dispatched to the specified widget. + + + +If event_type specifies one of the core X protocol events, then +select_data must be a pointer to a value of type +EventMask, +indicating +the event mask to be used to select for the desired event. This event +mask is included in the value returned by +. +If the widget is realized, + +calls +XSelectInput +if necessary. Specifying NULL for select_data is equivalent to +specifying a pointer to an event mask containing 0. This is similar +to the + +function. + + + +If event_type specifies an extension event type, then the semantics of +the data pointed to by select_data are defined by the extension +selector registered for the specified event type. + + + +In either case the Intrinsics are not required to copy the data +pointed to by select_data, so the caller must ensure that it remains +valid as long as the event handler remains registered with this value +of select_data. + + + +The position 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 +XtListTail, +which registers this event handler after any previously +registered handlers for this event type. + + + +Each widget has a single registered event handler list, which will +contain any procedure/client_data pair exactly once if it is +registered with +, +regardless of the manner +in which it is registered and regardless of the value(s) +of select_data. If the procedure is already registered with the +same client_data value, the specified mask augments the existing +mask and the procedure is repositioned in the list. + + + +To remove an event handler registered with +, +use +. + + + + +void XtRemoveEventTypeHandler + Widget widget + int event_type + XtPointer select_data + XtEventHandler proc + XtPointer client_data + + + + + + + widget + + + +Specifies the widget for which the event handler was registered. Must be of class Core or any subclass thereof. + + + + + + event_type + + + +Specifies the event type for which the handler was registered. + + + + + + select_data + + + +Specifies data used to deselect events of the specified type +from the server, or NULL. + + + + + + proc + + + +Specifies the event handler to be removed. + + + + + + client_data + + + +Specifies the additional client data with which the procedure was registered. + + + + + + +The + +function unregisters an event handler +registered with + +for the specified event type. +The request is ignored if client_data does not match the value given +when the handler was registered. + + + +If event_type specifies one of the core X protocol events, +select_data must be a pointer to a value of type +EventMask, indicating the event +mask to be used to deselect for the appropriate event. If the widget +is realized, + +calls +XSelectInput +if necessary. +Specifying NULL for select_data is equivalent to specifying a pointer +to an event mask containing 0. This is similar to the + +function. + + + +If event_type specifies an extension event type, then the semantics of +the data pointed to by select_data are defined by the extension +selector registered for the specified event type. + + + +To register a procedure to select extension events for a widget, use +. + + + + +void XtRegisterExtensionSelector + Display *display + int min_event_type + int max_event_type + XtExtensionSelectProc proc + XtPointer client_data + + + + + + + display + + + +Specifies the display for which the extension selector is to be registered. + + + + + + min_event_type + + + + + + + + max_event_type + + + +Specifies the range of event types for the extension. + + + + + + proc + + + +Specifies the extension selector procedure. + + + + + + client_data + + + +Specifies additional data to be passed to the extension selector. + + + + + + +The + +function registers a procedure to arrange +for the delivery of extension events to widgets. + + + +If min_event_type and max_event_type match the parameters +to a previous call to + +for the same display, then proc and client_data +replace the previously +registered values. If the range specified by min_event_type +and max_event_type overlaps the range of the parameters to a +previous call for the same display in any other way, an error results. + + + +When a widget is realized, +after the core.realize method is called, +the Intrinsics check to see if any event +handler specifies an event type within the range of a registered +extension selector. If so, the Intrinsics call each such selector. +If an event type handler is added or removed, the Intrinsics 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 Intrinsics +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. + + + +An extension selector is of type +. + + + + +typedef void (*XtExtensionSelectProc) + + Widget widget + int *event_types + XtPointer *select_data + int count + XtPointer client_data + + + + + + + widget + + + +Specifies the widget that is being realized or is having +an event handler added or removed. + + + + + + event_types + + + +Specifies a list of event types that the widget has +registered event handlers for. + + + + + + select_data + + + +Specifies a list of the select_data parameters specified in +. + + + + + + count + + + +Specifies the number of entries in the event_types and select_data +lists. + + + + + + client_data + + + +Specifies the additional client data with which the procedure was registered. + + + + + + +The event_types and select_data lists will always have the +same number of elements, specified by count. +Each event type/select data pair represents one call to +. + + + +To register a procedure to dispatch events of a specific type within +, +use +. + + + + +XtEventDispatchProc XtSetEventDispatcher + Display *display + int event_type + XtEventDispatchProc proc + + + + + + + display + + + +Specifies the display for which the event dispatcher is to be registered. + + + + + + event_type + + + +Specifies the event type for which the dispatcher should be invoked. + + + + + + proc + + + +Specifies the event dispatcher procedure. + + + + + + +The + +function registers the event dispatcher procedure specified by proc +for events with the type event_type. The previously registered +dispatcher (or the default dispatcher if there was no previously registered +dispatcher) is returned. If proc is NULL, the default procedure is +restored for the specified type. + + + +In the future, when + +is called with an event type of event_type, the specified proc +(or the default dispatcher) is invoked to determine a widget +to which to dispatch the event. + + + +The default dispatcher handles the Intrinsics modal cascade and keyboard +focus mechanisms, handles the semantics of compress_enterleave +and compress_motion, and discards all extension events. + + + +An event dispatcher procedure pointer is of type +. + + + + +typedef Boolean (*XtEventDispatchProc) + XEvent *event + + + + + + + event + + + +Passes the event to be dispatched. + + + + + + +The event dispatcher procedure should determine whether this event is of +a type that should be dispatched to a widget. + + + +If the event should be dispatched to a widget, the event dispatcher +procedure should determine the appropriate widget to receive the +event, call +XFilterEvent +with the window of this widget, or +None +if the event is to be discarded, and if +XFilterEvent +returns +False, +dispatch the event to the widget using +. +The procedure should return +True +if either +XFilterEvent +or + +returned +True +and +False +otherwise. + + + +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 +True +if it successfully dispatched the event and +False +otherwise. + + + +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 +. + + + + +Widget XtGetKeyboardFocusWidget + Widget widget + + + + + + + widget + + + +Specifies the widget to get forwarding information for. + + + + + + +The + +function returns the widget that would be the end result of keyboard +event forwarding for a keyboard event for the specified widget. + + + +To dispatch an event to a specified widget, use +. + + + + +Boolean XtDispatchEventToWidget + Widget widget + XEvent *event + + + + + + + widget + + + +Specifies the widget to which to dispatch the event. + + + + + + event + + + +Specifies a pointer to the event to be dispatched. + + + + + + +The + +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 continue_to_dispatch +value returned by each handler. +The Intrinsics behave as if event handlers were registered at the head +of the list for +Expose, +NoExpose, +GraphicsExpose, +and +VisibilityNotify +events to invoke the widget's expose procedure according to the exposure +compression rules and to update the widget's visible field +if visible_interest is +True. +These internal event handlers never set continue_to_dispatch to +False. + + + + +returns +True +if any event handler was called and +False +otherwise. + + + + + +Using the Intrinsics in a Multi-Threaded Environment + +The Intrinsics may be used in environments that offer multiple threads +of execution within the context of a single process. A multi-threaded +application using the Intrinsics must explicitly initialize the toolkit +for mutually exclusive access by calling +. + + +Initializing a Multi-Threaded Intrinsics Application + +To test and initialize Intrinsics support for mutually exclusive thread +access, call +. + + + + +Boolean XtToolkitThreadInitialize + + + + + + +returns True if the Intrinsics support mutually exclusive thread +access, otherwise it returns False. +must be called before +, +, +, +or +XtSetLanguageProc +is called. may be called more than once; +however, the application writer must ensure that it is not called +simultaneously by two or more threads. + + + + +Locking X Toolkit Data Structures + +The Intrinsics 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 Intrinsics process +global data. + + + +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. + + + +Most application writers will have little need to use locking as the +Intrinsics 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: + + + ... + XtAppLock(app_context); + XtCvtStringToPixel(dpy, args, num_args, fromVal, toVal, closure_ret); + XtAppUnlock(app_context); + ... + + +When the application relies upon + +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. + + + +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: + + +#include <X11/CoreP.h> +Boolean BeingDestroyed (widget) + Widget widget; +{ + Boolean ret; + XtAppLock(XtWidgetToApplicationContext(widget)); + ret = widget->core.being_destroyed; + XtAppUnlock(XtWidgetToApplicationContext(widget)); + return ret; +} + + +A client that wishes to atomically call two or more Intrinsics functions +must lock the application context. For example: + + + ... + XtAppLock(XtWidgetToApplicationContext(widget)); + XtUnmanageChild (widget1); + XtManageChild (widget2); + XtAppUnlock(XtWidgetToApplicationContext(widget)); + ... + + +Locking the Application Context + +To ensure mutual exclusion of application context, display, or +widget internal state, use +XtAppLock. + + + + +void XtAppLock + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context to lock. + + + + + + + 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. + + + +To unlock a locked application context, use +XtAppUnlock. + + + + +void XtAppUnlock + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context that was previously locked. + + + + + + + + +Locking the Process + +To ensure mutual exclusion of X Toolkit process global data, a +widget writer must use +XtProcessLock. + + + + +void XtProcessLock + + + + + + blocks until it is able to acquire the lock. +Widget writers may use XtProcessLock to guarantee mutually exclusive +access to widget static data. + + + +To unlock a locked process, use +. + + + + +void XtProcessUnlock + + + + + +To lock both an application context and the process at the same +time, call + +first and then +. +To release both locks, call + +first and then +. +The order is important to avoid deadlock. + + + + + +Event Management in a Multi-Threaded Environment + +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. + + + +To indicate that the event loop should terminate after the current +event dispatch has completed, use +. + + + + +void XtAppSetExitFlag + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context. + + + + + + + +tests the value of the flag and will return if the flag is True. + + + +Application writers who implement their own main loop may test the +value of the exit flag with +. + + + + +Boolean XtAppGetExitFlag + XtAppContext app_context + + + + + + + app_context + + + +Specifies the application context. + + + + + + + +will normally return False, indicating that event processing +may continue. When + +returns True, the loop must terminate and return to the caller, +which might then destroy the application context. + + + +Application writers should be aware that, if a thread is blocked in +, +, +or + +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. + + + +The Intrinsics manage access to events on a last-in, first-out basis. If +multiple threads in the same application context block in +, +, +or +, +the last thread to call one of these functions is the first +thread to return. + + + + -- cgit v1.2.3