.. highlightlang:: us

.. index:: DialogBox

.. _dialogbox:

DialogBox
=========

.. us.tag  DialogBox ENGLISH DialogBoxes Changed360 Changed420 Changed422 Changed425 Changed540 Changed560 Changed5100

:ref:`DialogBox` creates a dialog box with static text, edit fields, list boxes,
combo boxes, check boxes, a report list (list with multiple columns), a 
property list box, a group box, tree control and buttons.The dialog box can be
configured to be resizeable (see Dialog control ``|F @ xxx_callback|``). 

.. function::  svReturn = DialogBox(svTemplate)
    svReturn = DialogBox(svTemplate, svInitString)
    svReturn = DialogBox(svTemplate, svInitString, ssTitle)
    svReturn = DialogBox(svTemplate, svInitString, ssTitle, ssHelpItem)
    svReturn = DialogBox(svTemplate, svInitString, ssTitle, ssHelpItem, obj)
    svReturn = DialogBox(svTemplate, svInitString, ssTitle, ssHelpItem, obj, ssWizard)

.. us.return

**Return Value**

*svReturn* The return value is a string vector containing the user's input, if
the user chooses the :guilabel:`OK` button. If the user selects the
:guilabel:`Cancel` button, the return value is a scalar string with the value
``"DLG_CANCEL"``. In case of an error, the real number -1 is returned.

.. us.params

**Parameters**

.. uparam:: svTemplate

   The *svTemplate* parameter is a string vector. Each element of *svTemplate*
   specifies one row in the dialog box. Each row can have different dialog objects.
   Each object starts with the character ``"|"`` followed by one or two characters
   specifying the type of the dialog element. The size of the element is specified
   by the number of blanks before the ending ``"|"`` sign.
   For multi-line dialog controls, e.g. a list box, the template must contain
   enough lines to ensure the list box is completely inside the dialog box. (see 
   examples at the end of this help text.)
   List of available dialog elements:

.. list-table::
   :header-rows: 1

   * - Value
     - Meaning
   * - ``|    @ccc|``
     - edit field. ``ccc`` is the name of a callback function. The callback
       function is optional. Is is called when the user updates the text (adds
       of removes a character).
   * - ``|x       |``
     - Password field.
   * - ``|nn      |``
     - multi-line edit field. The number nn specifies the number of lines in the
       edit box. The lines in the initialize text are separated by the
       string ``\r\n``.
   * - ``|Bxxx    |``
     - check box. xxx is the check box string.
   * - ``|Bxxx @ccc|``
     - check box. xxx is the check box string. ccc is the name of an UniScript
       function. ``ccc`` is the name of a callback function. The function is
       called when the user checks or unchecks the button.
   * - ``|BR xxx @ccc|``
     - Radio button. ``xxx`` is the button text (do not forget to insert a blank
       behind ``|BR``). ``ccc`` is the name of a callback function. The function
       is called when the user clicks a radio button. The callback function is
       used to  clear all other radio buttons of a radio button group. See
       example 18.
   * - ``|Lnn     |``
     - list box. The number nn specifies the number of lines in the list box.
   * - ``|Lnn @ccc|``
     - list box. The number nn specifies the number of lines in the list box.
       ``ccc`` is the name of a callback function. The function is called when
       the user changes the selection.
   * - ``|Mnn     |``
     - multi-select list box. The number nn specifies the number of lines in the
       list box.
   * - ``|Cnn     |``
     - combo box. The number nn specifies the number of lines in the list box.
   * - ``|Cnn @ccc|``
     - combo box with callback function. ``ccc`` is the name of an UniScript
       function. The function is called when the user changes the selection.
   * - ``|CAnn @ccc|``
     - Auto-completion combo box with optional callback function. ccc is a
       UniScript function name which is invoked when the selection has changed.
       This combo box makes it easy to select an item if the list contains a
       large number of items. To search for an item type the name. The list box
       will display all items that match the text typed. If there is no match you
       cannot leave the combo box. This is indicated by a message beep.
   * - ``|CSnn @ccc|``
     - Symbol combo box to select color, line style, marker style with optional
       callback function. ccc is a UniScript function name which is  invoked when
       the selection has changed. See example 20.
   * - ``|+nnn    |``
     - empty field. This field can be used to format the fields in the dialog
       box. The field enlarges the space to the following field. nnn is a number
       in the range 0 to 255.
   * - ``|-nnn    |``
     - empty field. This field can be used to format the fields in the dialog
       box. The field reduces the space to the following field. nnn is a number
       in the range 0 to 255.
   * - ``|Pxxx@ccc |``
     - push button. xxx is the button text. ccc is the name of an UniScript
       function. The function is called when the user clicks the button. Example:
       ``|P Config...@_MY_ConfigDlg|``
   * - ``|Oxxx    |`` or ``|OSxxx    |``
     - Changes the text of the OK button. xxx is the new text. Example:
       ``|O&Continue|``, If O is followed by an S, the Cancel button is not 
       displayed, for example ``|OS Close |``.
   * - ``|Oxxx@ccc |`` or ``|OSxxx@ccc |``
     - OK button with callback function. xxx is the new button text. ccc is the
       name of an UniScript function. The function is called when the user clicks
       the button. Example: ``|OOK@_MY_CheckParameter|``. If the function returns
       TRUE (1) the dialog box will close. If the function returns FALSE (0) the
       dialog box will not close. The callback function can also return a string
       vector which will then be returned by DialogBox. Example: If the dialog
       box contains a list box and you would like to return all elements of the
       list box, you can create the return string in  this callback function.
   * - ``|S       |``
     - static text field. This text field must be set in the svInitString. It can
       be changed in any dialog callback function.
   * - ``|Sf      |``
     - static text field with a border. This text field must be set in the
       svInitString. It can be changed in any dialog callback function.
   * - ``|Snn     |``
     - static text field. This text field must be set in the ``svInitString``. It
       can be changed in any dialog callback function. The number nn specifies
       the number of lines in the static text field.
   * - ``|Sfnn    |``
     - Static text field with a border with nn lines.
   * - ``|SPnn    |``
     - UniPlot Page: Static control with multiple lines to display a UniPlot
       graphic (IPW page). The number ``nn`` sets the number of lines (height of
       the  control). The page handle is passed to the dialog box in the init
       string. See Example 19
   * - ``|E@ccc   |``
     - Enable. One field in the dialog template can be an Enable field. This
       field can be used to enable/disable any dialog box field. ccc is the name
       of a UniPlot callback function. The function is called for the following
       events: just before the dialog is displayed; every time after a dialog
       callback function is called; every time a check box is clicked. The
       callback function will be called with the current init values (string
       vector). The function returns a real vector with the values 1 (enable) or
       0 (disable) for each dialog element. Buttons (except for the OK, Cancel
       and Help buttons) have to be included.
   * - ``|Dnn     |``
     - A control that combines an edit control with a list box. This allows the
       user to type in an entry or choose one from the list. The number nn
       specifies the number of lines in the list box.
   * - ``|Dnn @ccc|``
     - combo-edit box with callback function. ccc is the name of an UniScript
       function. The function is called when the user changes the selection.
   * - ``|Rnnn,xxx RowTitle1 \t RowTitle... \t @ccc|``
     - Report list box (List with multiple columns) with optional callback
       function. ccc is the name of the optional callback function which will be
       called when the selected row has been changed. The number nn specifies the
       number of lines in the report list box. The optional number xxx specifies
       the control width in dialog box units (number of blanks). If the width is
       not specified it is calculated from the number of characters until the
       closing "|" or the first "@" character. The column titles are separated
       by a tab character (\t).
   * - ``|RBnnn,xxx RowTitle1 \t RowTitle... \t @ccc|``
     - Report list box (list with multiple columns) with a check box for each
       line and an optional callback function. ccc is the name of the optional
       callback function which will be called when the selected row has been
       changed. The number nn specifies the number of lines in the Report list
       box. The column titles are separated by a tab character (\t).
   * - ``|RMBnnn,xxx RowTitle1 \t RowTitle... \t @ccc|``
     - Report list box with multi- selection.
   * - ``|Gnnn    |``
     - Group box. This control displays a rectangle with a caption. The text is
       passed in the init vector. See example 10.
   * - ``|Nnnn    |``
     - Property list box. A two column list box. The left column shows the name
       of a property, the right column the value. (See example 11 and comment.)
   * - ``|F @ccc  |``
     - Dialog box size can be interactively modified.
   * - ``|Ann @ccc|``
     - Tree control. Displays a hierarchical list of items. ``ccc`` has a
       special meaning for tree controls (see \*\*Tree control\*\* further down).

