An application-defined widget ID for a static or dynamic widget. The value of this attribute must be an even INTEGER value between 2 and 65534, inclusive, and it must be unique across all widget IDs in a window.
Specify an application-defined widget ID when you want to identify the widget at run time while testing your ABL GUI application with a third-party automated test tool. When specified, the AVM uses this application-defined widget ID when creating the widget at run time, instead of using the widget ID it normally generates by default. The widget ID value of any given widget remains the same across ABL sessions, unless you purposely change the value of the widget ID using this attribute. This allows a third-party automated test tool to identify the same widget consistently each time you run the tool with your application.
To enable application-defined widget IDs in your ABL GUI application, you must specify the Use Widget ID (-usewidgetid) startup parameter. For more information about this startup parameter, see OpenEdge Deployment: Startup Command and Parameter Reference.
If you do not specify the Use Widget ID (-usewidgetid) startup parameter, and your application contains application-defined widget IDs, the AVM ignores any WIDGET-ID attribute or option settings and generates its own widget IDs. In this case, querying the WIDGET-ID attribute returns the Unknown value (?).
If you specify the Use Widget ID (-usewidgetid) startup parameter and your application contains application-defined widget IDs, or a combination of application-defined and ABL-defined widget IDs, the AVM honors any application-defined widget IDs and assigns ABL-defined widget IDs as necessary. In this case, querying the WIDGET-ID attribute returns the assigned widget ID (whether it be an application-defined value or an ABL-defined value).
For more information about using application-defined widget IDs when testing ABL GUI applications with third-party automated test tools, see OpenEdge Development: Programming Interfaces.
You can set this attribute only before the widget is realized. Once the widget is realized, this attribute is read-only.
For frames, the AVM uses this attribute value as the basis for assigning a unique widget ID for each child widget within the frame by combining the frame widget ID with the child widget ID. For example, a frame defined with a widget ID of 100 that contains a fill-in widget defined with a widget ID of 2 results in a fill-in widget with a widget ID of 102 at run time. In this way, the widget ID of each child widget within a given frame is unique within that frame, as well as across multiple instances of that frame within a given window. If the value of the frame widget ID combined with the child widget ID is greater than 65534, the AVM displays a warning message and assigns a unique widget ID to the child widget.
When a frame is displayed as a down frame, you can specify an application-defined widget ID for the first instance of the widget on the down frame. The AVM assigns a unique widget ID for each additional instance of the widget on the down frame (based on the number of iterations in the down frame) using consecutive even numbers. Likewise, when a frame contains extent fields, the AVM assigns a widget ID to each of the extent elements in the frame.
When a frame is displayed as a dialog box, which is a special type of frame displayed in its own window, the widget ID for any child widgets inside the dialog box must be unique only within that dialog box.
Note: The default widget ID for a frame is 0 (zero). Use caution when defining multiple frames, or multiple instances of a frame, in a single window and allowing the widget IDs to default to 0, because you are more likely to encounter a duplicate widget ID conflict.
For radio-set widgets, which are built with individual radio buttons, the AVM uses this attribute value as the basis for assigning a unique widget ID for each radio button of the given radio-set widget using consecutive even numbers.
For browse widgets, the AVM uses this attribute value as the basis for assigning a unique widget ID for each column within the browse by automatically incrementing the browse widget ID by 1 for each column within the browse sequentially from left to right.
ABL also provides for assigning widget IDs to widget labels by reserving the previous odd value of each widget ID for the widget's label. For example, if you assign a widget a widget ID of 10, ABL reserves widget ID 9 for the widget's label. ABL does not provide for assigning widget IDs to browse column labels.
You cannot specify an application-defined widget ID for FIELD-GROUP, LITERAL, MENU, MENU-ITEM, SUB-MENU, or WINDOW widgets.
If you specify an invalid widget ID value in a static widget definition, ABL generates a compiler error whether the Use Widget ID (-usewidgetid) startup parameter is specified or not. If you specify an invalid widget ID value in a dynamic widget definition, the AVM generates a run-time error only when the startup parameter is specified.
Caution: To avoid duplicate widget ID conflicts, within and across multiple instances of a widget in a single window, be sure to specify widget IDs within numeric ranges that take other widgets into account. For example, do not specify frame widget IDs in multiples of 10 when you have one or more frame widgets that contain more than 9 child widgets because it will result in a duplicate ID conflict.
