SectionControl

(System Library)

Description	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).
Returns	Object
Usage	Steady State only.
Function Groups	Advanced Module, Graphics
Related to:	DialogInitPos \| DropList \| GridList \| HScrollbar \| Listbox \| RadioButtons \| SplitList \| ToolBar \| VScrollbar
Format:	System.SectionControl(HeadingFont, HeadingTextColor, HeadingBackColor)
Parameters

HeadingFont

Required. The font to use for the heading.

HeadingTextColor

Required. The color to be used for the heading text.

HeadingBackColor

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

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.

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 pop-up window title string. Defaults to the value of Heading.

Height

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

Ready

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)

Sub-Functions:

AddSection
Comments:	AddSection returns the object value of a SectionControl\DisplaySection instance. This object value is used as a parameter to DeleteSection as well as providing some read-only values that the caller may access. These are: Ready When 1, the caller can safely access the public variables listed. Default 0. ExpandEnable Draws and enables the expand tool button. Default 1. WindowEnable Draws and enables the new window tool button. Default 1. 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.
Related to:
Format:	AddSection(Heading[, ContentModule, InitiallyExpanded, Param1, Param2, ExpandEnable, WindowEnable, Pop-upTitle, AvailableHeightPtr])
Parameters:

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:

Parameter	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

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.
Available Height (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

A parameter passed to the drawing module.

Param2

A parameter passed to the drawing module.

ExpandEnable

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

WindowEnable

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

PopupTitle

An initial title string for the pop-up window. Defaults to the value of Heading.

AvailableHeightPtr

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.

DeleteSection
Comments:	Deletes a section from the control.
Related to:
Format:	DeleteSection(Object)
Parameters:

Object

The object value returned from a previous AddSection call (see above).

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

DisplaySection
Comments:	Used internally by AddSection.
Related to:
Format:	DisplaySection(X, Heading, DisplayModule, VisibleContent, Param1, Param2, EpandEnable, WindowEnable, Pop-upTitle, AvailableHeightPtr)
Parameters:

The coordinate of LHS of section.

Heading

The heading text or module for the heading.

DisplayModule

The module value of the content drawing module.

VisibleContent

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

Param1

A parameter passed to the drawing module.

Param2

A parameter passed to the drawing module.

EpandEnable

Boolean 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 pop-up window

AvailableHeightPtr

Optional numeric - in case AddSection defines the height available for this section.