# CHAPTER 8: Function Reference

## empgui_c_action_execute
Description | Execute a script or C action
Syntax |
    gui_status empgui_c_action_execute(actname, params, argc, argv)
where:
`> char *actname` | name of the action to be executed
`> char *params` | string parameter
`> int argc` | count of optional parameters
`> char **argv` | array of optional parameters
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_ARGC_NEGATIVE` | negative `argc`
`E_C_ARGV_NIL` | `argv` is nil
`E_C_NAME_NIL` | action name string is nil
`E_C_MODULE_INACTIVE` | no active module
`E_C_NOT_FOUND` | action name not found
Notes | `actname`, `params`, `argc`, and `argv` are assigned values by the user. `params` is a string that is passed to the action when it is executed. `(int ) 0` can be passed for `argc` and `(char **) 0` can be passed for `argv` if they are not needed. The action name `actname` can be either a script or a C action in the current module, or in any shared module in the application.

## empgui_c_application_run
Description | Run an Empress GUI Builder application
Syntax |
    gui_status empgui_c_application_run (dbname, appname, argc, argv)
where:
`> char *dbname` | database name
`> char *appname` | application name
`> int argc` | count of optional parameter
`> char **argv` | array of optional parameter
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_ARGC_NEGATIVE` | negative `argc`
`E_C_ARGV_NIL` | `argv` is nil
`E_C_NAME_NIL` | name string is nil
`E_C_APPLICATION_NOT_FOUND` | application cannot be found
`E_C_MAIN_MODULE_NOT_FOUND` | main module cannot be found
`E_C_SCRIPT_NOT_INIT` | script cannot be initialized
`E_C_TABLE_OPEN` | cannot open database table
`E_C_TABLE_OPEN_PERM` | insufficient permissions to open database table
`E_C_TABLE_QUALIFY` | cannot read records from database table
`E_C_DB_INVALID` | invalid or inaccessible database
`E_C_GUIDB_INVALID` | database is invalid for Empress GUI Builder use
`E_C_APPLICATION_NO_MODULES` | application contains no modules
`E_C_APPL_MODULE_NOT_FOUND` | module not associated with the application
`E_C_APPL_MODULES_NOT_ALL_FOUND` | some modules associated with the application cannot be found
`E_C_APPL_NO_MAIN_MODULE` | main module is not specified for the application
`E_C_APPL_MAIN_MODULE_NOT_FOUND` | specified main module is not associated with the application
`E_C_APPL_NO_SHARED_MODULES` | application contains no shared modules
`E_C_APPLICATION_INVALID_LINK` | invalid link buffer for application
`E_C_SCRIPT_NOT_LOAD` | cannot load scripts from the application
Notes | `dbname`, `appname`, `argc` and `argv` are assigned values by the user.

## empgui_c_array_free
Description | Free array allocated to the pointer
Syntax |
    gui_status empgui_c_array_free(array)
where:
`> addr array` | pointer to which array has been allocated
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_POINTER_NOT_ALLOC` | pointer argument is not an allocated array
Notes | This function frees the memory allocated by several other C API functions.

## empgui_c_audio_get_state
Description | Get the state of an audio object
Syntax | `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
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_PROP_...` | failed to get the property
Notes | `audobj` must be assigned value by the user while the routine will assign value to `state`. This routine will return a numeric value in `state` which would correspond to one of the following:
`AUDIO_EMPTY` | the audio object has not been assigned a proper value
`AUDIO_PAUSE` | the audio object is in the pause state, a sound was playing and pause was hit
`AUDIO_PLAY` | the audio object is playing the sound
`AUDIO_STOP` | the audio object is in the stop state, a sound was playing and stop was hit
For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".

## empgui_c_audio_get_volume
Description | Get the volume associated with the audio device
Syntax | `gui_status empgui_c_audio_get_volume` (`audobj`, `&lvol`, `&rvol`) where:
`> object audobj` | audio object
`< int lvol` | left volume of the audio object
`< int rvol` | right volume of the audio object
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
Notes | `audobj` must be assigned value by the user while the routine will assign value to `lvol` and `rvol`. This routine will return numeric values of left and right volumes. Volume range is 0-999.

## empgui_c_audio_set
Description | Assign data to an audio object
Syntax |
    gui_status empgui_c_audio_set (audobj, bulkptr)
where:
`> object audobj` | audio object
`> addr bulkptr` | pointer to Empress bulk data format
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_PROP_...` | failed to set the property
Notes | `audobj` and `bulkptr` must be assigned values by the user. The audio data must be in Empress bulk internal format, described as follows: `typedef struct` `{` `long num_data_bytes;` `char sound_data [num_data_bytes];` `} bulk;` For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".

## empgui_c_audio_set_volume
Description | Set the volume of the audio device
Syntax |
    gui_status empgui_c_audio_set_volume (audobj, lvol, rvol)
where:
`> object audobj` | audio object
`> int lvol` | left volume of the audio object
`> int rvol` | right volume of the audio object
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
Notes | `audobj`, `lvol`, and `rvol` must be assigned values by the user. Range for `lvol` and `rvol` is 0-999. The volume of any other audio object in the application is also affected.

## empgui_c_bin_get_by_name
Description | Find a bin or window by its name
Syntax |
    gui_status empgui_c_bin_get_by_name (binname, &bin)
where:
`> char *binname` | name of bin or window to find
`< object bin` | bin or window
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_NAME_NIL` | name string is nil
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_MODULE_INACTIVE` | no current module
`E_C_NOT_FOUND` | bin not found
Notes | `binname` must be assigned value by the user while the routine will assign value to `bin`. Bin names must match the actual bin names in Empress GUI Builder. `binname` must point to a valid character string. If the bin is not found, function returns `E_C_NOT_FOUND` and the corresponding object variable is set to `(object)0`.

## empgui_c_bins_get_by_names
Description | Find bins or windows by their names
Syntax |
    gui_status empgui_c_bins_get_by_names (binnames, &bins)
where:
`> char **binnames` | array of string pointers of bin names or window names
`< object *bins` | pointer to bins or windows
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_NAME_NIL` | name string is nil
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_ARRAY_NULL` | no entries in array
`E_C_MODULE_INACTIVE` | no active module
`E_C_NOT_FOUND` | a bin is not found
Notes | `binnames` array must be assigned values by the user while the routine will assign value to `bins`. This function creates an array and assigns it to `bins`. Elements of that array will be accessible as `*bins`, `*(bins+1)`, and so on. Bin names must match the actual bin names in Empress GUI Builder. If the bin is not found, function returns `E_C_NOT_FOUND` and the corresponding object is set to `(object)0`. The array `binname`s must be null terminated. Each entry of the array `binname`s must point to a valid character string. The array allocated to `bins` should be freed with `empgui_c_array_free()`.
Warnings | Failure to null terminate the `binname`s array will cause this function to fail.
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)`.

## empgui_c_cursor_change
Description | Change the cursor shape in the current module
Syntax |
    gui_status empgui_c_cursor_change(cursor)
where:
`> int cursor` | One of the cursor values described in the notes
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_CURSOR_INVALID` | cursor argument is invalid
`E_C_MODULE_INACTIVE` | no active module
Notes | `cursor` is assigned value by the user. `cursor` can take on any of the following values:
`CURSOR_POSITION` | position cursor which is a "+"
`CURSOR_ACTIVE` | active cursor which is a northwest pointed arrow
`CURSOR_TEXT_POSITION` | text position cursor which is an "I"
`CURSOR_INACTIVE` | inactive cursor which is an "X"
`CURSOR_WAIT` | wait cursor which is a clock

## empgui_c_dialog_error
Description | Create and display an error dialog box
Syntax |
    gui_status empgui_c_dialog_error (style, title, text, position, help)