.. uparam:: svInitString

   *svInitString* is a string vector which contains the initializing string for
   each dialog element. The initializing string for a check box is either the string
   ``"1"``, if the check box is checked, or ``"0"``, if the check box is unchecked.
   For list and combo boxes, the strings are separated by a ``|`` (OR) character
   or the character ``\x01`` (see example 2). The string that is selected when 
   the dialog box appears on the monitor has to be added at the end of the 
   initializing string, separated by ``@`` or ``\x02`` (see example 2).
   If ``\x01`` and ``\x02`` is used as the separator, the string must begin
   with the character ``\x01`` see :ref:`CreateListBoxText`.
   For the report list box, the string elements of a row are separated by ``\t``
   character and the rows are separated by a new line character (``\n``).
   The strings for combo boxes and list boxes are limited to 1024 characters.
   No text has to be specified for button controls.

.. uparam:: ssTitle

   *ssTitle* is a scalar string specifying the dialog title.

.. uparam:: ssHelpItem

   *ssHelpItem* is a string of the form ``"helpitem@helpfile"``. Example:
   ``"DialogBox@d:/Program Files/UniPlot/up-en.chm"``

.. uparam:: obj

   The *obj* is optional. *obj* is a UniScript-Object created with :ref:`obj_create`. 
   If the parameter is specified it will be passed to all dialog callback functions 
   as the last parameter.

.. uparam:: ssWizard

   The parameter *ssWizard* is optional. The parameter can be used to add a 
   second OK button to a dialog box. The parameter sets the button text and
   the name of a callback function. The callback function will be invoked when
   the user presses the button. The button text and callback function name is
   separated by an @-character for example ``<Back@_MyDialog_back``. If the 
   parameter is invalid, the button is not displayed. The callback function has
   the same parameter as the callback function for the OK button.
   In Example 17 a wizard with 3 dialog boxes is shown.

.. us.comment

**Comment**

The callback function has one input parameter and should return one parameter.
The input parameter is a string vector with the current dialog box settings. The
callback function can change this parameter. The return parameter is a string
vector which is used to reinitialize the dialog. The input parameter and the
return vector has the same setup as the parameter *svInitString*.

For report, property, combination, or list fields, you can also return the value 
"DLG_IGNORE" for an element in *svInitString*. The corresponding control will
not initialized. Especially for lists with a large number of elements 
(greater than 1000), the initialization may take a little longer. 

The name of the callback function must be unique. To check if a name is unique,
use the function what(). Example: Open the command window and type 
``what("_MY_GetFile")``. If the function returns 0.000 the name
``_MY_GetFile`` is not in use.

Edit field
...........

If the edit field is modified by a callback function, text can be inserted
at the cursor position. In this case the text must start with ``\x01`` followed
by the text, followed by ``\x01`` followed by the insert text (replace text). 
Example: Insert  the text `` + `` at the cursor position::

   svInit[2] = "\x01" + svInit[2] + "\x01" + " + ";

If the replace text is empty the cursor is moved to the end of the line.

Property list box
.................

A property list box has two columns. The left column displays the name of a
property and the right column the value. The value can be edited by a combo list
box (ComboBox), a button (Button) an edit field (Edit) or an auto-complete
combo box (AutoCombo).

The keyboard keys :kbd:`TAB` and :kbd:`Shift-TAB` can be used to move to the next
property.

The example below shows the init string. The elements of one property are
separated by a TAB character ``\t``, the rows by a newline character ``\n``.
The maximum number of elements per line is 5:

.. list-table::
   :header-rows: 1

   * - Value
     - Meaning
   * - Column 1
     - Name
   * - Column 2
     - Value
   * - Column 3
     - Type: "Edit", "Combo", "Button", AutoCombo or an empty String "" for a static field. For edit fields the maximum string length can be specified, e.g. E20 means that the number of characters is limited to 20.
   * - Column 4
     - Callback function name. The callback function is called before the combo box or auto-complete combo box is displayed. This callback function should return a string where the elements are separated by a | character. This string is used to initialize the combo box.
   * - Column 5
     - Extra-Text. This text is passed to the callback function.

Auto-completion combo box: This combo box makes it easy to select an item
if the list contains a large number of items. To search for an item type
the name. The list box will display all items that match the text typed. If there
is no match you cannot leave the combo box. This is indicated by a message beep.

::

   ssInit = "Template Name\tKF.IPW\tButton\t__PL1_GetFileName\tc:/test/kf.ipw\n" + ..
   "x-Channel\tN\tCombo\t__PL1_ChannelNames\n" + ..
   "y-Channel\tMom\tCombo\t__PL1_ChannelNames\n" + ..
   "Title\tOtto2\tEdit\n" + ..
   "Operator\tP. Miller"

The callback function for a combo box returns the values displayed in the list box.
Example for a Yes/No selection callback function:

::

   def __YesNo_Combo(svProp)
   {
       return "Yes|No@" + svProp[2];
   }

The parameter *svProp* is a string vector with three elements. The first
element is the name of the property, the second element is the value and the
third parameter is Extra-Text.

The function returns a string vector with two elements. The first element is the
init string for the combo box (elements separated by a ``"|"`` character. The
selected string at the end is separated by a ``"@"`` character), the second
element is the Extra-Text.

Example: Button callback function. This example displays a file open dialog box:

::

   def __PL1_GetFileName(svProp)
   {
       ssFileName = GetOpenFileName(svProp[3]);
       if (ssFileName == "") {
           return 0;
       }
       return [sum(SplitPath(ssFileName)[3,4]), ssFileName];
   }

The parameter **svProp** is a string vector with three elements. The
first element is the name of the property, the second element is the
value and the third parameter is Extra-Text.

In this example the complete file name is saved in the Extra-Text element.
The second element contains the file name and the extension.

The function returns a string vector with two elements. The
first element is a string with the file name and the extension. This
element is displayed in list box in the right column. The second
element holds the complete file name.

Callback functions are not supported for edit fields in this version.

When the OK-button is pressed the :ref:`DialogBox` box returns a string vector with
one element for each control. For the property listbox control the elements are
separated by a TAB ``\t`` character, the rows are separated by a newline
``\n`` character. The :ref:`strtok` function can be used to split the string into
tokens.

Tree Control
............

A tree control is created by the template string "``|Ann@ccc|``". ``nn`` is the
number of rows and ``ccc`` the beginning of the callback function name. The name
is extended by a suffix. This makes it possible to specify 5 different callback
functions for the tree control. Example: ``_MyDialog_`` is extended to
``_MyDialog_GetImageList()``.

When the user closes the dialog box by pressing the OK button the control returns
a string with the path and IDs. The paths and IDs are separated by ``\x02``. The
path elements and IDs are separated by ``\x01``. To split the string the
:ref:`strtok` function can be used.

cccGetImageList()

The function returns a string vector with the complete path names of bitmaps.
Example::

   def _MyDialog_GetImageList()
   {
       return GetRootDirectory() + "bitmaps/" + ["folder.bmp", "file.bmp", "file2.bmp"];
   }

The bitmap size is 16 by 16 pixels. If UniPlot cannot find a bitmap an event is
printed into the event viewer.

**cccSelChanged(svInit, svText, nItemID)**

The function is called when the selection has changed. The parameter
*svText* is a string vector. The parameter contains a string for each
control in the dialog box. *svText* contains the path of the selected
tree item. *nItemID* is the ID of the selected item. The ID
is set in the ``cccExpand`` callback function.

**cccDblClicked(svInit, svText, nItemID)**

The function is called when the user double-clicks an element in the
tree control. The function parameters are identical to ``cccSelChanged``.

**cccRClicked(svInit, svText, nItemID)**

The function is called when the user right clicks an element in the
tree control. The function parameters are identical to ``cccSelChanged``.

**cccExpand(svText, rvItemID)**

The function is called when the user expands a tree node or when the dialog box
is initialized. The function is called for each branch only once.

``cccExpand`` must return a string matrix with four columns. For each element
in the branch the matrix contains one row:

.. list-table::
   :header-rows: 1

   * - Value
     - Description
   * - Column1
     - The first column contains the display text for the item
   * - Column2
     - Unique ID as a string (optional).
   * - Column3
     - Specifies if the item has children. "1" the item has children, "0" the item has no children.
   * - Column4
     - Specifies the bitmap. Is the index of the bitmap as a string. The index starts with "1". The bitmap list is specified using the cccGetImageList() function.

Init:

The init string can be an empty string. If you would like to open a branch, the
``RESET`` and ``SELECT`` keywords can be added to the init path. The path and
the keywords a separated by ``\x03``.

``Reset`` empties all loaded branches. ``SELECT`` selects the specified path.

Example::

   svInit[iTree] = "Root\x01Test";
   svInit[iTree] = svInit[iTree] + "\x03RESET\x03SELECT";

You can find a complete example at the bottom of this section.

Report control with edit fields
...............................

Fields in a report control can be edited if the template string contains a third
callback function. The field has the following syntax::

   "|Rnnn,xxx RowTitle1 \t RowTitle... \t @@@ccc|"

::

   "|RMnnn,xxx RowTitle1 \t RowTitle... \t @@@ccc|"

The report type ``"|RB  ...|"`` cannot be used.

