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
  1. actname, params, argc, and argv are assigned values by the user.
  2. params is a string that is passed to the action when it is executed.
  3. (int ) 0 can be passed for argc and (char **) 0 can be passed for argv if they are not needed.
  4. 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
  1. 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
  1. 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
  1. audobj must be assigned value by the user while the routine will assign value to state. 
  2. This routine will return a numeric value in state which would correspond to one of the following: 

    3.  
    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
     
  3. 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
  1. audobj must be assigned value by the user while the routine will assign value to lvol and rvol. 
  2. 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
  1. audobj and bulkptr must be assigned values by the user. 
  2. The audio data must be in Empress bulk internal format, described as follows: 

    3. typedef struct  
    {  
        long num_data_bytes;  
        char sound_data [num_data_bytes];  
    } bulk;  
     

  3. 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
  1. audobj, lvol, and rvol must be assigned values by the user. 
  2. Range for lvol and rvol is 0-999. 
  3. 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
  1. binname must be assigned value by the user while the routine will assign value to bin. 
  2. Bin names must match the actual bin names in Empress GUI Builder. 
  3. binname must point to a valid character string. 
  4. 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
  1. binnames array must be assigned values by the user while the routine will assign value to bins. 
  2. This function creates an array and assigns it to bins. Elements of that array will be accessible as *bins, *(bins+1), and so on. 
  3. Bin names must match the actual bin names in Empress GUI Builder. 
  4. If the bin is not found, function returns E_C_NOT_FOUND and the corresponding object is set to (object)0. 
  5. The array binnames must be null terminated. 
  6. Each entry of the array binnames must point to a valid character string. 
  7. The array allocated to bins should be freed with empgui_c_array_free(). 