where:
`> char *style` | dialog bin name from `empgui`, used for `style`, the style defined for that bin will be the style for the dialog box
`> char *title` | string to be displayed on the title bar of the error dialog box
`> char *text` | string to be displayed in the error dialog box
`> int position` | indicates where the error dialog box would pop up in relation to the main window of the current module
`> char *help` | string containing the name of a help module which is called when the `Help` button is hit in the error dialog box
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_MODULE_INACTIVE` | no active module
Notes | `style`, `title`, `text`, `position` and `help` are assigned values by the user. The error dialog box will have an error icon and two buttons, `OK` and `Help`. It will show the error message if one is specified. Clicking on the `OK` button will dismiss the dialog box while clicking on the `Help` button will call the specified module. If `(char *)0` is passed for `style`, the colors and the fonts are taken from the main window of the current module. If `(char *)0` is passed for `title`, error dialog title would be "`dialog_popup`". If `(char *)0` is passed for `text`, no text will be shown in the error dialog box. The value for position could be one of the following: `POSITION_CENTER` `POSITION_TOP_LEFT` `POSITION_TOP_RIGHT` `POSITION_BOTTOM_LEFT` `POSITION_BOTTOM_RIGHT` If `(char *)0` is passed for `help`, the `Help` button is not displayed in the error dialog box. The function halts the execution of the C routine until the user clicks on the `OK` button to dispose of the error dialog box.
Example | In an application, an error dialog box is needed if an error occurs and the user needs to be informed of that error. Variable declaration for the dialog part could be as follows: `char *style = "dialog_app_bin";` `char *title = "Sample Dialog Box";` `char *text = "An error has occurred while writing files to disk";` `int position = POSITION_CENTER;` `char *help = "help_module";` The call to pop up the dialog box would be as follows:
    status = empgui_c_dialog_error (style, title, text, position, help);

## empgui_c_dialog_file_selection
Description | Create and display a file selection dialog box
Syntax | `gui_status empgui_c_dialog_file_selection (style, title, text,` `position, def_button, apply_text, directory, mask, apply,` `filesearch, &filename)` where:
`> char *style` | dialog bin name from `empgui`, used for `style`, the style defined for that bin will be the style for the dialog box
`> char *title` | string to be displayed on the title bar of the file selection dialog box
`> char *text` | string to be displayed on top of the file box of the file selection dialog box
`> int position` | indicates where the file selection dialog box would pop up in relation to the main window of the current module
`> int def_button` | indicates which button in the file selection dialog box would be the default button
`> char *apply_text` | string to be displayed on the `Apply` button in the file selection dialog box
`> char *directory` | starting directory for the file selection dialog box
`> char *mask` | mask for listing files in the file box of the file selection dialog box
`> addr apply` | address of the `apply` function that would be called when the `Apply` button is hit in the file selection dialog box
`> addr filesearch` | address of the function that will be called after the mask filter is called. Output of mask filter, file by file, is passed to this function before the results are displayed in the files box of the file selection dialog box. This function would return true for every file name that would ultimately be displayed in the files box and false otherwise.
`< char *filename` | string that will hold the selected filename after the box is dismissed through the `OK` button
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_MODULE_INACTIVE` | no active module
Notes | `style`, `title`, `text`, `position`, `def_button`, `apply_text`, `directory`, `mask`, `apply`, `filesearch` are assigned values by the user, while the function assigns value to `filename`. If `(char *)0` is passed for `style`, the colors and the fonts are taken from the main window of the current module. If `(char *)0` is passed for `title`, file selection dialog title would be "`dialog_popup`". If `(char *)0` is passed for `text`, text on top of the files box in the file selection dialog box would be "Files". The value for position could be any of the following: `POSITION_CENTER` `POSITION_TOP_LEFT` `POSITION_TOP_RIGHT` `POSITION_BOTTOM_LEFT` `POSITION_BOTTOM_RIGHT` The value for `def_button` could be any of the following. These buttons are numbered as they would appear to the user from left to right in the dialog box. Thus, leftmost button is `DEFAULT_BUTTON_1` and so on. `DEFAULT_BUTTON_1` `DEFAULT_BUTTON_2` `DEFAULT_BUTTON_3` `DEFAULT_BUTTON_4` If `(char *)0` is passed for `apply_text`, the `Apply` button in the file selection dialog box is not displayed. If `(char *)0` is passed for `directory`, current directory is the default value taken. If `(char *)0` is passed for `mask`, "`*`" is the default value taken. If `(addr )0` is passed for `apply`, `Apply` button, if shown, as described above, is disabled. If `(addr )0` is passed for `filesearch` then the output of mask filter is directly displayed in the files box of the file selection dialog box. The function halts the execution of the C routine until the user clicks on the `OK` button or the `Cancel` button to dispose of the dialog box. For details on filesearch and `apply` functions, please refer to Chapter 4 - "Dialogs".
Example | In an application, a file selection dialog box is needed if the user needs to pick a file from the disk. Variable declaration for the dialog part could be as follows: `char *style = "dialog_app_bin";` `char *title = "File Selection Dialog Box";` `char *text = "Files";` `int position = POSITION_CENTER;` `int def_button = DEFAULT_BUTTON_1;` `char *apply_text = "Apply";` `char *directory = "/usr/folks/guest";` `char *mask = "*.c";` `char *filename;` Assuming that `apply` and `filesearch` has been defined before, the call to pop up the dialog box would be as follows: `status = empgui_c_dialog_file_selection (style, title, text, position,` `def_button, apply_text, directory, mask, apply, filesearch,` `&filename);` `fprintf(stderr, "File Selected is %s\n", filename);`

## empgui_c_dialog_info
Description | Create and display an info dialog box
Syntax |
    gui_status empgui_c_dialog_info (style, title, text, position)
where:
`> char *style` | dialog bin name from `empgui`, used for `style`, the style defined for that bin will be the style for the dialog box
`> char *title` | string to be displayed on the title bar of the info dialog box
`> char *text` | string to be displayed in the info dialog box
`> int position` | indicates where the info dialog box would pop up in relation to the main window of the current module
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_MODULE_INACTIVE` | no active module
Notes | `style`, `title`, `text`, and `position` are assigned values by the user. This dialog box would show the info icon " i" and an `OK` button. It would show the text message if one is specified. Clicking on the `OK` button will dismiss the dialog box. The `Help` button is permanently disabled. If `(char *)0` is passed for `style`, the colors and the fonts are taken from the main window of the current module. If `(char *)0` is passed for `title`, info dialog title would be "`dialog_popup`". If `(char *)0` is passed for `text`, no text will be show in the info dialog box. The value for position could be any of the following: `POSITION_CENTER` `POSITION_TOP_LEFT` `POSITION_TOP_RIGHT` `POSITION_BOTTOM_LEFT` `POSITION_BOTTOM_RIGHT` Unlike other dialog functions, this function does not halt the execution of the C routine.
Example | In an application, an info dialog box is needed if something happens and the user needs to be informed of that. Variable declaration for the dialog part could be as follows: `char *style = "dialog_app_bin";` `char *title = "Sample Dialog Box";` `char *text = "Color Style File Not Found";` `int position = POSITION_CENTER;` The call to this routine would be as follows:
    status = empgui_c_dialog_info (style, title, text, position);

## empgui_c_dialog_prompt
Description | Create and display a dialog box to prompt the user to enter a value
Syntax |
    gui_status empgui_c_dialog_prompt (style, title, text, position,
              def_button, init_text, help, &string)
where:
`> char *style` | dialog bin name from `empgui`, used for `style`, the style defined for that bin will be the style for the dialog box
`> char *title` | string to be displayed on the title bar of the prompt dialog box
`> char *text` | string to be displayed in the prompt box as a label
`> int position` | indicates where the prompt dialog box would pop up in relation to the main window of the current module
`> int def_button` | indicates which button in the prompt dialog box would be the default button
`> char *init_text` | string to be displayed in the prompt field of the prompt dialog box
`> char *help` | string containing the name of a module, which is called when the `Help` button is hit in the prompt dialog box
`< char *string` | string that will hold the prompt after the box is dismissed through the `OK` button
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_MODULE_INACTIVE` | no active module
Notes | `style`, `title`, `text`, `position`, `def_button`, `init_text`, and `help` are assigned values by the user, while the function assigns value to `string`. The prompt dialog box would show three buttons, `OK`, `Cancel`, and `Help` and a prompt field. A text string will be shown if one is specified. Clicking on the `OK` button will dismiss the dialog box and return the string in the prompt box to the `string`. Clicking on the `Cancel` button will dismiss the dialog box and return a null pointer to `string`. Clicking on the `Help` button will call the help module. If `(char *)0` is passed for `style`, the colors and the fonts are taken from the main window of the current module. If `(char *)0` is passed for `title`, prompt dialog title would be "`dialog_popup`". If `(char *)0` is passed for `text`, no text will be shown in the prompt dialog box. The value of position could be any of the following: `POSITION_CENTER` `POSITION_TOP_LEFT` `POSITION_TOP_RIGHT` `POSITION_BOTTOM_LEFT` `POSITION_BOTTOM_RIGHT` The value of `def_button` could be any of the following. These buttons are numbered as they would appear to the user from left to right in the dialog box. Thus, leftmost button is `DEFAULT_BUTTON_1` and so on. `DEFAULT_BUTTON_1` `DEFAULT_BUTTON_2` `DEFAULT_BUTTON_3` `DEFAULT_BUTTON_4` If `(char *)0` is passed for `init_text`, the prompt field will be initially empty. If `(char *)0` is passed for `help`, the `Help` button is not displayed in the prompt dialog box. The function halts the execution of the C routine until the user clicks on the `OK` button or the `Cancel` button to dispose of the dialog box.
Example | In an application, a prompt dialog box is needed if the user needs to input some information to the program. Variable declaration for the dialog part could be as follows: `char *style = "dialog_app_bin";` `char *title = "Sample Dialog Box";` `char *text = "Please input the value of color variable";` `int position = POSITION_CENTER;` `int def_button = DEFAULT_BUTTON_1;` `char *init_text = 0;` `char *help = "help_module";` `char *string;` The call to display the dialog box would be as follows:
    status = empgui_c_dialog_prompt (style, title, text, position,
             def_button, init_text, help, &string);

