Editor’s Note: This blog is based on a PTC Mathcad Prime 10 worksheet. Download the accompanying Text Box worksheet here. If you do not have a Mathcad Prime 10 worksheet viewer, download our free 30-day trial here.
Beginning with PTC Mathcad Prime 10, you can use the Text Box Advanced Control. The Text Box enables the users to accept a user input in the form of text and can be used as a string or number data (with the help of the str2num function) for calculations.
The Text Box is located on the Input/Output tab, in the Controls panel, under Advanced Controls.
The user can modify the behavior of the control on input and the resulting output through a Script in the Exec event using the Text Box Class. The appearance of a Text Box can be changed by right clicking on it and choosing “Edit” > “Properties”, and additional customization can be added from the Math Formatting tab.
There are 3 events in the default script for Text Box: Start, Exec and Stop. All actions associated with processing user entries should be written in the Exec event.
The Mathcad Prime 10 Help Center offers information for creating Text Boxes, and provides an Example to be inspected, copied, and modified in addition to the worksheet made available in this article that we will talk about for the rest of this article. Feel free to also follow along with the video:
We’ll use a scripted Text Box to check for the numeric value and display a “Pass” or “Fail” result in the Text Box.
Starting with a set of data, we’ll use the selected value in a scripted Text Box where JScript code will set the Pass/Fail result and format the Text Box appearance.
In other words, from having a data set which we are deriving specific values, we can connect the selection to text. The Text Box changes its formatting and contents depending on if the corresponding index values match our threshold expectations or not.
In Step 1, we create a List Box (Value) that goes through the values of the matrix N. Based on our selection, we see the appropriate returned evaluation.
In Step 2, we insert a Text Box. By default, it has no inputs. You can right click to add an input.
We’ll compare the selected value from the List Box to the threshold value of variable R, then set the text within the Text Box to Pass/Fail depending on comparison.
We’ll also format the appearance of the Text Box based on whether the result is Pass or Fail.
R will be our threshold value to use in the code for the Text Box control. This is the second input to the Text Box. In this case, we are adding two inputs. For the second input, you must go to the Matrices and Tables tab and click “Insert Right” (or keyboard shortcut Shift+Space):
Now let us examine the code of the Text Box Test:
function TextBoxEvent_Start(Inputs, Outputs) {
// This function is executed when the textbox event starts.
}
function TextBoxEvent_Exec(Inputs, Outputs) {
// This function is executed when the textbox's input values change.
// It processes the inputs and updates the textbox's appearance and text accordingly.
// Retrieve values from the inputs
var V = Inputs[0].Value; // Value to be checked
var R = Inputs[1].Value; // Reference value
if (V > R) {
// If V is greater than R, set the background color to greenish and display "Pass"
TextBox.BackColor(0x00F8AA);
TextBox.Text("Pass");
TextBox.Font.Size = 14; // Set the font size to 14
var Size = TextBox.Font.Size; // Store the current font size in the variable Size
} else {
// If V is not greater than R, set the background color to reddish and display "Fail"
TextBox.BackColor(0xFD7F7F);
TextBox.Text("Fail");
TextBox.Font.Size = 20; // Set the font size to 20
var Size = TextBox.Font.Size; // Store the current font size in the variable Size
}
}
function TextBoxEvent_Stop(Inputs, Outputs) {
// This function is executed when the textbox event stops.
// TODO: Add any cleanup code or final actions here.
}
Going outside the code, if we select a lower value from to compare from the List Box, we will see the second message.
It’s easy to imagine how the metric and output message could be used in a company from the engineering sector, for example.
The List Box could reflect production data or operational data, which in connection with a Text Box, will display that the required level being set is meeting the suitable values or not.
Moreover, it can be universally applied across all domains of activity, since scripted Text Boxes can be used in many different scenarios involving calculations.
Let us quickly recall this example:
We checked a selected value in a list against a threshold value and set a Pass/Fail message accordingly. This can be customized to suit your own purposes.
Further, here are Usage Notes for a better focus and understanding on the Text Box's main concepts.
Ensure the default selection is meaningful for the worksheet's context. This helps guide users towards a typical use case and ensures calculations start with valid data.
Use the selected value to conditionally display a certain text.
Customize the appearance of the Text Box to make it more visually appealing and aligned with the worksheet’s design. Formatting properties help maintain consistent styling and spacing for all Text Boxes to provide a clear and user-friendly interface.
BackColor and ForeColor - Sets or gets the background color for the control. The ForeColor property sets or gets the foreground color for the control.
FontSize - Sets or gets the font size of the text displayed in the control's text field.
Multiline - Indicates whether a Text Box can have multiple lines of text. When true, use the Enter key to go to the next line. When false, the text will be displayed in a single line and using the Enter key will move the cursor out of the Text Box.
Use Mathcad's Math Formatting to set the preferred font for values entered into the Text Box.
Text - The Text property sets or gets the text of the Text Box. The text is limited to 1000 characters.
ReadOnly - The ReadOnly property sets or gets whether the text is read-only or is editable.
Multi-line Text - In the JScript code, use "\r" to add a new line when setting text inside a Text Box.
Example: TextBox.Text("TextLine One\rTextLine Two")
Text Box Controls can integrate with other Mathcad Prime controls to create interactive and dynamic worksheets. Use the Text Box in conjunction with other input controls like list boxes, checkboxes, buttons, radio buttons or sliders to create comprehensive interactive worksheets.
By leveraging configuration options, integrating with other controls, and handling selections conditionally, you can create dynamic, user-friendly, and robust worksheets.
By adhering to these usage notes, you can create Text Boxes that enhance user experience and add flexibility to your worksheets.
If you’d like to learn more about the Advanced Control Text Box Class, or the Text Box Format Properties and Text Box State Properties, please reach out to the documentation provided in the Resources inside the software.
Learn more about use cases for all of the Advanced Controls by attending our free, on-demand training event: the Advanced Controls Crash Course!
