First you need to start a New Window, starting with its title, and then you list the items to construct inside the window. All the Display Box constructors end in “Box”. See Introduction to Display Boxes, to review what each type of display box looks like. There are similar objects that live inside of graphics frames called Display Segs (segments), and these all end in “Seg”. We have only made JSL constructors to a small subset of the various Display Boxes and Display Segs in JMP. You can nest display boxes inside each other as needed.
With an assignment, you can make a reference to a new window, so that you can send messages to it. (Throughout this document, db is a placeholder for a display box reference, dt for a data table reference, and obj for a scriptable object reference.)
This example uses Outline Boxes, H List Boxes, and Matrix Boxes to assemble a partial cheat-sheet for matrix JSL.
A Matrix Example
Formatted Matrix Example
Observe how placing Matrix Boxes inside Outline Boxes is a convenient way to arrange items neatly. You could add more topics by adding more outline branches following this pattern.
Use the Append message to add a display box to the bottom of an existing display. In the script, construct a single, empty box, then <<Append boxes to it for each variable in the analysis.
The following code example assumes that there is a list of effect names in the variable effectsList, and that each one corresponds to a column in a matrix varprop. In other words, effectsList[1] is the label for varprop[0,1]; effectsList[2] is the label for varprop[0,2]; and so on.
First, an empty Outline Box containing an H List Box is made. The interior empty container is given the name hb:
Then, a for loop steps through the effectsList and adds a Number Col Box for each element of effectsList:
The Prepend message works just like Append, but adds the item at the beginning of the display box rather than at the end. If the display box is one of several that do not allow appending, then it delegates the command to a child display box that can accept the command. It is fine to apply it to the top of the tree.
Click the Click Here for curve button to add a quadratic curve to the graph.
The Delete message removes the specified display box and all its children from the report. This is useful with the Append and Prepend messages for building completely dynamic displays. In the example below, a text box is replaced with another text box. In this case, the script could have used Set Text, but many display boxes cannot change their content.
You can use the Sib Append message to add a display element to an existing tree. Refer back to the display box tree shown in View Display Tree. Under ListBox(2), you see two picture box trees. PictureBox(1) holds the bivariate scatterplot. This is easily determined by seeing the two axis boxes holding the height and weight axes. Picture Box (2) holds the Fit Mean menu, determined by seeing the green line and the Fit Mean text box.
Appending a Sibling Text Box
The <{list}> argument specifies the new strings for the table.
Generally, JMP automatically wraps text within a Text Box. However, the default wrap point can be overridden with a Set Wrap (n) message, where n is the number of pixels to display before the wrap point.
JMP has several special types of display boxes that you do not normally see in a JMP platform: Button Box, Slider Box, Range Slider Box, and Global Box. These are useful for building custom windows with interactive graphics.
Note: The chapter Scripting Graphs, shows how Handle and MouseTrap both present controls inside the graph itself.
Slider Box draws a slider control for picking any value for the variable that you specify, within the range given by the min and max you specify. Any time the slider is moved, the value given by the current position of the slider is assigned to the global variable. The graph updates accordingly. Thus, Slider Box is another way to parameterize a graph.
Use Range Slider Box to draw a slider that contains two controls for picking a range of values.
Button Box draws a button with the name that you specify. Any time the button is clicked, the script executes. The button stays alive and remains available for the duration of the window. You might want to use Button Box in combination with sliders or to provide a choice to update a graph to reflect changing data conditions. You can also send a click() command to a button object at any time.
Number Edit Box creates an editable box with the specified number as the initial value. The box is interactive when combined with an object such as a date selector.
The following script sets the initial value of the Number Edit Box to 0 and the text field to 20 characters wide. <<Set Format specifies the format of the date that appears in the box and the number of characters to display. <<Set specifies the default date and its format. The user can either enter a date in the box or select the date from the pop-up calendar.
See Example of a Date Selector for a more detailed example.
Global Box shows the name and current value of a JSL global variable. The user can assign a new value to the global variable by editing the value directly in the window and pressing ENTER or RETURN to commit the change. Graphs using the global box automatically update for the new value. If you specify an expression, such as Sqrt(4), the global box first evaluates it and then stores and displays the result, 2.
Note: When using Global Box, every time the variable is changed it remeasures, reshows, and updates the window which, depending on the number of Global Box objects, can affect the refresh rate of the window. JMP recommends avoiding numerous global boxes in deliverable scripts. Global boxes can be replaced with text boxes that the script can manually update when necessary.
Example of Sliders and Buttons in a Report Window
The following script uses a Range Slider Box() instead of a Slider Box() to perform the same function:
Example of Using Range Slider Box
Note: For Range Slider Box controls, the upper variable cannot be less that the lower variable and the lower variable cannot exceed the upper variable.
The script below is similar but uses Global Box as an editable text box instead of two Slider Box controls:
Example of Using a Global Box Instead of Sliders
This example shows how to create an interactive calendar using Number Edit Box(). The user enters a date in the box or clicks the blue triangle to select a date from the calendar. The number appears in a text box below the number edit box.
A callback is assigned to the f variable. In the callback, this refers to the number edit box, the box that calls the function later. Referring to this prevents the need for using the numbox variable within the callback. The <<Get message is sent to the this argument to get the specified date. <<Set Text displays the date in the text box.
Note: The Dialog() function, which creates modal windows, was deprecated in JMP v10 and may not work in future versions of JMP. Use the New Window() function with the Modal argument in place of the Dialog() function.
See Modal Windows for more details on using New Window(). See also the JSL Syntax Reference book for syntax details.
Border Box (Left(pix), Right(pix), Top(pix), Bottom(pix), Sides(int), displaybox)
Used to add space around the displaybox argument. Left, Right, Top, and Bottom add space around the displaybox argument. Sides draws border around the box, as described in Border Box Sides Argument Values. Additional effects can also be applied to the borders using Sides, as described in Border Box Sides Argument Additional Effects. To add both an effect and a border, add the two numbers.
Button Box("text", <script>)
Other messages for Button Box include <<Set Button Name("string") and <<Get Button Name.
You can also send the message Open Next Outline as a script command, which causes the next outline box to open. If you are sending more than one message to the button box, this must be the first command listed.
The "-" in this example creates a menu separator. The separator counts as an item in the list. If you select c from the menu, 4 is returned, not 3.
Check Box ({“item 1”, “item 2”, ...}, <script>)
The following example shows how to get the user’s selection by sending <<Get Selected to the check box. Each selection is printed to the log.
Col List Box (<Data Table (<name>), <All>, <width(n)>, <maxSelected(n)>, <nlines(n)>, <script>, <MaxItems(n)),<MinItems(n)>, <character | numeric>, <onChange(expression)>)
All specifies that all columns in the current data table should be included. Width is measured in pixels. MaxSelected is the maximum number of items that might be selected in the list box. Nlines is the number of lines to display in the box.
You can send a Get Items message to a col list box to retrieve a list of all columns selected. Here is an example script showing Get Items in use:
Combo Box({“item 1”, “item 2”, ...}, <script>)
The Editable argument allows the user to enter text in the combo box. The following script creates a new window and an editable combo box with the list items “one”, “two”, and “three”. The script prints the selected item name and index number to the log.
Note that closing the window for an editable combo box can produce unexpected results. On Windows, the Print() script runs after you select an item from the list or enter the item name. On Macintosh, the Print() script runs after you select an item from the list or enter the item name and then press Return.
For cross-platform compatibility, include !Is Empty to test for an existing combo box before running the script.
The Journal Box function, like other functions ending in Box, constructs a Display Box appropriate for gluing together with other Display Boxes to create a display in a window.
box = Journal Box("journal text")
where "journal text" is text that has been extracted from a journal file.
Another way to get journal text is to send <<GetJournal to displayBoxes.
Line Up Box (NCol(nc), <Spacing(pixels)>, displaybox args)
Display boxes specified in the displaybox arguments are drawn in nc columns. Optional spacing can be specified, in pixels, for the space between columns.
List Box({“item 1”, “item 2”, ...}, <width(n)>, <max selected(n)>, <nlines(n)>, <script>)
Width is measured in pixels. Max selected is the maximum number of items that might be selected in the list box. Nlines is the number of lines to display in the box, with a default value of 3.
Append always adds the list to the end of the list box. Insert adds the list after the position specified.
Note that only the OK button appears in the window. This is the default behavior for New Window().
Panel Box (“title”, displaybox args)
Encloses the displaybox argument in a labeled border.
Popup Box({"command1", script1, "command2", script2, ...})
Sample Red Triangle Menu
Note that you can also disable and re-enable the menu using the message <<enable(Boolean). An argument of 1 turns the menu on, and an argument of 0 turns the menu off. Using the previous example, you would assign the popup box to a variable, and then send messages to it:
Radio Box({“item 1”, “item 2”, ...}, <script>)
Slider Box(min, max, global variable, script, <set width(n)>, <rescale slider(min, max)>)
Tab Box("page title 1", contents of page 1, "page title 2", contents of page 2, ...)
Tab Boxes
You can specify which tab should be selected by sending <<SetSelected(n), where n is the tab number, to the tab box object.
The <<Set Style message lets you select the visual appearance of the tab box. The default value is tab. Other options include:
combo creates a combo box.
outline creates an outline node.
vertical spread displays the tab title vertically.
horizontal spread displays the tab title horizontally.
minimize size bases the tab style on the width of the tab title. In the following script, the first tab title is fairly long.
Default Tab Box (Left) and Minimized Tab Box (Right)
Tip: Set Style() works for both bare words and quoted words. However, you cannot assign the style to a variable and then pass the variable as the argument.
To delete a tab box, send it the message <<Delete Box. Note that this will delete the entire display box (all tabs) not just a single tab.
Text Box(“text”)
Note: Rotated text boxes support Markup text except for larger text boxes with multiple lines, multiple formats or justifications applied.
The following script produces the Text Edit Box shown in Text Edit Box with Placeholder Text. The Hint() function returns "mm/dd/yyyy" and formats it as light gray text.
Text Edit Box with Placeholder Text
Example of Many Interactive Display Elements
You can use <<Set Selected (Item Number, <State>, <Run Script(0|1)>) command to pre-select an item. You can use this command separately to a saved display box reference, or you can specify it inline as a list box << argument.
To retrieve the selected value, use <<Get Selected, which returns the value of the selected item. << Get Selected Indices returns the index number of the selected item.
In the preceding examples, the Print expression is executed when you the <<Set Selected message is completed. To prevent the script from running, include Run Script(0) as the last argument. Run Script( 0|1 ) controls whether a display box on-change script runs after a <<Set or <<Set Selected message.
With Run Script( 1 ), the script is executed when the Set message is completed, even if the value is unchanged. (The script does not run again if the user selects the same value.) With Run Script( 0 ), the script does not run.
On most interactive display boxes, the script does not run if you leave out Run Script(). However, on List Box(), the script runs by default, which is consistent with previous behavior.
Note: Some functions (Recall and Help) are not implemented in the script, so an alert window is shown when they are clicked. In addition, switching from Hierarchical to K-Means clustering does not change anything unlike the real Cluster launch window.
The Cluster Launch Window
Use For loops for more complex movement:
This script uses the Summarize operator to collect summary statistics on the Height column of Big and then uses display box constructors to show the results in a nicely formatted window.
Producing a Customized Summary Report
Example: Multiple Graphs in One Report Window
Now you can work with the window by sending messages to the reference csp. This is a display box reference, whose capabilities are similar to those of a Report for a platform. You can use multiple-argument subscripting to locate specific items within the outline tree:
Notice that this script not only assigned the whole window to a reference (csp) but also assigned the platform-launch scripts to names (cc and dist) within their display boxes. This makes it easy to route messages to the platforms. You could in turn get the reports for these and have yet another way to manipulate display boxes. The following are equivalent messages that reopen the nodes:
Changing a Custom Report
An example in Manipulating expressions in Programming Methods, showed how to use the SubstituteInto function to input coefficients for a quadratic polynomial into the quadratic formula and then use the formula to calculate the roots of the polynomial. That example required specifying the coefficients as arguments to SubstituteInto.
The section Modal Windows shows an example to collect coefficients from the user using a modal dialog box.
Example: A Custom Platform Launch Window
Clicking OK, displays a results window (Example: The Custom Platform's Report, left), with either the roots or an error message. Rerun the script, input 5, 4, and 5 respectively and click OK. Note that JMP displays an error message (Example: The Custom Platform's Report, right).
Example: The Custom Platform's Report
Sheet box lets you create a grid of plots. H Sheet Box and V Sheet Box contain display boxes and arrange them in columns and rows. The general approach is to first consider what display boxes that you want, and in what arrangement. Then, create either an H or V Sheet Box and send it a Hold message for each plot. Finally, create interior H or V Sheet Boxes and tell each one which plot it should hold.
Use a V Sheet Box to organize the window into two columns.
Send it four Hold messages, one for each plot. The order matters.
Finally, add two H Sheet Boxes to the V Sheet Box and tell each one which plot it should hold. Each H Sheet Box holds two side-by-side plots. They are held by a V Sheet Box, so the H Sheet Boxes are displayed vertically.
Sheet Part displays a previously defined plot, held by Excerpt Box. The first argument is the number of the plot, determined by the order in which you defined the plots. So this first H Sheet Box contains the Bivariate plot on the left and the Distribution on the right. {Picture Box(1)} designates which picture box from the report to display. Generally speaking, use 1.
Finally, a note on the titles for Sheet Part. If you include an empty string as the title, the sheet part’s title is the default report title. For example, “Bivariate Fit of weight By height”. You can define your own title by enter your title as the string. For example, “My Title Here”.
Note: For Sheet Part, you must include a title, either an empty string or a character string. This argument is mandatory. If you want a blank title, use a string of one or more spaces.
To create picture data, send a Get Picture message to a displaybox.
displaybox<<Get Picture;
The function Expr As Picture evaluates its argument and creates a picture of the expression, using the same formatting mechanism as the formula editor. If you have a literal expression as the argument, remember to enclose it in Expr() so that JMP just takes a picture of the result, rather than evaluate the expression.
picture<<Save Picture("path", type)
where type can be WMF(Windows), EMF(Windows), PICT(Macintosh), BMP(Windows), JPEG or JPG, or PNG.