## empgui_c_dialog_question
Description | Create and display a dialog box to ask the user a question and allow him to choose from two possible values
Syntax |
    gui_status empgui_c_dialog_question (style, title, text, position,
        def_button, but1, but2, help, &string)
where:
`> char *style` | dialog bin name from `empgui`, used for `style`, the style defined for that bin will be the style for the dialog box
`> char *title` | string to be displayed on the title bar of the question dialog box
`> char *text` | string to be displayed in the question dialog box as a label
`> int position` | indicates where the question dialog box would pop up in relation to the main window
`> int def_button` | indicates which button in the question dialog box would be the default button
`> char *but1` | string to be displayed on the first button of the question dialog box
`> char *but2` | string to be displayed on the second button of the question dialog box
`> char *help` | string containing the name of a module, which is called when the `Help` button is hit in the question dialog box
`< char *string` | string that will hold the label of the button after the box is dismissed by hitting on that button. It would be the label of either `button1` or `button2.`
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_MODULE_INACTIVE` | no active module
Notes | `style`, `title`, `text`, `position`, `def_button`, `but1`, `but2`, and `help` are assigned values by the user, while the function assigns value to `string.` The question dialog box would have a question icon " ?", two buttons with user specified labels, a `Help` button and a text message if one is specified. Clicking on either of the buttons will dismiss the dialog box and return the label of that button in the `string` variable. Clicking on the `Help` button will call the help module. If `(char *)0` is passed for `style`, the colors and the fonts are taken from the main window of the current module. If `(char *)0` is passed for `title`, question dialog title would be "`dialog_popup`". If `(char *)0` is passed for `text`, no text will be shown in the dialog box. The value of position could be any of the following: `POSITION_CENTER` `POSITION_TOP_LEFT` `POSITION_TOP_RIGHT` `POSITION_BOTTOM_LEFT` `POSITION_BOTTOM_RIGHT` The value of `def_button` could be any of the following. These buttons are numbered as they would appear to the user from left to right in the dialog box. Thus, leftmost button is `DEFAULT_BUTTON_1` and so on. `DEFAULT_BUTTON_1` `DEFAULT_BUTTON_2` `DEFAULT_BUTTON_3` `DEFAULT_BUTTON_4` If `(char *)0` is passed for `but1` or `but2`, that button in the question dialog box would not be displayed. If `(char *)0` is passed for `help`, the `Help` button is not displayed in the question dialog box. The function halts the execution of the C routine until the user clicks on either of the buttons to dispose of the dialog box.
Example | In an application, a question dialog box is needed if the user needs to be asked something specific in form of a question. Variable declaration for the dialog part could be as follows: `char *style = "dialog_app_bin";` `char *title = "Sample Dialog Box";` `char *text = "Please click the appropriate button";` `int position = POSITION_CENTER;` `int def_button = DEFAULT_BUTTON1;` `char *but1 = "Do you want to stop?";` `char *but2 = "Do you want to continue?";` `char *help = "help_module";` `char *string;` The call to pop up the dialog box would be as follows: `status = empgui_c_dialog_question (style, title, text, position,` `def_button, but1, but2, help, &string);` `if ( (strcmp(string,but1)) == 0 )` `{` `printf("User wants to stop the program.\n");` `exit (0);` `}`

## empgui_c_dialog_warning
Description | Create and display a warning dialog box and allow the user to choose from two possible responses
Syntax |
    gui_status empgui_c_dialog_warning (style, title, text, position,
           def_button, but1, but2, help, &string)
where:
`> char *style` | dialog bin name from `empgui`, used for `style`, the style defined for that bin will be the style for the dialog box
`> char *title` | string to be displayed on the title bar of the warning dialog box
`> char *text` | string to be displayed in the warning dialog box as a label
`> int position` | indicates where the warning dialog box would pop up in relation to the main window of the current module
`> int def_button` | indicates which button in the warning dialog box would be the default button
`> char *but1` | string to be displayed on the first button of the warning dialog box
`> char *but2` | string to be displayed on the second button of the warning dialog box
`> char *help` | string containing the name of a module, which is called when the `Help` button is hit in the warning dialog box
`< char *string` | string that will hold the label of the button after the box is dismissed by hitting on that button. It would be the label of either `button1` or `button2`.
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_MODULE_INACTIVE` | no active module
Notes | `style`, `title`, `text`, `position`, `def_button`, `but1`, `but2`, and `help` are assigned values by the user, while the function assigns value to `string`. The warning dialog box would have a warning icon " !", two buttons with user specified text, a `Help` button, and a text label if one is specified. Clicking on either of the buttons will dismiss the dialog box and return the label of that button in the `string` variable. Clicking on the `Help` button will call the help module. If `(char *)0` is passed for `style`, the colors and the fonts are taken from the main window of the current module. If `(char *)0` is passed for `title`, warning dialog title would be "`dialog_popup`". If `(char *)0` is passed for `text`, no text will show in the warning dialog box. The value of position could be any of the following: `POSITION_CENTER` `POSITION_TOP_LEFT` `POSITION_TOP_RIGHT` `POSITION_BOTTOM_LEFT` `POSITION_BOTTOM_RIGHT` The value of `def_button` could be any of the following. These buttons are numbered as they would appear to the user from left to right in the dialog box. Thus, leftmost button is `DEFAULT_BUTTON_1` and so on. `DEFAULT_BUTTON_1` `DEFAULT_BUTTON_2` `DEFAULT_BUTTON_3` `DEFAULT_BUTTON_4` If `(char *)0` is passed for `but1` or `but2`, that button in the warning dialog box would not be displayed. If `(char *)0` is passed for `help`, the `Help` button is not displayed in the warning dialog box. The function halts the execution of the C routine until the user clicks on either of the buttons to dispose of the dialog box.
Example | In an application, a warning dialog box is needed if the user needs to be warned of something specific in form of a warning. Variable declaration for the dialog part could be as follows: `char *style = "dialog_app_bin";` `char *title = "Sample Dialog Box";` `char *text = "Please click the appropriate button";` `int position = POSITION_CENTER;` `int def_button = DEFAULT_BUTTON1;` `char *but1 = "Do you want to stop?";` `char *but2 = "Do you want to continue?";` `char *help = "help_module";` `char *string;` The call to pop up the dialog box would be as follows: `status = empgui_c_dialog_warning (style, title, text, position,` `def_button, but1, but2, help, &string);` `if ( (strcmp(string,but1)) == 0 )` `{` `printf("User wants to stop the program.\n");` `exit (0);` `}`

## empgui_c_dialog_working
Description | Create and display a dialog box to inform the user about on going work
Syntax |
    gui_status empgui_c_dialog_working (style, title, text, position,
             &dialog)
