 |
| |
The WIDGET_EVENT function returns events for the widget hierarchy rooted at Widget_ID . Widgets communicate information by generating events. Events are generated when a button is pressed, a slider position is changed, and so forth.
NOTE: Widget applications should use the XMANAGER procedure in preference to calling WIDGET_EVENT directly. See Widget Events .
Widget_ID specifies the widget hierarchy for which events are desired. The first available event for the specified widget or any of its children is returned. If this argument is not specified, WIDGET_EVENT processes events for all existing widgets.
Widget_ID can also be an array of widget identifiers, in which case all of the specified widget hierarchies are searched.
If one of the values supplied via Widget_ID is not a valid widget identifier, this function normally issues an error and causes program execution to stop. However, if BAD_ID is present and specifies a named variable, the invalid ID is stored into the variable, and this routine quietly returns. If no error occurs, a zero is stored.
This keyword can be used to handle the situation in which IDL is waiting within WIDGET_EVENT when the user kills the widget hierarchy.
This keyword has meaning only if Widget_ID is explicitly specified.
When no events are currently available for the specified widget hierarchy, WIDGET_EVENT normally waits until one is available and then returns it. However, if NOWAIT is set and no events are present, it immediately returns. In this case, the ID field of the returned structure will be zero.
Set this keyword to prevent the hourglass cursor from being cleared by WIDGET_EVENT. This keyword can be of use if a program has to poll a widget periodically during a long computation.
Unless the NOWAIT keyword is specified, WIDGET_EVENT does not return until the asked for event is available. If the user should enter a line of input from the keyboard, it cannot be processed until WIDGET_EVENT returns. If the YIELD_TO_TTY keyword is specified and the user enters a line of input, WIDGET_EVENT returns immediately. In this case, the ID field of the returned structure will be zero.
Note: This keyword is supported under Unix only, and there are no plans to extend it to other operating systems. Do not use it if you intend to use non-Unix systems.
All events for a given widget are processed in the order that they are generated. The event processing performed by WIDGET_EVENT consists of the following steps:
This behavior allows event functions to selectively act like event procedures and swallow events. If the returned value is a structure, it is checked to ensure that it has the standard first 3 fields: ID, TOP, and HANDLER. If not an error is issued. Otherwise the value replaces the event found in the first step and WIDGET_EVENT returns to the second step.
Hence, event functions are said to "rewrite" events. This ability to rewrite events is the basis of the "compound widget" in which several widgets are combined to give the appearance of a single, more complicated widget.
A widget event is returned in a structure. The exact contents of this structure vary depending upon the type of widget involved. The first three elements of this structure, however, are always the same. Any other elements vary from widget type to type. The three fixed elements are:
When an event is passed as the argument to an event handling procedure or function, as discussed in the previous section, this field contains the identifier of the widget associated with the handler routine. When an event is returned from WIDGET_EVENT, this value is always zero to indicate that no handler routine was found.