The three ``"@"``-characters are important. After the second ``"@"``-character a
sort callback function can be specified. The sort callback function is invoked
when the user clicks one of the buttons in the header of the report control. The
records will be sorted in ascending or descending order, see
:ref:`ReportControl_Sort`. 

``ccc`` is the beginning of the callback function name to specify the three 
different callback functions.

Example::

   "|R8 Name\tValue                      @@ReportControl_Sort@ __test_props_ |"

The following cell types can be used:

.. list-table::
   :header-rows: 1

   * - Type
     - Description
   * - "Edit"
     - Edit control to enter text.
   * - "StaticText"
     - Read Only edit control. Text can be copied to clipboard.
   * - "Text"
     - Text that cannot be edited.
   * - "GreyText"
     - Text on grey background. Cannot be edited.
   * - "Combo"
     - Combo box control
   * - "AutoCombo"
     - Combo box control with auto completion
   * - "Marker"
     - Combo box control to select marker styles,  line styles, colors etc.
   * - "Checkbox"
     - Check box control
   * - "ShowButton"
     - Text on a button, cannot be pressed.
   * - "Button"
     - Text with small button on the right side displaying the text "...".
   * - "ButtonText"
     - Button with text. Button covers the complete cell.
   * - "MarkerText"
     - Cell can display marker, line style, color, etc.
   * - "ButtonEdit"
     - Edit control to enter text with a small button on the right side displaying "...".
   * - "ButtonStatic"
     - Read Only edit control with a small button on the right side displaying "...". Text can be copied to clipboard.

For the "Combo", "AutoCombo" and "Marker" combo box, a callback function must
be specified in order to pass the items of the list box to the combo box.
For the "Button" and "Buttontext", a callback function must be specified
which is invoked when the user clicks on the button.

**Callback Functions**

The callback functions are invoked by UniPlot.

**cccGetOption(ssOption)**

This function is invoked when the dialog box is about to displayed on the monitor.

The function is called 6 times. Every time it is called, a different *ssOption*
string is passed to the function. Depending on the value of *ssOption*, the
function must return a scalar string, a string vector or a string matrix. If the
function does not handle an option, it should return the value FALSE (0).

Values of *ssOption*:

.. list-table::
   :header-rows: 1

   * - Type
     - Description
   * - "ColumnType"
     - Specifies the cell type . All cells in a column have the same type. For this option string, the function must return a string matrix with two columns.  The first column specifies the cell type and the second column the callback  function. See example.
   * - "CellType"
     - Specifies the cell type. When this option is handled each cell can  have a different cell type. The function must return a string matrix. The number  of rows and columns must match the number of records and columns in the report  control. The callback function is added to the cell type, separated by an  @-character, e.g. "Combo@__Test_VarNames".
   * - "Selection"
     - Specifies the number of highlighted columns when the user clicks  inside the report control. If the function returns the value "0", selection is  disabled. A value greater than "0" will specifiy the number of columns that will  show the selection.
   * - "ColumnOrder"
     - Specifies the display order of the columns in the report control.
   * - "ColumnWidth"
     - Sets the column width in pixels. A value of "-1" will enable autowidth.
   * - "EnableColumnDrag"
     - Specifies if the user can rearrange the column order by dragging the columns to a new position. If the function returns "1", the columns can be dragged. The return value "0" disables dragging. Default value is "0".

**cccOnCellChange(svInit, iControl, iRow, iCol)**

The function is invoked when a cell value has been modified.

*svInit* is a string vector with one element for each control in the dialog box.
*iControl* is the index of the control and can be used to access the element
in *svInit*, example **svInit[iControl]**. The parameter *iRow* und *iCol* 
specify the row and column of the modified cell.

**cccOnCellActivate(svInit, iControl, iRow, iCol)**

The function is invoked when a cell is activated with a mouse click.

**cccSaveOption(ssOption, svVal)**

The function is invoked before the dialog box is closed.

The function can be used to save the column order and column width.

The function is invoked two times. Values of *ssOption*:

.. list-table::
   :header-rows: 1

   * - Type
     - Description
   * - "ColumnOrder"
     - Column order. Enumeration starts with 1.
   * - "ColumnWidth"
     - Column width in pixels.

The parameter *svVal* is a string vector containing the column width or
column index. 

Example for ``cccSaveOption``:

::

   def __test_props_SaveOption(ssOption, svVal)
   {
       if (ssOption == "ColumnWidth") {
           WriteProfileString("test_props", "colwidth", strcat(svVal, ","));
       } else if (ssOption == "ColumnOrder") {
           WriteProfileString("test_props", "colorder", strcat(svVal, ","));
       } 
   }

**cccOnCellFillColor(iControl, iRow, iCol, ssCellText)**

**cccOnCellFillColor(iControl, iRow, iCol, ssCellText, obj)**

The function returns the cell fill color. It will be invoked for each cell in the
report control.

*iControl* is the index of the control. The parameter *iRow* und *iCol* 
specify the row and colum, values start with 1. *ssCellText* is the cell text.
*obj* is an optional paranmeter. See parameter *obj* of the *DialogBox* function.

The function must return the cell color as a COLORREF color or an empty string.
To calculate the color from the RGB valuse, use *Color_RGB_to_COLORREF(rvRGB)*.
If the function returns an empty string (""), the default color will be
displayed.

See **Example 23** below.

Example for cccOnCellFillColor (Example taken from the dataset list dialog from
the data exchange function):

::

   def __data_datasetlist_OnCellFillColor(iControl, iRow, iCol, ssCellText, obj) 
   {
      // If the cell text in column 4 contains a "!" set the cell color to red,
      // otherwise to green. 
      if (iCol == 4) {
         if (strfind(ssCellText, "!")[1]) {
            return Color_RGB_to_COLORREF([255,220,220]);  // bright red
         } else {
            return Color_RGB_to_COLORREF([220,255,220]);  // bright green
         }
      }

      // every second ro in bright yellow
      if (iRow%2) {
         return Color_RGB_to_COLORREF([250,250,223]);
      } else {
         return Color_RGB_to_COLORREF([255,255,255]);
      }

      // return an empty string to display the default cell color
      // return "";
   }

**Callback functions for the cell types Combo, AutoCombo, Marker, Button 
and Button text**

The function has the following syntax:

::

   ssInitCombo = __test_report_Combo(svInit, iControl, iRow, iCol)

or 

::

   svInit = __test_report_Button(svInit, iControl, iRow, iCol)

The function parameters are identical to **cccOnCellChange** callback function.
The return value depends on the cell type.

For the cell types Combo, AutoCombo and Marker the callback function must return
a scalar sting to initialize the combo box. The function is invoked when the 
user opens the combo box. To create the combo box init string see 
:ref:`CreateListBoxText`.

The "Marker" combo box can display markers, lines, arrows etc. The string 
must have the syntax described in the :ref:`text-objects` help topic.
For example: The following string will display an arrow:
``@a{1.2, 0, 5, 255, 0, 0, 1, 0.5, 0.2} This is an arrow``.

Helper functions for the "Marker" combo box:

::

   ReportControl_GetMarkerStyleNames()
   ReportControl_GetMarkerStyle(svMarker)
   ReportControl_GetLineStyleNames()
   ReportControl_GetLineStyle(svPen)
   ReportControl_GetColorNames()
   ReportControl_GetColorRGB(svColor)
   ReportControl_GetStyleNames(ssStyleFile)
   ReportControl_GetStyles(svMarker)

For the cell types "Button" and "ButtonText", the callback function 
must return an initialized string vector for all controls in the dialog box.

Helper functions for the report control:

::

   ReportControl_GetInit(smInit, bUseSaveSep)
   ReportControl_GetMatrix(ssRet)
   ReportControl_Sort(svInit, iControl, iColumn, bAscending)
   ReportControl_RemoveSelection(svInit, nControl)
   ReportControl_SelUpOrDown(svInit, nControl, bUp)

The columns and celltypes of an edit report control can be modified while
the dialog box is displayed.

Modify columns: To change the column names, the column order or number of
columns add the new column names separated by the string ``"\x03"`` to the init string.
The column names must be separated by tab characters.  The number of
column names and the number of columns in the init matrix must match.

Example:

::

   // 3 columns:
   ssColNames = "ID\tName\tValue";
   smMat = ["1", "Engine", "x12";
            "2", "Pistion", "k3";
            "3", "Oel", "15W40"];
   ssMat = ReportControl_GetInit(smMat, TRUE);
   ssInit = ssMat + ""\x03" + ssColNames;

To modify the cell type or the column types you must force the dialog box to
invoke the callback function ``cccGetOption(ssOption)``. To do so add the
string ``""\x03reset"`` to the init string of the edit report control in any 
callback function.

Example:

::

   // 3 columns:
   smMat = ["1", "Engine", "x12";
            "2", "Pistion", "k3";
            "3", "Oel", "15W40"];
   ssMat = ReportControl_GetInit(smMat, TRUE);
   ssInit = ssMat + "\x03reset";

