For the latest version of JMP Help, visit JMP.com/help.


JSL Syntax Reference > JSL Messages > Display Box Messages
Publication date: 05/05/2023

Display Box Messages

This section contains JSL messages that apply to display boxes. For additional examples, see Display Trees in the Scripting Guide and the JMP Scripting Index.

All Display Box Messages

db<<Add Text Annotation(Text(quoted string), Text Box(<x1, y1, x2, y2>))

Draws a text annotation box at the specified pixel location that contains the quoted string. The Text Box argument controls where the text annotation box is drawn in the window, from the upper left corner to the lower right corner.

Note that x1, y1, x2, and y2 are not graph axis values but the specific pixel locations in the window. Exactly where the text box appears depends on the user’s window size, display resolution, and so on.

db<<Append(db2)

Adds db2 as the last child of the db.

db<<Child

Returns the child of the box.

db<<Class Name

Returns the name of the display class for the box.

db<<Clone Box

Makes a new copy of the display box.

db<<Close Window

Closes the containing window.

db<<Copy Picture

Puts a picture of the box on the clipboard.

db<<Delete

Deletes the display box.

db<<Enable(Boolean)

Controls the ability to interact with the display box. 0 disables the display box. 1 enables the display box.

db<<Get HTML

Returns a quoted string containing HTML source for the box.

db<<Get Journal

Returns a quoted string containing journal source for the box.

db<<Get Menu Item State(index)

Returns the popup menu item state of the index menu item. The state can be normal (0), checked (1), or disabled (-1).

db<<Get Menu Items

Description

Returns the menu items used for popup menu when the button is clicked. Menu items are returned in a list.

See Also

For submenus see db<<Get Submenu(index).

db<<Get Menu Script

Returns the menu script attached to the calling object.

db<<Get Page Setup()

Returns the page setup settings.

Example

The example below creates a new window and returns the page setup configuration.

w = New Window( "Window",
	Text Box( "Page Setup Test" )
);
w << Get Page Setup();

The results of the message:

{Margins( {0.75, 0.75, 0.75, 0.75} ), Scale( 1 ), Portrait( 1 ),

Paper Size( "Letter" )}

db<<Get Picture( <Scale(n)> )

Captures db as a picture object. The Scale(n) argument is a factor of the original picture size. For example, Scale(2) makes the picture object twice as large.

db<<Get RTF

Returns a quoted string containing RTF source for the box.

db<<Get Script

Returns the script for recreating the display box.

db<<Get Size

Returns either { x, y } or { h, v } in pixels:

xy = DisplayBox << Get Size;

Returns x and y in pixels:

{ x, y } = DisplayBox << Get Size;

db<<Get Submenu(index)

Returns the number of submenu items under the given menu item.

Example

The example below creates a menu containing "A", "B", and "C" with "A" having a submenu "A1" and "A2" and "B" having a submenu "B1", "B2", and "B3". <<Get Submenu(inc) returns the number of submenu items under each indexed menu item.

New Window( "Title",
obj = Outline Box( "title" ) );
submenus = { };
obj << Set Menu Script(
	{"A", "", "A1", Print( "A1" ), "A2", Print( "A2" ),
	"B", "", "B1", Print( "B1" ), "B2", Print( "B2" ), "B3", Print( "B3" ),
	"C", Print( "C" )}
);
obj << Set Submenu( 1, 2 ); // menu A with 2 items in submenu A1 and A2
obj << Set Submenu( 4, 3 ); // menu B with 3 items in submenu B1, B2, and B3
For( inc = 1, inc <= N Items( Words( obj << Get Menu Script, "," ) )/2, inc++,
	Insert Into( submenus, obj << Get Submenu( inc ) );
);
submenus;

{2, 0, 0, 3, 0, 0, 0, 0}

The log output indicates that index(1) contains two submenu items and index(3) contains three submenu items.

db<<Get Text

Returns a quoted string containing the text of the box.

db<<Horizontal Alignment(position)

Aligns a child display box inside the display parent box according to the specified position. The default value is "Left", or you can specify "Center", or "Right".

Example

New Window( "Example",
	Outline Box( "Parent display box",
		Button Box( "OK", <<Horizontal Alignment( "Center" ) )
	)
);

db<<Inval

Invalidates the display box area in the window. The window is updated the next time the operating system has an opportunity to update windows (for example, when the user resizes the display box).

Notes

Consider including the message <<Update Window rather than including Wait(0). The problem with using Wait(n) is knowing how large n should be.

Many display box messages, such as <<Set Text, automatically mark the box as invalid, so the <<Inval message is usually unnecessary. Some interactive scripts that use sliders with JSL callbacks might need <<Update Window to keep various parts of the display synchronized with the slider.

db<<Is Enabled

Returns the enabled state of the control. The message is supported in Busy Light Box(), Button Box(), Calendar Box(), Check Box(), Col List Box(), Combo Box(), Completion Box(), Filter Col Selector(), gtext(), List Box(), Number Edit Box(), Popup Box(), Radio Box(), Range Slider Box(), Slider Box(), Spin Box(), Text Edit Box(), Tree Box(), Tree Map Box(), and Tree Map Seg().

