STATUS

A STATUS bar is a bar that typically appears along the bottom border of a window to display status messages. It can be divided up into several "parts", with each part displaying a different message (ie, text).


Uses

Can be used to provide feedback to the user about the success or failure of operations. Can also be used to display help information about a menu item or command.


Styles

A STATUS must be created with one of the following 4 styles for its alignment:

Top The control positions itself at the top of the parent window and sets its width to be the same as the parent window’s width.
Bottom The control positions itself at the bottom of the parent window and sets its width to be the same as the parent window’s width.
Left The control positions itself on the left edge of the parent window and sets its height to be the same as the parent window’s height.
Right The control positions itself on the right edge of the parent window and sets its height to be the same as the parent window’s height.

A STATUS also have any, all, or none of the following styles:

No divider (NODIVIDER) Prevents a two-pixel highlight from being drawn at the top of the control.
Show Gripper (GRIP) Includes a sizing grip at the right end of the status window. A sizing grip is similar to a sizing border; it is a rectangular area that the user can click and drag to resize the parent window.
No parent align (NOPARENTALIGN) Prevents the control from automatically moving to the top or bottom of the parent window. Instead, the control keeps its position within the parent window despite changes to the size of the parent window. If the TOP or BOTTOM style is also used, the height is adjusted to the default, but the position and width remain unchanged.
No resize (NORESIZE) Prevents the control from using the default width and height when setting its initial size or a new size. Instead, the control uses the width and height specified in the request for creation or sizing.
Hide Control is hidden. You can later make it visible with a call to GuiSetCtlPlacement.


Events

A STATUS bar generates the following events:

Event name When it occurs
CLICK The user has clicked the left mouse button within the control.
DBLCLK The user has double-clicked the left mouse button within the control.
RCLICK The user has clicked the right mouse button within the control.
RDBLCLK The user has double-clicked the right mouse button within the control.


REXX Variable

A STATUS bar must have a REXX variable associated with it. You do not need to initialize the variable before opening the window which contains the STATUS bar.


Dynamically add/remove a STATUS bar

You can dynamically add a STATUS bar to an already open window by calling GuiAddCtl. You must pass a line that describes the control. The format for this line is:

STATUS Styles, VariableName, Parts

Styles are those listed above, with each style separated by a | character.

VariableName is the variable name to be associated with the control.

Parts defines the width of each part. The first number is the width of the first part. If there are more parts, the remaining numbers (each separated by a space) are the width of each additional part. The last part may have a width of -1 to mean extend this part to fill the remainder of the status bar.

For example, here we add a STATUS with the style BOTTOM, a REXX Variable name of MyStatus, and 3 parts where the first and second parts have widths of 40 and 60, and the third part fills the remainder of the status bar:

error = GuiAddCtl("STATUS BOTTOM, MyStatus, 40 60 -1")
Note: You are limited to specifying 8 parts at most. If you need to specify more than 8 parts, then use GuiAddCtlText() below.

You can dynamically remove a STATUS bar by calling GuiRemoveCtl. Here we remove the above control:

error = GuiRemoveCtl("MyStatus")


Setting the number of parts

A STATUS bar can have upto 255 different parts (ie, areas of the status bar where text can be displayed). You change the desired number of parts by calling GuiAddCtlText, passing the variable associated with the STATUS bar, a second arg that tells how many parts you wish, and a third arg that is the name of a stem variable that has been set up to indicate the width of each part. For example, here we set 3 parts with the widths of 40, 20, and -1. The value of -1 means extend this part to fill the remainder of the status bar.

StatusBarWidths.1 = 40
StatusBarWidths.2 = 20
StatusBarWidths.3 = -1
error = GuiAddCtlText("MyStatus", 3, "StatusBarWidths")


Displaying a message in a part

To display a message in a particular part, call GuiSetCtlValue, passing the variable associated with the STATUS bar, and a second arg that tells which part you wish to set (where 1 is the first part). You must first set the variable to the message to display. For example, here we display the message New text in part 2:

MyStatus = "New text"
error = GuiSetCtlValue("MyStatus", 2)
To clear a message from a part, set the variable to an empty string:
MyStatus = ""
error = GuiSetCtlValue("MyStatus", 2)
You can optionally specify a drawing style after the part number. The drawing style must be one of:

NOBORDER The text is drawn with a border, appearing lower than the plane of the window.
POPOUT The text is drawn with a border, appearing higher than the plane of the window.
RTLREADING Displays text using right-to-left reading order on Hebrew or Arabic systems.

For example, here we specify a POPOUT drawing style:

MyStatus = "New text"
error = GuiSetCtlValue("MyStatus", 2 "POPOUT")