# CHAPTER 3: Objects

## 3.1 Introduction

An Empress GUI Builder application is made up of objects, bins and windows. Objects are components that make up an application. They provide an interface to the application developer for all kinds of manipulations on a database. Tools are available to manipulate the objects in many ways to build meaningful applications. Bins and windows are special types of objects used to act as containers for other objects. There are the following types of objects available in Empress GUI Builder:

Audio Field Bin Field Hypertext Field Label Cascade Button Image Field List Multilist | Option Menu Push Button Scale Toggle Button Radio Box Separator User Defined Window

Empress GUI Builder objects are controlled by a set of behaviors unique to each type of object. These behaviors are called Properties of Objects.

Properties define a way to use objects. There are many properties available in Empress GUI Builder. However, only a small subset of these properties apply to any single object, depending upon the nature and the use of that object. Following chapters define how to access objects, properties for each type of object and how to manipulate these properties though C Application Programming Interface functions.

## 3.2 Accessing Objects in C API

### 3.2.1 Initialization

All Empress GUI Builder objects are accessed through the bins or the windows they are contained in. Before objects can be accessed, the Empress GUI Builder application must be initialized and the bins that contain the objects must be accessed. The C API function to perform the operation is as follows:

    gui_status empgui_c_initialize (& mainwin, & menubar,

         {binname, & bin,} (char *)0)

Example

For an application that has a main window, a menu bar, and a radio box bin called `rboxbin`, the variable declaration could be as follows:

    object mainwin, menubar, radiobin;
    char *binname = "rboxbin";
    gui_status status;

then the call to this function to initialize variables would be:

    status = empgui_c_initialize (& mainwin, & menubar, binname,
             & radiobin, (char *)0);

### 3.2.2 Accessing Bins & Windows

The initialization routine can be used to access as many bins as needed. However, this routine should be called only once at the beginning of the program. C API provides routines to access bins at any other place in the program. To access only one bin through its name:

    gui_status empgui_c_bin_get_by_name (binname, & bin)

To get an array of bins through their names:

    gui_status empgui_c_bins_get_by_names (binnames, & bins)

Example

For an application that has a main window, a radio box bin called "`rboxbin"`, and an option menu bin called "`omenubin"`, the variable declaration could be as follows:

    object mainwin, *bins;
    char *binnames[3];

To get the bin objects using this function, the `binnames` array should be initialized with the names of the bins and null terminated:

    binnames[0] = "rboxbin";
    binnames[1] = "omenubin";
    binnames[2] = (char *)0;

the call to this function to get the bin objects would be:

    status = empgui_c_bins_get_by_names (binnames, & bins);

Bins corresponding to the binnames array would be accessible as `*bins`, `*(bins+1)`.

### 3.2.3 Accessing Component Objects

Once a bin has been accessed, all the objects in that bin can be accessed. C API provides many routines to access objects from a given bin. To get only one object through its name:

    gui_status empgui_c_obj_get_by_name (bin, name, & obj)

To get an array of objects contained in the same bin through their names:

    gui_status empgui_c_objs_get_by_names (bin, names, & objs)

Example

For an application that has a main window, and three push button objects called "`pushb1"`, "`pushb2"`, "`pushb3"` in the main window, the variable declaration could be as follows:

    object mainwin, *pbobjs;
    char *objnames[4];

To get the objects using this function, the `objnames` array would first be initialized with the names of the objects and null terminated:

    objnames[0] = "pushb1";
    objnames[1] = "pushb2";
    objnames[2] = "pushb3";
    objnames[3] = (char *)0;

the call to this function to get the bin objects would be:

    status = empgui_c_objs_get_by_names(mainwin, objnames, & pbobjs);

(Assuming that `mainwin` has already been initialized)

Objects corresponding to the objnames array would be accessible as `*(pbobjs)`, `*(pbobjs+1)`, and `*(pbobjs+2)`.

To access more than one object without creating the object and names arrays:

    gui_status empgui_c_objs_get_by_name_pair (bin, name, & obj, {name, & obj,}
    (char *)0)

The above routine can be used to access as many objects as needed without creating the names and object arrays. C API provides two more routines to access all the objects from a given bin. To access all the objects from a given bin:

    gui_status empgui_c_objs_get_from_bin (bin, & objs)

To get all the objects and their names from a given bin:

    gui_status empgui_c_objs_names_get_from_bin (bin, & objs, & names)

Please note that all the bins and objects do not need to be accessed at one time. They can be accessed as the need arises. This dynamic behavior allows greater flexibility in designing Empress GUI Builder applications.

## 3.3 Properties of Objects

All Empress GUI Builder objects are manipulated through their properties. The following sections describe general routines to manipulate properties of objects with examples for all types of property data, and all objects along with their properties with any special routines that are applicable to these objects and whether these properties are gettable or settable. There is also a section that describes all property errors.

### 3.3.1 General Property Routines

There are general purpose routines in C API to get and set properties of any object. To get an applicable property of an object:

    gui_status empgui_c_prop_get (obj, prop_type, &data)

where:

`> object obj` | `object`
`> int prop_type` | `property type`
`< type data` | `property data`

">" means input parameters
"<" means output parameters

To set an applicable property of an object:

    gui_status empgui_c_prop_set (obj, prop_type, &data)

where:

`> object obj` | `object`
| `> int prop_type` | `property type`
`> type data` | `property data`

">" means input parameters
"<" means output parameters

To access an applicable property for an array of objects:

    gui_status empgui_c_props_get (objs, prop_type, &datas)

where:

`> object *objs` | `array of objects`
`> int prop_type` | `property type`
`< type datas` | `property datas`

">" means input parameters
"<" means output parameters

To set an applicable property for an array of objects:

    gui_status empgui_c_props_set (objs, prop_type, datas)

where:

`> object *objs` | `object`
`> int prop_type` | `property type`
`> type datas` | `property datas`

">" means input parameters
"<" means output parameters

