Use the display reference to send messages to the display elements using the Send or << operator. For example, if out2 is a reference to an outline node, you can ask the node to close itself if it is open:
out2 << Close(); // close the outline node
Close() toggles an outline node back and forth between closed and open states, just like selecting items in the red triangle menu. You can include a Boolean argument (1 or 0) for “close or leave closed” or “open or leave open.”
rbiv["Fit Mean"] << Close; // toggle open and closed
rbiv["Fit Mean"] << Close( 1 ); // close or leave closed
rbiv["Fit Mean"] << Close( 0 ); // open or leave open
|
Tip: The Report Invalid Display Box Messages option in the General preferences helps you identify invalid display box messages. • The preference is off by default. When a display box receives an invalid message, JMP ignores those errors and continues executing the script. • When this preference is on, an error appears in the log. This option can be useful during script development but can cause unwanted log messages for existing scripts. |
You can send messages to display boxes using the send (<<) operator. The operator makes it clear when the script is evaluating child arguments and optional arguments. It also helps make it clearer which argument is an option and which is a script to run inside the graph.
Here is an example of sending a Graph Box a message:
win = New Window( "Messages",
gb = Graph Box(
Frame Size( 400, 400 ),
X Scale( 0, 25 ),
Y Scale( 0, 25 )
)
);
gb << Background Color( "red" );
When you stack (or nest) messages, each message is evaluated left to right.
• The following expression sends message1 to box, then message2 to box, then message3 to box. Note that any of the messages can change box before the next message is sent.
box << message1 << message2 << message3;
• The following expression sends message1 to box and gets the result. Message2 is sent to that result, and message3 is sent to the result of message2.
( (box << message1) << message2) << message3
• The result of message3 is assigned to the variable x.
x = box << message1 << message2 << message3;
Here is an example of using nested messages:
win = New Window( "Messages", gb = Graph Box() );
// message 1 sets the background color
sz = gb << Background Color( "red" )
// message 2 saves the graph box as a PNG file
<<Save Picture( "$DOCUMENTS/red.png", "png" )
// message 3 sets the graph box background color to white
<<Background Color( "white" )
// message 4 returns the graph box size and prints it to the log
<<Get Size();
If you nest several messages, you might want to use parentheses to group the messages to be sure your script does what you want it to.
The Send To Report() and Dispatch() functions provide a way for JMP to record display box modifications inside an analysis script in a self-contained way. For example, arguments within the two functions open and close outline nodes, resize graphics frames, or customize the colors in a graphics frame. You can also specify the arguments in separate JSL statements.
Send To Report() contains a list of options that change the display tree.
Dispatch() contains four arguments that change the display tree:
• The first argument is a list of outline nodes that need to be traversed to find the desired part of the display tree.
• The second and third arguments work together. The second argument is the name of a display element, and the third argument is the display element’s type. These two arguments specify which particular part of the display tree is to be customized.
• The fourth argument is a list of options.
For example, open Big Class.jmp and run the attached Bivariate script. This generates a report with a fitted line. Open the Lack of Fit outline node, and close the Analysis of Variance outline node. Select Save Script > To Script Window. The following script appears in the script editor window:
dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
biv = dt << Bivariate(
Y( :weight ),
X( :height ),
Fit Line(),
SendToReport(
Dispatch(
{"Linear Fit"},
"Lack Of Fit",
OutlineBox,
{Close( 0 )} ),
Dispatch(
{"Linear Fit"},
"Analysis of Variance",
OutlineBox,
{Close( 1 )}
)
)
);
The Send To Report() function contains two Dispatch() functions that customize the default report.
• The first argument finds an outline node named “Linear Fit”.
• The second and third arguments finds an outline box named “Lack of Fit” below the “Linear Fit” outline.
• The fourth argument is the argument to send to this outline box. In this case, the message is Close(0), in other words, open the node.
Note: If there are several outline nodes with identical names, subscripts are assigned to them. For example, if you have a Bivariate analysis with two quadratic fits (resulting in identical titles), when you dispatch a command to the second fit, the subscript [2] is added to the duplicated title.
The best way to deal with Send to Report() and Dispatch() is to first create a customized report interactively. Save the report as a script and then examine the script that JMP generates. Remember: the best JSL writer is JMP itself.
Creating a journal enables you to capture the contents of a JMP window at a fixed moment in time. Suppose that a JMP window contains a graph and selected check boxes. The journal shows the graph and the check boxes that were selected when you created the journal.
The following examples show what you can do with a journal.
Suppose that you start with a Bivariate report.
dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
biv = dt << Bivariate( Y( weight ), X( height ) );
rbiv = biv << Report;
Journal the results:
rbiv << Journal Window;
Save the journal to a file:
rbiv << Save Journal(
"$DOCUMENTS/test.jrn"
);
Note that the above example uses macOS pathname conventions. On Windows, you can use forward slashes (which are appropriate for all platforms) or backslashes (which are appropriate only for Windows).
When a script uses a By variable, the result is a list of references to the analysis results for each By group. In order to journal all By member parts of the report, you need to use parent messages to get to the top of the report.
For example, the following script creates a Bivariate report with a By group and then journals the entire report:
dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
biv = dt << Bivariate(
Y( weight ),
X( height ),
By( sex )
);
( ( Report( biv[1] ) << Parent ) << Parent ) <<
Save Journal( "test.jrn" );
To update a numeric column in a display box table, use the Set Values message.
win = New Window( "Numeric Column",
num = Number Col Box( "Values", [9, 10, 11] )
);
num << Set Values( [1, 2, 3] );
The matrix argument specifies the new numbers for the table.
To add the thousands separator in a numeric column, use the Set Format message.
New Window( "Example",
ncb = Number Col Box( "Random Numbers",
{Random Uniform(), Random Uniform() * 10,
Random Uniform() * 100, Random Uniform() * 1000,
Random Uniform() * 10000}
)
);
ncb << Set Format(10,3, "Fixed Dec", "Use thousands separator");
To update a string column in a display box table, use the Set Values message.
win = New Window( "String Column",
str = String Col Box( "Values", {"a", "b", "c"} )
);
str << Set Values( {"A", "B", "C"} );
The list argument specifies the new strings for the table.
Generally, JMP automatically wraps text within Text Box(). However, the default wrap point can be overridden with a Set Wrap (n) message. The following script wraps the text at 200 pixels.
win = New Window( "Set Wrap",
tb = Text Box(
"Place your cursor over a data point for more information."
)
);
tb << Set Wrap( 200 );
You can add bullet points using the Bullet Point( 1 ) message.
win = New Window( "Bullet List",
text1 = Text Box( "Place your cursor over a data point for more information." ),
text2 = Text Box( "Circle your cursor over a statistic for more information." )
);
text1 << Bullet Point( 1 );
text2 << Bullet Point( 1 );
Sending the Bullet Point( 1 ) message to a text box places a bullet in front of the text and indents subsequent lines within that text box.
You can also send the Bullet Point( 1 ) message inline as shown in the following example:
text1 = Text Box( "Place your cursor over a data point for more information." ), << Bullet Point( 1 ) ),
You can use Select, Reshow, and Deselect to blink the selection highlight on a display box. As previously described, you can string together several << clauses to send an object several messages in a row. The results read left to right; for example, here Select is done first, then Reshow, then Deselect, then the other Reshow.
dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
biv = dt << Bivariate(
Y( :weight ),
X( :height ),
Fit Mean( )
);
// assign the bivariate analysis layer to rbiv
rbiv = biv << Report;
/* find outline box with the specified string in the
rbiv report and assigns it to the out2 variable */
out2 = rbiv[Outline Box( "? Mean" )];
out2 << Close( 0 ); // open the outline box
// find the first string col box in rbiv and
assign the scbx variable */
scbx = rbiv[String Col Box( 1 )];
Wait( .25 ); // wait .25 seconds
For( i = 0, i < 20, i++, // set i to 0, iterate through the loop 20 times
/* select the string col box and reshow it,
deselect it and reshow it */
scbx << Select << Reshow << Deselect << Reshow
);
Headings are shaded and have column borders by default. To turn them off, use the Set Shade Headings ( 0 ) message and the Set Heading Column Borders ( 0 ) message. The following example shows the effect of turning shading and borders off:
dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
Summarize(
meanHt = Mean( Height ),
minHt = Min( Height ),
maxHt = Max( Height )
);
win = New Window( "Summary Results",
tb = Table Box(
Number Col Box( "Mean", meanHt ),
Number Col Box( "Min", minHt ),
Number Col Box( "Max", maxHt )
)
);
Wait( 2 );
tb << Set Shade Headings( 0 );
Wait( 1 );
tb << Set Heading Column Borders( 0 );
Wait( 2 );
tb << Set Shade Headings( 1 );
Wait( 1 );