where:
`> char *style` | dialog bin name from `empgui`, used for `style`, the style defined for that bin will be the style for the dialog box
`> char *title` | string to be displayed on the title bar of the working dialog box
`> char *text` | string to be displayed in the working dialog box
`> int position` | indicates where the working dialog box would pop up in relation to the main window
`< addr dialog` | id of the dialog box which will be used in the program to dismiss the dialog box
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_MODULE_INACTIVE` | no active module
Notes | `style`, `title`, `text`, and `position` are assigned values by the user while the routine assigns values to `dialog`. The working dialog will have a busy icon which is an hourglass and the message specified by the user. If `(char *)0` is passed for `style`, the fonts and the colors are taken from the main window of the current module. If `(char *)0` is passed for `title`, working dialog title would be "`dialog_popup`". If `(char *)0` is passed for `text`, no text will show in the dialog box. The value of the position could be any of the following: `POSITION_CENTER` `POSITION_TOP_LEFT` `POSITION_TOP_RIGHT` `POSITION_BOTTOM_LEFT` `POSITION_BOTTOM_RIGHT` Unlike other dialog functions, this function does not halt the execution of the C routine. The dialog created by this function is dismissed by calling `empgui_c_working_trash()`.
Example | In an application, a working dialog box is needed if process is going on and the user needs to be informed of that error. Variable declaration for the dialog part could be as follows: `char *style = "dialog_app_bin";` `char *title = "Sample Dialog Box";` `char *text = "Please Wait. ";` `int position = POSITION_CENTER;` `addr dialog;` `status = empgui_c_dialog_working (style, title, text, position,` `&dialog);`

## empgui_c_dialog_working_trash
Description | Remove a working dialog started by `empgui_c_dialog_working`
Syntax |
    gui_status empgui_c_dialog_working_trash (dialog)
where:
`> addr dialog` | id of the dialog box which will be used in the program to dismiss the dialog box
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_POINTER_NIL` | pointer argument is nil
Notes | The dialog id is obtained through the call to `empgui_c_dialog_working()`.

## empgui_c_display_refresh
Description | Refresh the display
Syntax |
    gui_status empgui_c_cursor_display_refresh()
Returns |
`E_C_SUCCESS` | operation successful
Notes | This function flushes out any pending X-events related to the display.

## empgui_c_edit_set
Description | Make an object editable or non-editable
Syntax |
    gui_status empgui_c_edit_set (obj,edit)
where:
`> object obj` | object
`> boolean edit` | flag to set the property true for editable, false for non-editable
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_FUNCTION_INVALID` | function invalid for object
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_PROP_...` | failed to set the property
Notes | `obj` and `edit` are assigned values by the user. This function only applies to objects to which editable property apply. Please refer to the section on "Properties of Objects" in Chapter 3. If an object is non-editable, the user cannot change its value. For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".

## empgui_c_edits_set
Description | Set the editable property of an array of objects to an array of values
Syntax |
    gui_status empgui_c_edits_set (objs,edits)
where:
`> object *objs` | array of objects
`> boolean *edits` | array of flag for the editable properties true for editable, false for non-editable
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_FUNCTION_INVALID` | function invalid for object
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_ARRAY_NULL` | no entries in array
`E_C_PROP_...` | failed to set the property
Notes | `objs` and `edits` are assigned values by the user. `objs` must be null terminated. `objs` and `edits` must point to valid arrays of their respective types. If the editable property of an object is false, the user cannot change its value This function only applies to objects to which editable property apply. Please refer to the section on "Properties of Objects" in Chapter 3. For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".
Example | For an application that has a main window and five fields called "`field1`", "`field2`", "`field3`", "`field4`", "`field5`", the variable declaration would be as follows: `object mainwin, *fobj;` `char *objsname[5] = {"field1", "field2", "field3", "field4", "field5"};` `boolean edits[5] = {false, false, true, true, true};` `gui_status status;` To get the objects:
    status = empgui_c_objs_get_by_names(mainwin, objnames, &fobjs);
(Assuming that `mainwin` has already been initialized) To make the first two field non-editable and last three editable:
    status = empgui_c_edits_set (fobjs, edits);

## empgui_c_edits_set_all
Description | Set the editable property of an array of objects to the same value
Syntax |
    gui_status empgui_c_edits_set_all (objs,edit)
where:
`> object *objs` | array of objects
`> boolean edit` | flag to set the property true for editable, false for non-editable
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_FUNCTION_INVALID` | function invalid for object
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_ARRAY_NULL` | no entries in array
`E_C_PROP_...` | failed to set the property
Notes | `objs` and `edit` are assigned values by the user. `objs` must be a null terminated array. This function only applies to objects to which editable property apply. Please refer to the section on "Properties of Objects" in Chapter 3. If an object is not editable, the user cannot change its value. For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".

## empgui_c_field_get
Description | Get the contents of a text field
Syntax |
    gui_status empgui_c_field_get (fldobj, &string)
where:
`> object fldobj` | field object
`< char *string` | string that will hold the value of the field object
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_PROP_...` | failed to get the property
Notes | `fldobj` is assigned value by the user while the routine assigns value to `string`. For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".

## empgui_c_field_set
Description | Set the contents of a text field
Syntax |
    gui_status empgui_c_field_set (fldobj, string)
where:
`> object fldobj` | field object
`> char *string` | string that contains the value of the field
"<" means input parameters ">" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_PROP_...` | failed to set the property
Notes | `fldobj` and `string` are assigned values by the user. `string` must be a valid character string. For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".

## empgui_c_field_set_focus
Description | Set the input focus to the field
Syntax |
    gui_status empgui_c_field_set_focus (fldobj)
where:
`> object fldobj` | field object
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
Notes | `fldobj` is assigned value by the user. If `fldobj` has an enter action specified, the action will be executed when the field gets the focus.

## empgui_c_image_set
Description | Set the value for an image field
Syntax |
    gui_status empgui_c_image_set (imgobj, bulkptr)
where:
`> object imgobj` | image object
`> addr bulkptr` | pointer to Empress bulk format
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_PROP_...` | failed to set the property
Notes | `imgobj` and `bulkptr` are assigned values by the user. The image data must be in Empress bulk internal format, described as follows: `typedef struct` `{` `long num_data_bytes;` `char image_data [num_data_bytes];` `} bulk;` For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".

## empgui_c_initialize
Description | Initialize common user variables for use in a C API program and get the main window, the menu bar and other bins
Syntax |
    gui_status empgui_c_initialize (&mainwin, &menubar, {binname, &bin,}
         (char *)0)
where:
`< object mainwin` | main window object
`< object menubar` | menubar object
`> char *binname` | name of bin or window to find
`< object bin` | bin or window object
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_MODULE_INACTIVE` | no active module
`E_C_NOT_FOUND` | bin not found
Notes | `binname` must be assigned value by the user while the routine will assign values to `mainwin`, `menubar` and `bin`. This should be the first C API function to be called in a program. This function should only be called only once for each module. If there is no menu bar or it is not needed, `(object *)0` should be passed for `&menubar.` If there are no bins or they are not needed, `(char *)0` must follow the `&menubar` argument. `(char *)0` must be passed as the last argument to this function call. Bin names must match the actual bin names in Empress GUI Builder. `binname` must point to a valid character string. If a bin is not found, function returns `E_C_NOT_FOUND` and the corresponding object is set to `(object)0`.
Warnings | Failure to pass `(char *)0` at the end will cause this function to fail.
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;` The call to this function to initialize variables and get main window, menu bar, and bins would be: `status = empgui_c_initialize (&mainwin, &menubar, binname,` `&radiobin, (char *)0);`

## empgui_c_list_delete_items
Description | Delete all the items from a list or a multilist
Syntax |
    gui_status empgui_c_list_delete_items (listobj)
where:
`> object listobj` | list or multilist object
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
Notes | `listobj` is assigned value by the user. This function is valid for both list and multilist. This function clears all the rows of the list or multilist specified.

## empgui_c_list_get_num_columns
Description | Get the number of columns in a list or multilist
Syntax |
    gui_status empgui_c_list_get_num_columns (listobj, &num)
where:
`> object listobj` | list or multilist object
`< int num` | number of columns in a list or multilist
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
Notes | `listobj` is assigned value by the user while the routine assigns value to `num`. This function is valid for both list and multilist. In case of a list, this function will always return 1 in the `num` variable.

## empgui_c_list_get_num_viewrows
Description | Get the number of viewable rows in a list or multilist
Syntax |
    gui_status empgui_c_list_get_num_viewrows (listobj, &num)
where:
`> object listobj` | list or multilist object
`< int num` | number of viewable rows in a list or multilist
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
Notes | `listobj` is assigned value by the user while the routine assigns value to `num`. This function is valid for both list and multilist.

## empgui_c_list_scroll_set_array
Description | Set scroll items to a list or multilist
Syntax |
    gui_status empgui_c_list_scroll_set_array ( listobj, toprow, num,
         numexprows, listvals )
where:
`> object listobj` | list or multilist object
`> int toprow` | number of the row from the total number of expected rows to be displayed at top of the list display
`> int num` | number of rows to be displayed in the list
`> int numexprows` | expected number of rows to be displayed or 0, if unknown
`> char ***listvals` | array of array of strings for the columns of the list
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_NARGS` | wrong number of arguments
Notes | `listobj`, `toprow`, `num`, `numexprows` and `listvals` are assigned values by the user. This function is valid for both list and multilist. `num` specifies the number of rows to be displayed in the list. `numexprows` is used to determine the size of the scroll bar. It is the total number of expected rows that will be displayed in the list. If that is unknown, set it to 0. In that case, Empress GUI Builder will try to guess a good number for this argument. `toprow` is used to determine the position of the scroll bar, It is the number of the row from the total number of expected rows to be displayed at the top of the list. `listvals` must be null terminated. If the object is a list, `listvals` will contain only two elements, an array and a null element. If the object is a multilist, first element of the `listvals` array will correspond to the first column of the multilist, second element will correspond to the second column of the multilist, and so on.
Warning | Failure to null terminate the `listvals` array will cause this function to fail.
Example | For an application that has a multi list called "`mlist`" with two columns/four rows in the main window, the variable declaration could be as follows: `object mainwin, mlistobj;` `char *objname = "mlist";` `gui_status status;` `char *listval1[4] = {"item1", "item2", "item3", "item4"};` `char *listval2[4] = {"item5", "item6", "item7", "item8"};` `char **listvals[3];` To get the object for this multilist:
    status = empgui_c_obj_get_by_name (mainwin, objname, &mlistobj);
