|
|
In this Topic Hide
SIMetrix has a feature that permits the creation of custom dialog boxes without the need to write program code. This can be done using a special graphical tool called the "SIMetrix Dialog Designer" supplied with SIMetrix from version 5.3. SIMetrix Dialog Designer is derived from a commericial tool developed by Trolltech AS who supply us with the Qt library used for SIMetrix UI development. Trolltech have kindly given us permission to ship this tool with SIMetrix. Note that "SIMetrix Dialog Designer" is a stripped down version of the full commercial product.
Currently we supply only a Windows version of this tool, but the dialogs generated will work with Linux versions of SIMetrix.
The tool is installed with the rest of the SIMetrix binaries and is called "designer.exe". Use windows explorer to locate designer.exe in the "bin" folder under the SIMetrix root. The SIMetrix installer does not create a short cut to this but you may create one yourself if required.
The basic procedure is:
Note that you do not need to restart after editing the dialog - only when creating it for the first time or when changing the function name. SIMetrix registers the filename and function name on startup, but will reread it when the function is called. This means that you can make changes to your dialog without having to shut down and restart SIMetrix each time.
You can select a different location for user dialogs with the option setting UserDialogsDir. Type this at the command line:
| Set UserDialogsDir=path |
"Widgets" are the dialog elements such as edit boxes and push buttons that you use to enter data and choices. In Windows "Widgets" are sometimes called "Controls".
A range of special widgets is supplied that have some extra properties to define how they will be initialised when the dialog is opened and what they will return through the SIMetrix script function call mechanism. These widgets can be found under the "SIMetrix" group. Always use these for anything used for data entry. Other widgets that do not require initialisation nor output data may also be used. E.g. the items under “Containers”. Note that the "Radio Button" widget in the "Buttons" group can only be used inside a "RadioGroup" which you will find in the SIMetrix group.
In general data is transferred to the dialog widgets by the arguments of the SIMetrix script function. Each argument is an array of strings and each widget may specify through its properties the argument index and the array element index where the data is located. In every case the data is a single string. If multiple values are required for a widget, it will either have multiple properties to define them, or, in the case of lists of values, the items will be delimited by a pipe ('|') symbol.
Data is returned in a similar manner. But as there is only one return value, just a single array element is specified.
There are five user settable properties in use by the various widgets, but not all widgets use all of the properties. Some widgets may have aditional special purpose properties. These five general properties are:
| Property Name | Description |
|---|---|
| argIndex | Index of script function argument used for initialisation of widget. First argument has index=0. You may use a maximum of 8 arguments so this property may not be larger than 7 |
| inElementIndex | Index into array supplied to argIndex for value used to initialise widget. First element has index=0 |
| outElementIndex | Index into array returned by script function for user entered value |
| itemsArgIndex | Index of script function argument used to supply items to initialise list. Items separated by pipe ('|') symbol. Currently used by list boxes and combo boxes. |
| itemsElementIndex | Index into array supplied to itemsArgIndex for items to initialise list. Items separated by pipe ('|') symbol. Currently used by list boxes and combo boxes |
The properties argIndex, inElementIndex and outElementIndex initialise and return the text value stored in a single line edit box.
As EditBox but multi-line.
Used for entering numeric values. argIndex, inElementIndex and outElementIndex used to initialise and return. Note that box stores a numeric value, but the script arguments must still be strings. This widget has the following properties that govern its behaviour:
| Property Name | Description |
|---|---|
| engMode | Boolean. If true, value is always displayed in engineering notaion using suffixes such as m, u, k etc |
| step125 | Boolean. If true, spinner buttons step in 1-2-5 sequence. Otherwise they step in a linear sequence controlled by the 'increment' property |
| increment | Increment for spinner buttons. Only effective if 'step125' property is false |
| max | Maximum value allowed for widget |
| min | Minimum value allowed for widget |
| precision | Value displayed and returned to precision specified. |
| allowExpressions | If true, the user may enter expressions enclosed with curly braces: '{' and '}'. If false, only numeric values will be allowed. |
A check box providing a simple on-off selection. argIndex, inElementIndex and outElementIndex used to define initial setting and return value in normal way. '1' indicates checked and '0' indicates unchecked. Label Static label. Can be set with static value in which case argIndex and inElementIndex should be -1. Alternatively can be initialised via function call using argIndex an inElementIndex. Does not return a value.
A container that should be filled with one or more Radio Buttons (these may be found under the "Buttons" group). Only one of the radio buttons in the group maybe checked at any time. The usual properties are used to initialise and the return values. '0' means check the top most button, '1' the second button, '2' the third etc.
A push button with two alternative modes of operation. If the property 'toggleButton' is false, then this may be used to close the dialog box. In this case the property 'action' must be set to either 'reject' or 'accept'. If 'reject' is set then the dialog box function will return an 'empty vector'. That is the array returned will have a length of zero. (You must test this with the script langauge's length() function). If set to 'accept' the normal data will be returned. The 'outElementIndex' property may be set in this case in which case the value returned will be 'clicked' if the button was clicked to close the box or 'notclicked'.
If 'toggleButton' is set to true then 'action' must be set to 'none' to be meaningful. In this case the button will toggle on or off. The return value controlled by outElementIndex will be either 'on' or 'off'. Currently there is no method to initialise the toggle state. This will be corrected in a later release.
These are identical to PushButton except for changes to default values of some properties. “Cancel Button” behaves as a button to cancel a dialog and will cause the calling function to return an empty vector. “Ok Button” closes a dialog and accepts the user’s input.
A list box containing a list of values. The values themselves are defined using itemsArgIndex and itemsElementIndex properties and must be in the form of a single string containing a list of values separated by a pipe symbol.
The initial value selected is defined by argIndex and inElementIndex. This is the actual value not the index into the list. The item selected in the list is returned in outElementIndex.
A drop down "combo box" otherwise the same as the ListBox.
This is experimental and currently unsupported.
SIMetrix Dialog Designer features an advanced system, known as geometry management, that automatically arranges widgets in the dialog. Geometry management controls the position and size of the widgets in a manner that maintains the layout in an aethestically pleasing form even if the dialog is resized.
These features are available via the "Layout" menu, via the toolbar and also with the context popup menu. The features available are:
The best way to learn about geometry management is to experiment with various widgets and containers. You may need to use the "spacer" widget available from the toolbar to provide empty spaces. Some widgets (e.g. buttons) resize to fill the space available and this is not always desirable. Further documentation on the Designer tool can be found at the developer's web site:
http://doc.trolltech.com. The version currently in use is 3.3. See under "Tools", the SIMetrix dialog designer is based on "Qt Designer".
A number of trivial examples are supplied that demonstrate each of the widgets. These are supplied in the examples directory under scripts/dialogs. To use them you must copy them to the support/dialogs folder (Windows) or /usr/local/share/dialogs folder (Linux). Here is a list:
Simple dialog with an edit box and an Ok button. Type:
| Show EditDialog(‘Initial message’) |
Demo of combo box, try this:
| Show TestCombo('bill', 'fred|bill|john') |
A spinner and a check box. Try:
| Show TestFunction([‘2.345’, ‘1’]) |
A list box and a check box, Try this:
| Show listboxfunction(['john','1'], 'fred|bill|john') |
TextEdit and two push buttons, one of them with toggle action. Try this:
| Show textedittest('A message') |
Bits and pieces. Try this:
| Show johnsmodeldialog(['bill', '2.345', '4.567', '1'], |
| 'fred|bill|john') |
A couple of radio buttons and a toggle button
| Show radiotest('1') |
The ExecuteDialog function executes a .sxdlg file directly using the dialog definition’s full path name. The first argument to this function is the full path to the dialog .sxdlg file and subsequent arguments are the dialog’s arguments shifted one place. So argument 0 of the dialog function is argument 1 of ExecuteDialog. Note that the first argument must be a full path, but you may use logical path symbols.
ExecuteDialog does not require the .sxdlg file to present when SIMetrix starts up unlike the usual method of calling the dialog functions.
All script functions are limited to a maximum of 8 arguments and ExecuteDialog is not an exception. Because the first argument is reserved for the path name, this means that the maximum number of arguments that can be passed to the dialog is 7. If calling the dialog directly, the limit is 8.
Complex dialog designs can take a noticeable time to open. This is because the definition file is read and parsed every time the dialog function is called.
|