Jw at 10:22, 19 September 2016

2016-09-19T10:22:37Z

← Older revision		Revision as of 12:22, 19 September 2016
Line 1:		Line 1:
	{{DISPLAYTITLE:{{SUBPAGENAME}}}}		{{DISPLAYTITLE:{{SUBPAGENAME}}}}
			{{TOC limit\|3}}
	==ModalDialog : CObj==		==ModalDialog : CObj==

Toni: moved Programmer Guide/Class Library/ModalDialog : CObj to Programmer Guide/Macro Library/ModalDialog

2011-04-28T08:01:50Z

moved Programmer Guide/Class Library/ModalDialog : CObj to Programmer Guide/Macro Library/ModalDialog

← Older revision	Revision as of 10:01, 28 April 2011
(No difference)

Christian: Text replace - "S_TOOLS-STx" to "{{STX}}"

2011-04-05T15:55:43Z

Text replace - "S_TOOLS-STx" to "{{STX}}"

← Older revision		Revision as of 17:55, 5 April 2011
Line 76:		Line 76:
	======Section Dialog Template definition======		======Section Dialog Template definition======

	Since ~~S_TOOLS-STx~~ 3.8, the class <code>ModalDialog</code> can load a dialog template from a section file. The section file has the following format:		Since {{STX}} 3.8, the class <code>ModalDialog</code> can load a dialog template from a section file. The section file has the following format:

	<code>[DialogTemplate SectionName]</code>		<code>[DialogTemplate SectionName]</code>
Line 102:		Line 102:
	'''font'''		'''font'''

	The font follows the standard ~~S_TOOLS-STx~~ font argument format as described in Fonts and Font Arguments.		The font follows the standard {{STX}} font argument format as described in Fonts and Font Arguments.

	===Destruct===		===Destruct===
Line 334:		Line 334:
	;<var>id</var>		;<var>id</var>

	:The id of a <code>TABLE</code> element in the ~~S_TOOLS-STx S_TOOLS-STx~~ INI file at the reference <var>setRef</var>.		:The id of a <code>TABLE</code> element in the {{STX}} {{STX}} INI file at the reference <var>setRef</var>.

	;<var>setRef</var>		;<var>setRef</var>
Line 477:		Line 477:
	;<var>id</var>		;<var>id</var>

	:The id of a <code>TABLE</code> element in the ~~S_TOOLS-STx S_TOOLS-STx~~ INI file at the reference <var>setRef</var>.		:The id of a <code>TABLE</code> element in the {{STX}} {{STX}} INI file at the reference <var>setRef</var>.

	;<var>setRef</var>		;<var>setRef</var>

Admin: 1 revision: Initial import

2010-11-18T16:31:29Z

1 revision: Initial import

← Older revision	Revision as of 18:31, 18 November 2010
(No difference)

193.171.195.8: initial import

2010-05-17T13:05:27Z

initial import

New page

{{DISPLAYTITLE:{{SUBPAGENAME}}}}
==ModalDialog : CObj==

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

====ModalDialog Class Members====

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

===Construct===

Construct a <code>ModalDialog</code> instance.

If <var>dialog</var> 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 <code>DialogTemplate</code> element in the Workspace file and is used to initialize the dialog controls and variables bound to the controls.

=====Usage:=====

<code>COBJ NEW MODALDIALOG <var>dialog</var> ; <var>title</var> ; <var>xmlDialogTemplateName</var> ; <var>iCtrl</var> ; <var>row</var> ; <var>col</var></code>

=====Parameters:=====

;<var>dialog</var>

:The name of a dialog-item or <code>NONE</code> if a new dialog item should be created.

;<var>title</var>

:The dialog window title. This is only used if <var>dialog</var> is <code>NONE</code>, otherwise, the title is generated automatically.

;<var>xmlDialogTemplateName</var>

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

;<var>iCtrl</var>

:The index to use for the first control.

;<var>row</var>

:The row offset for template controls.

;<var>col</var>

:The column offset for template controls.

=====Result:=====

<code>0</code> if initialized and <code>1</code> if initialization fails

=====Usage:=====

<code>COBJ NEW MODALDIALOG <var>dialog</var> ; <var>title</var> ; <var>templateSectionFilePath</var> ; <var>iCtrl</var> ; <var>row</var> ; <var>col</var> ; <var>templateSectionName</var></code>

=====Parameters:=====

;<var>templateSectionFilePath</var>

:The path to the section file containing the dialog template specified in <var>templateSectionName</var>.