(Assuming `mainwin` has already been initialized) To set up the array listvals: `listvals[0] = (char **) listval1;` `listvals[1] = (char **) listval2;` `listvals[2] = (char **) 0;` The call to this function to set items in the multilist would be:
    status = empgui_c_list_scroll_set_array (mlistobj, 1, 4, 1000, listvals);

## empgui_c_list_scroll_set_func
Description | Set the scroll function for a list or a multilist
Syntax | `gui_status empgui_c_list_scroll_set_func` (`listobj`, `scroll_func`) where:
`> object listobj` | list or multilist object
`> addr scroll_func` | address of the scroll function
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
Notes | `listobj` and `scroll_func` are assigned values by the user. This function is valid for both list and multilist. `scroll_func` is the address of the function that is called when the user activates scrolling. The function should be declared as follows: `void scroll_func (listobj, toprow, nviewrows, at_bottom)` where:
`object` | `listobj`,
`int` | `toprow`,
`int` | `nviewrows`,
`boolean` | `at_bottom`
`listobj` | is the list object passed directly from `empgui_c_list_scroll_set_func`.
`toprow` | is the item number which is now at the top of the list display
`nviewrows` | is the number of viewable rows in the list
`at_bottom` | is a boolean flag to indicate whether the scroll bar is at the bottom or not

## empgui_c_list_scroll_set_items
Description | Set scroll items to a list or multilist
Syntax |
    gui_status empgui_c_list_scroll_set_items (listobj, toprow, num,
        numexprows, listval, { listval, } (char **) 0 )
where:
`> object listobj` | list or multilist object
`> int toprow` | item number of the row to be displayed at top of the list display
`> int num` | number of rows to be displayed in the list
`> int numexprows` | total number of items to be displayed in the list, or 0 if unknown
`> char **listval` | array of strings
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_NARGS` | wrong number of arguments
Notes | `listobj`, `toprow`, `num`, `numexprows` and `listval` are assigned values by the user. This function is valid for both list and multilist. `(char **)0` must be passed as the last argument to the function call. `num` specifies the number of rows to be displayed in the list. `numexprows` is used to determine the size of the scroll bar. It is the total number of expected rows that will be displayed in the list. If that is unknown, set it to 0. In that case, Empress GUI Builder will try to guess a good number for this argument. `toprow` is used to determine the position of the scroll bar. It is the number of the row from the total number of expected rows to be displayed at the top of the list. If the object is a list, there must be only one `listval` array variable. If the object is a multilist, first `listval` variable will correspond to the first column of the multilist, second `listval` variable will correspond to the second column of the multilist, and so on.
Warning | Failure to pass `(char **)0` as the last argument will cause this function to fail.
Example | For an application that has a multi list called "`mlist`" with two columns/four rows in the main window, the variable declaration could be as follows: `object mainwin, mlistobj;` `char *objname = "mlist";` `gui_status status;` `char *listval1[4] = {"item1", "item2", "item3", "item4"};` `char *listval2[4] = {"item5", "item6", "item7", "item8"};` To get the object for this multilist:
    status = empgui_c_obj_get_by_name (mainwin, objname, &mlistobj);
(Assuming `mainwin` has already been initialized) The call to this function to set items in the multilist would be:
    status = empgui_c_list_scroll_set_items (mlistobj, 1, 4, 1000, listval1,
             listval2, (char **)0);

## empgui_c_list_set_array
Description | Set items to a list or multilist
Syntax | `gui_status empgui_c_list_set_array` (`listobj`, `num`, `listvals`) where:
`> object listobj` | list or multilist object
`> int num` | number of elements in the arrays that make up `listvals`
`> char ***listvals` | array of array of strings for the columns of the list
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_NARGS` | wrong number of arguments
Notes | `listobj`, `listvals` and `num` are assigned values by the user. This function is valid for both list and multilist. `num` specifies the number of elements in the arrays that make up `listvals`. `listvals` must be null terminated. If the object is a list, `listvals` will contain only two elements, an array and a null element. If the object is a multilist, first element of the `listvals` array will correspond to the first column of the multilist, second element will correspond to the second column of the multilist, and so on.
Warning | Failure to null terminate the `listvals` array will cause this function to fail.
Example | For an application that has a multi list called "`mlist`" with two columns/ two rows in the main window, the variable declaration could be as follows: `object mainwin, mlistobj;` `char *objname = "mlist";` `gui_status status;` `char *listval1[4] = {"item1", "item2", "item3", "item4"};` `char *listval2[4] = {"item5", "item6", "item7", "item8"};` `char **listvals[3];` To get the object for this multilist:
    status = empgui_c_obj_get_by_name (mainwin, objname, &mlistobj);
(Assuming `mainwin` has already been initialized) To set up the array listvals: `listvals[0] = (char **) listval1;` `listvals[1] = (char **) listval2;` `listvals[2] = (char **) 0;` The call to this function to set items in the multilist would be:
    status = empgui_c_list_set_array (mlistobj, 4, listvals);

## empgui_c_list_set_items
Description | Set items to a list or multilist
Syntax |
    gui_status empgui_c_list_set_items (listobj, num, listval, {listval,}
          (char **)0 )
where:
`> object listobj` | list or multilist object
`> int num` | number of elements in the `listval` arrays
`> char **listval` | array of strings
`` ">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_NARGS` | wrong number of arguments
Notes | `listobj`, `listval` and `num` are assigned values by the user. This function is valid for both list and multilist. `(char **)0` must be passed as the last argument to the function call. `num` specifies the number of elements in the `listval` arrays. If the object is a list, there must be only one `listval` array variable. If the object is a multilist, first `listval` variable will correspond to the first column of the multilist, second `listval` variable will correspond to the second column of the multilist, and so on.
Warning | Failure to pass `(char **)0` as the last argument will cause this function to fail.
Example | For an application that has a multi list called "`mlist`" with two columns/two rows in the main window, the variable declaration could be as follows: `object mainwin, mlistobj;` `char *objname = "mlist";` `gui_status status;` `char *listval1[4] = {"item1", "item2", "item3", "item4"};` `char *listval2[4] = {"item5", "item6", "item7", "item8"};` To get the object for this multilist:
    status = empgui_c_obj_get_by_name (mainwin, objname, &mlistobj);
