# CHAPTER 2: Objects

## 2.1 Accessing Objects in a Window

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'

or

    '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`.

## 2.2 Fields & Attributes

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.

## 2.3 Toggle Buttons

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.

## 2.4 Radio Box & Option Menu

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.

## 2.5 List & Multilist

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';

## 2.6 Scale

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.

## 2.7 Hypertext Field

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.

## 2.8 Image & Audio Fields

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.