Any widget application capable of doing real work will include one or more routines that are separate from the routine that creates the widget hierarchy, designed to handle and respond to user-generated events. Event processing routines are the routines that process information contained in widget event structures and respond accordingly; they often retrieve information contained in the widget values of the widgets that make up the interface, perform calculations, and modify the widget interface itself in response to user actions.
Since a widget ID is required to retrieve information from or set values in a widget, you will need a way for your event processing routines to retrieve the ID of a specified widget. This section describes techniques you can use to pass widget IDs between the routines in your widget application, most notably between the widget creation routine (where widget IDs are generated) and the event processing routines.
Use the Widget Event Structure
Every time a user interacts with a widget using the mouse or keyboard, a widget event structure is generated. Widget event structures contain the widget ID of the widget that generated the event. In addition, widget event structures provide the widget ID of the top-level base in the widget hierarchy to which the widget the generated the event belongs.
Getting the widget ID of the appropriate widget from the event structure is almost always the preferred method for passing a widget ID from one routine to another within your application. Widget event processing is discussed in detail in Widget Event Processing.
Pass the Widget ID Using a Widget User Value
The widget event structure always includes two widget IDs: the ID of the widget that generated the event, and the ID of the top-level base widget. If you need to pass multiple widget IDs between routines, it is often useful to place the widget ID values in the user value of the top-level base widget. Widget user values are discussed in Widget User Values.
Use a User Name to Locate the Widget
One of the pieces of information you can specify when you create a widget is a user name. You can associate a name with each widget in a specific hierarchy, and then use that name to query the widget hierarchy and get the correct widget ID. To specify a user name, set the UNAME keyword to the widget creation routine equal to a string that can be used to identify the widget in your code.
To query the widget hierarchy, use the WIDGET_INFO function with the widget ID of the top-level base widget and the FIND_BY_UNAME keyword. Note that user names must be unique within the widget hierarchy, because the FIND_BY_UNAME keyword returns the ID of the first widget with the specified name.
Pass the Widget ID Explicitly
In some cases, you may need to pass a specific widget ID available in one routine to a second routine. In this case, you can specify the widget ID as a parameter when calling the second routine from the first. While this method is not so general as using the widget event structure, it is useful in some circumstances.
Use a COMMON Block
In rare cases, it may be useful to store widget IDs in a COMMON block, making them available to all routines in the application. While using a COMMON block may seem like a good strategy on first inspection, this method has several drawbacks. Most importantly, using a COMMON block to hold widget IDs means that only one instance of a given widget application can be running at once.