Please note that to get or set a property for an array of objects, that property must be applicable to all the objects in the array. The type of data and datas in the above functions would depend on the property and the object in question.

The routine to get a property of an object, `empgui_c_prop_get()`, assigns a value to the pointer provided in the argument list of the function. In cases of the property data type being a pointer, the pointer in the argument list points to the internal Empress GUI Builder data structures. In cases like these, the user should not modify the contents of the pointer in the argument list.

The routine to get a property for an array of objects, `empgui_c_props_get()`, allocates an array and assigns it to the pointer provided in the argument list of the function. In cases of the data type being a pointer, this array is an array of pointers, and each of these pointers point to the internal Empress GUI Builder data structures. In cases like these, the user should not modify the contents of the pointers elements of the array in the argument list.

### 3.3.2 Property Data Types

In C API the data types of the parameters data and datas in the above general purpose routines depend only on the type of the property data they are used to store for that particular property / object pair. Empress GUI Builder supports the following types of property data types.

    TYPE_BOOLEAN
    TYPE_BULK
    TYPE_CHARACTER
    TYPE_INTEGER
    TYPE_SELECTION
    TYPE_STRING
    TYPE_STRING_ARRAY

The following examples describe the use of the above routines for each type of property data. They assume a generic property `PROP_GEN` and a generic object. All possible pairs of objects/property applicable to that property data type are also listed.

If `empgui_c_prop_get` or `empgui_c_props_get` is used to get a property of an object or an array of objects, that particular property must be gettable. Similarly, if `empgui_c_prop_set` or `empgui_c_props_set` is used to set a property of an object or an array of objects, that particular property must be "settable".

#### 3.3.2.1 TYPE_ADDRESS

`TYPE_ADDRESS` is applicable to the following pairs of objects/properties.

Possible Objects | Possible values for PROP_GEN
`User-defined object` | `PROP_USER_DATA`

Example

The C data-type for `TYPE_ADDRESS` is `addr`, which is a generic pointer data type.

    empgui_c_prop_get()

For an application that has a main window and an object called "`generic_object`" which has a gettable property called `PROP_GEN`, an example to use `empgui_c_prop_get` would be as follows:

The variable declaration would be:

    object mainwin, genobj;

    gui_status status;

    addr data;

To get the object

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_get` to get a generic property called `PROP_GEN` of this object:

    status = empgui_c_prop_get (genobj, PROP_GEN, &data);

Example

Note that the routine is passed the address of the property data type which is `addr` in this case.

    empgui_c_prop_set()

For an application that has a main window and an object called "`generic_object`" which has a settable property called `PROP_GEN`, an example to use `empgui_c_prop_set` would be as follows:

The variable declaration would be:

    object mainwin, genobj;

    gui_status status;

    addr data;

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_set` to set a generic property called `PROP_GEN` of this object:

    status = empgui_c_prop_set (genobj, PROP_GEN, &data);

Example

Note that the routine is passed the address of the property data type which is `addr` in this case.

    empgui_c_props_get()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_get` would be as follows:

The variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`addr *datas;`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_get` to get a generic property called `PROP_GEN` of all these objects:

    status = empgui_c_props_get (genobjs, PROP_GEN, &datas);

Example

Note that the routine is passed the address of a pointer. It allocates an array of type `addr` and assigns it to the pointer.

    empgui_c_props_set()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_set` would be as follows:

The variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`addr datas[5];`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_set` to set a generic property called `PROP_GEN` of all these objects:

    status = empgui_c_props_set (genobjs, PROP_GEN, datas);

Note that the routine is passed an array of type `addr`.

#### 3.3.2.2 TYPE_BOOLEAN

`TYPE_BOOLEAN` is applicable to the following pairs of objects/properties.

Possible Objects | Possible values for PROP_GEN
`Audio field` | `PROP_SENSITIVITY`
`Bin` | `PROP_SENSITIVITY`
`Cascade button` | `PROP_SENSITIVITY`
`Field` | `PROP_EDITABLE` `PROP_SENSITIVITY`
`Hypertext field` | `PROP_SENSITIVITY`
`Image field` | `PROP_SENSITIVITY`
`Label` | `PROP_SENSITIVITY`
`List` | `PROP_SENSITIVITY`
`Multilist` | `PROP_SENSITIVITY`
`Option menu` | `PROP_EDITABLE` `PROP_SENSITIVITY`
`Push button` | `PROP_SENSITIVITY`
`Radio box` | `PROP_EDITABLE` `PROP_SENSITIVITY`
`Scale` | `PROP_EDITABLE` `PROP_SENSITIVITY`
`Separator` | `PROP_SENSITIVITY`
`Toggle button` | `PROP_VALUE` `PROP_EDITABLE` `PROP_SENSITIVITY`
`User-defined object` | `PROP_SENSITIVITY`
`Window` | `PROP_SENSITIVITY`

Example

The C data type for `TYPE_BOOLEAN` is boolean, for which only two values are valid: true and false.

    empgui_c_prop_get()

For an application that has a main window and an object called "`generic_object`" which has a gettable property called `PROP_GEN`, an example to use `empgui_c_prop_get` would be as follows:

The variable declaration would be:

`object mainwin, genobj;`
`gui_status status;`
`boolean data;`

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_get` to get a generic property called `PROP_GEN` of this object:

`status = empgui_c_prop_get (genobj, PROP_GEN, &data);`
`if (data == true)`
`{`
`......`
`......`
`}`

Example

Note that the routine is passed the address of the property data type which is `boolean` in this case.

    empgui_c_prop_set()

For an application that has a main window and an object called "`generic_object`" which has a settable property called `PROP_GEN`, an example to use `empgui_c_prop_set` would be as follows:

The variable declaration would be:

`object mainwin, genobj;`
`gui_status status;`
`boolean data = true;`

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_set` to set a generic property called `PROP_GEN` of this object:

    status = empgui_c_prop_set (genobj, PROP_GEN, &data);