Warnings Failure to null terminate the binnames 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
  1. cursor is assigned value by the user. 
  2. cursor can take on any of the following values: 

    3.  
    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
  1. style, title, text, position and help are assigned values by the user. 
  2. 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. 
  3. If (char *)0 is passed for style, the colors and the fonts are taken from the main window of the current module. 
  4. If (char *)0 is passed for title, error dialog title would be "dialog_popup". 
  5. If (char *)0 is passed for text, no text will be shown in the error dialog box. 
  6. The value for position could be one of the following: 

    7. POSITION_CENTER  
    POSITION_TOP_LEFT  
    POSITION_TOP_RIGHT  
    POSITION_BOTTOM_LEFT  
    POSITION_BOTTOM_RIGHT 
  7. If (char *)0 is passed for help, the Help button is not displayed in the error dialog box. 
  8. 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
  1. 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. 
  2. If (char *)0 is passed for style, the colors and the fonts are taken from the main window of the current module. 
  3. If (char *)0 is passed for title, file selection dialog title would be "dialog_popup". 
  4. If (char *)0 is passed for text, text on top of the files box in the file selection dialog box would be "Files". 
  5. The value for position could be any of the following: 

    6. POSITION_CENTER  
    POSITION_TOP_LEFT  
    POSITION_TOP_RIGHT  
    POSITION_BOTTOM_LEFT  
    POSITION_BOTTOM_RIGHT  
     

  6. 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. 

    7. DEFAULT_BUTTON_1  
    DEFAULT_BUTTON_2  
    DEFAULT_BUTTON_3  
    DEFAULT_BUTTON_4  
     

  7. If (char *)0 is passed for apply_text, the Apply button in the file selection dialog box is not displayed. 
  8. If (char *)0 is passed for directory, current directory is the default value taken. 
  9. If (char *)0 is passed for mask, "*" is the default value taken. 
  10. If (addr )0 is passed for apply, Apply button, if shown, as described above, is disabled. 
  11. 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. 
  12. 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. 
  13. 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
  1. style, title, text, and position are assigned values by the user. 
  2. 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. 
  3. If (char *)0 is passed for style, the colors and the fonts are taken from the main window of the current module. 
  4. If (char *)0 is passed for title, info dialog title would be "dialog_popup". 
  5. If (char *)0 is passed for text, no text will be show in the info dialog box. 
  6. The value for position could be any of the following: 

    7. POSITION_CENTER  
    POSITION_TOP_LEFT  
    POSITION_TOP_RIGHT  
    POSITION_BOTTOM_LEFT  
    POSITION_BOTTOM_RIGHT  
     

  7. 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
  1. style, title, text, position, def_button, init_text, and help are assigned values by the user, while the function assigns value to string. 
  2. 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. 
  3. If (char *)0 is passed for style, the colors and the fonts are taken from the main window of the current module. 
  4. If (char *)0 is passed for title, prompt dialog title would be "dialog_popup". 
  5. If (char *)0 is passed for text, no text will be shown in the prompt dialog box. 
  6. The value of position could be any of the following: 

    7. POSITION_CENTER  
    POSITION_TOP_LEFT  
    POSITION_TOP_RIGHT  
    POSITION_BOTTOM_LEFT  
    POSITION_BOTTOM_RIGHT 
     

  7. 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. 

    8. DEFAULT_BUTTON_1  
    DEFAULT_BUTTON_2  
    DEFAULT_BUTTON_3  
    DEFAULT_BUTTON_4 
     

  8. If (char *)0 is passed for init_text, the prompt field will be initially empty. 
  9. If (char *)0 is passed for help, the Help button is not displayed in the prompt dialog box. 
  10. 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
  1. style, title, text, position, def_button, but1, but2, and help are assigned values by the user, while the function assigns value to string. 
  2. 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. 
  3. If (char *)0 is passed for style, the colors and the fonts are taken from the main window of the current module. 
  4. If (char *)0 is passed for title, question dialog title would be "dialog_popup". 
  5. If (char *)0 is passed for text, no text will be shown in the dialog box. 
  6. The value of position could be any of the following: 

    7. POSITION_CENTER  
    POSITION_TOP_LEFT  
    POSITION_TOP_RIGHT  
    POSITION_BOTTOM_LEFT  
    POSITION_BOTTOM_RIGHT 
     

  7. 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. 

    8. DEFAULT_BUTTON_1  
    DEFAULT_BUTTON_2  
    DEFAULT_BUTTON_3  
    DEFAULT_BUTTON_4 
     

  8. If (char *)0 is passed for but1 or but2, that button in the question dialog box would not be displayed. 
  9. If (char *)0 is passed for help, the Help button is not displayed in the question dialog box. 
  10. 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
  1. style, title, text, position, def_button, but1, but2, and help are assigned values by the user, while the function assigns value to string. 
  2. 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. 
  3. If (char *)0 is passed for style, the colors and the fonts are taken from the main window of the current module. 
  4. If (char *)0 is passed for title, warning dialog title would be "dialog_popup". 
  5. If (char *)0 is passed for text, no text will show in the warning dialog box. 
  6. The value of position could be any of the following: 

    7. POSITION_CENTER  
    POSITION_TOP_LEFT  
    POSITION_TOP_RIGHT  
    POSITION_BOTTOM_LEFT  
    POSITION_BOTTOM_RIGHT 
     

  7. 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. 

    8. DEFAULT_BUTTON_1  
    DEFAULT_BUTTON_2  
    DEFAULT_BUTTON_3  
    DEFAULT_BUTTON_4 
     

  8. If (char *)0 is passed for but1 or but2, that button in the warning dialog box would not be displayed. 
  9. If (char *)0 is passed for help, the Help button is not displayed in the warning dialog box. 
  10. 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
  1. style, title, text, and position are assigned values by the user while the routine assigns values to dialog. 
  2. The working dialog will have a busy icon which is an hourglass and the message specified by the user. 
  3. If (char *)0 is passed for style, the fonts and the colors are taken from the main window of the current module. 
  4. If (char *)0 is passed for title, working dialog title would be "dialog_popup". 
  5. If (char *)0 is passed for text, no text will show in the dialog box. 
  6. The value of the position could be any of the following: 

    7. POSITION_CENTER  
    POSITION_TOP_LEFT  
    POSITION_TOP_RIGHT  
    POSITION_BOTTOM_LEFT  
    POSITION_BOTTOM_RIGHT 
     

  7. Unlike other dialog functions, this function does not halt the execution of the C routine. 
  8. 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
  1. 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
  1. 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
  1. obj and edit are assigned values by the user. 
  2. This function only applies to objects to which editable property apply. Please refer to the section on "Properties of Objects" in Chapter 3. 
  3. If an object is non-editable, the user cannot change its value. 
  4. 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
  1. objs and edits are assigned values by the user. 
  2. objs must be null terminated. 
  3. objs and edits must point to valid arrays of their respective types. 
  4. If the editable property of an object is false, the user cannot change its value 
  5. This function only applies to objects to which editable property apply. Please refer to the section on "Properties of Objects" in Chapter 3. 
  6. 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
  1. objs and edit are assigned values by the user. 
  2. objs must be a null terminated array. 
  3. This function only applies to objects to which editable property apply. Please refer to the section on "Properties of Objects" in Chapter 3. 
  4. If an object is not editable, the user cannot change its value. 
  5. 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
  1. fldobj is assigned value by the user while the routine assigns value to string. 
  2. 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
  1. fldobj and string are assigned values by the user. 
  2. string must be a valid character string. 
  3. 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
  1. fldobj is assigned value by the user. 
  2. 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
  1. imgobj and bulkptr are assigned values by the user. 
  2. The image data must be in Empress bulk internal format, described as follows: 

    3. typedef struct  
    {  
       long num_data_bytes;  
       char image_data [num_data_bytes];  
    } bulk;  
     

  3. 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
  1. binname must be assigned value by the user while the routine will assign values to mainwin, menubar and bin. 
  2. This should be the first C API function to be called in a program. 
  3. This function should only be called only once for each module. 
  4. If there is no menu bar or it is not needed, (object *)0 should be passed for &menubar.  
  5. If there are no bins or they are not needed, (char *)0 must follow the &menubar argument. 
  6. (char *)0 must be passed as the last argument to this function call. 
  7. Bin names must match the actual bin names in Empress GUI Builder. 
  8. binname must point to a valid character string. 
  9. 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
  1. listobj is assigned value by the user. 
  2. This function is valid for both list and multilist. 
  3. 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
  1. listobj is assigned value by the user while the routine assigns value to num. 
  2. This function is valid for both list and multilist. 
  3. 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
  1. listobj is assigned value by the user while the routine assigns value to num. 
  2. 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
  1. listobj, toprow, num, numexprows and listvals are assigned values by the user. 
  2. This function is valid for both list and multilist. 
  3. num specifies the number of rows to be displayed in the list. 
  4. 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. 
  5. 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. 
  6. listvals must be null terminated. 
  7. If the object is a list, listvals will contain only two elements, an array and a null element. 
  8. 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
  1. listobj and scroll_func are assigned values by the user. 
  2. This function is valid for both list and multilist. 
  3. scroll_func is the address of the function that is called when the user activates scrolling. The function should be declared as follows: 

    4. 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
  1. listobj, toprow, num, numexprows and listval are assigned values by the user. 
  2. This function is valid for both list and multilist. 
  3. (char **)0 must be passed as the last argument to the function call. 
  4. num specifies the number of rows to be displayed in the list. 
  5. 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. 
  6. 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. 
  7. If the object is a list, there must be only one listval array variable. 
  8. 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
  1. listobj, listvals and num are assigned values by the user. 
  2. This function is valid for both list and multilist. 
  3. num specifies the number of elements in the arrays that make up listvals. 
  4. listvals must be null terminated. 
  5. If the object is a list, listvals will contain only two elements, an array and a null element. 
  6. 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
  1. listobj, listval and num are assigned values by the user. 
  2. This function is valid for both list and multilist. 
  3. (char **)0 must be passed as the last argument to the function call. 
  4. num specifies the number of elements in the listval arrays. 
  5. If the object is a list, there must be only one listval array variable. 
  6. 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
  1. If an exit action has been defined for this module, that action is called before the module is terminated. 
  2. 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
  1. 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
  1. modname, argc and argv are assigned values by the user. 
  2. 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
  1. bin and name must be assigned values by the user while the routine will assign value to obj. 
  2. name must be a valid character string. 
  3. 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
  1. obj must be assigned value by the user while the routine will assign value to name. 
  2. 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
  1. obj must be supplied by the user while the routine will assign a value to name. 
  2. 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
  1. bin and name must be assigned values by the user while the routine will assign value to obj. 
  2. All objects must be contained in the bin in the argument list. 
  3. If the object is not found, function returns E_C_NOT_FOUND and the corresponding object is set to (object )0. 
  4. (char *)0 must be passed as the last argument to this function call. 
  5. 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
  1. bin and names must be assigned values by the user while the routine will assign values to objs. 
  2. This function creates an array and assigns it to objs. Elements of that array will be accessible as *objs, *(objs+1), an so on. 
  3. All objects must be contained in the bin in the argument list. 
  4. If an object is not found, function returns E_C_NOT_FOUND and the corresponding object is set to (object )0. 
  5. The array names must be null terminated. That is, the last element of the array must be (char*)0. 
  6. Each entry of the array names must point to a valid character string. 
  7. The array objs is null terminated. That is, the last element of the array is (object)0. 
  8. 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
  1. bin must be assigned value by the user while the routine will assign values to objs. 
  2. The function allocates an array and assigns it to objs. Elements of the array objs are accessed as *objs, *(objs+1), and so on. 
  3. The array is null terminated. That is, the last element of the array is (object)0. 
  4. 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
  1. bin must be assigned value by the user while the routine will assign values to objs and names. 
  2. 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. 
  3. 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
  1. datatype is assigned value by the user while the routine assigns a value to datasize. 
  2. datatype must be any of the following property data types that Empress GUI Builder supports. 

    3. TYPE_ADDRESS 
    TYPE_BOOLEAN 
    TYPE_BULK 
    TYPE_CHARACTER 
    TYPE_INTEGER 
    TYPE_SELECTION 
    TYPE_STRING 
    TYPE_STRING_ARRAY
     

  3. 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
  1. obj and prop_type are assigned values by the user while the routine assigns value to data. 
  2. data is a variable of the appropriate data type for the property and object in question. 
  3. prop_type must be one of the following property types that Empress GUI Builder supports: 

    4. 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". 

  4. 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
  1. obj, prop_type, and data are assigned values by the user. 
  2. prop_type must be one of the following property types that Empress GUI Builder supports: 

    3. 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". 

  3. data is a variable of the appropriate data type for the property and object in question 
  4. 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
  1. obj and prop_type must be assigned values by the user while the routine will assign value to datatype. 
  2. prop_type must be one of the following property types that Empress GUI Builder supports: 

    3. 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". 

  3. 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: 

    4. 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
  1. objs and prop_type must be assigned values by the user while the routine will assign values to datas. 
  2. This function will allocate an array to datas. Accessing elements of datas will depend on the type of the object and property in question. 
  3. prop_type must be one of the following property types that Empress GUI Builder supports: 

    4. 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". 

  4. For details on E_C_PROP_..., please refer to Chapter 3 - "Objects". 
  5. objs must be a null terminated array. 
  6. 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
  1. objs, prop_type, and datas will be assigned values by the user. 
  2. prop_type must be one of the following property types that Empress GUI Builder supports: 

    3. 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". 

  3. objs array must be null terminated. 
  4. datas will be an array, the type of which will depend on the object and and the property in question. 
  5. 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
  1. objs and prop_type must be assigned values by the user while the routine will assign value to datatypes. 
  2. The function will allocate an array of type int and assign it to datatypes. 
  3. prop_type must be one of the following property types that Empress GUI Builder supports: 

    4. 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". 

  4. This routine will return a numeric value array which would correspond to one of the following property data type that Empress GUI Builder supports: 

    5. TYPE_ADDRESS 
    TYPE_BOOLEAN 
    TYPE_BULK 
    TYPE_CHARACTER 
    TYPE_INTEGER 
    TYPE_SELECTION 
    TYPE_STRING 
    TYPE_STRING_ARRAY
     

  5. objs array must be null terminated. 
  6. 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
  1. scaleobj is assigned values by the user while the routine will assign values to val. 
  2. 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
  1. scaleobj and val are assigned values by the user. 
  2. 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
  1. obj and sen are assigned values by the user. 
  2. This function only applies to objects to which sensitivity property apply. Please refer to the section on "Properties of Objects" in Chapter 3. 
  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
  1. objs and sens are assigned values by the user. 
  2. objs must be a null terminated array. 
  3. objs and sens must point to valid arrays of their respective types. 
  4. This function only applies to objects to which sensitivity property apply. Please refer to the section on "Properties of Objects" in Chapter 3. 
  5. 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
  1. objs and sen are assigned values by the user. 
  2. objs must be a null terminated array. 
  3. This function only applies to objects to which sensitivity property apply. Please refer to the section on "Properties of Objects" in Chapter 3. 
  4. 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
  1. 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
  1. interval, func, and data are assigned values by the user while the routine assigns value to timerid. 
  2. After the time interval specified in interval, the function func is called. 
  3. If (unsigned long) 0 is passed for interval, then this function call is practically ignored. 
  4. 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. 
  5. func is the address of the function called when the alarm happens. It should be declared as follows: 
    6. 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
  1. timerid is assigned value by empgui_c_timer_add. 
  2. 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
  1. togglebobj is assigned value by the user while the routine assigns value to val. 
  2. Boolean value true corresponds to ON state of the toggle button while boolean value false corresponds to OFF state of the toggle button. 
  3. 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
  1. togglebobj and val are assigned values by the user. 
  2. Boolean value true corresponds to ON state of the toggle button and boolean value false corresponds to OFF state of the toggle button. 
  3. 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
  1. userobj is assigned value by the user while the routine assigns value to widget. 
  2. 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
  1. winobj is assigned value by the user. 
  2. 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
  1. winobj is assigned value by the user. 
  2. It is not an error to call this function to show a window that is already shown.