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 |