or to change the number of columns and the cell type:

::

   // 3 columns:
   ssColNames = "ID\tName\tValue";
   smMat = ["1", "Engine", "x12";
            "2", "Pistion", "k3";
            "3", "Oel", "15W40"];
   ssMat = ReportControl_GetInit(smMat, TRUE);
   ssInit = ssMat + "\x03reset\x03" + ssColNames;

Helper functions for combo box and list box controls:

::

   ssComboInit = CreateListBoxText(svList, svSel)
   <svList, svSel> = GetListBoxText(ssText, bSplit)

The functions use the separators ``\x01`` and ``\x02``.

A complete example can be found at the end of this help topic (Example 16).

The return value for an edit report control is the complete content of the 
control including the selection.

Resizable dialog boxes
......................

To enable resizing you must add the string ``"|F @ccc|"`` to the template
parameter. ``ccc`` stands for the name of a callback function.

The following example shows the callback function for the :ref:`datadataset-list`
dialog box:

::

   def _DatasetListDialog_Resize(rvInit)
   {
       nElements = rvInit[6];
       nAction = rvInit[5];
       if (nAction == 1) {
           ssI = GetProfileString("DialogSize", "DatasetListDialog");
           svI = strtok(ssI, "|");
           return strtod(svI);
       } else if (nAction == 2) {
           return [2,3;    // checkbox
                   6,6;    // Report
                   5,3;    // blank field
                   5,3;    // Button 
                   5,3;    // Button 
                   5,3;    // Button 
                   5,3];    // Button 
       } else if (nAction == 3) {
           ssI = smprintf("%d", rvInit[1,2,3,4], "|", "|");
           WriteProfileString("DialogSize", "DatasetListDialog", ssI);
           return 0;
       }
   }

The function parameter *rvInit* is a real vector with  6 elements:

.. list-table::
   :header-rows: 1

   * - Value
     - Meaning
   * - rvInit[1]
     - Position left.
   * - rvInit[2]
     - Position top.
   * - rvInit[3]
     - Dialog box width in pixel.
   * - rvInit[4]
     - Dialog box height in pixel.
   * - rvInit[5]
     - nAction: see Note.
   * - rvInit[6]
     - Number of control elements in the dialog box. This information can be used for debugging purposes.

**Note**

rvInit[5] = 1: The function is called to receive the initial dialog box size
The function should return a vector with 4 elements [left, top, right, bottom]. 

rvInit[5] = 2: The callback function is called by the framework to receive
information about horizontal and vertical positions.

rvInit[5] = 3: Is called when the user is closing the dialog to save the dialog
box size.

The function is invoked by UniPlot before the dialog is displayed on the monitor
(nAction = 1 and nAction = 2).

**Position and Size of dialog elements**

By default, a dialog element is proportionally resized to the dialog box size, but
you can optionally fix the horizontal and/or vertical  dimension/position of a 
child window. E.g. it's reasonable to fix the height of single line edit controls.
In this case return the scalar value 0 if ``nAction`` is 2.

To change the default behavior you must return a real matrix. For each element in
the dialog box (including text and blank fields which are not enclosed in OR
signs) the matrix must contain one row except for the default buttons (OK, Cancel
and Help) and the ``|+xxx|`` and ``|-xxx|`` elements.

Horizontal Fixing:

.. list-table::
   :header-rows: 1

   * - Name
     - Value
     - Meaning
   * - kNoHFix
     - 0
     - Default Value: Horizontal size proportional to the dialog box size.
   * - kWidth
     - 1
     - Width fixed. Element is moved proportionally.
   * - kLeft
     - 2
     - Left fixed. Width proportional to the dialog box size.
   * - kRight
     - 4
     - Right fixed. Width proportional to the dialog box size.
   * - kWidthLeft
     - 3
     - Left fixed, width fixed.
   * - kWidthRight
     - 5
     - Right fixed, width fixed.
   * - kLeftRight
     - 6
     - Left and right keeps the distance to the edges.

Vertical Fixing:

.. list-table::
   :header-rows: 1

   * - Name
     - Value
     - Meaning
   * - kNoVFix
     - 0
     - Default Value: Vertical size proportional to the dialog box size.
   * - kHeight
     - 1
     - Constant height. Element is moved proportionally.
   * - kTop
     - 2
     - Top fixed. Height proportional to the dialog box size.
   * - kBottom
     - 4
     - Bottom fixed. Height proportional to the dialog box size.
   * - kHeightTop
     - 3
     - Top fixed, height fixed.
   * - kHeightBottom
     - 5
     - Bottom fixed, height fixed.
   * - kTopBottom
     - 6
     - Top and bottom keeps the distance to the edges.

::

   def _MyDialog_Resize(svInfo)
   {
       nAction = svInfo[5];
       if (nAction == 1) { // Init
           ssI = GetProfileString("DialogSize", "MyDialog");
           svI = strtok(ssI, "|");
           return strtod(svI);  // return the init size
       } else if (nAction == 2) { // resize 
           // svInfo[6] tells you how many elements you have 
           return [6,6; // Report control  see documentation for DialogBox 
                   5,3; // blank field
                   5,3; // button1
                   5,3; // space |+100|
                   5,3]; // button2
       } else if (nAction == 3) { // Exit User pressd OK or cancel
           ssI = smprintf("%d", svInfo[1,2,3,4], "|", "|");
           WriteProfileString("DialogSize", "MyDialog", ssI);
           return 0;
       }
   }
   def _MyDialog_Dialog()
   {
       svTemplate = ["|R10,100  Code Word |  |P Button1 @_MyDialog_Button1|", ...
                     "|+100|  |P Button2 @_MyDialog_Button2|", ...
                   strempty(1,8), ...
                     "|F @_MyDialog_Resize|"];
       svRet = DialogBox(svTemplate, "", "Test");
       if (svRet[1] == "DLG_CANCEL") {
           return svRet[1];
       }
       return svRet;
   }

See also **Example 15**.

.. us.example

**Example**

**Example 1**:

.. image:: S:/uniplot-obj/images/DialogBox1-en.*

::

   DialogBox("Name: |                 |");.

**Example 2**: In the next edit box, comma separated numbers can be specified.
The string can be split into tokens using the :ref:`strtok` function. The vector of
stings can be converted to numbers using :ref:`strtod`.

