 |
| |
The XMANAGER procedure provides the main event loop and management for widgets created using IDL. Calling XMANAGER "registers" a widget program with the XMANAGER event handler. XMANAGER takes control of event processing until all widgets have been destroyed.
Beginning with IDL version 5.0, IDL supports an active command line that allows the IDL command input line to continue accepting input while properly configured widget applications are running. See A Note About Blocking in XMANAGER for a more detailed explanation of the active command line.
This routine is written in the IDL language. Its source code can be found in the file
xmanager.pro
in the
lib
subdirectory of the IDL distribution.
A string that contains the name of the routine that creates the widget (i.e., the name of the widget creation routine that is calling XMANAGER).
NOTE: The Name argument is stored in a COMMON block for use by the XREGISTERED routine. The stored name is case-sensitive.
This keyword is obsolete and is included in XMANAGER for compatibility with existing code only. Its functionality has been replaced by the TIMER keyword to the WIDGET_CONTROL procedure.
A string that contains the name of a background task procedure to be called when the event loop is idle.
Set this keyword to cause XMANAGER to catch any errors, using the CATCH procedure, when dispatching widget events. If the CATCH keyword is set equal to zero, execution halts and IDL provides traceback information when an error is detected. This keyword is set by default (errors are caught and processing continues).
Do not specify either the Name or ID argument to XMANAGER when specifying the CATCH keyword (they are ignored). CATCH acts as a switch to turn error catching on and off for all applications managed by XMANAGER. When CATCH is specified, XMANAGER changes its error-catching behavior and returns immediately, without taking any other action.
NOTE: Beginning with IDL version 5.0, the default behavior of XMANAGER is to catch errors and continue processing events. In versions of IDL prior to version 5.0, XMANAGER halted when an error was detected. This change in default behavior was necessary in order to allow multiple widget applications (all being managed by XMANAGER) to coexist peacefully. When CATCH is set equal to zero, (the old behavior), any error halts XMANAGER, and thus halts event processing for all running widget applications.
Note also that CATCH is only effective if XMANAGER is blocking to dispatch errors. If event dispatching for an active IDL command line is in use, the CATCH keyword has no effect.
The CATCH=0 setting (errors are not caught and processing halts in XMANAGER when an error is detected) is intended as a debugging aid. Finished programs should not set CATCH=0.
Set this keyword to a string that contains the name of the routine to be called when the widget dies. If not specified, no routine is called. The cleanup routine must accept one parameter which is the widget ID of the dying widget. The routine specified by CLEANUP becomes the KILL_NOTIFY routine for the application, overriding any cleanup routines that may have been set previously via the KILL_NOTIFY keyword to WIDGET_CONTROL.
Set this keyword to a string that contains the name of a routine to be called when a widget event occurs in the widget program being registered. If this keyword is not supplied, XMANAGER will construct a default name by adding the "_event" suffix to the Name argument. See the example below for a more detailed explanation.
The widget ID of the group leader for the widget being processed. When the leader dies either by the users actions or some other routine, all widgets that have that leader will also die.
For example, a widget that views a help file for a demo widget would have that demo widget as its leader. When the help widget is registered, it sets the keyword GROUP_LEADER to the widget ID of the demo widget. If the demo widget were destroyed, the help widget led by it would be killed by the XMANAGER.
Set this keyword to indicate that XMANAGER should just register the widget and return immediately. This keyword is useful if you want to register a group of related top-level widgets before beginning event processing and either:
(See A Note About Blocking in XMANAGER for further discussion of the active command line.)
CAUTION: JUST_REG is not the same as NO_BLOCK. See JUST_REG vs. NO_BLOCK for additional details.
This keyword is obsolete and is included in XMANAGER for compatibility with existing code only. Its functionality has been replaced by the MODAL keyword to the WIDGET_BASE procedure.
When this keyw ord is set, the widget that is being registered traps all events and desensitizes all the other widgets. It is useful when input from the user is necessary to continue (i.e., "blocking" dialog boxes). Once the modal widget dies, the others are resensitized and the normal event processing continues.
Set this keyword to tell XMANAGER that the registering client does not require XMANAGER to block if active command line event processing is available. If active command line event processing is available and every current XMANAGER client specifies NO_BLOCK, then XMANAGER will not block and the user will have access to the command line while widget applications are running.
CAUTION: NO_BLOCK is not the same as JUST_REG. See JUST_REG vs. NO_BLOCK for additional details.
Although this routine is written in the IDL language, it may change in the future in its internal implementation. For future upgradability, it is best not to modify or even worry about what this routine does internally.
Beginning with IDL version 5.0, most versions of IDL's command-processing front-end are able to support an active command line while running properly constructed widget applications. What this means is that--provided the widget application is properly configured--the IDL command input line is available for input while a widget application is running and widget events are being processed.
There are currently 5 separate IDL command-processing front-end implementations:
All of these front-ends are able to process widget events except for the VMS plain tty. VMS users can still enjoy an active command line by using the IDLDE interface.
If the command-processing front-end can process widget events (that is, if the front-end is not the VMS plain tty), it is still necessary for widget applications to be well-behaved with respect to blocking widget event processing. Since in most cases XMANAGER is used to handle widget event processing, this means that in order for the command line to remain active, all widget applications must be run with the NO_BLOCK keyword to XMANAGER set. (Note that since NO_BLOCK is not the default, it is quite likely that some application will block.) If a single application runs in blocking mode, the command line will be inaccessible until the blocking application exits. When a blocking application exits, the IDL command line will once again become active.
Although their names imply a similar function, the JUST_REG and NO_BLOCK keywords perform very different services. It is important to understand what they do and how they differ.
The JUST_REG keyword tells XMANAGER that it should simply register a client and then return immediately. The result is that the client becomes known to XMANAGER, and that future calls to XMANAGER will take this client into account. Therefore, JUST_REG only controls how the registering call to XMANAGER should behave. The client can still be registered as requiring XMANAGER to block by setting NO_BLOCK=0. In this case, future calls to XMANAGER will block.
NOTE: JUST_REG is useful in situations where you suspect blocking might occur--if the active command line is not supported and you wish to keep it active before beginning event processing, or if blocking will be requested at a later time. If no blocking will occur or if the blocking behavior is useful, it is not necessary to use JUST_REG.
The NO_BLOCK keyword tells XMANAGER that the registered client does not require XMANAGER to block if the command-processing front-end is able to support active command line event processing. XMANAGER remembers this attribute of the client until the client exits, even after the call to XMANAGER that registered the client returns. NO_BLOCK is just a "vote" on how XMANAGER should behave--the final decision is made by XMANAGER by considering the NO_BLOCK attributes of all of its current clients as well as the ability of the command-processing front-end in use to support the active command line.
The issue of blocking in XMANAGER requires some explanation. IDL widget events are not processed until the WIDGET_EVENT function is called to handle them. Otherwise, they are queued by IDL indefinitely. Knowing how and when to call WIDGET_EVENT is the primary service provided by XMANAGER.
There are two ways blocking is typically handled:
XMANAGER will block unless all of the following conditions are met:
In general, we suggest that new widget applications be written with XMANAGER blocking disabled (that is, with the NO_BLOCK keyword set). Since a widget application that does block event processing for itself will block event processing for all other widget applications (and the IDL command line) as well, we suggest that older widget applications be upgraded to take advantage of the new, non-blocking behavior by adding the NO_BLOCK keyword to most calls to XMANAGER.
The following code creates a widget named EXAMPLE that is just a base widget with a "Done" button and registers it with the XMANAGER. Widgets being registered with the XMANAGER must provide at least two routines. The first routine creates the widget and registers it with the manager and the second routine processes the events that occur within that widget. An example widget is supplied below that uses only two routines. A number of other "Simple Widget Examples", can be viewed by entering WEXMASTER at the IDL prompt. These simple programs demonstrate many aspects of widget programming.
The following lines of code would be saved in a single file, named
example.pro
:
PRO example_event, ev ; Begin the event handler routine for the EXAMPLE widget.
WIDGET_CONTROL, ev.id, GET_UVALUE = uv ; The uservalue is retrieved from a widget when an event occurs.
if (uv eq 'DONE') THEN WIDGET_CONTROL, ev.top, /DESTROY
;
If the event occurred in the Done button, kill the widget example.
END ; End of the event handler part.
PRO example ; This is the routine that creates the widget and registers it with the XMANAGER.
base = WIDGET_BASE(TITLE='Example') ; Create the top-level base for the widget.
done = WIDGET_BUTTON(base, VALUE = 'Done', UVALUE = 'DONE')
;
Create the Done button and set its uservalue to "DONE".
WIDGET_CONTROL, base, /REALIZE ; Realize the widget (i.e., display it on screen).
XMANAGER, 'example', base, /NO_BLOCK ; Register the widget with the XMANAGER, leaving the IDL command line active.
END ; End of the widget creation part.
First the event handler routine is listed. The handler routine has the same name as the main routine with the characters "_event" added. If you would like to use another event handler name, you would need to pass its name to XMANAGER using the EVENT_HANDLER keyword.
Notice that the event routine is listed before the main routine. This is because the compiler will not compile the event routine if it was below the main routine. This is only needed if both routines reside in the same file and the file name is the same as the main routine name with the
.pro
extension added.
Notice also the NO_BLOCK keyword to XMANAGER has been included. This allows IDL to continue processing events and accepting input at the command prompt while the
example
widget application is running.
XMTOOL , XREGISTERED , .