Programmer Guide/Macro Library/CDlgMap

CDlgMap : CObj

A class to help map dialog control indices to meaningful keywords. If you use lots of controls in your dialogs, then associating them to keywords makes programming and maintenance a lot easier.

Constructor

Create a new dialog map instance for the dialog-item dlg. Note that this is the same as CObj NEW CDlgMap dlg.

Usage:

CDlgMap dlg|* [ type icon title ]

Parameters:

dlg

The id of a dialog item or an asterisk if the dialog should be created on construction. If the dialog map creates it's own dialog, it also destroys it on destruction.

See the macro CREATEMENU for details of the other parameters.

Result:

Always returns 0.

Examples:

#map := CDlgMap $#dlg

CDlgMap Member Variables

The CDlgMap class has the following member variables:

&dlg

The dialog this class is mapping control ids to names.

&map

The extended table mapping indices to names.

&ciBase

The control index base. Mapping starts from this value.

Member Functions

The CDlgMap class has the following member functions. See CObj Member Functions for a list of functions implemented in the parent class.

BEGIN

Displays the dialog as a modal dialog.

Usage:

mapinst BEGIN [ focuscontrol ; windowpos ]

Parameters:

focusControl

The control name assigned to the control which should receive keyboard focus.

windowPos

The position to display the dialog window. See DoModalDialog Begin for a description of this parameter.

Notes:

This function uses the macro DoModalDialog.

CI

Get the control index mapped to the string controlName. If the name does not exist in the mapping table, then the next free index is mapped to the string controlName and the index is returned. The first index returned by CI is the same as the number of dialog controls (0 for a new dialog).

Usage:

dlgmap CI controlName

Parameters:

controlName

The name to map to the control or an empty string to use the control index as the name.

Result:

The control index mapped to the string controlName.

CN

Get the name mapped to the control index cindex.

Usage:

dlgmap CN cindex

Parameters:

cindex

The index of the control.

Result:

The name mapped to the control index cindex or an empty string if the index is not mapped.

DESTROY

Usage:

dlgmap DESTROY

Description:

Delete the dialog map object dlgmap. Note that this is the same as calling COBJ DELETE dlgmap.

DLG

Returns the dialog map's dialog item.

Usage:

mapinst Dlg

Result:

The dialog map's dialog item.

END

End the modal dialog and destroy map. This is the same as mapinst DESTROY. If the dialog item was created in the constructer or a modal dialog loop has been started, the dialog item is also deleted.

Usage:

mapinst END

FCI

Usage:

dlgmap FCI

Result:

The index of the first (lowest) mapped control.

Description:

Get the index of the first mapped control. This is actually the next free dialog index at the time of construction and therefore can be greater than 1 even if there are no mapped controls.

ISCI

Query whether a control with a specified name or index exists.

Usage:

dlgmap ISCI controlName|controlIndex

Parameters:

controlName

The name used to map a control index in a previous ci function call.

controlIndex

An index greater or equal to 0.

Result:

The name of the control (controlName) if the control is defined, or an empty string.

LOOP

Executes the modal dialog message loop (via DoModalDialog Loop).

Usage:

mapinst LOOP okayControl cancelControl

Parameters:

okayControl

Either the index or control name of the dialog control to use as the OK button (when it is pressed, the dialog closes).

cancelControl

Either the index or control name of the dialog control to use as the cancel button (when it is pressed, the dialog closes).

Result:

A message id and parameters :

msgId msgPar

For COMMAND and UPDATE messages, the original msgPar is converted to a control name string if possible (if it has an associated name in the map).

NC

Usage:

dlgmap NC

Result:

The number of controls that have been mapped.

Description:

Get the total number of controls which are mapped.

SETCI

Like the CI member function, this function creates a map between a string and an integer id. The result returned, however, can be used directly as the first part of a SET dialog controlIndex command.

Usage:

dlgmap SETCI controlName

Parameters:

controlName

The name to map to the control or an empty string to use the control index as the name.

Result:

Returns the dialog item and control index mapped to the string controlName:

dialogItem controlIndex

SETHELP

The CDlgMap function SETHELP associates the dialog with a help topic referenced by an IREF. When used in conjunction with the CDlgMap functions BEGIN and END, the F1 key will call the relevant help topic if pressed whilst the associated dialog is being displayed.

Usage:

dlgmap SETHELP iref

Parameters:

iref

The IREF to the relevant help topic. Note that the IREF must be present in the stxconfig.xml file.

Result:

Returns the dialog item and control index mapped to the string controlName:

dialogItem controlIndex

Examples:

$#dmap sethelp 'Toolbox/AutoSeg/ASeg_Short_Clicks_Segmentation'

Examples

[Macro cdlgmap_example]
// create map and dialog
#dmap := cdlgmap * dialog * 'CDlgMap Test'
// create controls
$($#dmap setci ok) button 0 0 '&OK' * 8
$($#dmap setci cancel) button 1 0 '&Cancel' * 8
// display dialog and react to user input
$#dmap begin
do forever
        $($#dmap dlg) /W
        // use the CDlgMap LOOP command, which translates dialog ids
        // into control names
        readstr '$($#dmap loop ok cancel)' #msgId #ctrlName
        $($#dmap dlg) /R        
        if '$#msgId' == 'command' then
                if '$#ctrlName' == 'ok' then
                        // save settings
                        break
                else if '$#ctrlName' == 'cancel' then
                        break
                end
        else if '$#msgId' == 'update' then
                // react to update
        end
end
// destroy dialog and map
$#dmap end
exit 1 int 0