(Assuming `mainwin` has already been initialized) The call to this function to set items in the multilist would be:
    status = empgui_c_list_set_items (mlistobj, 4, listval1, listval2,
             (char **)0);

## empgui_c_module_exit
Description | Indicate that current module should exit
Syntax |
    gui_status empgui_c_module_exit ()
Returns |
`E_C_SUCCESS` | operation successful
`E_C_MODULE_INACTIVE` | no current module
Notes | If an exit action has been defined for this module, that action is called before the module is terminated. If the current module was called by another module, control is returned to that module after exiting the current module.

## empgui_c_module_exit_deny
Description | Deny the removal of a module through an exit action
Syntax |
    gui_status empgui_c_module_exit_deny ()
Returns |
`E_C_SUCCESS` | operation successful
Notes | When the function `empgui_c_module_exit()` is called, the exit action of the module is executed. In the exit action, if the application determines that the module should not be exited, this function should be called.

## empgui_c_module_run
Description | Run a module
Syntax |
    gui_status empgui_c_module_run (modname, argc, argv)
where:
`> char *modname` | module name
`> int argc` | argument count
`> char **argv` | array of string arguments
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_ARGC_NEGATIVE` | negative `argc`
`E_C_ARGV_NIL` | `argv` is nil
`E_C_NAME_NIL` | name string is nil
`E_C_MODULE_NOT_FOUND` | module cannot be found
`E_C_SCRIPT_NOT_INIT` | script cannot be initialized
Notes | `modname`, `argc` and `argv` are assigned values by the user. Module to be executed must be in the current database.

## empgui_c_obj_get_by_name
Description | Find an object in a bin or window, by its name
Syntax | `gui_status empgui_c_obj_get_by_name` (`bin`, `name`, `&obj`) where:
`> object bin` | bin or window which contains the object
`> char *name` | name of the object to find
`< object obj` | the object
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_NAME_NIL` | name string is nil
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_NOT_FOUND` | object not found
Notes | `bin` and `name` must be assigned values by the user while the routine will assign value to `obj`. `name` must be a valid character string. If the object is not found, function returns `E_C_NOT_FOUND` and the corresponding object variable is set to `(object)0`.

## empgui_c_obj_get_class_name
Description | Get the class name of an object
Syntax |
    gui_status empgui_c_obj_get_class_name (obj, &name)
where:
`> object obj` | object
`< char *name` | string containing the class name of the object
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_FUNCTION_INVALID` | function invalid for object
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
Notes | `obj` must be assigned value by the user while the routine will assign value to `name`. This function is useful mainly for debugging purposes.

## empgui_c_obj_get_name
Description | Get the name of an object
Syntax |
    gui_status empgui_c_obj_get_name (obj, &name)
where:
`> object obj` | object
`< char *name` | string containing the name of the object
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_FUNCTION_INVALID` | function invalid for object
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
Notes | `obj` must be supplied by the user while the routine will assign a value to `name`. This function is useful mainly for debugging purposes.

## empgui_c_objs_get_by_name_pair
Description | Find objects in a bin or window, by their names
Syntax |
    gui_status empgui_c_objs_get_by_name_pair (bin, name, &obj, {name, &obj,}
             (char *)0)
where:
`> object bin` | the given bin or window
`> char *name` | name of the given object
`< object obj` | the object to be searched
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_NARGS` | wrong number of arguments
`E_C_NOT_FOUND` | object not found
Notes | `bin` and `name` must be assigned values by the user while the routine will assign value to `obj`. All objects must be contained in the bin in the argument list. If the object is not found, function returns `E_C_NOT_FOUND` and the corresponding object is set to `(object )0`. `(char *)0` must be passed as the last argument to this function call. `name` must be a valid character string.
Warnings | Failure to pass `(char *)0` as the last argument will cause this function to fail.

## empgui_c_objs_get_by_names
Description | Find objects in a given bin or window, by their names
Syntax |
    gui_status empgui_c_objs_get_by_names (bin, names, &objs)
where:
`> object bin` | bin or window which contains all these objects
`> char **names` | array of strings of object names
`< object *objs` | pointer to objects
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_NAME_NIL` | name string is nil
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_ARRAY_NULL` | no entries in array
`E_C_NOT_FOUND` | an object is not found
Notes | `bin` and `names` must be assigned values by the user while the routine will assign values to `objs`. This function creates an array and assigns it to `objs`. Elements of that array will be accessible as `*objs`, `*(objs+1)`, an so on. All objects must be contained in the bin in the argument list. If an object is not found, function returns `E_C_NOT_FOUND` and the corresponding object is set to `(object )0`. The array `names` must be null terminated. That is, the last element of the array must be `(char*)0`. Each entry of the array `names` must point to a valid character string. The array `objs` is null terminated. That is, the last element of the array is `(object)0`. The array allocated to `objs` should be freed with `empgui_c_array_free()`.
Warnings | Failure to null terminate the `names` array will cause this function to fail.
Example | For an application that has a main window, and three pushbutton objects called "`pushb1`", "`pushb2`" and "`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)`.

## empgui_c_objs_get_from_bin
Description | Get all the objects in bin or window
Syntax |
    gui_status empgui_c_objs_get_from_bin (bin, &objs)
where:
`> object bin` | bin or window which contains all these objects
`< object *objs` | pointer to objects
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
Notes | `bin` must be assigned value by the user while the routine will assign values to `objs`. The function allocates an array and assigns it to `objs`. Elements of the array `objs` are accessed as `*objs`, `*(objs+1)`, and so on. The array is null terminated. That is, the last element of the array is`(object)0`. The array allocated to `objs` should be freed with `empgui_c_array_free()`.
Example | For an application that has a main window, and three push button objects in the main window, the variable declaration could be as follows:
    object mainwin, *pbobjs;
The call to this function to get the objects from the bin would be:
    status = empgui_c_objs_get_from_bin (mainwin, &pbobjs);
(Assuming that `mainwin` has already been initialized) Objects corresponding to the `objnames` array would be accessible as `*(pbobjs)`, `*(pbobjs+1)`, and `*(pbobjs+2)`.

## empgui_c_objs_names_get_from_bin
Description | Get all the objects and their names from a given bin or window
Syntax |
    gui_status empgui_c_objs_names_get_from_bin (bin, &objs, &names)
where:
`> object bin` | bin or window which contains all these objects
`< object *objs` | pointer to objects
`< char **names` | array of names pointers
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
Notes | `bin` must be assigned value by the user while the routine will assign values to `objs` and `names`. The routine will allocate two arrays and assign it to `objs` and `names`. Elements of the arrays assigned to `objs` are accessible as `*objs`, `*(objs+1)`, and so on. Elements of the array assigned to `names` are accessible as `*names`, `*(names+1)`, and so on. The arrays allocated to `objs` and `names` should be freed with `empgui_c_array_free()`.
Example | For an application that has a main window, and three pushbutton objects in the main window, the variable declaration could be as follows: `object mainwin, *pbobjs;` `char **objnames;` The call to this function to get the objects and their names from the bin would be:
    status = empgui_c_objs_names_get_from_bin (mainwin, &pbobjs, &objnames);
(Assuming that `mainwin` has already been initialized) Objects array would be accessible as `*(pbobjs)`, `*(pbobjs+1)`, `*(pbobjs+2)`. Names would be accessible as `*(objnames)`,`*(objnames+1),` `*(objnames+2)`.

## empgui_c_prop_datasize
Description | Get the size of the property data from its type
Syntax |
    gui_status empgui_c_prop_datasize (datatype,&datasize)