::

   sRet = DialogBox("Please type \"1,2,3,4\":|                    |")
   if (sRet != "DLG_CANCEL") {
       svRet = strtok(sRet, ",")
       rvData = strtod(svRet)
       MessageBox(sprintf("%10.5f\n", rvData'))
   }

**Example 3**:

.. image:: S:/uniplot-obj/images/DialogBox2-en.*

::

   svTemplate = ["Power  |          | kW "; "Engine |C10          |"];
   svEngines = ["1.3", "1.6 l", "2.0 l"];
   ssEngine = CreateListBoxText(svEngines, svEngines[2]) // Select the second item
   svInitString = ["127", ssEngine];
   ssTitle = "Engine-Selection";
   DialogBox(svTemplate, svInitString, ssTitle);

**Example 4**:

.. image:: S:/uniplot-obj/images/DialogBox3-en.*

::

   DialogBox(["|L4                       |", strempty(1,3)], ...
       "Line 1|Line 2|Line 3@Line 2", "Dialog 3")

**Example 5**: With a file name edit, the user can type a file name directly or
pick a file name from a dialog. When the user presses the browse button,
a modal file dialog appears. After the user picks a file name from the dialog,
the full file name is automatically entered into the edit field.

.. image:: S:/uniplot-obj/images/DialogBox4-en.*

::

   def GetMyFile()
   {
       DialogBox("File:|                           ||P Browse... @PickFile|")
   }
   def PickFile(svInit)
   {
       ssFilter = "My File (*.myf)|*.myf|All Files (*.*)|*.*|";
       ssFileName = GetOpenFileName(svInit[1], ssFilter);
       if (ssFileName == "") { // User clicked CANCEL
       return svInit;
       }
       svInit[1] = ssFileName;
       return svInit;
   }

**Example 6**: The following example displays a list box showing the names of all
loaded UniScript functions:

.. image:: S:/uniplot-obj/images/DialogBox5-en.*

::

   DialogBox(["|L10                     |", strempty(1,9)], CreateListBoxText(symbols(255)))

**Example 7**: In the following example, a dialog box with a list of names will
be created. New names can by added. The dialog saves the names in the window's
registry.

::

   def __TestAddItemToList(svInit)
   {
       svItem = strtok(svInit[1], "@");
       if (len(svItem) == 1) { return svInit; }
       svSel = strtok(svItem[2], "|");
       if (len(svSel) == 1) { return svInit;    }
       return svItem[1] + "|" + svSel[2] + "@" + svSel[1];
   }
   def __TEST_Ok(svInit)
   {
       // Add last name to list:
       __TestAddItemToList(svInit);
       WriteProfileString("MyFiends", "Name", svInit[1]);
       return TRUE;
   }
   def TestDialog()
   {
       svInit = _GetProfileStringEx("MyFiends", "Name", "Andy|Georg|Thomas|");
       // returns selected Name:
       return DialogBox("Friends:|D                  @__TestAddItemToList||O &OK@__TEST_Ok|", svInit);
   }

**Example 8**: The following example is a report with three columns.

.. image:: S:/uniplot-obj/images/DialogBox5-Report-en.*

::

   smMat = ["1.6l 16V", "4", "Otto";
            "2.0l 16V", "4", "Otto";
            "1.9l","4", "Diesel"];
   ssInit = ReportControl_GetInit(smMat, TRUE, 1);

   DialogBox(["|R4,40 Engine\tCylinder\tType|", strempty(1,3)], ..
              ssInit, ..
              "Report-Dialog")

**Example 9**: Report with three columns and a check box for each line.

.. image:: S:/uniplot-obj/images/DialogBox6-ReportWithCheckbox-en.*

::

   def TestCallback_OK9(svInit)
   {
       return svInit;
   }

   def TestDialog_9()
   {
      smData = ["1", "1.6l 16V", "4", "Otto";
            "0", "2.0l 16V", "4", "Otto";
            "0", "1.9l", "4", "Diesel"];

      // 5 rows, width=70
      svTemplate = ["|RB5,70 "  + "Engine\tCylinder\tType|", ..
                  strempty(1, 4), ..
                  "|OOk@TestCallback_OK9|"];

      ssTitle = "Report-Dialog";
      svInit = ReportControl_GetInit(smData, TRUE, 3);
      svRet = DialogBox(svTemplate, svInit, ssTitle);
      if (svRet[1] == "DLG_CANCEL") {
           return -1;
      }
      smMat = ReportControl_GetMatrix(svRet[1]);

      // Checkboxes, first column:
      r = strtod(smMat[;1]);
      return r;
   }
   TestDialog_9()

**Example 10**: The following example is a dialog box with two group boxes.

.. image:: S:/uniplot-obj/images/DialogBox7-Groupbox-en.*

::

   svTemplate = ["|G3                  | |G3                   |", ..
                 " x =|           ||+6|dx =|            |", ...
                 " y =|           ||+6|dy =|            |",..
                 "", ..
                 "|B Apply size to all selected elements|"]
   DialogBox(svTemplate, ["Position","Size", "0","10", "0", "10"], "Move Elements")

**Example 11**: The following example is a dialog box with a property
list box. The value in the right column can be edited by a combo box (Combo),
button (Button) or edit field (Edit).

.. image:: S:/uniplot-obj/images/DialogBox8-PropList-en.*

::

   def PropList_GetMatrix(ssRet)
   {
       sv = strtok(ssRet, "\n");
       n = len(sv);
       sm = strempty(n, 3);
       for (i in 1:len(sv)) {
           svT = strtok(sv[i], "\t")
           nn = len(svT);
           if (nn == 1) {
               sm[i;1] = svT;
           } else if (nn == 2) {
               sm[i;1:2] = svT;
           } else if (nn == 3) {
               sm[i;] = svT;
           }
       }
       return sm;
   }
   def __PL1_GetFileName(svProp)
   {
       ssFileName = GetOpenFileName(svProp[3]);
       if (ssFileName == "") {
           return 0;
       }
       return [sum(SplitPath(ssFileName)[3,4]), ssFileName];
   }
   def __PL1_ChannelNames(svProp)
   {
       return ["Speed|T|Torque|T_Act|be@" + svProp[2], ""];
   }
   def _EngineDialog()
   {
       ssInit = "Template Name\tKF.IPW\tButton\t__PL1_GetFileName\tc:/test/kf.ipw\n" + ..
            "x-Channel\tspeed\tCombo\t__PL1_ChannelNames\n" + ..
            "y-Channel\tT\tCombo\t__PL1_ChannelNames\n" + ..
            "z-Kanal\tTorque\tAutoCombo\t__PL1_ChannelNames\n" + ..
            "Title\tOtto2\tEdit\n" + ..
            "Operator\tP. Miller"
       svRet = DialogBox(["|N8                                                      |", strempty(1,7), ..
                  "|B Use Default Values"], ..
                  [ssInit, "0"], "Page Configuration")
       if (svRet[1] == "DLG_CANCEL") {
           return svRet[1];
       }
       smMat = PropList_GetMatrix(svRet[1]);
       // Do something with smMat[;2]
   }

**Example 12**: Multiline edit box.

.. image:: S:/uniplot-obj/images/DialogBox9-Multiline-en.*

::

   DialogBox(["|5                       |", strempty(1,4)], ..
              "This is the first line\nThis is the second line", "Multiline-Edit")

]]

**Example 13**: The following example checks if a number in the range 1 to 10 has
been typed:

.. image:: S:/uniplot-obj/images/DialogBox13-en.*

::

   def TestCallback(svInit)
   {
       <n, ssStop> = strtod(strtrim(svInit, 3));
       if (n < 1 || n > 10 || ssStop != "") {
           MessageBox("Please type in a number in the range 1 to 10.", ["Error", "ICONSTOP"]);
           return FALSE;
       }
       return TRUE;
   }
   def TestDialog()
   {
        ssRet = DialogBox("Number between 1 and 10: |                       ||OOK@TestCallback|", "0", "Edit");
        if (ssRet != "DLG_CANCEL") {
            MessageBox("Ok: You typed in " + ssRet + "!");
        }
   }

**Example 14**: The following example displays a list box that showing the names
of all loaded UniScript functions. The source file with the definition is
displayed for the selected function name.

.. image:: S:/uniplot-obj/images/DialogBox14-en.*

::

   def __ShowSourceName(svInit)
   {
       <a,b> = GetListBoxText(svInit[2]);
       svInit[1] = source(b);
       return svInit;
   }
   def _ListFunctions()
   {
       DialogBox(["|Sf                                   ", ..
                  "|L10                                @__ShowSourceName|", strempty(1,9)], ..
                   ["", CreateListBoxText(symbols(255))]);
   }

**Example 15**: The following example displays a tree control showing the
directory and files in the UniPlot root directory. The dialog box is resizeable.

.. image:: S:/uniplot-obj/images/DialogBox10-Tree-en.*