Example

Note that the routine is passed the address of the property data type which is `boolean` in this case.

    empgui_c_props_get()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_get` would be as follows:

The variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`boolean *datas;`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_get` to get a generic property called `PROP_GEN` of all these objects:

`status = empgui_c_props_get (genobjs, PROP_GEN, &datas);`
`if ( (*datas) == true && (*(datas+1)) == false )`
`{`
`.......`
`.......`
`}`

Example

Note that the routine is passed the address of a pointer. It allocates an array of type `boolean` and assigns it to the pointer.

    empgui_c_props_set()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_set` would be as follows:

The variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`boolean datas[] = { false, true, true, false, true };`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_set` to set a generic property called `PROP_GEN` of all these objects:

    status = empgui_c_props_set (genobjs, PROP_GEN, datas);

Note that the routine is passed an array of type `boolean`.

#### 3.3.2.3 TYPE_BULK

`TYPE_BULK` is applicable to the following pairs of objects/properties.

Possible Objects | Possible values for PROP_GEN
`Audio field` | `PROP_VALUE`
`Image field` | `PROP_VALUE`

Note that for `TYPE_BULK`, the above mentioned properties `PROP_VALUE` for audio and image field objects are only settable. In this case, `empgui_c_prop_get` and `empgui_c_props_get` do not apply.

The Empress bulk internal format is described as follows:

`typedef struct`
`{`
`long num_bytes;`
`char data [num_bytes];`
`} bulk;`

The C data type for `TYPE_BULK` is `(bulk *)`, where `bulk` is the structure defined above.

Example

    empgui_c_prop_set()

For an application that has a main window and an object called "`generic_object`" which has a settable property called `PROP_GEN`, an example to use `empgui_c_prop_set` would be as follows:

The variable declaration would be:

`object mainwin, genobj;`
`gui_status status;`
`bulk data, *dataptr;`

`data` must be assigned a value from an attribute of a table which is also of type `bulk`.

The address of data must be stored in `dataptr` variable.

    dataptr = &data;

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_set` to set a generic property called `PROP_GEN` of this object:

    status = empgui_c_prop_set (genobj, PROP_GEN, &dataptr);

Note that the routine is passed the address of the property data type which is `(bulk *)` in this case.

Example

    empgui_c_props_set()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_set` would be as follows:

The variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`bulk datas[5], *datasptr[5];`

Each entry of the array `datas` must be assigned a value from the attributes of a table which also must be of type `bulk`.

Each element of the array `datasptr` must be assigned the address of the corresponding element of the array `datas`:

`datasptr[0] = &datas[0];`
`datasptr[1] = &datas[1];`
`datasptr[2] = &datas[2];`
`datasptr[3] = &datas[3];`
`datasptr[4] = &datas[4];`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_set` to set a generic property called `PROP_GEN` of all these objects:

    status = empgui_c_props_set (genobjs, PROP_GEN, datasptr);

Note that the routine is passed an array of type `(bulk *)`.

#### 3.3.2.4 TYPE_CHAR

`TYPE_CHAR` is applicable to the following pairs of objects/properties.

Possible Objects | Possible values for PROP_GEN
`bin` | `PROP_TYPE`
`window` | `PROP_TYPE`

The C data type for `TYPE_CHAR` is char.

Note that for `TYPE_CHAR`, the above mentioned properties `PROP_TYPE` for bin and win objects are only "gettable". In this case, `empgui_c_prop_set` and `empgui_c_props_set` do not apply.

Example

    empgui_c_prop_get()

For an application that has a main window and an object called "`generic_object`" which has a gettable property called `PROP_GEN`, an example to use `empgui_c_prop_get` would be as follows:

The variable declaration would be:

`object mainwin, genobj;`
`gui_status status;`
`char data;`

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_get` to get a generic property called `PROP_GEN` of this object:

`status = empgui_c_prop_get (genobj, PROP_GEN, &data);`

`if (data == w')`
`{`
`......`
`......`
`}`

Note that the routine is passed the address of the property data type which is `char` in this case.

Example

    empgui_c_props_get()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_get` would be as follows:

The variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`char *datas;`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_get` to get a generic property called `PROP_GEN` of all these objects:

`status = empgui_c_props_get (genobjs, PROP_GEN, &datas);`
`if ( (*datas) == w' && (*(datas+1)) == a' )`
`{`
`.......`
`.......`
`}`

Note that the routine is passed the address of a pointer and it allocates an array of type `char` and assigns it to the pointer.

#### 3.3.2.5 TYPE_INTEGER

`TYPE_INTEGER` is applicable to the following pairs of objects/properties.

Possible Objects | Possible values for PROP_GEN
`Audio field` | `PROP_STATE`
`Field` | `PROP_LINE`
`List` | `PROP_VALUE` `PROP_VIEWABLE_ROWS`
`Multilist` | `PROP_VALUE` `PROP_COLUMNS` `PROP_VIEWABLE_ROWS`
`Scale` | `PROP_VALUE`

The C data type for `TYPE_INTEGER` is `int`.

Example

    empgui_c_prop_get()

For an application that has a main window and an object called "`generic_object`" which has a gettable property called `PROP_GEN`, an example to use `empgui_c_prop_get` would be as follows:

The variable declaration would be:

`object mainwin, genobj;`
`gui_status status;`
`int data;`

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_get` to get a generic property called `PROP_GEN` of this object:

`status = empgui_c_prop_get (genobj, PROP_GEN, &data);`

`if (data == 5)`
`{`
`......`
`......`
`}`

Note that the routine is passed the address of the property data type which is `int` in this case.

Example

    empgui_c_prop_set()

For an application that has a main window and an object called "`generic_object`" which has a settable property called `PROP_GEN`, an example to use `empgui_c_prop_set` would be as follows:

The variable declaration would be:

`object mainwin, genobj;`
`gui_status status;`
`int data = 5;`

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_set` to set a generic property called `PROP_GEN` of this object:

    status = empgui_c_prop_set (genobj, PROP_GEN, &data);