where:
`> int datatype` | data type
`< int datasize` | size of the data
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_DATATYPE_INVALID` | invalid datatype
Notes | `datatype` is assigned value by the user while the routine assigns a value to `datasize`. `datatype` must be any of the following property data types that Empress GUI Builder supports. `` `TYPE_ADDRESS` `TYPE_BOOLEAN` `TYPE_BULK` `TYPE_CHARACTER` `TYPE_INTEGER` `TYPE_SELECTION` `TYPE_STRING` `TYPE_STRING_ARRAY` `` `datasize` would be the size of `datatype` in bytes.

## empgui_c_prop_get
Description | Get a property of an object
Syntax |
    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
Returns |
`E_C_SUCCESS` | everything OK
`E_C_FUNCTION_INVALID` | function not valid for this object
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_PROP_...` | failed to get the property
Notes | `obj` and `prop_type` are assigned values by the user while the routine assigns value to `data`. `data` is a variable of the appropriate data type for the property and object in question. `prop_type` must be one of the following property types that Empress GUI Builder supports: `` `PROP_COLUMNS` `PROP_DESCRIPTION` `PROP_EDITABLE` `PROP_FIELD_TYPE` `PROP_ITEMS_INSENSITIVE` `PROP_ITEMS_SENSITIVE` `PROP_LABEL_TEXT` `PROP_LABEL_PIXMAP` `PROP_LINE` `PROP_LIST_SELPOS` `PROP_SENSITIVITY` `PROP_STATE` `PROP_TEXT` `PROP_TEXT_VALUE` `PROP_TYPE` `PROP_USER_DATA` `PROP_VALUE` `PROP_VALUE_APPEND` `PROP_VALUE_INSERT``` However, not all of these properties apply to all of the objects. Please refer to Chapter 3 - "Objects". For details on `E_C_PROP_...` please refer to Chapter 3 - "Objects".

## empgui_c_prop_set
Description | Set a property of an object
Syntax |
    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
Returns |
`E_C_SUCCESS` | everything OK
`E_C_FUNCTION_INVALID` | function not valid for this object
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_PROP_...` | failed to set the property
Notes | `obj`, `prop_type`, and `data` are assigned values by the user. `prop_type` must be one of the following property types that Empress GUI Builder supports: `` `PROP_COLUMNS` `PROP_DESCRIPTION` `PROP_EDITABLE` `PROP_FIELD_TYPE` `PROP_ITEMS_INSENSITIVE` `PROP_ITEMS_SENSITIVE` `PROP_LABEL_TEXT` `PROP_LABEL_PIXMAP` `PROP_LINE` `PROP_LIST_SELPOS` `PROP_SENSITIVITY` `PROP_STATE` `PROP_TEXT` `PROP_TEXT_VALUE` `PROP_TYPE` `PROP_USER_DATA` `PROP_VALUE` `PROP_VALUE_APPEND` `PROP_VALUE_INSERT``` However, not all of these properties apply to all of the objects. Please refer to Chapter 3 - "Objects". `data` is a variable of the appropriate data type for the property and object in question For details on `E_C_PROP_...` please refer to Chapter 3 - "Objects".

## empgui_c_prop_type
Description | Get the data type of a property of an object
Syntax |
    gui_status empgui_c_prop_type (obj, prop_type, &datatype)
where:
`> object obj` | object
`> int prop_type` | property type
`< int datatype` | data type
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_FUNCTION_INVALID` | function not valid for this object
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_PROP_TYPE_INVALID` | invalid property type
Notes | `obj` and `prop_type` must be assigned values by the user while the routine will assign value to `datatype`. `prop_type` must be one of the following property types that Empress GUI Builder supports: `` `PROP_COLUMNS` `PROP_DESCRIPTION` `PROP_EDITABLE` `PROP_FIELD_TYPE` `PROP_ITEMS_INSENSITIVE` `PROP_ITEMS_SENSITIVE` `PROP_LABEL_TEXT` `PROP_LABEL_PIXMAP` `PROP_LIST_SELPOS` `PROP_LINE` `PROP_SENSITIVITY` `PROP_STATE` `PROP_TEXT` `PROP_TEXT_VALUE` `PROP_TYPE` `PROP_USER_DATA` `PROP_VALUE` `PROP_VALUE_APPEND` `PROP_VALUE_INSERT``` However, not all of these properties apply to all of the objects. Please refer to Chapter 3 - "Objects". This routine will return a numeric value in `datatype` which would correspond to one of the following property data type that Empress GUI Builder supports: `` `TYPE_ADDRESS` `TYPE_BOOLEAN` `TYPE_BULK` `TYPE_CHARACTER` `TYPE_INTEGER` `TYPE_SELECTION` `TYPE_STRING` `TYPE_STRING_ARRAY`

## empgui_c_props_get
Description | Get a property for an array of objects
Syntax |
    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
Returns |
`E_C_SUCCESS` | everything OK
`E_C_FUNCTION_INVALID` | function not valid for this object
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_ARRAY_NULL` | no entries in array
`E_C_PROP_...` | failed to get the property
Notes | `objs` and `prop_type` must be assigned values by the user while the routine will assign values to `datas`. This function will allocate an array to `datas`. Accessing elements of `datas` will depend on the type of the object and property in question. `prop_type` must be one of the following property types that Empress GUI Builder supports: `` `PROP_COLUMNS` `PROP_DESCRIPTION` `PROP_EDITABLE` `PROP_FIELD_TYPE` `PROP_ITEMS_INSENSITIVE` `PROP_ITEMS_SENSITIVE` `PROP_LABEL_TEXT` `PROP_LABEL_PIXMAP` `PROP_LINE` `PROP_LIST_SELPOS` `PROP_SENSITIVITY` `PROP_STATE` `PROP_TEXT` `PROP_TEXT_VALUE` `PROP_TYPE` `PROP_USER_DATA` `PROP_VALUE` `PROP_VALUE_APPEND` `PROP_VALUE_INSERT``` However, not all of these properties apply to all of the objects. Please refer to Chapter 3 - "Objects". For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects". `objs` must be a null terminated array. The array allocated to `datas` should be freed with `empgui_c_array_free()`.
Warnings | Failure to null terminate the `objs` array will cause this function to fail.

## empgui_c_props_set
Description | Set a property for an array of objects
Syntax |
    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
Returns |
`E_C_SUCCESS` | everything OK
`E_C_FUNCTION_INVALID` | function not valid for this object
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_PROP_...` | failed to set the property
Notes | `objs`, `prop_type`, and `datas` will be assigned values by the user. `prop_type` must be one of the following property types that Empress GUI Builder supports: `` `PROP_COLUMNS` `PROP_DESCRIPTION` `PROP_EDITABLE` `PROP_FIELD_TYPE` `PROP_ITEMS_INSENSITIVE` `PROP_ITEMS_SENSITIVE` `PROP_LABEL_TEXT` `PROP_LABEL_PIXMAP` `PROP_LINE` `PROP_LIST_SELPOS` `PROP_SENSITIVITY` `PROP_STATE` `PROP_TEXT` `PROP_TEXT_VALUE` `PROP_TYPE` `PROP_USER_DATA` `PROP_VALUE` `PROP_VALUE_APPEND` `PROP_VALUE_INSERT``` However, not all of these properties apply to all of the objects. Please refer to Chapter 3 - "Objects". `objs` array must be null terminated. `datas` will be an array, the type of which will depend on the object and and the property in question. For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".
Warnings | Failure to null terminate `objs` array will cause this function to fail.

## empgui_c_props_type
Description | Get the data type of a property of an array of objects
Syntax |
    gui_status empgui_c_props_type (objs, prop_type, &datatypes)
where:
`> object *objs` | object
`> int prop_type` | property type
`< int *datatypes` | pointer to datatypes
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | everything OK
`E_C_FUNCTION_INVALID` | function not valid for this object
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_ARRAY_NULL` | no entries in array
`E_C_PROP_TYPE_INVALID` | invalid property type
Notes | `objs` and `prop_type` must be assigned values by the user while the routine will assign value to `datatypes`. The function will allocate an array of type `int` and assign it to `datatypes`. `prop_type` must be one of the following property types that Empress GUI Builder supports: `` `PROP_COLUMNS` `PROP_DESCRIPTION` `PROP_EDITABLE` `PROP_FIELD_TYPE` `PROP_ITEMS_INSENSITIVE` `PROP_ITEMS_SENSITIVE` `PROP_LABEL_TEXT` `PROP_LABEL_PIXMAP` `PROP_LINE` `PROP_LIST_SELPOS` `PROP_SENSITIVITY` `PROP_STATE` `PROP_TEXT` `PROP_TEXT_VALUE` `PROP_TYPE` `PROP_USER_DATA` `PROP_VALUE` `PROP_VALUE_APPEND` `PROP_VALUE_INSERT``` However, not all of these properties apply to all of the objects. Please refer to Chapter 3 - "Objects". This routine will return a numeric value array which would correspond to one of the following property data type that Empress GUI Builder supports: `` `TYPE_ADDRESS` `TYPE_BOOLEAN` `TYPE_BULK` `TYPE_CHARACTER` `TYPE_INTEGER` `TYPE_SELECTION` `TYPE_STRING` `TYPE_STRING_ARRAY` `` `objs` array must be null terminated. The array allocated to `datatypes` should be freed with `empgui_c_array_free()`.
Warnings | Failure to null terminate the `objs` array will result in the failure of this routine.

