GROUP
This is a rectangular box, within which other controls can be placed. The box can have its own label, which usually pertains to whatever is the purpose of the controls within the box.
A user can move the mouse pointer over the group box area and click the mouse button to cause an event to occur.
Uses
Identifies controls that "belong together" usually because they are all related to one operation.
Styles
A GROUP box must be created with one of the following 3 styles for its alignment:
Left | Displays the label on the top left side of the box. |
Center | Displays the label in the top right center of the box. |
Right | Displays the label on the top right side of the box. |
A GROUP box may additionally have any, all, or none of the following styles:
Bitmap | Displays a bitmap. |
Icon | Displays an icon. |
Flat | Flat appearance. |
Notify | Causes the Window Layout's DBLCLK or CLICK subroutines for this control to be called when the mouse is double-clicked or clicked inside of the group box area (but not on some control within it). |
No sibling | (NOSIBLING) Prevents this control from drawing into any overlapping controls. |
Group | Marks this control as the first of a group of controls in which the user can move from one control to the next with the arrow keys. All subsequent controls (after this first control) belong to the same group up to the next control that has its GROUP flag set. (ie, One group ends where the next begins). |
Disabled | Control is initially disabled. You can later enable it with a call to GuiSetCtlPlacement. |
Hide | Control is hidden. You can later make it visible with a call to GuiSetCtlPlacement. |
Events
A GROUP box generates the following events:
Event name When it occurs CLICK The user has clicked inside the groupbox area. Note: A disabled group box does not cause a CLICK event. This event also does not occur if the NOTIFY style is not specified for the group box. DBLCLK The user has double-clicked inside the groupbox area. Note: A disabled group box does not cause a DBLCLK event. This event also does not occur if the NOTIFY style is not specified for the group box.
REXX Variable
A GROUP box must have a REXX variable associated with it only if you specify the NOTIFY style, or you wish to be able to change its label or state (with GuiSetCtlPlacement). You do not need to initialize the variable before opening the window which contains the group box.
Change the label
You can dynamically change the label by calling GuiAddCtlText. You pass the REXX variable name for the group box (ie, you must have associated a variable with the control), and the new label. Here we change the label to Stuff (assuming the associated variable is "MyGroupbox"):
error = GuiAddCtlText("MyGroupbox", "Stuff")To blank out the label, omit the second arg.
Dynamically add/remove a GROUP box
You can dynamically add a GROUP control to an already open window by calling GuiAddCtl. You must pass a line that describes the control. The format for this line is:
GROUP X, Y, Width, Height, Styles, ExtraStyles, VariableName, Accelerator, TextX and Y is the position of the top left corner of the control, relative to the window's top left corner.
Width and Height are the size of the control, in pixels.
Styles and ExtraStyles are those listed above, with each style separated by a | character.
VariableName is the variable name to be associated with the control. You can omit this if you do not need to later remove/modify the control, nor receive events from it.
Accelerator is the keyboard shortcut that causes the control to generate a CLICK event.
Text is the label displayed by the control. You can omit this field if you want the label initially blank, or if you intend to set the text with GuiAddCtlText().
Note: There is a limit of 255 characters for the Text field. If you need to set a longer string, then use GuiAddCtlText().
For example, here we add a GROUP control at an X Y position of 10, 10, with a width and height of 80 and 40, with the styles FLAT, extra styles of CLIENTEDGE and QUIET, a REXX Variable name of MyGroupbox, and a label of Stuff:
error = GuiAddCtl("GROUP 10,10,80,40, FLAT, CLIENTEDGE|QUIET, MyGroupbox, Stuff")
You can dynamically remove a GROUP box by calling GuiRemoveCtl. Here we remove the above group box:
error = GuiRemoveCtl("MyGroupbox")