How to Dynamically Populate Value Options with List Box Advanced Controls

Editor’s Note: This blog is based on a PTC Mathcad Prime 10 worksheet. Download the accompanying List Box worksheet here. If you do not have a Mathcad Prime 10 worksheet viewer, download our free 30-day trial here.

In engineering and scientific calculations, providing users with an intuitive and interactive way to select input parameters is crucial for enhancing productivity and accuracy. PTC Mathcad Prime 10 offers a list box along with other advanced control feature to facilitate this. However, many users may not be fully aware of how to effectively implement and utilize list boxes to dynamically update calculations and enhance the user experience in their worksheets. This blog aims to address this gap by detailing the creation, configuration, and application of list boxes in Mathcad Prime, demonstrating their benefits in practical scenarios, and providing step-by-step guidance to leverage this tool for more efficient and error-free data input.

Explanation of List Box in Mathcad Prime

Purpose and Usage

The list box in Mathcad Prime is used to:

• Provide a selection of options that users can choose from.
• Dynamically change the content or calculations in a worksheet based on user input.
• Enhance the interactivity and usability of Mathcad worksheets.

Creating a List Box

To create a list box in Mathcad Prime 10:

1. Insert the List Box:
• Navigate to the "Input/Output" tab “Controls” section
• Select the "List Box" control from the available options.
2. Define List Items:
• After inserting the list box, you can define the list of items that will appear in the box.
• This is usually done by specifying a range or an array of items.
3. Linking to Variables:
The selection made in the list box can be linked to a variable in the worksheet.
This variable can then be used in further calculations or to dynamically change the content of the worksheet.

Default Script of List Box

The default script for a list box in Mathcad Prime defines several key components and events that manage the list box's behavior. Here is a detailed explanation of the script, including the major events:

1. Initialization Section:
• ListBox.ResetContent(): Clears any existing items in the list box.
  ListBox.AddString("One");
  ListBox.AddString("Two");
  ListBox.AddString("Three");
  Adds three items ("One", "Two", "Three") to the list box.
• ListBox.CurSel(0): Sets the default selected item to the first item in the list ("One"), as the index is zero-based.
2. ListBoxEvent_Start:
• This function is called when the list box event starts.
• Typically used for any initialization that needs to occur when the list box becomes active.
• Currently, it contains a placeholder comment indicating where the user can add custom initialization code.
3. ListBoxEvent_Exec:
• This function is executed to process the current state of the list box.
• ListBox.CurSel() returns the index of the currently selected item.
• Outputs[0].Value = ListBox.CurSel() + 1; sets the output value to the index of the selected item plus one (converting from zero-based to one-based indexing).
4. ListBoxEvent_Stop:
• This function is called when the list box event stops.
• Typically used for cleanup or finalization tasks.
• Contains a placeholder comment for user-defined code.
5. ListBox_SelChanged:
• This function is called when the selection in the list box changes.
• It can be used to handle any actions or updates needed when a new item is selected.
• Currently contains a placeholder comment for custom code.
6. ListBox_DblClick
• This function is triggered when an item in the list box is double-clicked.
• It can be used to define specific actions that should occur on a double-click event.
• Contains a placeholder comment for user-defined code.

Properties of List Boxes

The script can be written in either JScript or VBScript. However, please note that VBScript will be deprecated in a future Mathcad Prime release. Therefore, all the scripting in this worksheet has been implemented using JScript.

The default script sets up a list box with three items and initializes the first item as selected. It includes placeholders for additional initialization, execution, stopping, selection change, and double-click events, allowing users to customize the behavior of the list box according to their needs.

By adding appropriate code to these placeholders, users can make the list box interact dynamically with other parts of the Mathcad Prime worksheet, responding to user selections and triggering calculations or updates as required.

List Box Worksheet Problem Overview

In the petroleum industry, selecting the appropriate crude oil type and understanding its by-products is crucial for efficient refining operations. This process involves multiple steps, from choosing the crude oil type to calculating the necessary pipe diameter for transporting these by-products. Using Mathcad Prime, we can create an interactive and dynamic worksheet to streamline this process. This blog post will guide you through a comprehensive use case that demonstrates how to utilize list boxes in Mathcad Prime for these calculations. You may also watch the embedded video about this same worksheet to follow along.

STEP 1: List Box 1: Selecting Crude Oil Type

The first step involves selecting a crude oil type from a list of ten options. This list box allows users to choose the specific type of crude oil they are working with. Upon selection, the main by-products associated with the chosen crude oil type will be populated in a second list box. The output is set to get the standing of the oil in the list (the index number to which selected oil is listed) along with the name of the oil.

The left side of this control is hidden in the worksheet , and this can be done by going to Input / Output > Controls > Hide Left Side.
Features utilized to construct this list box:

Methods	Formatting properties	State Properties
AddString	RightAlignedText	CurSel
GetText
ResetContent

STEP 2: List Box 2: Dynamic Update based on Crude Oil Selection

In the second list box, users can select a by-product. The output will dynamically update to display based on selection of list box 1.
The output consists of 1 x 3 Matrix which is as follows:

1. A two-digit number representing the position of the crude oil in the first list box and the position of the by-product in the second list box.
2. The number of items in the by-products list.
3. The name of the selected by-product.

Features utilized to construct this list box:

Methods	Formatting properties	State Properties
AddString	RightAlignedText	CurSel
GetText		Count
ResetContent

Step 3: List Box 3 & 4: Selecting flow rate and velocity

Users can then select the flow rate and velocity based on the chosen by-product. These selections are crucial for determining the appropriate pipe diameter and are dynamically updated based on selection.

Features utilized to construct these list boxes:

Methods	State Properties
AddString	CurSel
GetText
ResetContent

Step 4 : Adding Tank Volume via Text Box

Users can add a new volume to the list box by entering a value in a text box and appending a space to confirm the addition. The list of tank volumes is then updated accordingly. This will also check if the number entered is already in the list and then will not add the repeated number.

STEP 4.1 Selecting Tank Volume

You now have the option to choose from the pre-defined list box and an added customised tank volume. Here are the features used for the Step 4 List Boxes:

Methods	Formatting properties	State Properties
AddString	RightAlignedText	CurSel
DeleteString
FindString
FindStringExact
GetText
ResetContent

With the help of flow rate and velocity, you can now calculate the diameter for the selected byproduct.

List Box Benefits

Using list boxes in Mathcad Prime offers several distinct benefits over other advanced controls. Here are ten key advantages:

Simplicity and Ease of Use

Intuitive Interface

List boxes provide a straightforward and user-friendly way for users to select from a predefined set of options. This simplicity makes them easy to understand and operate, even for users with limited technical expertise.

Minimal Input Errors

By restricting input to a set of predefined options, list boxes significantly reduce the risk of user input errors compared to text fields or other free-form input methods.

Dynamic Interactivity

Dynamic Updates

List boxes can be dynamically updated based on user selections. For example, selecting a crude oil type can automatically populate the by-products list box, ensuring relevant and context-specific options are always available.

Event Handling

List boxes support event handling for selection changes, double-clicks, and other interactions. This allows for real-time updates and calculations, enhancing the interactivity and responsiveness of the worksheet.

Efficiency in Data Entry

Quick Selection

List boxes allow users to quickly select from multiple options without typing, saving time and improving efficiency, especially when dealing with extensive lists of items.

Clear Options Presentation

Items in a list box are clearly displayed, making it easy for users to see all available choices at a glance. This is particularly beneficial for presenting categorized or hierarchical data.

Integration with Calculations

Linked Variables

Selections in list boxes can be directly linked to variables used in calculations. This seamless integration simplifies the process of using user inputs in computational formulas, ensuring that calculations are always based on the latest selections.

Automated Updates

Changes in list box selections can trigger automatic updates in related calculations and outputs, ensuring that the worksheet always reflects the current state of user inputs without requiring manual updates.

Customization and Control

Customizable Options

List boxes can be easily customized to include any number of options, tailored to the specific needs of the worksheet. This flexibility allows for precise control over the data input process.

Hierarchical Selection

When used in conjunction with multiple list boxes, hierarchical selection can be implemented (e.g., choosing a crude oil type, then its by-products leading to selection of flow rate and velocity), making complex data structures manageable and easy to navigate.

List Box Conclusions

By integrating these list boxes and calculations into a Mathcad Prime worksheet, users can interactively select crude oil types, by-products, flow rates, velocities, and tank volumes. This approach ensures accurate and efficient calculations for pipe diameter, area, Reynolds number, and time required for filling tanks. The use of Mathcad Prime’s list boxes not only enhances user experience but also streamlines complex engineering calculations in the petroleum industry.

List boxes in Mathcad Prime offer an ideal balance of simplicity, interactivity, and efficiency, making them a powerful tool for managing user inputs in engineering calculations. Their ability to dynamically update, minimize errors, and integrate seamlessly with worksheet variables makes them superior to other advanced controls for many practical applications.

If you’re interested in learning more about the Advanced Control List Box Class, List Box Events, List Box Format Properties, List Box Methods and List Box State Properties then you may consult the Help documentation provided online and also inside the software.

Advanced Controls Crash Course

Learn more about use cases for all of the Advanced Controls by attending our free, on-demand training event: the Advanced Controls Crash Course!

Take the course!

---