db<<Journal

Appends the box to the journal.

db<<Journal Window

Appends the containing window of the display box to the journal; compare with Journal.

db<<Move Window(x, y)

Moves the window to the (x, y) location on your screen.

db<<Page Break

Inserts a page break before the box.

db<<Parent

Returns the parent of this display box.

db<<Prepend(db2)

Add db2 to the display tree before db.

db<<Prev Sib

Returns the previous sibling of the display box.

db<<Reshow

Invalidates the display box’s area in the window and immediate removes invalid areas from the window.

db<<Save Capture(<path>, <format>, <Add Sibling(n)>)

Saves the display box as a graphic to the specified quoted path in the specified quoted format. The optional Add Sibling argument adds the number of sibling display boxes to include in the capture. The default value is 1, which captures only the specified display box. Note that the specified portion of the report is not guaranteed to be scrolled into view or unobstructed by other windows. If the display box is not visible, the saved graphic will not contain the contents that you expect.

If you omit the path, you are prompted to name and save the file when running the path.

db<<Save HTML(<path>, <format>)

Saves the HTML source and folder of graphics to the quoted path and in the quoted format. If you omit the path argument, you are prompted to name and save the file when running the script.

db<<Save Interactive HTML(<path>, "Is Static")

Saves the display box as a web page (that includes interactive HTML features) in the quoted path. Non-JMP users can then explore the data. Note that the data is embedded in the web page.

Arguments

path

A optional quoted path that specifies the location where the web page will be saved.

"Is Static"

Omits the data from the web page and saves a static version of the web page.

Examples

dt = Open( "$SAMPLE_DATA/Big Class.jmp" );
biv = dt << Bivariate( y( weight ), x( height ) );
rbiv = (biv << Report);
rbiv << Save Interactive HTML( "$DOCUMENTS/MyInteractiveHTML.htm" );

db<<Save Journal(<path>)

Saves the journal source for the box in the quoted path. If you omit the argument, you are prompted to name and specify the graphic type.

db<<Save MSWord(<path>)

(Windows Only) Saves the display box as a Microsoft Word document in the quoted path. If you omit the path argument, you are prompted to name and save the file when running the script.

db<<Save PDF(<path>, <Show Page Setup(Boolean)>, <Portrait(Boolean)>)

Description

Saves a PDF of the display box in the quoted path.

Optional Arguments

path

Saves the file in the quoted path. If you omit the argument, you are prompted to name and save the file when running the script.

Show Page Setup(Boolean)

(Windows only) Displays the Page Setup window, where you can specify page orientation, headers and footers, margins, page scale, and paper size.

Portrait(Boolean)

Displays the content in portrait or landscape orientation.

Notes

The PDF file contains headers and footers. Use Save Picture to omit these components.

db<<Save Picture(<path>, <format>)

Description

Saves a picture of the display box in the quoted path and with the specified quoted format.

Notes

If you omit the quoted path argument, you are prompted to name and save the file when running the script.

Valid file formats include "PDF", "PNG", "GIF", "JPG" or "JPEG", "EPS", "SVG", and "EMF".

On Windows, the Windows Specific preferences determine the resolution (or DPI), or you can run the following script:

Pref( Save Image DPI( number ) );

On macOS, the operating system determines the DPI.

Use Save Picture to export a report as a PDF file with no headers or footers. Use Save PDF to include these components.

db<<Save Presentation(<path>, <Template(path)>, <Insert("Begin"|"End"|n)|Replace("Begin"|"End"|n)|Append>, <Outline Titles(title location)>, <format>)

Saves display boxes in a Microsoft PowerPoint presentation. You can open the file in any presentation software program.

Optional Arguments

path

Saves the file in the quoted path. You must include the .pptx extension in the filename. If you omit the path argument, you are prompted to name and save the file when running the script.

Template(path)

Specifies the quoted path of a custom PowerPoint template. Without this argument, JMP uses the default template located in the pptx folder of the installation directory.

Include a simple table in your template, or a default table format is applied to report tables. For an example on Windows, see /pptx/JMPExportTemplate.pptx in the JMP installation folder.

Insert

Determines where the slides are inserted in an existing presentation.

n inserts the slides as the nth slide number.

"Begin" inserts the slides at the beginning of the presentation.

"End" inserts the slides at the end of the presentation.

Replace

Determines which slides are replaced in an existing presentation. The arguments are n, "Begin", and "End" as described for Insert.

Append

The slides are inserted at the end of an existing presentation.

Outline Titles

The location of the outline title and any parent outline titles on the slide. By default, the immediate parent outline title appears as a slide title above the slide content, with any parent outline titles positioned in the bottom left corner of the slide.

"None" omits the slide title above the graphic and the outline titles.

"Hide" omits the outline titles.

"TopLeft", "TopRight", "BottomLeft", "BottomRight" determine the position of any of the parent outline titles on the slide.

format

