User Language Dialogs allow you to define your own frontend to a User Language Program. The following sections describe User Language Dialogs in detail:
Predefined Dialogs implement the typical standard dialogs that are frequently used for selecting file names or issuing error messages.
See Dialog Objects for information on how to define your own complex user dialogs.
Function
Displays a directory dialog.
Syntax
string dlgDirectory(string Title[, string Start])
Returns
The dlgDirectory function returns the full pathname of the selected directory. If the user has canceled the dialog, the result will be an empty string.
See also dlgFileOpen
The dlgDirectory function displays a directory dialog from which the user can select a directory. Title will be used as the dialog's title.
If Start is not empty, it will be used as the starting point for the dlgDirectory.
Example
string dirName;
dirName = dlgDirectory("Select a directory", "");
Function
Displays a file dialog.
Syntax
string dlgFileOpen(string Title[, string Start[, string Filter]])
string dlgFileSave(string Title[, string Start[, string Filter]])
Returns
The dlgFileOpen and dlgFileSave functions return the full pathname of the selected file. If the user has canceled the dialog, the result will be an empty string.
See also dlgDirectory
The dlgFileOpen and dlgFileSave functions display a file dialog from which the user can select a file. Title will be used as the dialog's title.
If Start is not empty, it will be used as the starting point for the file dialog. Otherwise the current directory will be used.
Only files matching Filter will be displayed. If Filter is empty, all files will be displayed.
Filter can be either a simple wildcard (as in "*.brd"), a list of wildcards (as in "*.bmp *.jpg") or may even contain descriptive text, as in "Bitmap files (*.bmp)". If the "File type" combo box of the file dialog shall contain several entries, they have to be separated by double semicolons, as in "Bitmap files (*.bmp);; Other images (*.jpg *.png)".
Example
string fileName;
fileName = dlgFileOpen("Select a file", "", "*.brd");
Function
Displays a message box.
Syntax
int dlgMessageBox(string Message[, button_list])
Returns
The dlgMessageBox function returns the index of the button the user has selected. The first button in button_list has index 0.
See also status()
The dlgMessageBox function displays the given Message in a modal dialog and waits until the user selects one of the buttons defined in button_list.
If Message contains any HTML tags, the characters '<', '>' and '&' must be given as <, > and &, respectively, if they are to be displayed as such.
button_list is an optional list of comma separated strings, which defines the set of buttons that will be displayed at the bottom of the message box. A maximum of three buttons can be defined. If no button_list is given, it defaults to "OK".
The first button in button_list will become the default button (which will be selected if the user hits ENTER), and the last button in the list will become the "cancel button", which is selected if the user hits ESCape or closes the message box. You can make a different button the default button by starting its name with a '+', and you can make a different button the cancel button by starting its name with a '-'. To start a button text with an actual '+' or '-' it has to be escaped.
If a button text contains an '&', the character following the ampersand will become a hotkey, and when the user hits the corresponding key, that button will be selected. To have an actual '&' character in the text it has to be escaped.
The message box can be given an icon by setting the first character of Message to
';' - for an Information
'!' - for a Warning
':' - for an Error
If, however, the Message shall begin with one of these characters, it has to be escaped.
On Mac OS X only the character ':' will actually result in showing an icon. All others are ignored.
Example
if (dlgMessageBox("!Are you sure?", "&Yes", "&No") == 0) {
// let's do it!
}
A User Language Dialog is built from the following Dialog Objects:
| dlgCell | a grid cell context |
| dlgCheckBox | a checkbox |
| dlgComboBox | a combo box selection field |
| dlgDialog | the basic container of any dialog |
| dlgGridLayout | a grid based layout context |
| dlgGroup | a group field |
| dlgHBoxLayout | a horizontal box layout context |
| dlgIntEdit | an integer entry field |
| dlgLabel | a text label |
| dlgListBox | a list box |
| dlgListView | a list view |
| dlgPushButton | a push button |
| dlgRadioButton | a radio button |
| dlgRealEdit | a real entry field |
| dlgSpacing | a layout spacing object |
| dlgSpinBox | a spin box selection field |
| dlgStretch | a layout stretch object |
| dlgStringEdit | a string entry field |
| dlgTabPage | a tab page |
| dlgTabWidget | a tab page container |
| dlgTextEdit | a text entry field |
| dlgTextView | a text viewer field |
| dlgVBoxLayout | a vertical box layout context |
Function
Defines a cell location within a grid layout context.
Syntax
dlgCell(int row, int column[, int row2, int column2]) statement
See also dlgGridLayout, dlgHBoxLayout, dlgVBoxLayout, Layout Information, A Complete Example
The dlgCell statement defines the location of a cell within a grid layout context.
The row and column indexes start at 0, so the upper left cell has the index (0, 0).
With two parameters the dialog object defined by statement will be placed in the single cell addresses by row and column. With four parameters the dialog object will span over all cells from row/column to row2/column2.
By default a dlgCell contains a dlgHBoxLayout, so if the cell contains more than one dialog object, they will be placed next to each other horizontally.
Example
string Text;
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Cell 0,0");
dlgCell(1, 2, 4, 7) dlgTextEdit(Text);
}
Function
Defines a checkbox.
Syntax
dlgCheckBox(string Text, int &Checked) [ statement ]
See also dlgRadioButton, dlgGroup, Layout Information, A Complete Example
The dlgCheckBox statement defines a check box with the given Text.
If Text contains an '&', the character following the ampersand will become a hotkey, and when the user hits Alt+hotkey, the checkbox will be toggled. To have an actual '&' character in the text it has to be escaped.
dlgCheckBox is mainly used within a dlgGroup, but can also be used otherwise. All check boxes within the same dialog must have different Checked variables!
If the user checks a dlgCheckBox, the associated Checked variable is set to 1, otherwise it is set to 0. The initial value of Checked defines whether a checkbox is initially checked. If Checked is not equal to 0, the checkbox is initially checked.
The optional statement is executed every time the dlgCheckBox is toggled.
Example
int mirror = 0;
int rotate = 1;
int flip = 0;
dlgGroup("Orientation") {
dlgCheckBox("&Mirror", mirror);
dlgCheckBox("&Rotate", rotate);
dlgCheckBox("&Flip", flip);
}
Function
Defines a combo box selection field.
Syntax
dlgComboBox(string array[], int &Selected) [ statement ]
See also dlgListBox, dlgLabel, Layout Information, A Complete Example
The dlgComboBox statement defines a combo box selection field with the contents of the given array.
Selected reflects the index of the selected combo box entry. The first entry has index 0.
Each element of array defines the contents of one entry in the combo box. None of the strings in array may be empty (if there is an empty string, all strings after and including that one will be dropped).
The optional statement is executed whenever the selection in the dlgComboBox changes. Before the statement is executed, all variables that have been used with dialog objects are updated to their current values, and any changes made to these variables inside the statement will be reflected in the dialog when the statement returns.
If the initial value of Selected is outside the range of the array indexes, it is set to 0.
Example
string Colors[] = { "red", "green", "blue", "yellow" };
int Selected = 2; // initially selects "blue"
dlgComboBox(Colors, Selected) dlgMessageBox("You have selected " + Colors[Selected]);
Function
Executes a User Language Dialog.
Syntax
int dlgDialog(string Title) block ;
Returns
The dlgDialog function returns an integer value that can be given a user defined meaning through a call to the dlgAccept() function.
If the dialog is simply closed, the return value will be -1.
See also dlgGridLayout, dlgHBoxLayout, dlgVBoxLayout, dlgAccept, dlgReset, dlgReject, A Complete Example
The dlgDialog function executes the dialog defined by block. This is the only dialog object that actually is a User Language builtin function. Therefore it can be used anywhere where a function call is allowed.
The block normally contains only other dialog objects, but it is also possible to use other User Language statements, for example to conditionally add objects to the dialog (see the second example below).
By default a dlgDialog contains a dlgVBoxLayout, so a simple dialog doesn't have to worry about the layout.
A dlgDialog should at some point contain a call to the dlgAccept() function in order to allow the user to close the dialog and accept its contents.
If all you need is a simple message box or file dialog you might want to use one of the Predefined Dialogs instead.
Examples
int Result = dlgDialog("Hello") {
dlgLabel("Hello world");
dlgPushButton("+OK") dlgAccept();
};
int haveButton = 1;
dlgDialog("Test") {
dlgLabel("Start");
if (haveButton)
dlgPushButton("Here") dlgAccept();
};
Function
Opens a grid layout context.
Syntax
dlgGridLayout statement
See also dlgCell, dlgHBoxLayout, dlgVBoxLayout, Layout Information, A Complete Example
The dlgGridLayout statement opens a grid layout context.
The only dialog object that can be used directly in statement is dlgCell, which defines the location of a particular dialog object within the grid layout.
The row and column indexes start at 0, so the upper left cell has the index (0, 0).
The number of rows and columns is automatically extended according to the location of dialog objects that are defined within the grid layout context, so you don't have to explicitly define the number of rows and columns.
Example
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Row 0/Col 0");
dlgCell(1, 0) dlgLabel("Row 1/Col 0");
dlgCell(0, 1) dlgLabel("Row 0/Col 1");
dlgCell(1, 1) dlgLabel("Row 1/Col 1");
}
Function
Defines a group field.
Syntax
dlgGroup(string Title) statement
See also dlgCheckBox, dlgRadioButton, Layout Information, A Complete Example
The dlgGroup statement defines a group with the given Title.
By default a dlgGroup contains a dlgVBoxLayout, so a simple group doesn't have to worry about the layout.
dlgGroup is mainly used to contain a set of radio buttons or check boxes, but may as well contain any other objects in its statement. Radio buttons within a dlgGroup are numbered starting with 0.
Example
int align = 1;
dlgGroup("Alignment") {
dlgRadioButton("&Top", align);
dlgRadioButton("&Center", align);
dlgRadioButton("&Bottom", align);
}
Function
Opens a horizontal box layout context.
Syntax
dlgHBoxLayout statement
See also dlgGridLayout, dlgVBoxLayout, Layout Information, A Complete Example
The dlgHBoxLayout statement opens a horizontal box layout context for the given statement.
Example
dlgHBoxLayout {
dlgLabel("Box 1");
dlgLabel("Box 2");
dlgLabel("Box 3");
}
Function
Defines an integer entry field.
Syntax
dlgIntEdit(int &Value, int Min, int Max)
See also dlgRealEdit, dlgStringEdit, dlgLabel, Layout Information, A Complete Example
The dlgIntE*dit statement defines an integer entry field with the given Value.
If Value is initially outside the range defined by Min and Max it will be limited to these values.
Example
int Value = 42;
dlgHBoxLayout {
dlgLabel("Enter a &Number between 0 and 99");
dlgIntEdit(Value, 0, 99);
}
Function
Defines a text label.
Syntax
dlgLabel(string Text [, int Update])
See also Layout Information, A Complete Example, dlgRedisplay()
The dlgLabel statement defines a label with the given Text.
Text can be either a string literal, as in "Hello", or a string variable.
If Text contains any HTML tags, the characters '<', '>' and '&' must be given as "<", ">" and "&", respectively, if they shall be displayed as such.
External hyperlinks in the Text will be opened with the appropriate application program.
If the Update parameter is not 0 and Text is a string variable, its contents can be modified in the statement of, for example, a dlgPushButton, and the label will be automatically updated. This, of course, is only useful if Text is a dedicated string variable (not, for example, the loop variable of a for statement).
If Text contains an '&', and the object following the label can have the keyboard focus, the character following the ampersand will become a hotkey, and when the user hits Alt+hotkey, the focus will go to the object that was defined immediately following the dlgLabel. To have an actual '&' character in the text it has to be escaped.
Example
string OS = "Windows";
dlgHBoxLayout {
dlgLabel(OS, 1);
dlgPushButton("&Change OS") { OS = "Linux"; }
}
Function
Defines a list box selection field.
Syntax
dlgListBox(string array[], int &Selected) [ statement ]
See also dlgComboBox, dlgListView, dlgSelectionChanged, dlgLabel, Layout Information, A Complete Example
The dlgListBox statement defines a list box selection field with the contents of the given array.
Selected reflects the index of the selected list box entry. The first entry has index 0.
Each element of array defines the contents of one line in the list box. None of the strings in array may be empty (if there is an empty string, all strings after and including that one will be dropped).
The optional statement is executed whenever the user double clicks on an entry of the dlgListBox (see dlgSelectionChanged for information on how to have the statement called when only the selection in the list changes). Before the statement is executed, all variables that have been used with dialog objects are updated to their current values, and any changes made to these variables inside the statement will be reflected in the dialog when the statement returns.
If the initial value of Selected is outside the range of the array indexes, no entry will be selected.
Example
string Colors[] = { "red", "green", "blue", "yellow" };
int Selected = 2; // initially selects "blue"
dlgListBox(Colors, Selected) dlgMessageBox("You have selected " + Colors[Selected]);
Function
Defines a multi column list view selection field.
Syntax
dlgListView(string Headers, string array[], int &Selected[, int &Sort]) [ statement ]
See also dlgListBox, dlgSelectionChanged, dlgLabel, Layout Information, A Complete Example
The dlgListView statement defines a multi column list view selection field with the contents of the given array.
Headers is the tab separated list of column headers.
Selected reflects the index of the selected list view entry in the array (the sequence in which the entries are actually displayed may be different, because the contents of a dlgListView can be sorted by the various columns). The first entry has index 0.
If no particular entry shall be initially selected, Selected should be initialized to -1. If it is set to -2, the first item according to the current sort column is made current. If no view entry has been selected, -1 is returned.
Sort defines which column should be used to sort the list view. The leftmost column is numbered 1. The sign of this parameter defines the direction in which to sort (positive values sort in ascending order). If Sort is 0 or outside the valid number of columns, no sorting will be done. The returned value of Sort reflects the column and sort mode selected by the user by clicking on the list column headers. By default dlgListView sorts by the first column, in ascending order.
Each element of array defines the contents of one line in the list view, and must contain tab separated values. If there are fewer values in an element of array than there are entries in the Headers string the remaining fields will be empty. If there are more values in an element of array than there are entries in the Headers string the superfluous elements will be silently dropped. None of the strings in array may be empty (if there is an empty string, all strings after and including that one will be dropped).
A list entry that contains line feeds ('\n') will be displayed in several lines accordingly.
The optional statement is executed whenever the user double clicks on an entry of the dlgListView (see dlgSelectionChanged for information on how to have the statement called when only the selection in the list changes). Before the statement is executed, all variables that have been used with dialog objects are updated to their current values, and any changes made to these variables inside the statement will be reflected in the dialog when the statement returns.
If the initial value of Selected is outside the range of the array indexes, no entry will be selected.
If Headers is an empty string, the first element of the array is used as the header string. Consequently the index of the first entry is then 1.
The contents of a dlgListView can be sorted by any column by clicking on that column's header. Columns can also be swapped by "click&dragging" a column header. Note that none of these changes will have any effect on the contents of the array. If the contents shall be sorted alphanumerically a numeric string[] array can be used.
Example
string Colors[] = { "red\tThe color RED", "green\tThe color GREEN", "blue\tThe color BLUE" };
int Selected = 0; // initially selects "red"
dlgListView("Name\tDescription", Colors, Selected) dlgMessageBox("You have selected " + Colors[Selected]);
Function
Defines a push button.
Syntax
dlgPushButton(string Text) statement
See also Layout Information, Dialog Functions, A Complete Example
The dlgPushButton statement defines a push button with the given Text.
If Text contains an '&', the character following the ampersand will become a hotkey, and when the user hits Alt+hotkey, the button will be selected. To have an actual '&' character in the text it has to be escaped.
If Text starts with a '+' character, this button will become the default button, which will be selected if the user hits ENTER. If Text starts with a '-' character, this button will become the cancel button, which will be selected if the user closes the dialog.
Make sure that the statement of such a marked cancel button contains a call to dlgReject()! Otherwise the user may be unable to close the dialog at all!
To have an actual '+' or '-' character as the first character of the text it has to be escaped.
If the user selects a dlgPushButton, the given statement is executed. Before the statement is executed, all variables that have been used with dialog objects are updated to their current values, and any changes made to these variables inside the statement will be reflected in the dialog when the statement returns.
Example
int defaultWidth = 10;
int defaultHeight = 20;
int width = 5;
int height = 7;
dlgPushButton("&Reset defaults") {
width = defaultWidth;
height = defaultHeight;
}
dlgPushButton("+&Accept") dlgAccept();
dlgPushButton("-Cancel") { if (dlgMessageBox("Are you sure?", "Yes", "No") == 0) dlgReject(); }
Function
Defines a radio button.
Syntax
dlgRadioButton(string Text, int &Selected) [ statement ]
See also dlgCheckBox, dlgGroup, Layout Information, A Complete Example
The dlgRadioButton statement defines a radio button with the given Text.
If Text contains an '&', the character following the ampersand will become a hotkey, and when the user hits Alt+hotkey, the button will be selected. To have an actual '&' character in the text it has to be escaped.
dlgRadioButton can only be used within a dlgGroup. All radio buttons within the same group must use the same Selected variable!
If the user selects a dlgRadioButton, the index of that button within the dlgGroup is stored in the Selected variable. The initial value of Selected defines which radio button is initially selected. If Selected is outside the valid range for this group, no radio button will be selected. In order to get the correct radio button selection, Selected must be set before the first dlgRadioButton is defined, and must not be modified between adding subsequent radio buttons. Otherwise it is undefined which (if any) radio button will be selected.
The optional statement is executed every time the dlgRadioButton is selected.
Example
int align = 1;
dlgGroup("Alignment") {
dlgRadioButton("&Top", align);
dlgRadioButton("&Center", align);
dlgRadioButton("&Bottom", align);
}
Function
Defines a real entry field.
Syntax
dlgRealEdit(real &Value, real Min, real Max)
See also dlgIntEdit, dlgStringEdit, dlgLabel, Layout Information, A Complete Example
The dlgRealEdit statement defines a real entry field with the given Value.
If Value is initially outside the range defined by Min and Max it will be limited to these values.
Example
real Value = 1.4142;
dlgHBoxLayout {
dlgLabel("Enter a &Number between 0 and 99");
dlgRealEdit(Value, 0.0, 99.0);
}
Function
Defines additional space in a box layout context.
Syntax
dlgSpacing(int Size)
See also dlgHBoxLayout, dlgVBoxLayout, dlgStretch, Layout Information, A Complete Example
The dlgSpacing statement defines additional space in a vertical or horizontal box layout context.
Size defines the number of pixels of the additional space.
Example
dlgVBoxLayout {
dlgLabel("Label 1");
dlgSpacing(40);
dlgLabel("Label 2");
}
Function
Defines a spin box selection field.
Syntax
dlgSpinBox(int &Value, int Min, int Max)
See also dlgIntEdit, dlgLabel, Layout Information, A Complete Example
The dlgSpinBox statement defines a spin box entry field with the given Value.
If Value is initially outside the range defined by Min and Max it will be limited to these values.
Example
int Value = 42;
dlgHBoxLayout {
dlgLabel("&Select value");
dlgSpinBox(Value, 0, 99);
}
Function
Defines an empty stretchable space in a box layout context.
Syntax
dlgStretch(int Factor)
See also dlgHBoxLayout, dlgVBoxLayout, dlgSpacing, Layout Information, A Complete Example
The dlgStretch statement defines an empty stretchable space in a vertical or horizontal box layout context.
Factor defines the stretch factor of the space.
Example
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") { dlgAccept(); };
dlgPushButton("Cancel") { dlgReject(); };
}
Function
Defines a string entry field.
Syntax
dlgStringEdit(string &Text[, string &History[][, int Size]])
See also dlgRealEdit, dlgIntEdit, dlgTextEdit, dlgLabel, Layout Information, A Complete Example
The dlgStringEdit statement defines a one line text entry field with the given Text.
If History is given, the strings the user has entered over time are stored in that string array. The entry field then has a button that allows the user to select from previously entered strings. If a Size greater than zero is given, only at most that number of strings are stored in the array. If History contains data when the dialog is newly opened, that data will be used to initialize the history. The most recently entered user input is stored at index 0. None of the strings in History can be empty. If there is an empty string, all strings after and including that one will be dropped.
Example
string Name = "Linus";
dlgHBoxLayout {
dlgLabel("Enter &Name");
dlgStringEdit(Name);
}
Function
Defines a tab page.
Syntax
dlgTabPage(string Title) statement
See also dlgTabWidget, Layout Information, A Complete Example
The dlgTabPage statement defines a tab page with the given Title containing the given statement.
If Title contains an '&', the character following the ampersand will become a hotkey, and when the user hits Alt+hotkey, this tab page will be opened. To have an actual '&' character in the text it has to be escaped.
Tab pages can only be used within a dlgTabWidget.
By default a dlgTabPage contains a dlgVBoxLayout, so a simple tab page doesn't have to worry about the layout.
Example
dlgTabWidget {
dlgTabPage("Tab &1") {
dlgLabel("This is page 1");
}
dlgTabPage("Tab &2") {
dlgLabel("This is page 2");
}
}
Function
Defines a container for tab pages.
Syntax
dlgTabWidget { tabpages }
dlgTabWidget(int &Index) { tabpages }
See also dlgTabPage, Layout Information, A Complete Example
The dlgTabWidget defines a container for a set of tab pages.
tabpages must be a sequence of one or more dlgTabPage objects. There must be no other dialog objects in this sequence.
Index defines which tab should be selected initially. If this selection changes the variable Index is set accordingly. The first page has index 0 (independent of its title).
Examples
dlgTabWidget {
dlgTabPage("Tab &1") {
dlgLabel("This is page 1");
}
dlgTabPage("Tab &2") {
dlgLabel("This is page 2");
}
}
dlgDialog("test")
{
int TabNr = 0;
int CheckBoxValue[];
dlgTabWidget(TabNr) {
for (int i = 0; i <= 9; i++) {
string s;
sprintf(s, "%d", i);
dlgTabPage("Tab " + s) {
dlgLabel("This is page " + s);
dlgCheckBox(s, CheckBoxValue[i]) {
string Msg;
sprintf(Msg, "Value #%d: %d\n", TabNr, CheckBoxValue[TabNr]);
dlgMessageBox(Msg);
}
}
}
}
};
Function
Defines a multiline text entry field.
Syntax
dlgTextEdit(string &Text)
See also dlgStringEdit, dlgTextView, dlgLabel, Layout Information, A Complete Example
The dlgTextEdit statement defines a multiline text entry field with the given Text.
The lines in the Text have to be delimited by a newline character ('\n'). Any whitespace characters at the end of the lines contained in Text will be removed, and upon return there will be no whitespace characters at the end of the lines. Empty lines at the end of the text will be removed entirely.
Example
string Text = "This is some text.\nLine 2\nLine 3";
dlgVBoxLayout {
dlgLabel("&Edit the text");
dlgTextEdit(Text);
}
Function
Defines a multiline text viewer field.
Syntax
dlgTextView(string Text) dlgTextView(string Text, string &Link) statement
See also dlgTextEdit, dlgLabel, Layout Information, A Complete Example
The dlgTextView statement defines a multiline text viewer field with the given Text.
The Text may contain HTML tags.
External hyperlinks in the Text will be opened with the appropriate application program.
If Link is given and the Text contains hyperlinks, statement will be executed every time the user clicks on a hyperlink, with the value of Link set to whatever the <a href=...> tag defines as the value of href. If, after the execution of statement, the Link variable is not empty, the default handling of hyperlinks will take place. This is also the case if Link contains some text before dlgTextView is opened, which allows for an initial scrolling to a given position. If a Link is given, external hyperlinks will not be opened.
Example
string Text = "This is some text.\nLine 2\nLine 3"; dlgVBoxLayout { dlgLabel("&View the text"); dlgTextView(Text); }
Function
Opens a vertical box layout context.
Syntax
dlgVBoxLayout statement
See also dlgGridLayout, dlgHBoxLayout, Layout Information, A Complete Example
The dlgVBoxLayout statement opens a vertical box layout context for the given statement.
By default a dlgDialog contains a dlgVBoxLayout, so a simple dialog doesn't have to worry about the layout.
Example
dlgVBoxLayout {
dlgLabel("Box 1");
dlgLabel("Box 2");
dlgLabel("Box 3");
}
All objects within a User Language Dialog a placed inside a layout context.
Layout contexts can be either grid, horizontal or vertical.
Objects in a grid layout context must specify the grid coordinates of the cell or cells into which they shall be placed. To place a text label at row 5, column 2, you would write
dlgGridLayout {
dlgCell(5, 2) dlgLabel("Text");
}
If the object shall span over more than one cell, you need to specify the coordinates of the starting cell and the ending cell. To place a group that extends from row 1, column 2 up to row 3, column 5, you would write
dlgGridLayout {
dlgCell(1, 2, 3, 5) dlgGroup("Title") {
//...
}
}
Objects in a horizontal layout context are placed left to right. The special objects dlgStretch and dlgSpacing can be used to further refine the distribution of the available space.
To define two buttons that are pushed all the way to the right edge of the dialog, you would write
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") dlgAccept();
dlgPushButton("Cancel") dlgReject();
}
Objects in a vertical layout context follow the same rules as those in a horizontal layout context, except that they are placed top to bottom.
Vertical, horizontal and grid layout contexts can be mixed to create the desired layout structure of a dialog. See the complete example for a demonstration of this.
The following functions can be used with User Language Dialogs:
Function
Closes the dialog and accepts its contents.
Syntax
void dlgAccept([ int Result ]);
See also dlgReject, dlgDialog, A Complete Example
The dlgAccept function causes the dlgDialog to be closed and return after the current statement sequence has been completed.
Any changes the user has made to the dialog values will be accepted and are copied into the variables that have been given when the dialog objects were defined.
The optional Result is the value that will be returned by the dialog. Typically this should be a positive integer value. If no value is given, it defaults to 1.
Note that dlgAccept() does return to the normal program execution, so in a sequence like
dlgPushButton("OK") {
dlgAccept();
dlgMessageBox("Accepting!");
}
the statement after dlgAccept() will still be executed!
Example
int Result = dlgDialog("Test") {
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
};
Function
Redisplays the dialog after changing values.
Syntax
void dlgRedisplay(void);
See also dlgReset, dlgDialog, A Complete Example
The dlgRedisplay function can be called to immediately refresh the dlgDialog after changes have been made to the variables used when defining the dialog objects.
You only need to call dlgRedisplay() if you want the dialog to be refreshed while still executing program code. In the example below the status is changed to "Running..." and dlgRedisplay() has to be called to make this change take effect before the "program action" is performed. After the final status change to "Finished." there is no need to call dlgRedisplay(), since all dialog objects are automatically updated after leaving the statement.
Example
string Status = "Idle";
int Result = dlgDialog("Test") {
dlgLabel(Status, 1); // note the '1' to tell the label to be updated!
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
dlgPushButton("Run") {
Status = "Running...";
dlgRedisplay();
// some program action here...
Status = "Finished.";
}
};
Function
Resets all dialog objects to their initial values.
Syntax
void dlgReset(void);
See also dlgReject, dlgDialog, A Complete Example
The dlgReset function copies the initial values back into all dialog objects of the current dlgDialog.
Any changes the user has made to the dialog values will be discarded.
Calling dlgReject() implies a call to dlgReset().
Example
int Number = 1;
int Result = dlgDialog("Test") {
dlgIntEdit(Number);
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
dlgPushButton("Reset") dlgReset();
};
Function
Closes the dialog and rejects its contents.
Syntax
void dlgReject([ int Result ]);
See also dlgAccept, dlgReset, dlgDialog, A Complete Example
The dlgReject function causes the dlgDialog to be closed and return after the current statement sequence has been completed.
Any changes the user has made to the dialog values will be discarded. The variables that have been given when the dialog objects were defined will be reset to their original values when the dialog returns.
The optional Result is the value that will be returned by the dialog. Typically this should be 0 or a negative integer value. If no value is given, it defaults to 0.
Note that dlgReject() does return to the normal program execution, so in a sequence like
dlgPushButton("Cancel") {
dlgReject();
dlgMessageBox("Rejecting!");
}
the statement after dlgReject() will still be executed!
Calling dlgReject() implies a call to* dlgReset()*.
Example
int Result = dlgDialog("Test") {
dlgPushButton("+OK") dlgAccept(42);
dlgPushButton("Cancel") dlgReject();
};
Function
Tells whether the current selection in a dlgListView or dlgListBox has changed.
Syntax
int dlgSelectionChanged(void);
Returns
The dlgSelectionChanged function returns a nonzero value if only the selection in the list has changed.
See also dlgListView, dlgListBox
The dlgSelectionChanged function can be used in a list context to determine whether the statement of the dlgListView or dlgListBox was called because the user double clicked on an item, or whether only the current selection in the list has changed.
If the statement of a dlgListView or dlgListBox doesn't contain any call to dlgSelectionChanged, that statement is only executed when the user double clicks on an item in the list. However, if a ULP needs to react on changes to the current selection in the list, it can call dlgSelectionChanged within the list's statement. This causes the statement to also be called if the current selection in the list changes.
If a list item is initially selected when the dialog is opened and the list's statement contains a call to dlgSelectionChanged, the statement is executed with dlgSelectionChanged returning true in order to indicate the initial change from "no selection" to an actual selection. Any later programmatical changes to the strings or the selection of the list will not trigger an automatic execution of the list's statement. This is important to remember in case the current list item controls another dialog object, for instance a dlgTextView that shows an extended representation of the currently selected item.
Example
string Colors[] = { "red\tThe color RED", "green\tThe color GREEN", "blue\tThe color BLUE" };
int Selected = 0; // initially selects "red"
string MyColor;
dlgLabel(MyColor, 1);
dlgListView("Name\tDescription", Colors, Selected) {
if (dlgSelectionChanged())
MyColor = Colors[Selected];
else
dlgMessageBox("You have chosen " + Colors[Selected]);
}
Some characters have special meanings in button or label texts, so they need to be escaped if they are to appear literally. To do this you need to prepend the character with a backslash, as in
dlgLabel("Miller \\& Co.");
This will result in "Miller & Co." displayed in the dialog. Note that there are actually two backslash characters here, since this line will first go through the User Language parser, which will strip the first backslash.
Here is a complete example of a User Language Dialog:
int hor = 1;
int ver = 1;
string fileName;
int Result = dlgDialog("Enter Parameters") {
dlgHBoxLayout {
dlgStretch(1);
dlgLabel("This is a simple dialog");
dlgStretch(1);
}
dlgHBoxLayout {
dlgGroup("Horizontal") {
dlgRadioButton("&Top", hor);
dlgRadioButton("&Center", hor);
dlgRadioButton("&Bottom", hor);
}
dlgGroup("Vertical") {
dlgRadioButton("&Left", ver);
dlgRadioButton("C&enter", ver);
dlgRadioButton("&Right", ver);
}
}
dlgHBoxLayout {
dlgLabel("File &name:");
dlgStringEdit(fileName);
dlgPushButton("Bro&wse") {
fileName = dlgFileOpen("Select a file", fileName);
}
}
dlgGridLayout {
dlgCell(0, 0) dlgLabel("Row 0/Col 0");
dlgCell(1, 0) dlgLabel("Row 1/Col 0");
dlgCell(0, 1) dlgLabel("Row 0/Col 1");
dlgCell(1, 1) dlgLabel("Row 1/Col 1");
}
dlgSpacing(10);
dlgHBoxLayout {
dlgStretch(1);
dlgPushButton("+OK") dlgAccept();
dlgPushButton("Cancel") dlgReject();
}
};