5.2.1 Adding Basic Parameter-Editing Dialogs

To download the examples for Module 5, click Module_5_Examples.zip.

In this topic:

Key Concepts

This topic addresses the following key concepts:

  • Basic Parameter-Editing Dialog definitions require three symbol properties:
    • LABELS
    • PARAMETERS
    • VALUESCRIPT
  • Each parameter editing control definition is a string concatenation of the descriptive label, the control type, and the allowed range.
  • The LABELS property contains all parameter editing control definitions concatenated with comma delimiters.
  • You can use a spreadsheet to concatenate the parameter control definitions.
  • You can copy script commands from a spreadsheet and paste the commands in the command line to execute the commands.
  • After you have added the symbol properties, you need to use a different script command to change the properties.

What You Will Learn

In this topic, you will learn the following:

  • The required data fields for each parameter-editing control definition
  • How to concatenate individual parameter-editing control definitions
  • Where the parameter-editing control data is stored
  • The form in which the symbol property, PARAMETERS, stores the parameter names and default values
  • How to use a parameter definition spreadsheet to define a basic parameter editing dialog

Parameter-Editing Control Data Fields

In this topic, you will add a basic parameter-editing dialog to the parameterized RC filter schematic component symbol. Consider the following dialog configured to edit the three parameters used in the parameterized RC filter subcircuit:

To define each parameter-editing control, three data elements are required: Descriptive Label, Type, and Range. The following table describes these elements in detail.

Parameter-Editing Control Fields

Data Element Example Data Value Description
Descriptive Label Cutoff Frequency (Hz) Any text string which does not contain the colon or comma characters. The descriptive label is compliant with basic HTML markup, which means that you can do the following:
  • Enclose text in <b> and </b> tags to create bold text.
  • Add <br /> to create a line break.
  • Place text that should remain on a single line inside the html markup, <nobr> ... </nobr> to prevent a line break.
Type REAL Five types of parameter-editing controls are allowed with NewValueDialog 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 five types are described in the table below:
Type Example Application
REAL General parameters whose values can be floating point numbers
INTEGER Parameters whose the values must be limited to integers
STRING Parameter values which are text
BOOL Logical true or false parameter values
LIST Parameters whose values must be limited to a list of values. Although this example uses Y/N, any list of values can be used.
Range 1p|100G
  • To define only a minimum, enter the minimum value in this field.
  • To define only a maximum, enter the pipe (|) followed by the maximum value.  
For the LIST 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.

Concatenating Data Fields

In SIMetrix/SIMPLIS, the three data fields for each control are concatenated into a string using the colon character as a delimiter. For example, the three data elements for the Cutoff Frequency parameter control are concatenated into the following string with the colons in red:

Cutoff Frequency (Hz):REAL:1p|100G

This string is a complete parameter-editing control definition for a single parameter. Multiple parameter-editing control definitions are further concatenated to create a single string to define the set of parameter-editing controls for a dialog.

Concatenating Parameter-Editing Control Definitions

Each parameter-editing control definition is then concatenated into a single string using the comma character as a delimiter. In this example, there are three parameter-editing controls, and the concatenated string of parameter-editing control definitions is shown below with the commas in red: 

Cutoff Frequency (Hz):REAL:1p|100G,Resistor Value (ohms):INT:1|100k,Filter Gain (V/V):LIST:1|2|5|10

Adding the Dialog Definition to the Symbol

The actual parameter-editing functionality is provided by a script. In topic 4.0 What is a Symbol?, you learned that the VALUESCRIPT symbol property holds the script name which is executed when you double click on the symbol. SIMetrix/SIMPLIS includes parameter-editing valuescripts that are specialized for the combination of each dialog definition (NewValueDialog or TabValueDialog) with each parameterization method (Single-Property or Multi-Property).

All valuescripts read the symbol or subcircuit definition for the dialog definition and then present the user with the dialog for editing. In this section, you will store the dialog definition on three Reserved Symbol Properties.

The LABELS Symbol Property

All parameter-editing dialogs use the LABELS symbol property to store the parameter-editing control information. The following string defines the LABELS property for the parameter-editing dialog shown below:

Cutoff Frequency (Hz):REAL:1p|100G,Resistor Value (ohms):INT:1|100k,Filter Gain (V/V):LIST:1|2|5|10

The PARAMETERS Symbol Property

The PARAMETERS symbol property holds the parameter names and their default values in a parameter string. In this example, the PARAMETERS property is:

FC=10k R_VAR=1k GAIN=1
CAUTION:
The parameter names in the PARAMETERS symbol property must be in the same order as the parameter-editing control definitions stored in the LABELS symbol property.

The VALUESCRIPT Symbol Property

The VALUESCRIPT symbol property holds the script name to execute when a user double clicks on the symbol. This example uses the Multi-Property Method, which requires the multi-property valuescript:

edit_parameterised_multi_prop_device

Spreadsheet Tool

Although the amount of data required to define a parameter-editing dialog is reasonable, the syntax is exacting. For this reason, a spreadsheet tool has been created to help define dialog parameter-editing controls. This spreadsheet,   5.3_new_value_dialog_definition_worksheet.xlsx, is included with the Module 5, in the  Module_5_Examples.zip file.

In the next exercise, you will add the dialog definition described in this topic to the multi-property parameterized RC filter symbol using the spreadsheet.