::

   def _MyDialogTree_GetImageList(obj)
   {
       return GetRootDirectory() + "bitmap/" + ["folder.bmp", "file.bmp"];
   }
   def _MyDialogTree_SelChanged(svInit, svText, nItemID, obj)
   {
       svInit[2] = obj.Path +strcat(svText, "/");
       return svInit;
   }
   def _MyDialogTree_DblClicked(svInit, svText, nItemID, obj)
   {
       MessageBox("Path: " + obj.Path +strcat(svText, "/"));
   }
   def _MyDialogTree_RClicked(svInit, svText, nItemID, obj)
   {
       MessageBox("Path: " + obj.Path +strcat(svText, "/"));
   }
   def _MyDialogTree_Expand(svText, rvItemID, obj)
   {
       smFiles = FindFiles(obj.Path + strcat(svText, "/") + "/*");
       // remove . and ..
       if (nr(smFiles) < 3) {
           return "";
       }
       smFiles = strtrim(smFiles[3:nr(smFiles);], 3);
       nFiles = nr(smFiles);
       smName = strempty(nFiles, 4);
       for (i in 1:nFiles) {
           smName[i;1] = smFiles[i;1];
           smName[i;2] = "0"; // sprintf("%d", o.lastid);
           if (smFiles[i;3] == "16") {
               smName[i;3] = "1";
               smName[i;4] = "1";
           } else {
               smName[i;3] = "0";
               smName[i;4] = "2";
           }
       }
       return smName;
   }
   def _MyDialogTree_Resize(svInfo, obj)
   {
       nAction = svInfo[5];
       if (nAction == 1) { // Init
           ssI = GetProfileString("DialogSize", "MyDialogTree");
           svI = strtok(ssI, "|");
           return strtod(svI);  // return the init size
       } else if (nAction == 2) { // resize 
           return [6,6; 
                   6,5];
       } else if (nAction == 3) { // Exit User pressd OK or cancel
           ssI = smprintf("%d", svInfo[1,2,3,4], "|", "|");
           WriteProfileString("DialogSize", "MyDialogTree", ssI);
           return 0;
       }
   }
   def _MyDialogTree_Dialog()
   {
       ssTreeSelection = GetProfileString("_MyDialogTree", "TreeSelection");
       ssTreeSelection = ssTreeSelection + "\x03select";
       svTemplate = ["|A10                                                             @_MyDialogTree_|", ...
                   strempty(1,9), ...
                     "|Sf                                                                ||F @_MyDialogTree_Resize|"];
       svInit = [ssTreeSelection, ""];
       ssHelp = "";
       obj = obj_create();
       obj.Path = GetRootDirectory();
       svRet = DialogBox(svTemplate, svInit, "Browse " + obj.Path, ssHelp, obj);
       if (svRet[1] == "DLG_CANCEL") {
           return svRet[1];
       }
       svEle = strtok(svRet[1], "\x02");
       svPfad = strtok(svEle[1], "\x01");
       WriteProfileString("_MyDialogTree", "TreeSelection", strcat(svPfad, "\x01"));
       return GetRootDirectory() + strcat(svPfad, "\");
   }

**Example 16**:  The following example shows a report control, in which cells
can be edited in. Column width an order can be interactivly altered and will
be saved. The dialog box can be resized.

Call see function _test_report().

.. image:: S:/uniplot-obj/images/DialogBox11-EditReport-en.*

::

   def __test_report_Combo(svInit, iControl, iRow, iCol)
   {
       <ssMat, svSel> =GetListBoxText(svInit[iControl], FALSE);
       smMat = ReportControl_GetMatrix(ssMat);
       return CreateListBoxText(["Otto","Diesel","DI-Otto"], smMat[iRow; iCol]);
   }
   def __test_report_Button(svInit, iControl, iRow, iCol)
   {
       <ssMat, svSel> =GetListBoxText(svInit[iControl], FALSE);
       smMat = ReportControl_GetMatrix(ssMat);
       ssFile = GetOpenFileName();
       if (ssFile != "") {
           smMat[iRow; iCol] = ssFile;
           svInit[iControl] = ReportControl_GetInit(smMat, TRUE);
       }
       return svInit;
   }
   def __test_report_Color(svInit, iControl, iRow, iCol)
   {
       svColor = ReportControl_GetColorNames();
       <ssMat, svSel> =GetListBoxText(svInit[iControl], FALSE);
       smMat = ReportControl_GetMatrix(ssMat);
       return CreateListBoxText(svColor, smMat[iRow;iCol]);
   }
   def __test_report_GetOption(ssOption)
   {
       if (ssOption == "Selection") {
           return "255";
       } else if (ssOption == "EnableColumnDrag") {
           return "1";
       } else if (ssOption == "ColumnType") {
           return ["ShowButton", "";
                   "Edit", "";
                   "Combo", "__test_report_Combo";
                   "Button", "__test_report_Button";
                   "Checkbox", "";
                   "Marker", "__test_report_Color"];
       } else if (ssOption == "ColumnWidth") {
           return _GetProfileStringEx("DialogSize", "_test_props_colwidth", "50,70,50,150,60,140");
       } else if (ssOption == "ColumnOrder") {
           return _GetProfileStringEx("DialogSize", "_test_props_colorder", "1,2,3,4,5,6");
       }
   }
   def __test_report_SaveOption(ssOption, svVal)
   {
       if (ssOption == "ColumnWidth") {
           WriteProfileString("DialogSize", "_test_props_colwidth", strcat(svVal, ","));
       } else if (ssOption == "ColumnOrder") {
           WriteProfileString("DialogSize", "_test_props_colorder", strcat(svVal, ","));
       } 
   }
   def __test_report_Resize(rvInit)
   {
       nElements = rvInit[6];
       nAction = rvInit[5];
       if (nAction == 1) {
           ssI = GetProfileString("DialogSize", "_test_report");
           svI = strtok(ssI, "|");
           return strtod(svI);
       } else if (nAction == 2) {
           return [6,6];
       } else if (nAction == 3) {
           ssI = smprintf("%d", rvInit[1,2,3,4], "|", "|");
           WriteProfileString("DialogSize", "_test_report", ssI);
           return 0;
       }
   }
   def _test_report()
   {
       svColor = ReportControl_GetColorNames();
       svTemplate = ["|R4,60 Engine\tComment\tType\tData File\tShow\tColor @@@__test_report_|", ..
                     strempty(1,2), ...
                     "|F @ __test_report_Resize |"];
       smData =["1.6l 16V",	"With AGR",		"Otto",		"","1",	svColor[10];
            "2.0l 16V",	"Without AGR",	"Otto", 	"","0", svColor[11];
            "1.9l",		"",				"Diesel",	"","2", svColor[12];
            "1.6l 16V",	"",				"Otto", 	"","1", svColor[13];
            "1.6l 16V",	"",				"Otto",		"","1", svColor[14]];
       ssInit = ReportControl_GetInit(smData, TRUE);
       svRet = DialogBox(svTemplate, ssInit, "Edit-Report-Dialog")
       if (svRet[1] == "DLG_CANCEL") {
           return svRet;
       }
       smMat = ReportControl_GetMatrix(svRet[1]);
       rmColor = ReportControl_GetColorRGB(smMat[;6]);
       return svRet
   }

**Example 17**: The following example shows a Wizard with three dialog boxes.

Short function description:

In the _TestWizard() function an object is created. The object is used to define
the three dialogboxes. For each dialog box a separate object with the indices
1,2 and 3 is created. In these objects the parameters Template, svInit, Title, Back
and Help are specified. 

The object is passed to the WizardDialog() function. The WizardDialog
functions invokes the DialogBox function for the obj.dialog_id == 1.

For the Next, Back and Finish button a separate callback function is
specified. These callback functions save the current settings and 
set the element obj.dialog_id. obj.dialog_id specifies which dialog box
will be displayed next.

The template string vector has been filled with empty rows (strempty())
to make all dialogs the same height so that the Next and Back button
will be displayed at the same position on the monitor.

The user input is saved in the elemenst obj[i].svInit.

To test the dialog box, copy the program into an ic file, press F4.
and call the _TestWizard() function in the command window.

.. image:: S:/uniplot-obj/images/DialogBox17-Wizard-en.*

::

   def _TestWizard_Next(svInit, obj)
   {
       obj[obj.dialog_id].svInit = svInit;
       obj.dialog_id = obj.dialog_id + 1;
       return 1;
   }
   def _TestWizard_Back(svInit, obj)
   {
       obj[obj.dialog_id].svInit = svInit;
       obj.dialog_id = obj.dialog_id - 1;
       return 1;
   }

   def _TestWizard()
   {
       obj = obj_create();
       obj[1] = [.];
       obj[2] = [.];
       obj[3] = [.];
       obj.dialog_id = 1;

       obj[1].Template = [strempty(1,4), ..
                          "File1:|                                 |", ..
                          "File2:|                                 |", ..
                           strempty(1,4),"|OS Next>@_TestWizard_Next"];
       // If you remove the S in [[|OS Next>@_TestWizard_Next|]] a \b(Cancel) 
       // button will be displayed.
       obj[1].svInit = ["c:/test1", "c:/test2"];
       obj[1].Title = "Step1: Select Files";
       obj[1].Back = "";    // No Back-Button
   //  obj[1].Help = "";    // No Help-Button
       obj[1].Help = "DialogBox" + "@" + GetHelpFileName();

       obj[2].Template = ["Kanäle:|L10                             |", ..
                           strempty(1,9),"|OS Next>@_TestWizard_Next"];
       obj[2].svInit = CreateListBoxText(["speed","torque","nox"], "nox");
       obj[2].Title = "Step2: Select Channels";
       obj[2].Back = "<Back@_TestWizard_Back";
    // obj[2].Help = "";  
       obj[2].Help = "DialogBox" + "@" + GetHelpFileName();

       obj[3].Template = [strempty(1,5), ..
                           "Title:|                                  |", ..
                           strempty(1,4), "|OS Finish@_TestWizard_Next"];
       obj[3].svInit = ["This is Text 1"];
       obj[3].Title = "Step3: Specify Title";
       obj[3].Back = "<Back@_TestWizard_Back";
       obj[3].Help = "";
       obj[3].Help = "DialogBox" + "@" + GetHelpFileName();

       ssRet = WizardDialog(obj);
       if (ssRet == "OK") {
           ssFile1 = obj[1].svInit[1];
           ssFile2 = obj[1].svInit[2];
           ssChannel = GetListBoxText(obj[2].svInit);
           ssTitle = obj[3].svInit[1];
           print obj[1].svInit, obj[2].svInit, obj[3].svInit
       } else {
           print "Wizard: Cancel";
       }
   }
   def WizardDialog(obj)
   {
       while (obj.has_key(obj.dialog_id)) {
           od = obj[obj.dialog_id];
           svRet = DialogBox(od.Template, od.svInit, od.Title, od.Help, obj, od.Back);
           if (svRet[1] == "DLG_CANCEL") {
               return svRet[1];
           }
       }
       return "OK";
   }

**Example 18**: Dialog box with two groups of radio buttons.

.. image:: S:/uniplot-obj/images/DialogBox18-Radio-en.*

The radio button is a manual radio button. This means that your 
application must clear other radio buttons in the group manually 
each time a user selects a button. This can be done by calling the 
function :ref:`RadioControl_Group` in the callback function of a radio control. 
The indices of all radio buttons in the group are passed as a third parameter.

::

   def _Radio1(svInit, iRadio) 
   { 
       return RadioControl_Group(svInit, iRadio, [2, 3, 4]); 
   }
   def _Radio2(svInit, iRadio) 
   { 
       return RadioControl_Group(svInit, iRadio, [6, 7, 8, 9]); 
   }
   def RadioDialogBox()
   {
       svTemplate = ["|G4                                  |", ..
                     "|BR Radio 1    @_Radio1|", ..
                     "|BR Radio 2    @_Radio1|", ..
                     "|BR Radio 3    @_Radio1|", ..
                     "", ..
                     "|G5                                  |", ..
                     "|BR Radio 1    @_Radio2|", ..
                     "|BR Radio 2    @_Radio2|", ..
                     "|BR Radio 3    @_Radio2|", ..
                     "|BR Radio 4    @_Radio2|", ..
                     ""];
       svInit = ["Group 1", "1", "0", "0", "Group2", "1", "0", "0", "0"];
       DialogBox(svTemplate, svInit, "Example 18");
   }

**Example 19**: The following example displays a dialog box with a UniPlot 
graphic.

.. image:: S:/uniplot-obj/images/DialogBox19-IPWGraphic-en.*

The page handle is passed to the dialog box in the init string. The optionnal
callback function, in this example __Test_Example19_UpdatePageSize, is invoked
when the dialog box size is modified. The first parameter is a scalar string 
containing three numbers with the page handle, control width and height, 
separated by a comma. This string is given to all dialog callback functions.

In the example an object is used to pass the handles.

::

   def __Test_Example19_Resize(rvInit)
   {
       nAction = rvInit[5];
       if (nAction == 1) {
           ssI = GetProfileString("DialogSize", "Test_Example19");
           svI = strtok(ssI, "|");
           return strtod(svI);
       } else if (nAction == 2) {
           return [2,3; 6,3; 2,3; 6,3; 5,3; 6,6];
       } else if (nAction == 3) {
           ssI = smprintf("%d", rvInit[1,2,3,4], "|", "|");
           WriteProfileString("DialogSize", "Test_Example19", ssI);
           return 0;
       }
   }
   def __Test_Example19_Update(svInit, obj)
   {
       LayerSetAxisTitle(obj.hLayer, "X", svInit[1]);
       LayerSetAxisTitle(obj.hLayer, "Y", svInit[2]);
       __Test_Example19_UpdatePageSize(svInit[3], obj)
       return svInit;
   }
   def __Test_Example19_UpdatePageSize(ssInfo, obj)
   {
       rvInfo = strtod(strtok(ssInfo, ","));
       hPage = rvInfo[1];    // Page handle
       dx = rvInfo[2];     // control width in centimeter
       dy = rvInfo[3];        // control height in centimeter
       rvPosSize = OBJGetPosSize(obj.hLayer);
       rvPosSize[1] = 3;
       rvPosSize[2] = -rvInfo[3]-1;
       rvPosSize[3] = rvInfo[2]-1;
       rvPosSize[4] = rvInfo[3]-1;
       OBJSetPosSize(obj.hLayer, rvPosSize);
       return 0;
   }
   def Test_Example19()
   {
       obj = [.];
       hDoc = DocCreate("", DOC_HIDDEN);
       hPage = PageCreate();
       DocAddPage(hDoc, hPage);
       hLayer = LayerCreate();
       LayerSetAutoScale(hLayer, "X", TRUE);
       LayerSetAutoScale(hLayer, "Y", TRUE);
       hData = XYCreate("Test", [1,2,3,4,5], [1,3,2,5,4]);
       PageAddLayer(hPage, hLayer);
       LayerAddDataset(hLayer, hData);
       obj.hPage = hPage;
       obj.hLayer =hLayer;
       obj.hData = hData;
       // Save Handle so the control knows what to plot
       ssPage = sprintf("%d", hPage);
       svInit = [LayerGetAxisTitle(hLayer, "X"),LayerGetAxisTitle(hLayer, "Y"), ssPage];
       svRet = DialogBox(["x-Title=|                 |", ...
                          "y-Title=|                 ||P Update @__Test_Example19_Update", ...
                          "|SP5                         @__Test_Example19_UpdatePageSize|" + ...
                          "|F @ __Test_Example19_Resize|", ...
                          strempty(1,4)], svInit, "Test Example 19", "", obj);
       DocDestroy(hDoc);
   }

**Example 20**: Dialog box with combobox controls to select colors line styles
and marker styles.

.. image:: S:/uniplot-obj/images/DialogBox20-en.*

::

   def Test_Example20()
   {
       svColor = ReportControl_GetColorNames();
       ssColorList = CreateListBoxText(svColor, svColor[1]);
       svStyle = ReportControl_GetLineStyleNames();
       ssStyleList = CreateListBoxText(svStyle, svStyle[1]);
       svMarker = ReportControl_GetMarkerStyleNames();
       ssMarkerList = CreateListBoxText(svMarker, svMarker[1]);
       svRet = DialogBox(["Color: |CS15                               |", ...
                             "Line:  |CS15                               |",...
                          "Symbol:|CS15                               |"], ...
                           [ssColorList, ssStyleList, ssMarkerList], "Example 20");
       if (svRet[1] == "DLG_CANCEL") {
           return 0;
       }
       rvColor = ReportControl_GetColorRGB(svRet[1]);
       nLine = ReportControl_GetLineStyle(svRet[2])
       nMarker = ReportControl_GetMarkerStyle(svRet[3]);
   }

**Example 21**: Dialog box to select channels from an NC/NC2 file:

.. image:: S:/uniplot-obj/images/DialogBox21-en.*

::

   // Callback "Select All"
   def _NC_Channel_Selection_SelectAll(svInit)
   {
      <smMatrix, smSelMat, rvSelRow> = ReportControl_GetMatrix(svInit[1])
      if (len(smMatrix) == 1) {
         return 0;
      }
      smMatrix[;1] = "1";
      svInit[1] = ReportControl_GetInit(smMatrix, TRUE, rvSelRow);
      return svInit;
   }

   // Callback "Deselect All"
   def _NC_Channel_Selection_DeselectAll(svInit)
   {
      <smMatrix, smSelMat, rvSelRow> = ReportControl_GetMatrix(svInit[1])
      if (len(smMatrix) == 1) {
         return 0;
      }
      smMatrix[;1] = "0";
      svInit[1] = ReportControl_GetInit(smMatrix, TRUE, rvSelRow);
      return svInit;
   }

   // Callback "Toggle"
   def _NC_Channel_Selection_Toggle(svInit)
   {
      <smMatrix, smSelMat, rvSelRow> = ReportControl_GetMatrix(svInit[1])
      if (rvSelRow[1] == 0) {
         MessageBoxError(_s("Select at least one element in the list"));
         return 0;
      }
      ssSel = smMatrix[rvSelRow[1]; 1];
      if (ssSel == "1") {
         ssSel = "0";
      } else {
         ssSel = "1";
      }
      smMatrix[rvSelRow;1] = ssSel;
      svInit[1] = ReportControl_GetInit(smMatrix, TRUE, rvSelRow);
      return svInit;
   }

   // Callback "OK" button
   def _NC_Channel_Selection_Dialog_OK(svInit)
   {
      smVars = ReportControl_GetMatrix(svInit[1]);
      idx = find(smVars[;1] == "1");
      if (idx[1] == 0) {
         MessageBoxError(_s("Select at least one element in the list"));
         return FALSE;
      }
      svVars = smVars[idx;2];
      return svVars;
   }

   // Callback "Dialog Resize"
   def _NC_Channel_Selection_Resize(rvInit)
   {
      nElements = rvInit[6];
      nAction = rvInit[5];
      if (nAction == 1) {
         ssI = GetProfileString("DialogSize", "NC_Channel_Selection_Dialog");
         svI = strtok(ssI, "|");
         return strtod(svI);
      } else if (nAction == 2) {
         return [6,6;
                  5,3;
                  5,3;
                  5,3;
                  5,3];
      } else if (nAction == 3) {
         ssI = smprintf("%d", rvInit[1,2,3,4], "|", "|");
         WriteProfileString("DialogSize", "NC_Channel_Selection_Dialog", ssI);
         return 0;
      }
   }

   // returns "" if Cancel is selected
   def NC_Channel_Selection_Dialog(ssNCFile)
   {
      svVarNames = NC_GetVarNames(ssNCFile);
      if (svVarNames[1] == "") {
         MessageBoxError("Ungültige Datendatei: %s", ssNCFile);
         return "";
      }

      ssTitle = "Channel Selection";
      svTemplate = ["|RMB10,65   Name@@ReportControl_Sort| " + ...
             " |P Select All       @ _NC_Channel_Selection_SelectAll |", ..
         "|+68||P Deselect All     @ _NC_Channel_Selection_DeselectAll |", ..
         "|+68||P Toggle Selection @ _NC_Channel_Selection_Toggle|", .. 
         "|O OK @_NC_Channel_Selection_Dialog_OK||F @_NC_Channel_Selection_Resize|", ..
         strempty(1, 6)]

      smVars = strempty(len(svVarNames), 2);
      smVars[;1] = "0"; // deselect all
      smVars[;2] = svVarNames'
   
      svInit = ReportControl_GetInit(smVars, TRUE);
      svRet = DialogBox(svTemplate, svInit, ssTitle);
      if (svRet[1] == "DLG_CANCEL") {
         return "";
      }
      return svRet;
   }

   // Test
   NC_Channel_Selection_Dialog(GetOpenFileName())

**Example 22**: Property Listbox with color selection, etc.:

.. image:: S:/uniplot-obj/images/DialogBox22-en.*

::

   def _MyProp_Button(svInit, iControl, iRow, iCol)
   {
       <ssMat, svSel> =GetListBoxText(svInit[iControl], FALSE);
       smMat = ReportControl_GetMatrix(ssMat);
       ssFile = GetOpenFileName();
       if (ssFile != "") {
           smMat[iRow; iCol] = ssFile;
           svInit[iControl] = ReportControl_GetInit(smMat, TRUE);
       }
       return svInit;
   }

   def _MyProp_Color(svInit, iControl, iRow, iCol)
   {
      if (nargsin() == 1) {
         return ReportControl_GetColorNames(Color_RGB_to_COLORREF(_sty_color_to_number(svInit)), " ");
      } else if (nargsin() == 2) {
         rvColor = ReportControl_GetColorRGB(svInit);
         return _sty_color_print(0, "", _sty_rgb(rvColor), "", FALSE);
      } else {
         svColor = [" ", ReportControl_GetColorNames()];
         <smMat, svSel, rsSel> = ReportControl_GetMatrix(svInit[iControl]);
         return CreateListBoxText(svColor, smMat[iRow;iCol]);
   }

   def _MyProp_LineWidth(svInit, iControl, iRow, iCol)
   {
      if (nargsin() == 1) {
         if (svInit == "") {
            return " ";
         }
         nVal = strtod(svInit)
         if (nVal <= 0) {
            return "1";
         }
         if (nVal > 50) {
         return "50";
         }
         return svInit;
      } else if (nargsin() == 2) {
         if (svInit == " ") {
            return "";
         }
         return svInit;
      }
      <ssMat, svSel> =GetListBoxText(svInit[iControl], FALSE);
      smMat = ReportControl_GetMatrix(ssMat);
      return " |" + _CreateComboBoxNumbers(1, 50) + "@" + smMat[iRow; iCol];
   }
   
   def _MyProp_LineStyle(svInit, iControl, iRow, iCol)
   {
      if (nargsin() == 1) {
         return ReportControl_GetLineStyleNames(_sty_curve_style_to_number(svInit), " ");
      } else if (nargsin() == 2) {
         rsLineStyle = ReportControl_GetLineStyle(svInit);
         return _sty_curve_style_print(0, "", rsLineStyle, "", FALSE);
      } else { 
         svNames = [" ", ReportControl_GetLineStyleNames()];
         <smMat, svSel, rsSel> = ReportControl_GetMatrix(svInit[iControl]);
      return CreateListBoxText(svNames, smMat[iRow;iCol]);
      }
   }
   
   
   def _MyProp_Marker(svInit, iControl, iRow, iCol)
   {
      if (nargsin() == 1) {
         return ReportControl_GetMarkerStyleNames(_sty_marker_style_to_number(svInit), " ");
      } else if (nargsin() == 2) {
         rsVal = ReportControl_GetMarkerStyle(svInit);
         return _sty_marker_style_print(0, "", rsVal, "", FALSE);
      } else {
         svNames = [" ", ReportControl_GetMarkerStyleNames()];
         <smMat, svSel, rsSel> = ReportControl_GetMatrix(svInit[iControl]);
         return CreateListBoxText(svNames, smMat[iRow;iCol]);
      }
   }
   
   // callback function to set the cell type
   // The function name is the name behind the third @ character in dialog template
   // folloed by the text GetOption
   def _MyProp_GetOption(ssOption)
   {
      if (ssOption == "CellType") {
            return ["GreyText", "Edit";
                  "GreyText", "Button@_MyProp_Button"; 
                  "GreyText", "Checkbox@_MyProp_OnOff";
                  "GreyText", "Marker@_MyProp_Color";
                  "GreyText", "Marker@_MyProp_LineStyle";
                  "GreyText", "Combo@_MyProp_LineWidth";
                  "GreyText", "Marker@_MyProp_Marker"];
         } 
      }
      
   def _Test_Prop_Dialog_Template()
      {
      ssTitle = "Property Dialog";
      svTemplate = ["|R8,90 Name\tValue @@@_MyProp_|", strempty(1,7)];
      // Create an object and return it
      return [. ssTitle = ssTitle, svTemplate = svTemplate];
   }
   
   def _MyProp_Dialog()
   {
      dlg = _Test_Prop_Dialog_Template();
      ssColor = _MyProp_Color("RGB(0,255,0)"); //green  sprintf("RGB(%d,%d,%d)", r,b,g);
      ssLineStyle = _MyProp_LineStyle("1");
      ssMarker = _MyProp_Marker("5");
   
      smInit = ["Text", "This is Text";
               "File Name", "c:\\b.txt";
               "On/Off", "1";
              "Color", ssColor;
              "Line Type", ssLineStyle;
              "Line Width", "5";
              "Marker", ssMarker];
   
      svInit = ReportControl_GetInit(smInit, TRUE);  // TRUE is important!

      svRet = DialogBox(dlg.svTemplate, svInit, dlg.ssTitle);
      if (svRet[1] == "DLG_CANCEL") {
         return 0;
      }
      smMat = ReportControl_GetMatrix(svRet[1]);
      obj = [.];
      obj.ssText = smMat[1;2];
      obj.ssFile = smMat[2;2];
      obj.bOnOff = strtod(smMat[3;2]);
      obj.rvColor = ReportControl_GetColorRGB(smMat[4;2]);
      obj.nLineWidth = strtod(smMat[6;2]);
      obj.ssMarker = strtod(_MyProp_Marker(smMat[7;2], 1));
   
      return obj;
   }

**Example 23**: The following example displays a matrix of random numbers.
The color depends of the value.

.. image:: S:/uniplot-obj/images/DialogBox23-OnCellFillColor-en.*

::

   def __testdialog_23_OnCellFillColor(iControl, iRow, iCol, ssCellText)
   {
      if (iCol == 1) {
         return Color_RGB_to_COLORREF([250,250,250]);  // bright grey
      }
      rsVal = strtod(ssCellText);
   
      if (rsVal >= -0.2 && rsVal <= 0.2) {
         return Color_RGB_to_COLORREF(sty_prop_color_to_RGB("lightgreen"));  // bright green
      } else if (rsVal <= -0.2) {
         return Color_RGB_to_COLORREF(color_html_to_rgb("#fa8072"));  // bright red
      } else {
         return Color_RGB_to_COLORREF(sty_prop_color_to_RGB("powderblue"));
      }
   }
   
   def TestCallback_23_OK9(svInit)
   {
       return svInit;
   }
   
   def TestDialog_23()
   {
      smData = smprintf("%g", rand(10,10)*2-1);
      svCols = strcat(smprintf("%d", 1:nc(smData)), "\t");
      svRows = smprintf("%d", 1:nr(smData))';
   
      svTemplate = ["|R12,100 \t" + svCols + "@@@__testdialog_23_|", ..
                  strempty(1, 11), ..
                  "|OOk@TestCallback_23_OK9|"];
   
      ssTitle = "Report-Dialog";
      svInit = ReportControl_GetInit([svRows, smData], TRUE, 3);
       svRet = DialogBox(svTemplate, svInit, ssTitle);
       if (svRet[1] == "DLG_CANCEL") {
           return -1;
       }
      smMat = ReportControl_GetMatrix(svRet[1]);
      return smMat;
   }
   TestDialog_23()

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - R2016.1
     - Add Callback function for edit fields.
   * - R2015.4
     - New Callback function OnCellFillColor for a ReportControl.
   * - R2013.12
     - New Callback function OnCellActivate for a ReportControl.
   * - 5.10.0
     - Symbol combo box added.
   * - 5.6.0
     - ``"\x03reset"`` added to edit report controls.
   * - 5.4.0
     - Graphic Control added. (See Example 19)
   * - 4.2.5
     - Radio buttons added.
   * - 4.2.4
     - Wizard-Parameter added.
   * - 4.2.2
     - Report control now editable.
   * - 4.2.0
     - Tree control and dialog box resizing added.

.. seealso::
   :ref:`overview-dialogboxes`,
   :ref:`MessageBox`,
   :ref:`GetSaveFileName`,
   :ref:`GetOpenFileName`,
   :ref:`GetDirectoryDialog`

:sub:`id-2012604`