ModalDialog

ModalDialog : CObj

A class for creating modal dialog boxes from templates, or adding templates to existing dialog boxes.

ModalDialog Class Members

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

Construct

Construct a ModalDialog instance.

If dialog is a dialog item, the instance is attached to this dialog, otherwise a new dialog item is created. The template, if specified, must be a DialogTemplate element in the Workspace file and is used to initialize the dialog controls and variables bound to the controls.

Usage:

COBJ NEW MODALDIALOG dialog ; title ; xmlDialogTemplateName ; iCtrl ; row ; col

Parameters:

dialog

The name of a dialog-item or NONE if a new dialog item should be created.

title

The dialog window title. This is only used if dialog is NONE, otherwise, the title is generated automatically.

xmlDialogTemplateName

The name of the dialog template to use. This template must exist in the /CurrentSetup/Global/DialogTemplates path in the Workspace file. The template is used to initialize the dialog controls and variables bound to the controls.

iCtrl

The index to use for the first control.

row

The row offset for template controls.

col

The column offset for template controls.

Result:

0 if initialized and 1 if initialization fails

Usage:

COBJ NEW MODALDIALOG dialog ; title ; templateSectionFilePath ; iCtrl ; row ; col ; templateSectionName

Parameters:

templateSectionFilePath

The path to the section file containing the dialog template specified in templateSectionName.

templateSectionName

The section name of the section containing the dialog template. The section defines one control per line in the following format:

type ; name ; caption ; row col width height ; flags ; font ; defaultValue ; valueList

See Section Dialog Template definition for a detailed description.

For all other parameters, see above.

Result:

0 if initialized and 1 if initialization fails

Section Dialog Template definition

Since STx 3.8, the class ModalDialog can load a dialog template from a section file. The section file has the following format:

[DialogTemplate SectionName]

type ; name ; caption ; row col width height ; flags ; font ; defaultValue ; valueList

type

The following types are supported:

static, edit, checkbox, combobox, button and variable.

Button Notes

If a control of type button is pressed, a message is sent with the name of the button stored in MsgPar. If no caption is specified, the name of the button is used for the caption.

Variable Notes

The type variable creates a variable, and not a control.

name

The name is used for message parameters (MsgPar) and for variable access.

font

The font follows the standard STx font argument format as described in Fonts and Font Arguments.

Destruct

If a new dialog item was created on instantiation, it is destroyed.

GetDialog

Return the name of the dialog item.

Usage:

inst GetDialog

Result:

The name of the dialog item used by the instance

GetMode

Usage:

inst GetMode

Result:

0 if the dialog window is not created and 1 if it exists.

GetMsg

Usage:

inst GetMsg

Result:

The last dialog message ('id par')

GetMsgId

Usage:

inst GetMsgId

Result:

The id of the last dialog message.

GetMsgPar

Get the parameter for the last dialog message.

Usage:

inst GetMsgPar

Result:

The parameter (par) of the last dialog message.

Examples:

See ModalDialog::Loop for an example.

GetVarCount

Usage:

inst GetVarCount

Result:

The number of variables bound to the template controls.

GetVarName

Usage:

inst GetVarName index

Parameters:

index

The template variable index (0 .. varcount-1).

Result:

The name of the template variable or an empty string if the index is invalid.

GetVarValue

Get the value of a control. Note that the combobox has its own special usage (see below).

Usage:

inst GetVarValue index|name

Parameters:

index

The template variable index (0 .. varcount-1).

name

The template variable name.

Result:

The value of the template variable or an empty string if the variable index or name is invalid.

Description:

The combobox GetVarValue has an additional cmd parameter, allowing you to retrieve the value, index or list of values.

Usage:

inst GetVarValue comboBoxName [ cmd ]

Parameters:

comboBoxName

The name of a combobox as defined in the template.

cmd

One of the following keywords:

VALUE - returns the value of the currently selected item (i.e. $#list[$#index]).

INDEX - returns the zero-based index of the currently selected item.

LIST - returns the list of available values.

If no cmd is specified, the current value is returned.

Result:

Depending on cmd, the selected value, index or space separated list of all values.

GetWindowPos

Retrieve the position and size of the dialog window. This function uses the macro GetWindowPos.

Usage:

inst GetWindowPos

Result:

The position and size of the dialog window in the following format:

x y w h

LoadVars

Loads variable values from external sources.

Description:

Load variable values from an instance. Member variables with the names <varPrefix><controlName> must exist

Usage:

inst LoadVars INSTANCE ; instItem ; varPrefix

Parameters:

instItem

The id of the instance.

varPrefix

The prefix to prefix control names with when reading instance variable contents.

Result:

none

Description:

Load variable values from a table. Each table entry must use the format:

controlName = controlValue

Usage:

inst LoadVars TABLE ; table

Parameters:

table

The name of a shell table item containing the name=value entries.

Result:

none

Description:

Load variable values from a string. The values in the string must be separated by semi-colons and must be in the same order as the controls in the dialog.

Usage:

inst LoadVars STRING ; string

Parameters:

string

A semi-colon separated list of values. Values are assigned in the same order as the controls were defined in the dialog template .

Result:

none

Description:

Load variable values from the workspace.

Usage:

inst LoadVars WORKSPACE ; id ; setRef

Parameters:

id

The id of a TABLE element in the STx STx INI file at the reference setRef.

setRef

An IRef to the position at which the TABLE element id can be found.

Result:

none

Loop

Enters the modal message loop and returns if a dialog message is received. If the dialog is not visible, the function SHOW is called to create the window and save okay/cancel index. The Loop function converts the control indices into control names on COMMAND and UPDATE messages where possible. This means that a call to GetMsgPar will return the control name of the control which generated the message.

Usage:

inst Loop [ okay cancel ] [ ; windowPosition ]

Parameters:

okay

The index of the okay control (button).

cancel

The index of the cancel control (button).

windowPosition

The position at which to show the dialog. The parameter windowPosition is passed to the function SetWindowPos. See SetWindowPos for details.

Result:

The message id (OKAY, CANCEL, COMMAND, UPDATE, POPUP or KEY).

Examples:

forever
    #msg := $#mdlg loop ok cancel
    #par := $#mdlg GetMsgPar
    if '$#msg' == 'command' then
        if '$#par' == 'cancel' then
            // user pressed Cancel
            break
        else if '$#par' == 'ok' then
            // user pressed Ok
            break
        end
    end
end

ResetVars

Reset all variables to the default values set in the template.

Usage:

inst ResetVars

Result:

none

SaveVars

Saves variable values from external sources.

Description:

Save variable values to instance member variables. Values are saved in member variables with the names <varPrefix><controlName>.

Usage:

inst SaveVars INSTANCE ; instItem ; varPrefix

Parameters:

instItem

The id of the instance.

varPrefix

The prefix to prefix control names with when saving their values to instance variables.

Result:

none

Description:

Save variable values to the table table. One entry per variable in the following format:

controlName = controlValue

Usage:

inst SaveVars TABLE ; table

Parameters:

table

The name of a shell table item where name=value entries should be saved.

Result:

none

Description:

Save variable values from a string. The values in the string must be separated by semi-colons and must be in the same order as the controls in the dialog.

Usage:

inst SaveVars STRING

Parameters:

string

A semi-colon separated list of values. Values are assigned in the same order as the controls were defined in the dialog template.

Result:

A semi-colon separated list of control values.

Description:

Save variable values in the workspace.

Usage:

inst SaveVars WORKSPACE ; id ; setRef

Parameters:

id

The id of a TABLE element in the STx STx INI file at the reference setRef.

setRef

An IRef to the position at which the TABLE element id should be saved.

Result:

none

SetVarMode

Set a control's visibility and state (i.e. its mode).

Usage:

inst SetVarMode name=mode [...]

Parameters:

name

The name of an existing control (as specified in the dialog template).

mode

The mode. The following values are supported:

HIDDEN|VISIBLE|ENABLED

Result:

none

SetVarTitle

Set a control's text.

Usage:

inst SetVarTitle name title

Parameters:

name

The name of the control as defined in the dialog template.

title

The text to set the control's text to.

Result:

none

SetVarValue

Assign the value to the specified variable.

Usage:

inst SetVarValue index|name [value]

Parameters:

index

The template variable index (0 .. varcount-1).

name

The template variable name.

value

The value to be assigned to the variable.

Result:

none

SetWindowPos

Set the position and size of the dialog. This function uses the macro SetWindowPos.

Usage:

inst SetWindowPos x y w h [ ; m ]

Parameters:

x,y

The upper left corner position of the dialog in pixels (relative to the monitor m).

w,h

The width and height of the dialog in pixels.

m

The monitor to position the dialog on (1-nMonitors). See the macro GetMonitor for details.

Result:

none

Show

Shows the dialog window. The arguments okay and cancel are stored and used as the okay and cancel button id's in the message loop.

Usage:

inst Show [ okay cancel ] [ ; windowPosition ]

Parameters:

okay

The index of the okay control (button).

cancel

The index of the cancel control (button).

windowPosition

The position at which to show the dialog. The parameter windowPosition is passed to the function SetWindowPos. See SetWindowPos for details.

Result:

none