Advanced SIMPLIS Training

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

5.2.2 Adding Tabbed Parameter-Editing Dialogs

In this Topic ShowHide

What You Will Learn

• How the tabbed parameter-editing dialogs work as an extension of the basic parameter-editing dialogs
• The differences between the NewValueDialog and TabValueDialog dialog definitions that prevent them from being interchanged
• How to work with three additional parameter types: GROUP, GROUPCHECK, and LABEL
• How to specify the tab names in the TABS symbol property
• How to specify the group box definitions in the GROUPS symbol property
• How to specify the dialog title and caption in the DESCRIPTIONS symbol property
• Why a spreadsheet software tool is almost mandatory for defining tabbed dialogs

Introduction

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.

Hierarchy of a Tabbed Dialog

The following dialog serves as an example to illustrate the hierarchy within a tabbed dialog.

• At the top level of the hierarchy are two tabs: Filter Pole Frequency and Other Parameters.
  • In the second level of the hierarchy on the Other Parameters tab is the group box Gain and Resistor. Although a tab can have multiple group boxes, this example has just one.
    • On the third level of hierarchy are the parameter-editing controls Filter Gain and Resistor Value.

This hierarchical structure allows you to easily build custom dialog boxes to edit your model parameters; however, certain rules are absolute:

• You cannot place a parameter-editing control on a tab without placing it inside a group box.
• Group boxes are placed on a grid on each tab.
• Each parameter-editing control is made up of the descriptive label, the editing control, and an optional units label.
• Parameter-editing controls are placed on a grid inside a group box.

Required Data Elements

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:

• Tabs
• Groups
• Descriptions

Tabs

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:

Groups

The groups definition for any single group box is made up of 10 data fields described in the following table.

As with the basic dialog definition, each group data element is concatenated with the colon character to produce a group definition string:

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:

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.

Descriptions

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:

Parameter-Editing Control Data Fields

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.

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:

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:

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

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:

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.

You Really Need a Tool for This

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.

Exercise #1: The TabValueDialog Spreadsheet

This exercise walks you through the structure of the spreadsheet to help you understand the process.

1. Open the spreadsheet 5.4_tab_value_dialog_definition_worksheet.xlsx located in the C:\Training\Module_5_Examples directory.

2. Notice that the spreadsheet is broken down into 4 numbered steps:

   • Step #1 defines the tabs
   • Step #2 defines the groups
   • Step #3 defines the labels
   • Step #4 defines the descriptions

3. Notice that the same formatting is used as with the basic dialogs:

   • User inputs are formatted as follows:
     
   • Calculated cells are shown with this format:
     

4. Six script commands are concatenated in cells B38~B43. When executed in SIMetrix/SIMPLIS, these commands add the symbol properties to the symbol that is currently open in the Symbol Editor.

In the next exercise you will add the tabbed parameter-editing dialog to the parameterized RC filter symbol.

Exercise #2: Add Parameter-Editing Dialog

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.

1. Open the schematic 5.5_parametrized_rc_filters_multi_prop_dialogs.sxsch. This example is pre-prepared with the Multi-Property parameterization method. The only part missing is the parameter editing dialog.

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 training 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 B38~B43.
      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 parameters below the symbol.

      Note: This step overwrites the previous NewValueDialog definition.
      

3. From the Symbol Editor menu, select File ▶ Save... 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 appears:
   

5. Change the Resistor Value 10k.

6. Click Ok to save your changes.
   Result: The parameter value for R_VAR changes to 10000 on the schematic.

   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 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.

1. Navigate to the spreadsheet window.

2. To create only one tab, delete the content (Other Parameters) from cell B9.

3. To rename the single tab, change cell B8 from Filter Pole Frequency to Filter Parameters.

4. To move both group boxes to one tab, copy the Filter Parameters text in cell B8 to cells B13 and B14.

5. To place the group boxes on two rows, change cells E14 and G14 to 1.
   Result: This will move the Gain and Resistor group box to the second row on the Filter Parameters tab.

6. To create each parameter in the group boxes on the new parent tab, Filter Parameters, copy cell B13 to cells H18, H19, and H20.

7. Change the content of cells F19 and F20 to REAL.

8. Delete the contents of cell G20, which is the range entry for the Gain parameter.
   Result: Without a range entry, any gain, including negative gain, can be input to the parameter-editing control.

9. As in the previous example, copy the red script commands in cells B38~B43,  and paste the commands into the SIMetrix/SIMPLIS command line.

10. From the Symbol Editor menu, select File ▶ Save..., and then click Ok on the Save Symbol dialog.

11. Double click on the RC Filter symbol.
    Result: The modified dialog appears. Each control type is a Real type, and the controls are all on one tab.
    

12. Click Ok.
    Result: On the schematic, the value of the Resistor Value parameter R_VAR changes from 10000 to 10k. The REAL type parameter editing control returns values formatted in engineering notation.

What Can Go Wrong?

In addition to the common problems described in 5.2.1, What_Can_Go_Wrong?, the tabbed value dialog has these additional common problems.

• Typing and spelling errors. Seemingly minor typographical errors as well as any spelling mismatches will have significant consequences.

  • An extra space character: If the Parent Tab for Exercise #3 contains an extra space after the "s" in Parameters, the dialog will have only a tab with no group boxes and no parameter controls as shown below:

    Note: Observe the extra space that appears in the dotted outline around Filter Parameters.

    

  • An extra letter: When a group title does not match the parameter controls, such as adding an "s" to the group name as shown below for Gain and Resistor, the group will be empty because no control matches the Parent Tab and Parent Group:
    

  • Mismatched spelling of a Parent Group or Parent Tab for a parameter control: When the parameter-editing control value for the Parent Tab or Parent Group does not exactly match the spelling of the actual name of the group or tab, that parameter control is not constructed. For example, if Gain and Resistors was defined as the parent group for Resistor Value when it should have been Gain and Resistor, that control will not appear as illustrated in the dialog below.
    

• Over-writing groups or parameter controls. Groups are created on each tab in a grid pattern. If you specify the same grid location for more than one group box, the second group box will be created on top of the previous group box. Both the Filter Parameters and Gain and Resistor groups were created at Start Row = End Row = Start Column = Stop Column = 0. A similar problem occurs when multiple parameter-editing controls are placed at the same row and column in a single group box.
  
  

Conclusions and Key Points to Remember

• Tabbed parameter-editing dialogs allow you to create more precise dialogs at the expense of requiring more data and more development time.

• The dialog definitions for the NewValueDialog and TabValueDialog are not interchangeable.

• Three additional parameter types in the TabValueDialog are allowed: GROUP, GROUPCHECK, and LABEL.

• The TABS symbol property holds the tab names for the dialog definition.

• The GROUPS symbol property holds the group box definitions for the dialog.

• The dialog title and dialog box caption are stored in the DESCRIPTIONS symbol property.

• A spreadsheet software tool is almost mandatory to define tabbed dialogs.

© 2015 simplistechnologies.com | All Rights Reserved