;<var>templateSectionName</var>

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

:<code>type ; name ; caption ; row col width height ; flags ; font ; defaultValue ; valueList</code>

:See Section Dialog Template definition for a detailed description.

For all other parameters, see above.

=====Result:=====

<code>0</code> if initialized and <code>1</code> if initialization fails

======Section Dialog Template definition======

Since S_TOOLS-STx 3.8, the class <code>ModalDialog</code> can load a dialog template from a section file. The section file has the following format:

<code>[DialogTemplate SectionName]</code>

<code>type ; name ; caption ; row col width height ; flags ; font ; defaultValue ; valueList</code>

'''type'''

The following types are supported:

<code>static</code>, <code>edit</code>, <code>checkbox</code>, <code>combobox</code>, <code>button</code> and <code>variable</code>.

Button Notes

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

Variable Notes

The type <code>variable</code> creates a variable, and not a control.

'''name'''

The <code>name</code> is used for message parameters (MsgPar) and for variable access.

'''font'''

The font follows the standard S_TOOLS-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:=====

<code><var>inst</var> GetDialog</code>

=====Result:=====

The name of the dialog item used by the instance

===GetMode===

=====Usage:=====

<code><var>inst</var> GetMode</code>

=====Result:=====

<code>0</code> if the dialog window is not created and <code>1</code> if it exists.

===GetMsg===

=====Usage:=====

<code><var>inst</var> GetMsg</code>

=====Result:=====

The last dialog message ('<code>id par</code>')

===GetMsgId===

=====Usage:=====

<code><var>inst</var> GetMsgId</code>

=====Result:=====

The id of the last dialog message.

===GetMsgPar===

Get the parameter for the last dialog message.

=====Usage:=====

<code><var>inst</var> GetMsgPar</code>

=====Result:=====

The parameter (par) of the last dialog message.

=====Examples:=====

See ModalDialog::Loop for an example.

===GetVarCount===

=====Usage:=====

<code><var>inst</var> GetVarCount</code>

=====Result:=====

The number of variables bound to the template controls.

===GetVarName===

=====Usage:=====

<code><var>inst</var> GetVarName <var>index</var></code>

=====Parameters:=====

;<var>index</var>

: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:=====

<code><var>inst</var> GetVarValue <var>index</var>|<var>name</var></code>

=====Parameters:=====

;<var>index</var>

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

;<var>name</var>

: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 <code>GetVarValue</code> has an additional <var>cmd</var> parameter, allowing you to retrieve the value, index or list of values.

=====Usage:=====

<code><var>inst</var> GetVarValue <var>comboBoxName</var> [ <var>cmd</var> ]</code>

=====Parameters:=====

;<var>comboBoxName</var>

:The name of a combobox as defined in the template.

;<var>cmd</var>

:One of the following keywords:

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

:<code>INDEX</code> - returns the zero-based index of the currently selected item.

:<code>LIST</code> - returns the list of available values.

:If no <var>cmd</var> is specified, the current value is returned.

=====Result:=====

Depending on <var>cmd</var>, 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 <code>GetWindowPos</code>.

=====Usage:=====

<code><var>inst</var> GetWindowPos</code>

=====Result:=====

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

<code>x y w h</code>

===LoadVars===

Loads variable values from external sources.

=====Description:=====

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

Usage:

<code><var>inst</var> LoadVars INSTANCE ; <var>instItem ; varPrefix</var></code>

=====Parameters:=====

;<var>instItem</var>

:The id of the instance.

;<var>varPrefix</var>

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

<code>controlName = controlValue</code>

=====Usage:=====

<code><var>inst</var> LoadVars TABLE ; <var>table</var></code>

=====Parameters:=====

;<var>table</var>

:The name of a shell table item containing the <code>name=value</code> 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:=====

<code><var>inst</var> LoadVars STRING ; <var>string</var></code>

=====Parameters:=====

;<var>string</var>

: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:=====

<code><var>inst</var> LoadVars WORKSPACE ; <var>id</var> ; <var>setRef</var></code>

=====Parameters:=====

;<var>id</var>

:The id of a <code>TABLE</code> element in the S_TOOLS-STx S_TOOLS-STx INI file at the reference <var>setRef</var>.

;<var>setRef</var>

:An IRef to the position at which the TABLE element <var>id</var> 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 <code>SHOW</code> is called to create the window and save okay/cancel index. The <code>Loop</code> function converts the control indices into control names on <code>COMMAND</code> and <code>UPDATE</code> messages where possible. This means that a call to <code>GetMsgPar</code> will return the control name of the control which generated the message.

