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:

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

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)

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

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)

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)

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

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)

To set an applicable property of an object:

gui_status empgui_c_prop_set (obj, prop_type, &data)

To access an applicable property for an array of objects:

gui_status empgui_c_props_get (objs, prop_type, &datas)

To set an applicable property for an array of objects:

gui_status empgui_c_props_set (objs, prop_type, datas)

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

TYPE_BOOLEAN
TYPE_BULK
TYPE_CHARACTER
TYPE_INTEGER
TYPE_SELECTION
TYPE_STRING
TYPE_STRING_ARRAY

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

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

empgui_c_prop_get()

The variable declaration would be:

object mainwin, genobj;

gui_status status;

addr data;

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

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

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

empgui_c_prop_set()

The variable declaration would be:

object mainwin, genobj;

gui_status status;

addr data;

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

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

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

empgui_c_props_get()

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

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

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()

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

status = empgui_c_props_set (genobjs, PROP_GEN, datas);

Example

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

empgui_c_prop_get()

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

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()

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

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

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

empgui_c_props_get()

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

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()

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

status = empgui_c_props_set (genobjs, PROP_GEN, datas);

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()

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;

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

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

Example

empgui_c_props_set()

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

status = empgui_c_props_set (genobjs, PROP_GEN, datasptr);

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()

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

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()

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

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

Example

empgui_c_prop_get()

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

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()

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

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

Example

empgui_c_props_get()

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

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()

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

status = empgui_c_props_set (genobjs, PROP_GEN, datas);

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()

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

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()

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

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

Example

empgui_c_props_get()

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

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()

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

status = empgui_c_props_set (genobjs, PROP_GEN, datas);

Example

empgui_c_prop_get()

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

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()

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

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

Example

empgui_c_props_get()

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

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()

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

status = empgui_c_props_set (genobjs, PROP_GEN, datas);

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

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()

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

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

Example

empgui_c_props_set()

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

status = empgui_c_props_set (genobjs, PROP_GEN, datas);

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

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)

To set the sensitivity of several objects to different values:

gui_status empgui_c_sens_set (objs, sens)

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

gui_status empgui_c_sens_set_all (objs, sen)

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)

To set the editability of several objects to different values:

gui_status empgui_c_edits_set (objs, edits)

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

gui_status empgui_c_edits_set_all (objs, edit)

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

gui_status empgui_c_audio_get_state (audobj, &state)

PROP_VALUE can be set by the following convenience function:

gui_status empgui_c_audio_set (audobj, bulkptr)

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

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

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)

PROP_VALUE can be set by the following convenience function:

gui_status empgui_c_field_set (fldobj, string)

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

PROP_VALUE can be set by the following convenience function:

gui_status empgui_c_image_set (imgobj, bulkptr)

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

PROP_VIEWABLE_ROWS can be obtained by the following convenience function:

gui_status empgui_c_list_get_num_viewrows (listobj, &num)

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

3.5.9 Multilist

PROP_VIEWABLE_ROWS can be obtained by the following convenience function:

gui_status empgui_c_list_get_num_viewrows (listobj, &num)

PROP_COLUMNS can be obtained by the following convenience function:

gui_status empgui_c_list_get_num_columns (listobj, &num)

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

3.5.10 Option Menu

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

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

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)

PROP_VALUE can be set by the following convenience function:

gui_status empgui_c_scale_set (scaleobj, val)

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

3.5.14 Separator

PROP_VALUE can be obtained by the following convenience function:

gui_status empgui_c_toggleb_get (togglebobj, &val)

PROP_VALUE can be set by the following convenience function:

gui_status empgui_c_toggleb_set (togglebobj, val)

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

3.5.16 User Defined Object