Module 5 - Parameterization / 5.2 Parameter-Editing Dialogs |
To download the examples for Module 5, click Module_5_Examples.zip.
In this topic:
This topic addresses the following key concepts:
In this topic, you will learn the following:
In 5.2.1 Adding Basic Parameter-Editing Dialogs, you learned how to add basic dialog definitions. For many applications, the basic dialog is perfectly acceptable; however, when editing a large number of parameters, it is helpful to collect related parameters into a group box and then separate the group boxes on tabs. The resulting dialog is smaller, and the user is less likely to be overwhelmed by the number of controls presented at one time.
In this topic, you will learn the benefits of using the TabValueDialog to create parameter-editing dialogs.
The following dialog serves as an example to illustrate the hierarchy within a tabbed
dialog.
This hierarchical structure allows you to easily build custom dialog boxes to edit your model parameters; however, certain rules are absolute:
This dialog example requires far more information to generate the definition than the basic dialogs described in 5.2.1 Adding Basic Parameter-Editing Dialogs. The three additional data elements are described below:
The TabValueDialog function constructs a map of available tabs based on the tab titles you provide. Tabs are created in left-to-right order from the comma separated list of tabs definitions. In this dialog example, the TABS symbol property value has two elements separated by a comma as shown below:
Filter Pole Frequency,Other Parameters
The groups definition for any single group box is made up of 10 data fields described in the following table.
Data Field | Example Data Value | Description |
Parent Tab | Other Parameters | The tab defined in the Tabs section on which to create the group box. |
Group Type | GROUP |
|
Group Title | Gain and Resistor | Title for the group |
Starting Row | 0 | The starting row on the tab grid pattern. 0 is the first row |
Starting Column | 0 | The starting column on the tab grid pattern. 0 is the first column |
Ending Row | 0 |
The ending row on the tab grid pattern. Note: If
you make this number larger than the starting row, the group box spans
multiple rows.
|
Ending Column | 0 |
The ending column on the tab grid pattern Note: If
you make this number larger than the starting column, the group box
spans multiple columns.
|
Control Idx | 0 | The CHECK group type is
considered a Boolean parameter, which returns a value of 0 or 1; however,
to use a checkable group you must tell the program which parameter in the
parameter string, PARAMETERS, is assigned the returned value of Checked
(1) or not Checked (0). The Control Idx data element identifies which parameter should be assigned the checkable group box Boolean value. The first parameter in the PARAMETERS string is at index 0. To use the checkable group box, first assign the parameter-editing controls including a parameter name for the checkable group box. Then, assign the index of this parameter in the PARAMETERS string to the Control Idx for the Group definition. The Control Idx is ignored for the GROUP type. |
Add Vertical Lines | 1 | Adds a vertical separation line between multiple columns of parameter-editing controls in a single group box. Does nothing if the group has a single column of parameter-editing controls. |
Column Spacing | 0 | A positive integer to indicate the number of pixels between columns. 0 specifies the default, which is 6 pixels. |
As with the basic dialog definition, each group data element is concatenated with the colon character to produce a group definition string:
Other Parameters:GROUP:Gain and Resistor:0:0:0:0:0:1:0
Multiple group definitions are further concatenated with the comma character. This dialog example has two groups. The complete definition for both groups used in this dialog is as follows:
Filter Pole Frequency:GROUP:Filter Parameters:0:0:0:0:0:0:0,Other Parameters:GROUP:Gain and Resistor:0:0:0:0:0:1:0
The order of the individual group definitions doesn't matter. After concatenating this text string the group information is stored on the symbol property GROUPS.
The tabbed dialog provides a bold dialog title and a dialog caption. These two data elements are stored in a comma separated list on the DESCRIPTIONS symbol property. For this dialog, the dialog title is RC Filter, and the caption is Edit RC Filter. Notice in the dialog image, the caption is actually Edit RC Filter : U2. The colon and the reference designator are added by the valuescript when the user double clicks on the symbol. The complete DESCRIPTIONS definition for this dialog is as follows:
Edit RC Filter,RC Filter
Each parameter-editing control for the basic parameter-editing dialog has three data elements. For the tabbed value dialog, considerably more information is required, and there are 10 fields for each parameter-editing control as described in the following table.
Data Field | Example Data Value | Description | ||||||||||||||||||
Parent Tab | Other Parameters | The tab containing the group box and the parameter-editing control | ||||||||||||||||||
Parent Group | Gain and Resistor | The group on the Parent Tab in which to place this parameter editing control | ||||||||||||||||||
Descriptive Label | Filter Gain | Any text string which does not contain colon or comma characters | ||||||||||||||||||
Row | 0 | The row on the grid inside the group box to place this control. 0 is the first row | ||||||||||||||||||
Column | 0 | The column on the grid inside the group box to place this control. 0 is the first column | ||||||||||||||||||
Units | V/V | Any text string which does
not
contain colon or comma characters. Can contain the
following special keywords, which are case
sensitive!:
|
||||||||||||||||||
Type | LIST | Eight types of
parameter-editing controls are allowed with the TabValueDialog function.
The most common types are the Real and Integer spinner controls, followed
by the List and Boolean types. The String entry type can be used to
prompt the user for general string information and is used infrequently.
The eight types are
described in the table below:
|
||||||||||||||||||
Range | 1|2|5|10 | For REAL and INTEGER types,
the minimum and maximum values separated by a pipe "|" character.
Engineering suffixes are permitted.
For the LIST (used in this example) control type, the range is a pipe separated list of allowed values. The available options in the list box are populated from top to bottom with the range data in left-to-right order. |
||||||||||||||||||
Flags | 0 |
Four types can have an associated flag:
For all other data types, the value is ignored. |
||||||||||||||||||
Tool Tip | The Gain of the Filter | A text string which does not contain a colon or comma. The tool tip appears in a box with a yellow background when the user hovers the mouse over the control or the descriptive label for that control. |
As with the basic dialog definition, the data elements are concatenated with the colon character into a parameter-editing control definition. The single parameter-editing control definition for the Filter Gain control is as follows:
Other Parameters:Gain and Resistor:Filter Gain:1:0:V/V:LIST:1|2|5|10:0:The Gain of the Filter
Multiple parameter-editing control definitions are further concatenated with the comma character. This dialog example has three parameters and the complete definition for all parameters is as follows:
Filter Pole Frequency:Filter Parameters:Cutoff Frequency:0:0:Hz:REAL:1p|100G:0:The Filter Frequency,Other Parameters:Gain and Resistor:Resistor Value:1:1:__Ohms__:INT:1|100k:1:The resistor used in the filter,Other Parameters:Gain and Resistor:Filter Gain:1:0:V/V:LIST:1|2|5|10:0:The Gain of the Filter
As with the basic parameter-editing dialog, the order of the parameter editing control definitions must be the same as the parameters in the PARAMETERS symbol property. After concatenating the parameter-editing control definitions, the resulting string is stored on the LABELS symbol property.
The VALUESCRIPT symbol property holds the script name to execute when a user double clicks on the symbol. The tabbed parameter editing dialogs are only available for symbols which use the Multi-Property Method. The valuescript is:
edit_parameterised_multi_prop_device_tab_value_dialog 1
This valuescript takes a single argument - in this case 1. The argument determines if the reference designator is appended to the caption defined in the Descriptions. If the argument is 1, the reference designator is appended, if the argument is 0, the caption defined in the DESCRIPTIONS symbol property is used.
By now you should see the benefit of a tabbed dialog, especially for a large number of parameters. However, the complexity of this dialog definition can be overwhelming. As with the basic dialogs, a spreadsheet can help ease the design process.
This exercise walks you through the structure of the spreadsheet to help you understand the process.
In the next exercise you will add the tabbed parameter-editing dialog to the parameterized RC filter symbol.
As with the Basic Add Parameter-Editing Dialog Exercise, you will copy a set of script commands from the spreadsheet and execute the commands in SIMetrix/SIMPLIS.
In the previous exercise, you added a parameter-editing definition saved in the spreadsheet. This definition used three control types as a demonstration; however, the parameters being edited should be REAL types. In this exercise you will modify the dialog definition to use the REAL type control for all parameters. You will also move the three filter parameters onto one tab but inside two group boxes.
In addition to the common problems described in 5.2.1, What Can Go Wrong?, the tabbed value dialog has these additional common problems.