# CHAPTER 1: Introduction

## 1.1 Overview

The Empress GUI Builder has its own script language for accessing Empress databases and controlling objects in a GUI application. While the script language is very compact and powerful, it cannot match the versatility of the C language.

The Empress GUI Builder C API provides the developer with a complete set of functions for accessing GUI objects in an application from a C program. These functions are easy to use and shield the developer from the complexity of the underlying X Window and Motif calls.

The C API does not provide any function for accessing databases. For that purpose, any of the Empress C interfaces (Embedded and Dynamic SQL, mr or mx Routines) or other DBMS vendors of Dynamic SQL (such as Oracle, Ingres, etc.) can be included in the Empress GUI Builder C API program for database access. With this functionality, Empress GUI Builder can be used as a presentation manager for data that comes from anywhere such as satellite data, flat files, Empress databases or other DBMS database.

## 1.2 Summary of Functions

All C API functions return a status code which is of data type `gui_status`.

The following tables summarize the routines according to the use their function.

Initialization
Function Name | Description
`empgui_c_initialize` | Initialize program to access GUI objects

Retrieving Objects
Function Name | Description
`empgui_c_bin_get_by_name` | Get a bin or window, using its name
`empgui_c_bins_get_by_name` | Get several bins or windows, using their names
`empgui_c_obj_get_by_name` | Get an object, using its name
`empgui_c_objs_get_by_name_pair` | Get several objects, using their names
`empgui_c_objs_get_by_names` | Get several objects, using their names
`empgui_c_objs_get_from_bin` | Get all objects in a bin or window
`empgui_c_objs_names_get_from_bin` | Get all objects (and their names) in a bin or window

Object Class & Name
Function Name | Description
`empgui_c_obj_get_class_name` | Get the class name of the object
`empgui_c_obj_get_name` | Get the name of the object

Object Properties
Function Name | Description
`empgui_c_prop_datasize` | Find the size of the data type of an object's property
`empgui_c_prop_get` | Get the value of a property of an object
`empgui_c_prop_set` | Assign a value to a property of an object
`empgui_c_prop_type` | Find the data type of a property of an object
`empgui_c_props_get` | Get the values of a property of several objects
`empgui_c_props_set` | Assign values to a property of several objects
`empgui_c_props_type` | Find the data types of a property of several objects

Audio Object
Function Name | Description
`empgui_c_audio_get_state` | Find the state of an audio object
`empgui_c_audio_get_volume` | Find the volume of an audio object
`empgui_c_audio_set` | Assign audio data to an audio object
`empgui_c_audio_set_volume` | Set the volume of an audio object

Field Object
Function Name | Description
`empgui_c_field_get` | Get the contents of a text field
`empgui_c_field_set` | Place a string into a text field
`empgui_c_field_set_focus` | Set the input focus to a text field

Image Object
Function Name | Description
`empgui_c_image_set` | Assign image data to an image object

List Object
Function Name | Description
`empgui_c_list_delete_items` | Clear the contents of a list
`empgui_c_list_get_num_columns` | Find the number of columns in a multilist
`empgui_c_list_get_num_viewrows` | Find the number of viewable rows in a list
`empgui_c_list_scroll_set_array` | Assign items to a list, for user-controlled scrolling
`empgui_c_list_scroll_set_func` | Specify the function to be called for user-controlled scrolling of a list
`empgui_c_list_scroll_set_items` | Assign items to a list, for user-controlled scrolling
`empgui_c_list_set_array` | Assign items to a list, for automatic scrolling
`empgui_c_list_set_items` | Assign items to a list, for automatic scrolling

Scale Object
Function Name | Description
`empgui_c_scale_get` | Read the value of a scale
`empgui_c_scale_set` | Set the value of a scale

Toggle Button Object
Function Name | Description
`empgui_c_toggleb_get` | Get the value of a toggle button
`empgui_c_toggleb_set` | Set the value of a toggle button

User Defined Object
Function Name | Description
`empgui_c_user_get_widget` | Get the widget associated with a user object

Window Object
Function Name | Description
`empgui_c_window_hide` | Remove a window
`empgui_c_window_show` | Display a window

Editable Property
Function Name | Description
`empgui_c_edit_set` | Make an object editable or non-editable
`empgui_c_edits_set` | Set the editable property of several objects
`empgui_c_edits_set_all` | Make several object editable or non-editable

Sensitivity Property
Function Name | Description
`empgui_c_sen_set` | Make an object sensitive or insensitive
`empgui_c_sens_set` | Set the sensitivity property of several objects
`empgui_c_sens_set_all` | Make several objects sensitive or insensitive

Application & Module
Function Name | Description
`empgui_c_application_run` | Run another Empress GUI application
`empgui_c_module_exit` | Terminate the current module
`empgui_c_module_exit_deny` | Abort the termination of the current module
`empgui_c_module_run` | Run another module

Dialog Box
Function Name | Description
`empgui_c_dialog_error` | Display an error message in a dialog box
`empgui_c_dialog_file_selection` | Display a dialog for selecting a file
`empgui_c_dialog_info` | Display an information message in a dialog box
`empgui_c_dialog_prompt` | Display a dialog for the user to input a value
`empgui_c_dialog_question` | Display a dialog to ask the user a question
`empgui_c_dialog_warning` | Display a warning message in a dialog box
`empgui_c_dialog_working` | Display a dialog to inform the user of a work in progress
`empgui_c_dialog_working_trash` | Remove a working dialog

Miscellaneous
Function Name | Description
`empgui_c_action_execute` | Execute a script or C action
`empgui_c_array_free` | Release an array which was allocated by one of the C API functions
`empgui_c_cursor_change` | Change the shape of the mouse cursor
`empgui_c_display_refresh` | Flush all pending X-events related to the display
`empgui_c_status_message` | Get the message associated to a status code
`empgui_c_timer_add` | Set a timer to execute a function later
`empgui_c_timer_trash` | Remove a timer

Miscellaneous
Global Variable | Data Type | Description
`empgui_c_dbname` | `char*` | Name of application database