The format of the embedded graphics. Options are "Native", "EMF", "PNG", "JPG", "BMP", "GIF", "TIF". On Windows, the native format is EMF. On macOS, the native format is PDF. See “Notes” for compatibility issues. Without this argument, JMP applies the “Image Format for PowerPoint” General preference.

Notes

Windows does not support the native PDF graphics produced on macOS. macOS does not support the native EMF graphics produced on Windows. For cross-platform compatibility, specify "PNG", "JPG", "GIF", or "TIF".

If no arguments are provided, the user is prompted to name and save the file.

db<<Save RTF(<path>, format)

Saves the file in the specified quoted path and with the quoted format. If you omit the path argument, you are prompted to name and save the file when running the script.

db<<Save Text(<path>, format)

Saves a file containing the text of the box in the quoted path and with the specified quoted format. If you omit the path argument, you are prompted to name and save the file when running the script.

db<<Scroll Window(Display Box|relative-vertical-pixels|relative-horizontal-pixels, relative-vertical-pixels|{absolute-vertical-pixels, absolute-horizontal-pixels})

Scrolls the containing window.

db<<Select

db<<Deselect

Selects (highlights) or deselects the box.

db<<Set Menu Item State(index, 0|1|-1)

Sets the popup menu item at index to be normal (0), selected (1), or disabled (-1).

db<<Set Page Setup<Margins(left, right, top, bottom)>, <Scale(s)>,<Portrait(Boolean)>, <Paper Size(paper size)>)

db<<Set Page Setup<Margins({left, right, top, bottom})>, <Scale(s)>,<Portrait(Boolean)>, <Paper Size(paper size)>)

Sets the page settings. Margins are set in inches. Scale variable s is a number in the range of 10 (for 1000%) to 0.2 (for 20%) with the default as 1 (for 100%). If Portrait is True the page is oriented for portrait, otherwise the page is landscape. Paper Size is a quoted string specifying the paper size, for example, "Letter" or "Legal".

Example

The example below creates a new window and configures the page setup.

w = New Window( "Window",
	Text Box( "Page Setup Test" )
);
w << Set page setup(
	margins( 1, 1, 1, 1 ),
	scale( 1 ),
	portrait( 1 ),
	paper size( "Letter" )
);

db<<Set Print Headers(left header, center header, right header)

Description

Sets the left, center, and right header for print output.

Example

w = New Window( "Window", Text Box( "Header Example" ) );
w << Set Print Headers(
	"Today is: &d;", // left
	"&wt;", // center
	"Page &pn; of &pc;" // right
);
w << Print Window;

db<<Set Print Footers(left footer, center footer, right footer)

Description

Sets the left, center, and right footer for print output.

Example

w = New Window( "Window", Text Box( "Footer Example" ) );
w << Set Print Footers(
	"Today is: &d;", // left
	"&wt;", // center
	"Page &pn; of &pc;" // right
);
w << Print Window;

db<<Set Stretch(x,y)

Description

Sets the horizontal and vertical stretching of display boxes.

Arguments

"Window"

The box stretches to fill the space provided by the window, The sizing depends on the minimum and maximum properties for the box.

"Fill"

The box stretches to fill the available space in its container.

"Off"

The box does not stretch.

"Neutral"

Many boxes start in the neutral state. A leaf box (a box that has no children) that is neutral resolves to "Off". Most container boxes aggregate the stretching behavior (and minimum and maximum) of their child boxes.

db<<Set Submenu (index, submenu count)

Description

Sets the submenu items for the item (specified by index number) by specifying the number of items in the submenu.

Example

The example below creates a menu containing “A”, “B”, and “C” with “A” having a submenu “A1” and “A2” and “B” having a submenu “B1”, “B2”, and “B3”.

New Window( "title", ob = Outline Box( "title" ) );
ob << Set Menu Script(
	{"A", "", "A1", Print( "A1" ), "A2", Print( "A2" ),
	"B", "", "B1", Print( "B1" ), "B2", Print( "B2" ), "B3", Print( "B3" ),
	"C", Print( "C" )}
);
ob << Set Submenu(1, 2); // menu A with 2 items in submenu A1 and A2
ob << Set Submenu(4, 3); // menu B with 3 items in submenu B1, B2, and B3

db<<Set Report Title(title)

Sets a new title. The title is quoted.

Show Properties(db)

Shows the messages a given display box can interpret.

db<<Sib

Returns the sibling of the display box.

db<<Sib Append(db2)

Appends a display as a sibling to this one. The argument must evaluate to a display box owner or reference.

db<<Size Window(x, y)

Resizes the containing window.

db<<Update Window

Updates the window that holds the display box (and possibly other windows as well, depending on the operating system) if there are invalidated regions. Previously invalidated box areas are redrawn with their new content.

Notes

In some interactive JSL scripts that combine sliders with JSL callbacks, you might need to use <<Update Window to keep parts of the display synchronized with the slider.

db<<Zoom Window

Resizes the window to be large enough to show all of its contents.

Want more information? Have questions? Get answers in the JMP User Community (community.jmp.com).