CHAPTER 2: Objects

An Empress GUI Builder module can have multiple windows, and each window can contain objects of different types. In the script language, objects are accessed using the following notation:

'window_name'@'object_name'

'bin_name'@'object_name'

depending on whether the object is contained by a window or a bin (such as a menu). In that sense, a window is considered as a special type of bin.

Names must be quoted (with single quotes or double quotes) unless they are string variables.

In the following examples, window_name can be replaced by bin_name.

Fields and attributes are treated as global variables. The data type of fields can be specified by the developer.

Assigning a value to a field or attribute:

let 'window_name'@'field_name' = value;

let 'table_instance'.'attr_name' = value;

Obtaining the value of a field or attribute:

let variable = 'window_name'@'field_name';

let variable = 'table_instance'.'attr_name';

Assigning a null value to a field will cause the contents of the field to be cleared.

Toggle buttons are objects which are either "on" or "off". They treated as boolean fields. A toggle button is set as follows:

let 'window_name'@'toggle_name' = boolean_value;

The toggle button can also be assigned an integer value as follows:

let 'window_name'@'toggle_name' = integer;

Boolean value false (or integer value 0) will set the toggle off; boolean value true (or any non-zero integer value) will set the toggle on. The value of a toggle can be obtained as follows:

let boolean_variable = 'window_name'@'toggle_name';

In this case, the value read will be false if the toggle is off, and true if it is on.

The data type of a toggle button is boolean, so the following statement is valid:

if ('window'@'toggle') ...

Note that the following statement is invalid since the data type of a toggle button is not integer:

if ('window'@'toggle' = 1) ...

Any action associated with the toggle button will be called when the toggle changes state.

Example

Toggle button t1 in window w1 is initially unset. It has action a1 associated with it.

The statement:

let 'w1'@'t1' = true;

will cause t1 to be set, and a1 will be executed.

Executing the same statement a second time will not cause a change of state, as the toggle is already set, and hence a1 will not be executed a second time.

The radio box and the option menu serve a similar purpose. They both allow the user to select one (and only one) of several values. A radio box can be considered as a set of toggle buttons, all of which are displayed. An option menu can be considered as a set of push buttons, only one of which (the selected one) is displayed.

Most often, the programmer will want to get the setting of a radio box or option menu. Getting the value of the object as follows will return the name of the selected toggle in the radio box, or the selected push button in the option menu.

let variable = 'window_name'@'radio_box';

let variable = 'window_name'@'option_menu';

Similarly, a radio box or option menu can be set as follows:

let 'window_name'@'radio_box' = toggle_name;

let 'window_name'@'option_menu' = pushbutton_name;

Since the radio box is a collection of toggle buttons, when the radio box is set to value, it will trigger the actions associated with the toggle buttons which have changed states.

When an option menu is set to a value, it always triggers the action associated with the push button corresponding to that value.

Both the list and the multilist are treated in the same way in the script language. The list object has a single column, and it is simply considered a special case of the multilist, which can have multiple columns.

The 'window'@'list' syntax cannot be used to assign values to a list or multilist. There are special functions to place data in these objects.

It is not possible to retrieve the contents of the list or multilist. In fact, there is no need to do so, because these objects are non-editable. The only information which can obtained from them is the selected (highlighted) row:

let int_var = 'window_name'@'list_name';

Scales are treated as integer fields. Their values can be read:

let int_var = 'window_name'@'scale_name';

or set:

let 'window_name'@'scale_name' = integer;

A scale has maximum and minimum values (defined by the developer). Attempting to set it to a value greater than the maximum causes it to be set to that maximum value. Attempting to set it to a value lower than the minimum causes it to be set to that minimum value.

Although the scale object can be defined to display values with decimal places, these decimal places are ignored in the script language. For example, a scale defined to have a minimum of 0, maximum of 100, with two decimal places, will be displayed with a range of 0.00 to 1.00. However, values read from the scale will still be in the range of 0 to 100.

A hypertext field can be assigned a character string value:

let 'window_name'@'h_text_field' = doc_name;

Provided that the string value is the name of a hypertext document, the latter will be displayed in the hypertext field.

Assigning a null value to a hypertext field will cause the contents of the field to be cleared.

Image and audio fields can be assigned a bulk attribute:

let 'window_name'@'picture_field' = 'tab_inst'.'bulk_attr';

let 'window_name'@'audio_field' = 'tab_inst'.'bulk_attr';

Provided that the bulk attribute contains a valid image or audio data, it will be handled appropriately by the object.

Assigning a null value to an image field will cause the contents of the field to be cleared.