Layered API Functions

This appendix contains an abbreviated list of Layered API functions. The information in this appendix is provide to help in the creation of option dialogs boxes. The functions discussed are those used to create the default options dialog box and those used to generate the Dracula options dialog box.
This appendix also contains a listing of the dialog elements that have been used in the default options dialog and the Dracula options dialog.

Layered API Functions

The following lists the layered API functions and definitions.

api_dlg_add_callback

This function adds a callback to the dialog object. The function does not return a value.

Syntax

api_add_callback( itemH ,  functionName  ,  callbackType  ,  callbackData  );

Where
itemH is the handle to the dialog object
functionName is a string designating the name of the callback function
callbackType is an enumerated integer that designates the action that will cause the callback to be executed
callbackData is a pointer to the AEL data that will be passed as the second argument to the callback function

Example

api_dlg_add_callback(pbClose, "close_cb", API_ACTIVATE_CALLBACK, dlgH);

api_dlg_create_dialog

This function creates a custom dialog box according to the specified arguments. The function returns the handle to the dialog.

Syntax

api_dlg_create_dialog( dlgName  ,  winInst , [  resource  ,  value , ...], [ itemH , ...]);

Where
dlgName is a string name that designates the unique name of the dialog
winInst is the window instance that the dialog is associated to
resource, value These are integer values that designate properties for the dialog box. These allow you to set the dialog caption, the modality, etc. The format specifies the resource type and the value to use for that resource type. You can specify as many resources as you need.
itemH is a handle to a dialog object that will be displayed as a child object in the dialog window. You can specify as many child object as needed. Child objects are created using the command api_dlg_create_item .

api_dlg_create_item

This function creates a new dialog object. The function returns the handle to the child object.

Syntax

api_dlg_create_item( name  ,  type , [ resource  ,  value , ...], [ itemH , ...]);

Where
name is the name of the dialog object. This should be a unique name, so that the handle to the object can be retrieved using the command api_dlg_find_item .
type is an enumerated integer that specifies the type of dialog object will be created.
resource,value is a set of integers and values that specify properties for the dialog object. Each dialog object type has a different set of resources that can be set for it.
itemH is a set of optional dialog objects to place as children in the dialog object, if the dialog object supports having children. For instance, API_TABLE_GROUP can have dialog object arguments because it supports having children.

Example

pbOkay=api_dlg_create_item("pbOkay", API_PUSH_BUTTON_ITEM,
API_RN_CAPTION, "OK");

api_dlg_find_item

This function retrieves the dialog box object with a specified name from its parent. The function returns the handle of the dialog object if it is found, otherwise it returns NULL.

Syntax

api_dlg_find_item( parentH  ,  name  );

Where
parentH is the handle to the parent dialog object
name is the name of the dialog object to find

Example

decl pbOkay=api_dlg_find_item(dlgH, "pbOkay");

api_dlg_get_resources

This function gets the value of a specified dialog object resource. The function does not return a value.

Syntax

api_dlg_get_resources(itemH, resource, &var);

Where
itemH is the dialog object handle from which to retrieve data
resource is an enumerated integer value that designates the resource value to retrieve
&var is the address of a variable that has its value assigned to the resource value

Examples

decl val1;

api_dlg_get_resources(checkH, API_RN_TOGGLE_STATE, &val1);

fputs(stderr, identify_value(val1)); Outputs 1 to the terminal window

api_dlg_get_resources(editH, API_RN_VALUE, &val1);

fputs(stderr, identify_value(val1)); Outputs "R" to the terminal window

api_dlg_set_resources

This function sets the value of a specified dialog object resource. The function does not return a value.

Syntax

api_dlg_set_resources(itemH, resource, value);

Where
itemH is the dialog object handle from which to retrieve data
resource is an enumerated integer value that designates the resource value to retrieve
value is the value to assign to the specified resource of the object

Examples

api_dlg_set_resources(checkH, API_RN_TOGGLE_STATE, TRUE);

api_dlg_set_resources(editH, API_RN_VALUE, "L");