Note that the routine is passed the address of the property data type which is `int` in this case.

Example

    empgui_c_props_get()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_get` would be as follows:

The variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`int *datas;`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_get` to get a generic property called `PROP_GEN` of all these objects:

`status = empgui_c_props_get (genobjs, PROP_GEN, &datas);`
`if ( (*datas) == 5 && (*(datas+1)) == 6 )`
`{`
`.......`
`.......`
`}`

Note that the routine is passed the address of a pointer and it allocates an array of type `int` and assigns it to the pointer.

Example

    empgui_c_props_set()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_set` would be as follows:

The variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`int datas[] = { 5, 6, 7, 8, 9 };`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_set` to set a generic property called `PROP_GEN` of all these objects:

    status = empgui_c_props_set (genobjs, PROP_GEN, datas);

Note that the routine is passed an array of type `int`.

#### 3.3.2.6 TYPE_SELECTION

`TYPE_SELECTION` is applicable to the following pairs of objects/properties.

Possible Objects | Possible values for PROP_GEN
`List` | `PROP_LIST_SELPOS`
`Multilist` | `PROP_LIST_SELPOS`

The C data type for `TYPE_SELECTION` is `(struct *)`, where the structure is defined as follows:

`typedef struct`
`{`
`int number ;`
`int * selected ;`
`boolean notify ;`
`} selection;`

where:

`number` | is the actual number of rows selected
`selected` | is an array that stores the row numbers for all rows selected.
`notify` | is only applicable for `empgui_c_prop_set` and `empgui_c_props_set`. If it is set to true, the single-click action defined for the object is executed.

For instance, if only fifth row is selected for a list or a multilist, number would be 1, and selected will only be a one element array with that element equal to 5.

Warning

When getting the property, the memory allocated to the selection structure and the selected integer array is internally maintained by Empress GUI Builder. The programmer should not attempt to free or change the contents of the array. Also, the array is de-allocated whenever the user changes the selection on the list or multilist object. Hence, the programmer should make use of the array before the user changes the selection.

Example

    empgui_c_prop_get()

For an application that has a main window and an object called "`generic_object`" which has a gettable property called `PROP_GEN`, an example to use `empgui_c_prop_get` would be as follows:

Assuming that the selection structure has been defined, the variable declaration would be:

`object mainwin, genobj;`
`gui_status status;`
`selection *data;`

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_get` to get a generic property called `PROP_GEN` of this object:

`status = empgui_c_prop_get (genobj, PROP_GEN, &data);`

`for (i=0; i < (data->number); i++)`
`{`
`let x = data->selected[i];`
`......`
`......`
`}`

Note that the routine is passed the address of the property data type which is `(selection *)` in this case.

Example

    empgui_c_prop_set()

For an application that has a main window and an object called "`generic_object`" which has a settable property called PROP_GEN, an example to use `empgui_c_prop_set` would be as follows:

Assuming that the selection structure has been defined, the variable declaration would be:

`object mainwin, genobj;`
`gui_status status;`
`selection sel_data, *data;`
`int sel_array[10];`

`sel_data.selected = sel_array;`
`data = &sel_data;`

Assigning values to elements of `data`, assuming that memory has already been allocated:

`data->number = 1;`
`data->selected[0] = 2;`
`data->notify = true;`

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_set` to set a generic property called `PROP_GEN` of this object:

    status = empgui_c_prop_set (genobj, PROP_GEN, &data);

Note that the routine is passed an address of the property data type which is `(selection *)` in this case.

Example

    empgui_c_props_get()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_get` would be as follows:

Assuming that the selection structure has been defined, the variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`selection **datas;`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_get` to get a generic property called `PROP_GEN` of all these objects:

`status = empgui_c_props_get (genobjs, PROP_GEN, &datas)`
`if ( (*datas)->number == 1 && (*(datas+1))->number == 1 )`
`{`
`.......`
`.......`
`}`

Note that the routine is passed the address of a pointer. It allocates an array of type`(selection *)` and assigns it to the pointer.

Example

    empgui_c_props_set()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_set` would be as follows:

Assuming that the selection structure has been defined, the variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`selection sdata1, sdata2, sdata3, sdata4, sdata5;`
`selection *data1, *data2, *data3, *data4, *data5;`
`selection *datas[5];`

`data1 = &sdata1;`
`data2 = &sdata2;`
`data3 = &sdata3;`
`data4 = &sdata4;`
`data5 = &sdata5;`

Assigning values to structures, assuming memory has already been allocated:

`data1->number = 1;`
`data1->selected[0] = 2;`
`data1->notify = true;`

`data2->number = 1;`
`data2->selected[0] = 2;`
`data2->notify = true;`
`.....`

Assigning values to array `datas`:

`datas[0] = data1;`
`datas[1] = data2;`
`datas[2] = data3;`
`datas[3] = data4;`
`datas[4] = data5;`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_set` to set a generic property called `PROP_GEN` of all these objects:

    status = empgui_c_props_set (genobjs, PROP_GEN, datas);

Note that the routine is passed an array of type `(selection *)`.

#### 3.3.2.7 TYPE_STRING

`TYPE_STRING` is applicable to the following pairs of objects/properties.

