System Widget

_______________________________________________________

SYSTEM Widget

Acts as a container and manager for the widgets specified in files generated by the ScreenBuilder application

_______________________________________________________

Legal Usage Level-0 Widget: Yes

Parent to: None

Child of: PANEL

Example Image

Example Program

See SYSTEM Widget as a Child for an example program that generates a display similar to that shown above.

NOTE

See the following programs for other examples using the SYSTEM widget:

Bomb Squad (Using ScreenBuilder)

Bomb Squad (Using SYSTEM Widget)

SYSTEM Widget as a Child

SYSTEM Widget Event Disabling

SYSTEM Widget Event Handler

SYSTEM Widget Event Queuing

Attributes

See SYSTEM Widget Attributes for the SYSTEM widget attribute list.

Remarks

The SYSTEM widget acts as a container and manager for the widgets specifiedin files generated by the ScreenBuilder application. The SYSTEM widget is a unique widget in that it does not create a window. Rather, it manages other widgets. The SYSTEM widget can also manage a queue of events generated by the widgets it contains.

The SYSTEM widget provides attributes to select and modify the attributes of the widgets it manages or to manage their events. It also provides the ability to programmatically create new widgets.

The convention used to name the widgets of a SYSTEM widget is similar to that used for hierarchical file systems. The top-level widgets have simple names while their child widgets always have the names of their parents affixed to the beginning of their simple names. For example:

"Meter1"

"Panel0/Panel2/Meter0"

The SYSTEM widget does not have any of the generic attributes usually associated with other widgets. The SYSTEM widget has only the following SYSTEM-specific attributes which have the "*" prefix. Any other attribute will be forwarded to one of the managed widgets as specified by the most recent *NAME attribute.

The ScreenBuilder is used to generate a file that describes a user interface, and the SYSTEM widget is used to integrate this file into a program. The SYSTEM widget's only function is to help control a system of widgets.

The SYSTEM widget has no attributes that control its appearance. However, it has a set of specific attributes that are used to change the widgets it controls. Because the special nature of these attributes, their names are prefixed with an asterisk. For example, "*NAME" is the SYSTEM widget attribute used to select one of its widgets. You can use the SYSTEM widget in one of two ways:

·	Using ScreenBuilder (*LOAD)

·	Using SYSTEM Widget Alone (*CREATE)

Using ScreenBuilder (*LOAD)

The ScreenBuilder generates a file containing the names and specified attributes of the widgets defined with that application. This file is read by the SYSTEM widget to connect it to a program, using the "*LOAD" attribute:

ASSIGN @Sys TO WIDGET "SYSTEM";SET("*LOAD":<filename>)

This must be done every time you run the program. The file must be present, or the program will stop with an error. Once the ScreenBuilder file has been loaded, any of the widgets defined in the file can be controlled via the SYSTEM widget by selecting it with the *NAME attribute. For example, if a main PANEL is defined in the file with the name "Main", it can be accessed with:

CONTROL @Sys;SET("*NAME":"Main", "WIDTH":10, "HEIGHT":20)

Once a widget has been selected with *NAME, all subsequent widget CONTROL and STATUS statements are passed through the SYSTEM widget and affect that widget and that widget only until a different *NAME is set. Similarly, if, for example, "Main"has a child widget named "Meter2", that child can be accessed with:

CONTROL @Sys;SET("*NAME":"Main/Meter2", "X":10, "Y":20)

This scheme implies that widgets - at least those defined by the ScreenBuilder application - can now be defined in string (or string array) variables:

W$="Main/Bar1" STATUS @Sys;RETURN("*NAME":W$, "X":I, "Y":J)

Events can be trapped through the SYSTEM widget as well, although all you can specify is the event type to be trapped, not the particular event source:

ON EVENT @Sys,"CLICKED" GOTO Handler

ON EVENT @Sys,"DONE" GOTO Handler

ON EVENT @Sys "SYSTEM CLOSE" GOTO Handler

You can determine the source by using the *QUEUED EVENT attribute:

Ev$(1:2)[50]

STATUS @Sys;RETURN("*QUEUED EVENT":Ev$(*))

PRINT "Widget name: ";Ev$(1);" Widget event: ";Ev$(2)

By default, the SYSTEM widget only keeps track of the latest event. That is, if you do not read the events as they happen, you will lose all but the last event.

In some cases this is not a problem. The user clicks on a button, the program traps the event and does something, and then the user does something else. However, in user interfaces that contain multiple widgets that have the same event name, you must arrange for the SYSTEM widget to queue up events.

You can set up event queuing by setting the *QUEUE EVENTS attribute to 1. The SYSTEM widget will then store all events that happen within it in the order they occur. You can determine the number of events in the queue with the *QUEUED EVENTS attribute:

STATUS @Sys;RETURN ("*QUEUED EVENTS":Numevents)

and then read each event in sequence using the *QUEUED EVENT attribute. The SYSTEM widget has three attributes that have similar names:

·	QUEUE EVENTS -- to set event handling

QUEUE EVENTS -- to set event

·	QUEUED EVENT -- to get the last event

·	QUEUED EVENTS -- to get the number of events in the queue

You may want to get all events of a certain type at the same time, however, to allow you to sort them out. The SYSTEM widget has two attributes to allow you to specify which widget and event type will be read from the queue (leaving all the others remaining):

·	EVENT NAME FILTER

·	EVENT WIDGET FILTER

Using SYSTEM Widget Alone (*CREATE)

The SYSTEM widget can also be used without a ScreenBuilder file by using the *CREATE attribute. For example, to create a PANEL named "Main", execute thefollowing (*NAME must be specified before *CREATE can create the widget):

CONTROL @Sys; SET("*NAME":"Main","*CREATE":"PANEL")

You can specify widget pathnames to define a parent-child relationship. For example, to create a child CLOCK widget named "Clock", execute:

CONTROL @Sys; SET("*NAME":"Main/Clock","*CREATE":"CLOCK")

Creating an entire user interface with the SYSTEM widget using *CREATE can have some disadvantages. For example, if all widgets are different, it takes more work than building the user interface in the normal fashion. The advantage of doing this, however, is when you have a set of widgets that are exactly the same - say, a grid of PUSHBUTTON,STRING, or LABEL widgets. Since you define the widgets using names given as strings in a string variable or string array you avoid the normal HTBasic restriction of having a widget handle for each widget and a separate ON EVENT handler for each event.

Events

The SYSTEM widget has no events of its own, but inherits the events defined by its widgets. ON EVENT branches for each of the contained widgets must be set up using the SYSTEM widget's I/O path.

For widgets that share the same event name (e.g., "CHANGED"), only one ON EVENT branch can be established for all of them. Once the branch has been taken, use the "*QUEUED EVENT" attribute to determine which widget and/or which event caused the branch.

The SYSTEM widget accepts the "SYSTEM CLOSE" event for programmatically closing System Widgets.