=====Usage:=====

<code><var>inst</var> Loop [ <var>okay</var> <var>cancel</var> ] [ ; <var>windowPosition</var> ]</code>

=====Parameters:=====

;<var>okay</var>

:The index of the okay control (button).

;<var>cancel</var>

:The index of the cancel control (button).

;<var>windowPosition</var>

:The position at which to show the dialog. The parameter <var>windowPosition</var> is passed to the function <code>SetWindowPos</code>. See SetWindowPos for details.

:

=====Result:=====

The message id (<code>OKAY</code>, <code>CANCEL</code>, <code>COMMAND</code>, <code>UPDATE</code>, <code>POPUP</code> or <code>KEY</code>).

=====Examples:=====

<pre>
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
</pre>
===ResetVars===

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

=====Usage:=====

<code><var>inst</var> ResetVars</code>

=====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:

<code><var>inst</var> SaveVars INSTANCE ; <var>instItem ; varPrefix</var></code>

=====Parameters:=====

;<var>instItem</var>

:The id of the instance.

;<var>varPrefix</var>

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

=====Result:=====

none

=====Description:=====

Save variable values to the table <var>table</var>. One entry per variable in the following format:

<code>controlName = controlValue</code>

=====Usage:=====

<code><var>inst</var> SaveVars TABLE ; <var>table</var></code>

=====Parameters:=====

;<var>table</var>

:The name of a shell table item where <code>name=value</code> 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:=====

<code><var>inst</var> SaveVars STRING</code>

=====Parameters:=====

;<var>string</var>

: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:=====

<code><var>inst</var> SaveVars WORKSPACE ; <var>id</var> ; <var>setRef</var></code>

=====Parameters:=====

;<var>id</var>

:The id of a <code>TABLE</code> element in the S_TOOLS-STx S_TOOLS-STx INI file at the reference <var>setRef</var>.

;<var>setRef</var>

:An IRef to the position at which the TABLE element <var>id</var> should be saved.

=====Result:=====

none

===SetVarMode===

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

=====Usage:=====

<code><var>inst</var> SetVarMode <var>name</var>=<var>mode</var> [...]</code>

=====Parameters:=====

;<var>name</var>

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

;<var>mode</var>

:The mode. The following values are supported:

:<code>HIDDEN</code>|<code>VISIBLE</code>|<code>ENABLED</code>

=====Result:=====

none

===SetVarTitle===

Set a control's text.

=====Usage:=====

<code><var>inst</var> SetVarTitle <var>name title</var></code>

=====Parameters:=====

;<var>name</var>

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

;<var>title</var>

:The text to set the control's text to.

=====Result:=====

none

===SetVarValue===

Assign the value to the specified variable.

=====Usage:=====

<code><var>inst</var> SetVarValue <var>index</var>|<var>name</var> [<var>value</var>]</code>

=====Parameters:=====

;<var>index</var>

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

;<var>name</var>

:The template variable name.

;<var>value</var>

:The value to be assigned to the variable.

=====Result:=====

none

===SetWindowPos===

Set the position and size of the dialog. This function uses the macro <code>SetWindowPos</code>.

=====Usage:=====

<code><var>inst</var> SetWindowPos <var>x y w h</var> [ ; <var>m</var> ]</code>

=====Parameters:=====

;<var>x,y</var>

:The upper left corner position of the dialog in pixels (relative to the monitor <var>m</var>).

;<var>w,h</var>

:The width and height of the dialog in pixels.

;<var>m</var>

:The monitor to position the dialog on (1-nMonitors). See the macro <code>GetMonitor</code> 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:=====

<code><var>inst</var> Show [ <var>okay</var> <var>cancel</var> ] [ ; <var>windowPosition</var> ]</code>

=====Parameters:=====

;<var>okay</var>

:The index of the okay control (button).

;<var>cancel</var>

:The index of the cancel control (button).

;<var>windowPosition</var>

:The position at which to show the dialog. The parameter <var>windowPosition</var> is passed to the function <code>SetWindowPos</code>. See SetWindowPos for details.

=====Result:=====

none

Programmer Guide/Macro Library/ModalDialog - Revision history

Jw at 10:22, 19 September 2016

Toni: moved Programmer Guide/Class Library/ModalDialog : CObj to Programmer Guide/Macro Library/ModalDialog

Christian: Text replace - "S_TOOLS-STx" to "{{STX}}"

Admin: 1 revision: Initial import

193.171.195.8: initial import