Possible Objects | Possible values for PROP_GEN
`Audio field` | `PROP_NAME` `PROP_DESCRIPTION`
`Bin` | `PROP_NAME` `PROP_DESCRIPTION`
`Field` | `PROP_NAME` `PROP_DESCRIPTION` `PROP_FIELD_TYPE` `PROP_VALUE` `PROP_VALUE_INSERT` `PROP_VALUE_APPEND`
`Hypertext` | `PROP_NAME` `PROP_DESCRIPTION` `PROP_TEXT_VALUE` `PROP_VALUE`
`Label` | `PROP_NAME` `PROP_DESCRIPTION` `PROP_LABEL_TEXT` `PROP_LABEL_PIXMAP`
`Cascade button` | `PROP_NAME` `PROP_DESCRIPTION` `PROP_LABEL_TEXT` `PROP_LABEL_PIXMAP`
`Image field` | `PROP_NAME` `PROP_DESCRIPTION`
`List` | `PROP_NAME` `PROP_DESCRIPTION`
`Multilist` | `PROP_NAME` `PROP_DESCRIPTION`
`Option menu` | `PROP_NAME` `PROP_DESCRIPTION` `PROP_LABEL_TEXT` `PROP_LABEL_PIXMAP` `PROP_VALUE`
`Push button` | `PROP_NAME` `PROP_DESCRIPTION`
`Scale` | `PROP_NAME` `PROP_DESCRIPTION`
`Toggle button` | `PROP_NAME` `PROP_DESCRIPTION`
`Radio box` | `PROP_NAME` `PROP_DESCRIPTION` `PROP_VALUE`
`Separator` | `PROP_NAME` `PROP_DESCRIPTION`
`User defined object` | `PROP_NAME` `PROP_DESCRIPTION`
`Window` | `PROP_NAME` `PROP_DESCRIPTION`

``
The C data type for `TYPE_STRING` is `(char *)`.

Example

    empgui_c_prop_get()

For an application that has a main window and an object called "`generic_object`" which has a gettable property called `PROP_GEN`, an example to use `empgui_c_prop_get` would be as follows:

The variable declaration would be:

`object mainwin, genobj;`
`gui_status status;`
`char *data;`

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_get` to get a generic property called `PROP_GEN` of this object:

`status = empgui_c_prop_get (genobj, PROP_GEN, &data)`

`fprintf (stdout, "String is %s\n", data);`

Note that the routine is passed the address of the property data type which is `(char *)` in this case.

Example

    empgui_c_prop_set()

For an application that has a main window and an object called "`generic_object`" which has a settable property called `PROP_GEN`, an example to use `empgui_c_prop_set` would be as follows:

The variable declaration would be:

`object mainwin, genobj;`
`gui_status status;`
`char *data = "Hello Object";`

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using `empgui_c_prop_set` to set a generic property called `PROP_GEN` of this object:

    status = empgui_c_prop_set (genobj, PROP_GEN, &data);

Note that the routine is passed the address of the property data type which is `(char *)` in this case.

Example

    empgui_c_props_get()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_get` would be as follows:

The variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`char **datas;`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_get` to get a generic property called `PROP_GEN` of all these objects:

`status = empgui_c_props_get (genobjs, PROP_GEN, &datas);`
`fprintf (stdout, "Strings are %s and %s\n", (*datas), (*(datas+1)));`

Note that the routine is passed the address of a pointer. It allocates an array of type `(char *)` and assigns it to the pointer.

Example

    empgui_c_props_set()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_set` would be as follows:

The variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`char *datas[];`
`char *data1 = "Object 1";`
`char *data2 = "Object 2";`
`char *data3 = "Object 3";`
`char *data4 = "Object 4";`
`char *data5 = "Object 5";`

Assigning values to the elements of datas:

`datas[0] = data1;`
`datas[1] = data2;`
`datas[2] = data3;`
`datas[3] = data4;`
`datas[4] = data5;`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_set` to set a generic property called `PROP_GEN` of all these objects:

    status = empgui_c_props_set (genobjs, PROP_GEN, datas);

Note that the routine is passed an array of type `(char *)`.

#### 3.3.2.8 TYPE_STRING_ARRAY

`TYPE_STRING_ARRAY` is applicable to the following pairs of objects/properties.

Possible Objects | Possible values for PROP_GEN
`Option menu` | `PROP_ITEMS_SENSITIVE` `PROP_ITEMS_INSENSITIVE`

The C data type for `TYPE_STRING_ARRAY` is `(char **)`.

Note that for `TYPE_STRING_ARRAY`, the above mentioned properties `PROP_ITEMS_SENSITIVE` and `PROP_ITEMS_INSENSITIVE` for an option menu object are only "settable". In this case, `empgui_c_prop_get` and `empgui_c_props_get` do not apply.

Example

    empgui_c_prop_set()

For an application that has a main window and an object called "`generic_object`" which has a settable property called `PROP_GEN`, an example to use `empgui_c_prop_set` would be as follows:

The variable declaration would be:

`object mainwin, genobj;`
`gui_status status;`
`char *data[5];`

`char *data1 = "Object 1";`
`char *data2 = "Object 2";`
`char *data3 = "Object 3";`
`char *data4 = "Object 4";`
`char *data5 = "Object 5";`

Assigning values to the elements of datas:

`data[0] = data1;`
`data[1] = data2;`
`data[2] = data3;`
`data[3] = data4;`
`data[4] = data5;`

To get the object:

    status = empgui_c_obj_get_by_name(mainwin, "generic_object", &genobj);

Using this function to set a generic property called `PROP_GEN` of this object

    status = empgui_c_prop_set (genobj, PROP_GEN, &data);

Note that the routine is passed the address of the property data type which is `(char **)` in this case.

Example

    empgui_c_props_set()

For an application that has a main window and five generic objects called "`generic_object1`", "`generic_object2`", "`generic_object3`", "`generic_object4`", "`generic_object5`", all of which have a gettable property called `PROP_GEN`, an example to use `empgui_c_props_set` would be as follows:

The variable declaration would be:

`object mainwin, *genobjs;`
`char *objsname[5] = {"generic_object1", "generic_object2",`
`"generic_object3", "generic_object4", "generic_object5"};`
`gui_status status;`
`char **datas[5];`
`char *data1[2], *data2[2], *data3[2], *data4[2], *data5[2];`

`char *data11 = "Object 1";`
`char *data22 = "Object 2";`

Assigning values to the elements of `data1`, `data2`, and so on.

`data1[0] = data11;`
`data1[1] = data22;`

`data2[0] = data11;`
`data2[1] = data22;`

`.......`

Assigning values to the elements of `datas`:

`datas[0] = data1;`
`datas[1] = data2;`
`datas[2] = data3;`
`datas[3] = data4;`
`datas[4] = data5;`

To get the objects:

    status = empgui_c_objs_get_by_names(mainwin, objnames, &genobjs);

Using `empgui_c_props_set` to set a generic property called `PROP_GEN` of all these objects:

    status = empgui_c_props_set (genobjs, PROP_GEN, datas);

Note that the routine is passed an array of `(char **)`.

## 3.4 Special Property Functions

Apart from the general property routines described previously, there are many additional property routines which are used either for specific properties or specific types of objects. These special routines do not add functionality to the C API (since they call the general property routines). They are provided for convenience.

The `PROP_SENSITIVITY` property can be set for all types of objects. It is a boolean flag; true means sensitive, and false means insensitive. A sensitive object can be activated (it is the default state). An insensitive object cannot be activated, and it has a "grayed out" appearance. For example, the label on an insensitive push button will look faded, and the button will not react to mouse clicks. For bins and windows, insensitivity implies that all the objects that they contain are insensitive. Several convenience routines are available to set this property:

To set the sensitivity of a single object:

    gui_status empgui_c_sen_set (obj, sen)

where:

`> object obj` | `object`
`> boolean sen` | `boolean flag`

">" means input parameters

To set the sensitivity of several objects to different values:

    gui_status empgui_c_sens_set (objs, sens)

where:

`> object *objs` | `array of objects`
`> boolean *sens` | `array of boolean flags`

">" means input parameters

To set the sensitivity of several objects to the same value:

    gui_status empgui_c_sens_set_all (objs, sen)

where:

`> object *objs` | `array of objects`
`> boolean sen` | `boolean flag`

">" means input parameters

The `PROP_EDITABLE` property is applicable for several types of objects. It is a boolean flag; true means editable, and false means non-editable. The default for an object is specified in the object's Property Editor. If an object is editable, it means that its value can be changed interactively by the user (e.g., by typing into an editable field). If it is non-editable, the object is still active, but its value cannot be changed interactively. For example, a non-editable option menu button can still be activated (i.e., clicking on the button will display an option menu), but its value cannot be changed by selecting from the menu. Several convenience routines are available to set this property:

To set the editability of a single object:

    gui_status empgui_c_edit_set (obj, edit)

where

`> object obj` | `object`
`> boolean edit` | `boolean flag`

">" means input parameters

To set the editability of several objects to different values:

    gui_status empgui_c_edits_set (objs, edits)

where

`> object *objs` | `array of objects`
`> boolean *edits` | `array of boolean flags`

">" means input parameters

To set the editability of several objects to the same value:

    gui_status empgui_c_edits_set_all (objs, edit)

where:

`> object *objs` | `array of objects`
`> boolean edit` | `boolean flag`

">" means input parameters

For details on these functions, please refer to their respective man pages.

## 3.5 Objects and Properties

The following sections describe objects along with their properties, whether they are "gettable" or "settable" and any special routines that might apply to that object to get and set properties. These convenience routines are in addition to the property routines described previously.

### 3.5.1 Audio Field

The audio field is used to play sound data with controllers to pause and stop the playback. Note that volume is not a property of an audio field (adjusting the volume using `empgui_c_audio_set_volume` will also affect the volume of all audio fields).

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Audio Field Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the audio field is sensitive
`g` | `PROP_STATE` | `int` | State of audio field, which could be one of `AUDIO_STOP`, `AUDIO_PLAY`, `AUDIO_EMPTY` or `AUDIO_PAUSE`
`s` | `PROP_VALUE` | `bulk*` | Pointer to audio data in Empress bulk format

"g" means gettable
"s" means settable
``
`PROP_STATE` would return one of the following values, depending on the state of the audio object:

`AUDIO_EMPTY` | the audio object has not been assigned a proper value
`AUDIO_PAUSE` | a sound was playing and the pause button was pressed
`AUDIO_PLAY` | sound data is being played
`AUDIO_STOP` | a sound was playing and the stop button was pressed

`PROP_STATE` can be obtained by the following convenience function:

    gui_status empgui_c_audio_get_state (audobj, &state)

where:

`> object audobj` | `audio object`
`< int state` | `state of the audio object`

">" means input parameters
"<" means output parameters

`PROP_VALUE` can be set by the following convenience function:

    gui_status empgui_c_audio_set (audobj, bulkptr)

where:

`> object audobj` | `audio object`
`> addr bulkptr` | `pointer to Empress bulk data format`

">" means input parameters

For details on these functions, please refer to their respective man pages.

### 3.5.2 Bin

The bin object is a container for component objects. If a bin is insensitive, then all objects in the bin are insensitive.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Bin Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the bin is sensitive
`g` | `PROP_TYPE` | `char` | Character to indicate the bin type

"g" means gettable
"s" means settable
``

The valid values for `PROP_TYPE` are:

`'b'` | Menu-bar
`'d'` | Pull-down menu
`'g'` | Dialog
`'h'` | Menu-bar help menu
`'o'` | Option menu
`'r'` | Radio-box
`'u'` | Pop-up menu

### 3.5.3 Cascade Button

The cascade button is used to provide access to pull-down menus.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Cascade Button Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the cascade button is sensitive
`s` | `PROP_LABEL_TEXT` | `char*` | Text to be displayed on the cascade button
`s` | `PROP_LABEL_PIXMAP` | `char*` | Name of the pixmap to be displayed on the cascade button

"g" means gettable
"s" means settable

### 3.5.4 Field

The field object is used to display text values. It can have a single line or multiple lines with scroll bars. If a field is insensitive, input focus cannot be set to the field. If a field is non-editable (but sensitive), input focus can be set to the field and the scroll bars can be used, but the value in the field cannot be edited.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Field Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`g` | `PROP_FIELD_TYPE` | `char*` | Data type of field specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the field is sensitive
`gs` | `PROP_EDITABLE` | `boolean` | Flag to indicate whether the field is editable
`gs` | `PROP_VALUE` | `char*` | Text string in the field
`s` | `PROP_VALUE_INSERT` | `char*` | Add text to the end of field
`s` | `PROP_VALUE_APPEND` | `char*` | Add text to the end of the field and remove old data if the field buffer is full

"g" means gettable
"s" means settable

The `PROP_FIELD_TYPE` property can have one of the following values:

`"boolean"` | Values allowed are "1" (true) and "0" (false)
`"char"` | Any string is allowed
`"date"` | Valid dates are allowed
`"decimal"` | Fixed-point numbers are allowed, e.g., "259.98"
`"float"` | Floating-point numbers are allowed, e.g., "1.23e10"
`"integer"` | Integers are allowed
Nil pointer | External format of attributes in a table

Note that Empress GUI Builder does not do any checking to ensure that the contents of the field are valid for the field type. It is up to the application (i.e., the programmer) to do so.

`PROP_VALUE` can be obtained by the following convenience function:

    gui_status empgui_c_field_get (fldobj, &string)

where

`> object fldobj` | `field object`
`< char *string` | `string pointing to the contents of the field`

">" means input parameters
"<" means output parameters

`PROP_VALUE` can be set by the following convenience function:

    gui_status empgui_c_field_set (fldobj, string)

where:

`> object fldobj` | `field object`
`> char *string` | `string to be placed in the field`

">" means input parameters
"<" means output parameters

For details on these functions, please refer to their respective man pages.

### 3.5.5 Hypertext Field

The hypertext field is used to display hypertext documents. Formatting instructions embedded in the document (using HTML - Hyper Text Markup Language) are interpreted automatically. The contents of a hypertext field can be set by providing either the name of a hypertext document or a string which will be displayed in the hypertext field.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Hypertext Field Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the hypertext field is sensitive
`s` | `PROP_TEXT_VALUE` | `char*` | String to display in the hypertext field
`s` | `PROP_VALUE` | `char*` | Name of hypertext document to display

"g" means gettable
"s" means settable

### 3.5.6 Image Field

The image field is a rectangular area used for displaying images.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Image Field Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the image field is sensitive
`s` | `PROP_VALUE` | `bulk*` | Pointer to image data in Empress bulk format

"g" means gettable
"s" means settable

`PROP_VALUE` can be set by the following convenience function:

    gui_status empgui_c_image_set (imgobj, bulkptr)

where:

`> object imgobj` | `image object`
`> addr bulkptr` | `pointer to Empress bulk data format`

">" means input parameters

Please refer to the man page of the above function for further details.

### 3.5.7 Label

A label is an area on the screen which contains non-editable text or an icon (pixmap). It is used to help the user identify other objects (such as fields).

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Label Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the label is sensitive
`s` | `PROP_LABEL_TEXT` | `char*` | Text to be displayed on the label
`s` | `PROP_LABEL_PIXMAP` | `char*` | Name of the pixmap to be displayed on the label

"g" means gettable
"s" means settable
``

### 3.5.8 List

The list is used to display an array of data values. By definition, a list object has only one column. The C API provides functions to delete items from a list, get the number of viewable rows, and set items in the list with user controlled scrolling. Please refer to the Chapter on "Lists" for further details.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the List Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the list is sensitive
`gs` | `PROP_VALUE` | `int` | Row number of the first selected row
`gs` | `PROP_LIST_SELPOS` | `struct*` | Row numbers of the selected rows
`g` | `PROP_VIEWABLE_ROWS` | `int` | Number of viewable rows in the list

"g" means gettable
"s" means settable
``

`PROP_VIEWABLE_ROWS` can be obtained by the following convenience function:

    gui_status empgui_c_list_get_num_viewrows (listobj, &num)

where:

`> object listobj` | `list object`
`< int num` | `number of viewable rows in the list`

">" means input parameters
"<" means output parameters

Please refer to the man page of the function for further details.

### 3.5.9 Multilist

The multilist is used to display several related arrays of data values. The C API provides convenience functions to delete items from a multilist, get the number of viewable rows, get the number of columns and set items in the multilist with user controlled scrolling. Please refer to the chapter on "Lists" for further details.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Multilist Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the multilist is sensitive
`gs` | `PROP_VALUE` | `int` | Row number of the first selected row
`gs` | `PROP_LIST_SELPOS` | `struct*` | Row numbers of selected rows
`g` | `PROP_COLUMNS` | `int` | Number of columns in the multilist
`g` | `PROP_VIEWABLE_ROWS` | `int` | Number of viewable rows in the multilist

"g" means gettable
"s" means settable
``

`PROP_VIEWABLE_ROWS` can be obtained by the following convenience function:

    gui_status empgui_c_list_get_num_viewrows (listobj, &num)

where:

`> object listobj` | `multilist object`
`< int num` | `number of viewable rows in the multilist`

">" means input parameters
"<" means output parameters

`PROP_COLUMNS` can be obtained by the following convenience function:

    gui_status empgui_c_list_get_num_columns (listobj, &num)

where:

`> object listobj` | `multilist object`
`< int num` | `number of columns in the multilist`

">" means input parameters
"<" means output parameters

For details on these functions, please refer to their respective man pages.

### 3.5.10 Option Menu

The option menu button is used to pop-up a menu allowing the user to choose one of several items. The selected item is displayed on the button.

Setting the properties `PROP_ITEMS_SENSITIVE` and `PROP_ITEMS_INSENSITIVE` is equivalent to setting `PROP_SENSITIVITY` for the individual push buttons representing the items in the option menu's bin. This allows the programmer to control which items can be chosen by the user.

Setting `PROP_EDITABLE` to false causes all the push buttons in the option menu's bin to be insensitive except the selected item's push button, so that the user cannot select another item.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Option Menu Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the option menu button is sensitive
`gs` | `PROP_EDITABLE` | `boolean` | Flag to indicate whether the option menu is editable.
`s` | `PROP_LABEL_TEXT` | `char*` | String to be displayed on the left of the option menu button
`s` | `PROP_LABEL_PIXMAP` | `char*` | Name of the pixmap to be displayed on the left of the option menu button
`gs` | `PROP_VALUE` | `char*` | Name of selected item in the option menu
`s` | `PROP_ITEMS_SENSITIVE` | `char**` | Array of item names in the option menu to make sensitive
`s` | `PROP_ITEMS_INSENSITIVE` | `char**` | Array of item names in the option menu to make insensitive

"g" means gettable
"s" means settable

### 3.5.11 Push Button

The push button is normally used to activate actions. They usually appear in windows and in pull down menus, but they are also used in option menus to represent the items to choose.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char` | Name specified in the Push Button Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the push button is sensitive

