SectionControl

(System Library)

Description: This statement creates a control that displays a variable number of sections. Visually, a section consists of a header and content. The control manages the layout and geometry for the sections and runs a caller-supplied module to display the section content (see Comments below).

Returns: Object

Usage: Steady State

Format: \System\SectionControl(HeadingFont, HeadingTextColor, HeadingBackColor)

Parameters: HeadingFont { Font } { required } { no default }

The font to use for the heading.

HeadingTextColor { numeric } { required } { no default }

The color to be used for the heading text.

HeadingBackColor { numeric } { required } { no default }

The color to be used as the background for the heading text.

Related Sub-functions and Variables:

Public Variables:

ExpandEnable – Enable/Disable the expand tool button. Default: 1

WindowEnable – Enable/Disable the new window tool button. Default: 1

PopupTitle – The popup window title string. Defaults to the value of Heading.

Sub-Functions

AddSection(Heading;[, ContentModule, InitiallyExpanded, Param1, Param2, ExpandEnable, WindowEnable, PopupTitle, AvailableHeightPtr])

Heading can be a text value or a module value. If a text value, it is rendered in the header. If it is a module value, it is a caller-supplied module to draw the header with the following parameters:

Heading	Description
X (in)	X coordinate of LHS of drawing area
Y (in)	Y coordinate of the top of the drawing area.
Width (in)	The number of X-pixels available in which to draw.
Height (in)	The number of Y-pixels available in which to draw.
TextColor (in)	The default heading text color.
BackColor (in)	The background color for the heading text.
TextFont (in)	The default heading text font.
Param1 (in)	Param1 passed to AddSection.
Param2 (in)	Param2 passed to AddSection.

ContentModule is a module value of the caller-supplied module to render the content. It is called with the following Parameters:

ContentModule	Description
X (in)	X coordinate of LHS of drawing area
Y (in)	Y coordinate of the top of the drawing area.
Width (in)	The number of X-pixels available in which to draw.
ContentHeight (out)	The number of Y-pixels this method needs.
VisibleContent (in)	Boolean: TRUE if content is visible.
Param1 (in)	Param1 passed to AddSection.
Param2 (in)	Param2 passed to AddSection.
AvailableHeight (in)	Numeric value used if the DisplaySection module knows how much height can be made available

The content drawing module must maintain the value of ContentHeight in steady-state. It is used by the control to manage the geometry of other sections in the control. When the Boolean VisibleContent is TRUE (set by the SectionControl), the module must draw the content. When the control sets VisibleContent FALSE, the module must stop drawing the content. By setting the output value ContentHeight, the drawing module tells the control that it is no longer drawing and the section can be collapsed.

InitiallyExpanded can be set to TRUE if the heading is to be initially expanded, or FALSE if the heading is to be initially collapsed.

Param1 is a parameter passed to the drawing module.

Param2 is a parameter passed to the drawing module.

ExpandEnable is a Boolean value giving the initial setting for whether the expand button should be enabled. Default: 1

WindowEnable is a Boolean value giving the initial setting for whether the popup window button should be enabled. Default: 1

PopupTitle is an initial title string for the popup window. Defaults to the value of Heading.

AvailableHeightPtr is a numeric value indicating the number of pixels in the Y-axis available to be drawn in. Can be useful where ContentModule needs to present scrollable content to the operator.

AddSection Comments: AddSection returns the object value of a SectionControl\DisplaySection instance (see below). This object value is used as a parameter to DeleteSection (see below) as well as providing some read-only values that the caller may access. These are:

Ready Default 0. When 1, the caller can safely access the public variables listed below.

ExpandEnable Default 1. Draws and enables the expand toolbutton.

WindowEnable Default 1. Draws and enables the new window toolbutton.

AddButtons Subroutine module. Takes a single parameter, being a ToolBar format data array containing additional tool buttons to insert at the LHS of the embedded ToolBar.

DeleteSection (Module)

Deletes a section from the control.

DeleteSection(Object)

Object is the object value returned from a previous AddSection call (see above).

Note: The following sub-function, DisplaySection, is not meant to be used externally. It is used internally by AddSection

DisplaySection (Module)

DisplaySection(X, Heading, DisplayModule, VisibleContent, Param1, Param2, EpandEnable, WindowEnable, PopupTitle, AvailableHeightPtr)

X is the coordinate of LHS of section.

Heading is the heading text or module for the heading.

DisplayModule is the module value of the content drawing module.

VisibleContent is a Boolean value that can be set to TRUE when content is visible.

Param1 is a parameter passed to the drawing module.

Param2 is a parameter passed to the drawing module.

EpandEnable, Booean to enable the Expand button (default: 1)

WindowEnable, Boolean to enable the New Window button (default: 1)

PopupTitle, Text string giving the title of the popup window

AvailableHeightPtr Optional numeric – in case AddSection defines the height available for this secton.

Height (Public Variable)

Height is a public (read-only) variable that gives the overall height of the SectionControl in pixels.

Ready (Public Variable)

Ready is a public (read-only) variable that must go to a non-zero value prior to AddSection or DeleteSection being called (see Comments section below).

Comments: As indicated above, a section consists of a header and content. The control manages the layout and geometry for the sections and runs a caller-supplied module to display the section content.

Call a SectionControl in steady-state, wait until the public variable Ready goes TRUE (non-zero), and then call AddSection and DeleteSection (see the Related Sub-functions section above) to add sections to and delete sections from the control.

SectionControl assumes that it is being run in a child window and expands to consume the entire window. It automatically adds a vertical scroll bar when required.