Layered API Dialog Elements

The following descriptions are the enumerated item types that can be specified in the api_dlg_create_item function to create a new dialog object. Each description includes the callbacks that can be assigned to the dialog object and the resources that are available for the dialog box object.

API_CHECK_BUTTON_ITEM

This is a toggle button item. Each time the user clicks on the object, it will toggle between on or off .

Callbacks

Called when the user toggles the button:

API_VALUE_CHANGED_CALLBACK

Resources

API_DROPDOWNLIST_COMBO_ITEM

This dialog box object consists of a single text field which has a pop-up list of available elements that can be chosen as the value. The text field displays the currently selected value.

Callbacks

Called when an item is selected by clicking on it in the pop-up dialog box area:

API_LIST_SELECTION_CALLBACK

Called when an item is double clicked in the pop-up dialog box area:

API_LIST_DBLCLK_CALLBACK

Resources

API_EDIT_TEXT_ITEM

This is a text window for text editing. A caption is displayed above the text editing area. You can set up the text window to be a single or multi lined editing area.

Callbacks

Called when the edit text item gets the focus:

API_FOCUS_CALLBACK

Called when the edit text item loses the focus:

API_LOSING_FOCUS_CALLBACK

Called when the text of the edit text item is changed:

API_VALUE_CHANGED_CALLBACK

Called when the RETURN key is pressed if the edit text item is a single line edit text item:

API_ACTIVATE_CALLBACK

Arguments

API_LABEL_ITEM

A text label or a bitmap image.

Callbacks

None

Resources

API_LIST_ITEM

A scrollable list of strings.

Callbacks

Called when the user makes a selection change in the list:

API_LIST_SELECTION_CALLBACK

Called when user double clicks on an item on the list:

API_LIST_DBLCLK_CALLBACK

Called when user scrolls the list so that a new item becomes the first index being shown:

API_LIST_TOP_INDEX_CHANGED_CALLBACK

Resources

API_PUSH_BUTTON_ITEM

This button can use a text label or a bitmap image. The item is activated when the user left clicks it.

Callbacks

Called when the button item is activated with the mouse:

API_ACTIVATE_CALLBACK

Called when the left mouse button is down, and the cursor is over the button:

API_LEFT_BUTTON_DOWN_CALLBACK

Called when the left mouse button is released, and the cursor is over the button:

API_LEFT_BUTTON_UP_CALLBACK

Resources

API_TABLE_GROUP

The table item is used to design dialog boxes. The table item is a container that controls the size and location of the dialog box objects. The item uses an array model to simplify the arrangement of child objects. The table item also controls formatting for dialog boxes.

Items inside the table are placed at row and column locations in a variable size array. Items may span more than one row or column. The array can expand or contract in size as needed. There are options to control justification and place size restrictions on rows and columns of items.

The table can contain any number and type of children, including other table items.

Callbacks

None

Resources

All child items in the table container will have the following additional resources:

Layered API Table

You can or the following enumerations produce justifications and size adjustments for tables and child objects of tables:

• API_RV_TBL_LEFT
  Horizontally left justified
• API_RV_TBL_RIGHT
  Horizontally right justified
• API_RV_TBL_TOP
  Vertically top justified
• API_RV_TBL_BOTTOM
  Vertically bottom justified
• API_RV_TBL_LK_WIDTH
  Do not expand the item horizontally
• API_RV_TBL_LK_HEIGHT
  Do not expand the item vertically
• API_RV_TBL_SM_HEIGHT
  Force the column to be the minimum height
• API_RV_TBL_SM_WIDTH
  Force the column to be the minimum width
• API_RV_FIX_WIDTH
  Equivalent to setting: API_RV_TBL_LK_WIDTH|API_RV_TBL_SM_WIDTH
• API_RV_FIX_HEIGHT
  Equivalent to setting: API_RV_TBL_LK_HEIGHT|API_RV_TBL_SM_HEIGHT
• API_RV_FIX_SIZE
  Equivalent to setting: API_RV_FIX_WIDTH|API_RV_FIX_HEIGHT