## empgui_c_scale_get
Description | Get the value of a scale object
Syntax |
    gui_status empgui_c_scale_get (scaleobj, &val)
where:
`> object scaleobj` | scale object
`< int val` | variable where the value will be stored
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_PROP_...` | failed to get the property
Notes | `scaleobj` is assigned values by the user while the routine will assign values to `val`. For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".
Warning | If the value assigned to the scale is greater than the maximum allowed, the function returns `E_C_PROP_FAIL_SCALE_MAX`. If the value is less than the minimum allowed, the function returns `E_C_PROP_FAIL_SCALE_MIN`.

## empgui_c_scale_set
Description | Set the value of a scale object
Syntax |
    gui_status empgui_c_scale_set (scaleobj, val)
where:
`> object scaleobj` | scale object
`> int val` | value to assign to the scale
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_PROP_...` | failed to set the property
Notes | `scaleobj` and `val` are assigned values by the user. For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".
Warning | If the value assigned to the scale is greater than the maximum allowed, the function returns `E_C_PROP_FAIL_SCALE_MAX`. If the value is less than the minimum allowed, the function returns `E_C_PROP_FAIL_SCALE_MIN`.

## empgui_c_sen_set
Description | Set the sensitivity of an object
Syntax |
    gui_status empgui_c_sen_set (obj,sen)
where:
`> object obj` | object
`> boolean sen` | flag to set the property true for sensitive, false for insensitive
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_FUNCTION_INVALID` | function invalid for object
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
Notes | `obj` and `sen` are assigned values by the user. This function only applies to objects to which sensitivity property apply. Please refer to the section on "Properties of Objects" in Chapter 3. If an object is insensitive, it cannot be activated and it looks grayed out.

## empgui_c_sens_set
Description | Set the sensitivity of an array of objects to an array of values
Syntax |
    gui_status empgui_c_sens_set (objs,sens)
where:
`> object *objs` | array of objects
`> boolean *sens` | array of flag to set the property true for sensitive, false for insensitive
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_FUNCTION_INVALID` | function invalid for object
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_ARRAY_NULL` | no entries in array
Notes | `objs` and `sens` are assigned values by the user. `objs` must be a null terminated array. `objs` and `sens` must point to valid arrays of their respective types. This function only applies to objects to which sensitivity property apply. Please refer to the section on "Properties of Objects" in Chapter 3. If an object is insensitive, it cannot be activated and it looks grayed out.
Example | For an application that has a main window and five buttons called "`button1`", "`button2`","`button3`", "`button4`" and "`button5`", the variable declaration would be as follows: `object mainwin, *fobjs;` `char *objsname[5] = {"button1", "button2", "button3", "button4",` `"button5"};` `boolean sens[5] = {false, false, true, true, true};` `gui_status status;` To get the objects:
    status = empgui_c_objs_get_by_names(mainwin, objnames, &fobjs);
(Assuming that `mainwin` has already been initialized) Using this function to sensitize the last three buttons and de-sensitize the first two:
    status = empgui_c_sens_set (fobjs, sens);

## empgui_c_sens_set_all
Description | Set the sensitivity of an array of objects to the same value
Syntax |
    gui_status empgui_c_sens_set_all (objs,sen)
where:
`> object *objs` | array of objects
`> boolean sen` | flag to set the property true for sensitive, false for insensitive
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_FUNCTION_INVALID` | function invalid for object
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_POINTER_NIL` | pointer argument is nil
`E_C_ARRAY_NULL` | no entries in array
Notes | `objs` and `sen` are assigned values by the user. `objs` must be a null terminated array. This function only applies to objects to which sensitivity property apply. Please refer to the section on "Properties of Objects" in Chapter 3. If an object is insensitive, it cannot be activated and it looks grayed out.

## empgui_c_status_message
Description | Get the message associated with C API status code
Syntax |
    gui_status empgui_c_status_message (status, &message)
where:
`> gui_status status` | status
`< char *message` | string where message will be returned
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_STATUS_INVALID` | invalid status
Notes | `status` is assigned value by the user or a previous function call has returned a value in `status`. `message` is assigned value by the routine.

## empgui_c_timer_add
Description | Call a function after a specified interval
Syntax |
    gui_status empgui_c_timer_add (interval, func, data, &timerid)
where:
`> unsigned long interval` | time interval in milliseconds
`> void (*func)` | timer function
> addr data | data for the timer function
< addr timerid | id of the timer created
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_POINTER_NIL` | pointer argument is nil
Notes | `interval`, `func`, and `data` are assigned values by the user while the routine assigns value to `timerid`. After the time interval specified in `interval`, the function `func` is called. If `(unsigned long) 0` is passed for `interval`, then this function call is practically ignored. This function registers an alarm and returns `timerid` to the user. This can be used later on to cancel that alarm using `empgui_c_timer_trash`. `func` is the address of the function called when the alarm happens. It should be declared as follows:
    void (*func)(data, timerid)
where:
`addr data` | pointer to any data structure passed to the `empgui_c_timer_add` function
`addr timerid` | id of timer created by `empgui_c_timer_add`

## empgui_c_timer_trash
Description | Remove the timer associated with the given timer id
Syntax |
    gui_status empgui_c_timer_trash (timerid)
where:
`> addr timerid` | timer id
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
Notes | `timerid` is assigned value by `empgui_c_timer_add`. This function is useful only when the call is made before the alarm set by `empgui_c_timer_add` expires.

## empgui_c_toggleb_get
Description | Get the value of a toggle button object
Syntax |
    gui_status empgui_c_toggleb_get (togglebobj, &val)
where:
`> object togglebobj` | toggle button object
`< boolean val` | value of the toggle button, either true or false
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_PROP_...` | failed to get the property
Notes | `togglebobj` is assigned value by the user while the routine assigns value to `val`. Boolean value `true` corresponds to ON state of the toggle button while boolean value `false` corresponds to OFF state of the toggle button. For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".

## empgui_c_toggleb_set
Description | Set the value of a toggle button object
Syntax |
    gui_status empgui_c_toggleb_set (togglebobj, val)
where:
`> object togglebobj` | toggle button object
`> boolean val` | value of the toggle button, either true or false
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_PROP_...` | failed to set the property
Notes | `togglebobj` and `val` are assigned values by the user. Boolean value `true` corresponds to ON state of the toggle button and boolean value `false` corresponds to OFF state of the toggle button. For details on `E_C_PROP_...`, please refer to Chapter 3 - "Objects".

## empgui_c_user_get_widget
Description | Get the widget associated with the user object
Syntax |
    gui_status empgui_c_user_get_widget (userobj, &widget)
where:
`> object userobj` | user object
`< addr widget` | Motif widget
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
`E_C_POINTER_NIL` | pointer argument is nil
Notes | `userobj` is assigned value by the user while the routine assigns value to `widget`. The widget variable is a generic `addr`, which corresponds to the Motif `Widget` data type.

## empgui_c_window_hide
Description | Hide the given window
Syntax |
    gui_status empgui_c_window_hide (winobj)
where:
`> object winobj` | window object
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
Notes | `winobj` is assigned value by the user. It is not an error to hide a window that is not currently shown.

## empgui_c_window_show
Description | Show the given window
Syntax |
    gui_status empgui_c_window_show (winobj)
where:
`> object winobj` | window object
">" means input parameters "<" means output parameters
Returns |
`E_C_SUCCESS` | operation successful
`E_C_OBJECT_NIL` | object is nil
`E_C_OBJECT_INVALID` | argument is not an object
`E_C_OBJECT_TYPE` | wrong type of object
Notes | `winobj` is assigned value by the user. It is not an error to call this function to show a window that is already shown.