Exercise #1: The NewValueDialog Spreadsheet

  1. Open the spreadsheet 5.3_new_value_dialog_definition_worksheet.xlsx located in the C:\Training\Module_5_Examples directory.
  2. Notice the following formats:
    • User inputs are formatted as follows:
    • Calculated cells are shown with the this format:
  3. Notice the content of the various columns and rows:
    • Columns B and C contain the parameter names and default values, respectively.
    • Columns E, F, and G contain the Descriptive Label, Type and Range data fields.
    • Rows 8 through 10 hold the parameter-editing control definitions. Each row concatenates the PARAMETERS (column D) and LABELS (column H) properties with the appropriate delimiters.
    • The Blue text in cells B14, B15, and B16 contain the LABELS, PARAMETERS and VALUESCRIPT property values which define this dialog.
    • Three script commands are concatenated in cells B19, B20, and B21. When executed in SIMetrix/SIMPLIS, these commands add the symbol properties to the symbol that is currently open in the Symbol Editor.
    • Three additional script commands are concatenated in cells B24, B25, and B26. These commands are used to change the symbol properties once the properties have been added.

Exercise #2: Add Parameter-Editing Dialog

Instead of adding individual symbol properties in this exercise, you will copy a set of script commands from the spreadsheet and execute the commands in SIMetrix/SIMPLIS.

  1. Open the schematic 5.5_parametrized_rc_filters_multi_prop_dialogs.sxsch.
  2. To add the parameter-editing control definitions to the symbol for the parameterized RC filter, follow these steps:
    1. On the SIMetrix/SIMPLIS schematic, select the symbol for U2.
    2. To open the schematic component in the Symbol Editor, type the keyboard shortcut Shift+S, or right click and select Edit Symbol....
      Result: The symbol opens in the Symbol Editor.
    3. Navigate to the spreadsheet window, and select the red text in cells B19, B20, and B21.
      Result: The selected cells should appear as follows:
    4. Press Ctrl+C to copy the cells to the Windows clipboard.
      Result: The selected cells have an animated border indicating the cells are selected.
    5. Navigate to the SIMetrix/SIMPLIS command shell window.
    6. Click the mouse in the command line entry located at the top of the command shell window:
    7. Press Ctrl+V to paste the commands in the command line.
      Result: The last part of the command string is visible in the command line:
    8. Press Enter, or click Ok on the command line.
      Result: The commands are executed in SIMetrix/SIMPLIS. Each AddSymbolProperty command adds a single symbol property to the symbol. The commands apply the Hidden and Protected property flags and add the properties below the symbol.
  3. Press Ctrl+S to save the symbol, and then click Ok on the Save Symbol dialog.
  4. Navigate to the Schematic Editor window. Double click on U2, which is the RC filter attached to the multi-prop(30kHz) probe.
    Result: The parameter-editing dialog opens:
  5. Change the Resistor Value from 1k to 10k.
  6. Click Ok to save your changes.
    Result: The parameter value for R_VAR changes to 10000 on the symbol.
    Note: The parameter-editing control for the resistor value is currently an integer type control, which returns numbers in non-engineering notation.

Exercise #3: Modify The Dialog Definition

In the previous exercise you added the 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.

As you modify the spreadsheet, the script commands will automatically reflect your changes. When you go to modify the existing dialog definition, you will still use the AddSymbolProperty command.

  1. Navigate to the spreadsheet window.
  2. Modify cells F9 and F10 to be REAL. Note that the spreadsheet only allows the values you can select in the drop-down list.
  3. Delete the Range entry for the Gain parameter in cell G10. This will allow any gain, including negative gain to be input into the parameter-editing control.
    Result: : The changed cells in the spreadsheet appear as follows:
  4. Copy the red script commands in cells B19, B20, and B21, and paste them into the SIMetrix/SIMPLIS command line as before. and press enter or click Ok.
    Note: You must have the symbol editor open and the parameterized RC filter symbol loaded before executing these commands and the symbol properties must already exist on the symbol.
  5. Press Ctrl+S to save the symbol, and then click Ok on the Save Symbol dialog.
  6. Double click on U2, the RC Filter symbol.
    Result: : The modified dialog opens. Each control type is a Real type, and any gain value, positive or negative can be input into the Filter Gain control. The resistor value is now presented in engineering notation.
  7. Click Ok.
    Result: The R_VAR value on the schematic changes to 10k, which is the return value for the REAL parameter-editing control.

What Can Go Wrong?

  • One of the most common problems with dialog definitions occurs when the parameter control definition order in the LABELS property is different than the order in the PARAMETERS property. The program expects these two "arrays" to be in the same order.
  • If your symbol is missing one of the LABELS or PARAMETERS properties, the program produces an error in the command shell. All three special symbol properties must be present for the dialog to function properly.
  • At times, parameter-editing dialogs have been added to symbols without any parameters being passed to the subcircuit. In 5.1 Passing Parameters into Subcircuits Using the SIMPLIS_TEMPLATE Property, you learned that parameters are passed to the subcircuit using the SIMPLIS_TEMPLATE property. It is entirely possible to add a dialog that functions properly, allowing edits to the appropriate symbol properties, but the symbol does not pass these properties to the subcircuit. It is important to remember that passing parameters through the symbol-to-subcircuit interface is different than editing the symbol properties.
  • It is possible to have valid LABELS and PARAMETERS symbol properties but the critical VALUESCRIPT property was not added.
  • Accidental new line characters in the LABELS or PARAMETERS definitions can cause "mysterious" errors.

Conclusions and Key Points to Remember

  • Each parameter-editing control is made up of three data fields: Descriptive label, Type, and Range.
  • Individual parameter-editing control data fields are concatenated into a colon-delimited string.
  • Individual parameter-editing control definitions are concatenated into a comma-delimited string and stored on the LABELS symbol property.
  • The PARAMETERS symbol property stores the parameter names and default values as a parameter string.
  • The order of the parameter-editing control definitions must match the order of the individual parameters in the PARAMETERS symbol property string.
  • A spreadsheet can help ease the task of defining the dialog controls.