"g" means gettable
"s" means settable

### 3.5.12 Radio Box

The radio box is a grouping of several toggle buttons which are mutually exclusive (i.e., only one button can be ON at any time).

If the radio box is non-editable, all the toggle buttons in the radio box bin are insensitive except the selected toggle button, so that the user cannot select another one.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Radio Box Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the radio box is sensitive
`gs` | `PROP_EDITABLE` | `boolean` | Flag to indicate whether user can change the selected button in the radio box
`gs` | `PROP_VALUE` | `char*` | Name of the selected button in the radio box bin

"g" means gettable
"s" means settable

### 3.5.13 Scale Object

The scale object is used to show a scale with maximum and minimum values selected by the developer. Attempting to set the value of the scale greater than the maximum value will cause it to be set to that maximum value. Attempting to set its value lower than the minimum value will cause it to be set to the minimum value. Even though the scale can be defined to display decimal values, C API function calls ignore the decimal part and treat the values as integers.

If a scale is non-editable, the user can click and drag the slider, but when it is released, it returns to its original position, since the value of the scale cannot be changed by the user.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Scale Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the scale is sensitive
`gs` | `PROP_EDITABLE` | `boolean` | Flag to indicate whether user can change the value of the scale
`gs` | `PROP_VALUE` | `int` | Integer value of the scale

"g" means gettable
"s" means settable

`PROP_VALUE` can be read by the following convenience function:

    gui_status empgui_c_scale_get (scaleobj, &val)

where:

`> object scaleobj` | `scale object`
`< int val` | `integer value of scale`

">" means input parameters
"<" means output parameters

`PROP_VALUE` can be set by the following convenience function:

    gui_status empgui_c_scale_set (scaleobj, val)

where:

`> object scaleobj` | `scale object`
`> int val` | `value to assign to scale`

">" means input parameters

For details on the above functions, please refer to the respective man pages.

### 3.5.14 Separator

The separator is used to provide visually separate items in menus and to group various related objects on the screen.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Separator Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the separator is sensitive

"g" means gettable
"s" means settable

### 3.5.15 Toggle Button

The toggle button is used to indicate a binary (ON/OFF) state, with true corresponding to the ON state and false corresponding to the OFF state.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Toggle Button Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the toggle button is sensitive
`gs` | `PROP_EDITABLE` | `boolean` | Flag to indicate whether the user can change the state of the toggle
`gs` | `PROP_VALUE` | `boolean` | State of the toggle button

"g" means gettable
"s" means settable
`` ``

`PROP_VALUE` can be obtained by the following convenience function:

    gui_status empgui_c_toggleb_get (togglebobj, &val)

where:

`> object togglebobj` | `toggle button object`
`< boolean val` | `current value of button`

">" means input parameters
"<" means output parameters``

`PROP_VALUE` can be set by the following convenience function:

    gui_status empgui_c_toggleb_set (togglebobj, val)

where:

`> object togglebobj` | `toggle button object`
`> boolean val` | `value to assign to button`

">" means input parameters

For details on the above functions, please refer to the appropriate man pages.

### 3.5.16 User Defined Object

The user-defined object is used to provide a drawing area widget that the user can manipulate and customize according to the requirements of the application.

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the User Defined Object Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the user object is sensitive
`gs` | `PROP_USER_DATA` | `addr` | Pointer to any data structure that the developer wants to associate with the object

"g" means gettable
"s" means settable

### 3.5.17 Window

The window is a special case of the bin object. Like any bin, it is a container of objects. Unlike other bins, it has position (X and Y coordinates), size (Height and Width) and other attributes which are defined in Empress GUI Builder .

| Name of Property | Type of Data | Description
`g` | `PROP_NAME` | `char*` | Name specified in the Window Property Editor in Empress GUI Builder
`g` | `PROP_DESCRIPTION` | `char*` | Description specified in the Property Editor in Empress GUI Builder
`s` | `PROP_SENSITIVITY` | `boolean` | Flag to indicate whether the window is sensitive
`g` | `PROP_TYPE` | `char` | Character to indicate the bin type - always '`w`'

"g" means gettable
"s" means settable

### 3.5.18 Property Errors

Empress GUI Builder generates the following property errors while trying to get or set a property of an object.

Property Error | Description
`E_C_PROP_TYPE_INVALID` | property type argument is not valid for the object
`E_C_PROP_FAIL_HFLD_NOT_FOUND` | hypertext document cannot be found
`E_C_PROP_FAIL_IMAGE_INVALID` | image argument is not valid
`E_C_PROP_FAIL_IMAGE_COLOR` | image argument specifies too many colors
`E_C_PROP_FAIL_OPTION_NOT_FOUND` | option item name cannot be found
`E_C_PROP_FAIL_RADIO_NOT_FOUND` | radiobox item name cannot be found
`E_C_PROP_FAIL_SCALE_MAX` | scale value argument is greater than the maximum
`E_C_PROP_FAIL_SCALE_MIN` | scale value argument is less than the minimum