CHECK
A CHECK(mark) button is a graphical, square button that is filled in with a graphical checkmark depending upon whether the button is "on" or "off". The label is immediately to the right of the button. Alternately, an image can be used for the button.
A CHECK button's state toggles between "on" and "off" each time that the user activates it. (ie, If it's currently "off" when he activates it, it turns "on" and stays "on", and vice versa). Like the push button, the user activates a checkmark button when he clicks the mouse upon it. Alternately, pressing the SPACE BAR will activate the button which currently has the focus (ie, is highlighted). But, unlike radio buttons, each checkmark's state is independent of the others in the Group. So, all of them can be turned "on", or all of them can be turned "off", or any combination inbetween.
Uses
Checkmark buttons are used to allow the user to choose any, all, or no items from several available choices. For example, there may several checkmark buttons, each offering a different style for a font (ie, underlined, italic, boldface), and the user can choose any/all/none of those choices to be applied to the font simultaneously.
Styles
Shortcut | The Shortcut box lets you enter a keyboard shortcut that will automatically select this control whenever the user presses that shortcut. |
A CHECK button must be created with one of the following 3 styles:
Text | Displays a label next to the check box. |
Bitmap | Displays a bitmap next to the check box. |
Icon | Displays an icon next to the check box. |
When you choose Text style, then the button can have a label (ie, caption). If you choose Bitmap or Icon styles, then you instead must choose some Bitmap or Icon resource you have already added to your Window Layout script. This image will be displayed in the button.
A CHECK button may additionally have any, all, or none of the following styles:
3 State | (3STATE) The check box has three states -- checked, unchecked, and disabled. |
Auto | The operating system automatically toggles the check box's graphic when the user clicks on the check box. If AUTO is not specified, the Window Layout script must have a function to handle the CLICK event for the control, and manually check/uncheck/disable using GuiSetCtlValue(). |
Flat | Flat appearance. |
Pushlike | The CHECK has the appearance of a PUSH button. When selected, it remains "pushed in". |
Multiline | (MULTI) Wraps the label to multiple lines if the text is too long to fit on a single line inside the button rectangle. |
Button on right | (RBUTTON) Positions the check box on the right side of the button rectangle. |
Notify | Causes the Window Layout's DBLCLK, FOCUS, and UNFOCUS subroutines to be called when the button is double-clicked, loses the focus, or gains the focus, respectively. Note that you can always add a function to handle a button's CLICK event regardless of this style. |
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). |
Tabstop | The user can move to this control using the TAB key. |
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. |
In addition to the above styles, a CHECK button may have one of the following 3 styles:
Left | Left-justifies the label, bitmap, or icon. If the RBUTTON style is not specified, the item is left-justified on the right side of the check box. |
Right | Right-justifies the label, bitmap, or icon. If the RBUTTON style is not specified, the item is right-justified on the right side of the check box. |
Center | The label, bitmap, or icon is horizontally centered. |
In addition to the above styles, a CHECK button may have one of the following 3 vertical alignment styles:
Top | The label, bitmap, or icon is positioned at the top of the button. |
Bottom | The label, bitmap, or icon is positioned at the bottom of the button. |
Center | (VCENTER) The label, bitmap, or icon is vertically centered. |
Extra styles
A CHECK button can have any, all, or none of the following extra styles:
Quiet | Do not report any events for this control. |
Modal Frame | (MODALFRAME) Has a double border. |
Static Edge | (STATICEDGE) Has a three-dimensional border intended to be used for windows that do not accept user input. |
Client Edge | (CLIENTEDGE) Has a 3D look comprised of a border with a sunken edge. |
Accept files | (FILES) Accepts drag-and-drop files (ie, the DROPFILES event). |
Align text right | (RIGHT) Gives the control generic right-aligned properties (as opposed to the default of left-aligned properties). |
Read right-to-left | (RTLREADING) Displays the window text using right-to-left reading order properties (instead of the default of left-to-right). |
Transparent | The control is to be transparent. Any controls that are beneath this one are not obscured. |
Events
A CHECK button generates the same events as a PUSH button.
REXX Variable
A CHECK button must have a REXX variable associated with it. Before opening the window which contains the CHECK button, you must set this variable's value to either 0 or 1, depending upon whether you wish the box to be unchecked or checked. You may alternately set the value to 3 for a 3STATE style CHECK button, which is the "indeterminate" state.
Dynamically add/remove a CHECK button
You can dynamically add a CHECK button to an already open window by calling GuiAddCtl. You must pass a line that describes the control. The format for this line is:
CHECK X, Y, Width, Height, Styles, ExtraStyles, VariableName, Accelerator, LabelX 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.
Accelerator is the keyboard shortcut that causes the button to be "pushed".
Label is the (text) label for the control. You can use the two characters \t to represent a TAB character. You can also include multiple lines by using the characters \n to mark the end of a line. If you want to put a \ character in the text, then you must double it up as \\.
If the button has the ICON or BITMAP style, then Label will instead be either the name of a file containing the icon/bitmap image, or the image number if the image is embedded inside of an EXE you created with the Window Editor. In this case, you do not need to initialize the associated REXX variable before calling GuiAddCtl.
Before adding a check button, you should set its associated REXX variable to the value 0 or 1 (or 2 if a 3STATE). For example, here we add a CHECK button at an X Y position of 10, 10, with a width and height of 40 and 20, with the styles AUTO and RBUTTON, extra styles of CLIENTEDGE and QUIET, a REXX Variable name of MyCheckButton, and a label of Check me. We set its value to 1 (ie, checked).
MyCheckButton = 1 error = GuiAddCtl("CHECK 10,10,40,20, AUTO|RBUTTON, CLIENTEDGE|QUIET, MyCheckButton,, Check me")You can dynamically remove a CHECK button by calling GuiRemoveCtl. Here we remove the above button:
error = GuiRemoveCtl("MyCheckButton")
Change a CHECK button's label.
If the button has the TEXT style, you can dynamically change its label by calling GuiAddCtlText. You pass the REXX variable name for the button, and the new label. Here we change the above button's label to Don't check me:
error = GuiAddCtlText("MyCheckButton", "Don't check me")
Change a CHECK button's image.
If the button has the ICON or BITMAP style, you can dynamically change its image by calling GuiAddCtlText. You pass the REXX variable name for the button, and either the filename of the icon/bitmap, or the image number if the image is embedded in an EXE you created with the Window Editor. Here we change the above button's image to the image in the file named C:/MyIcon.ico:
error = GuiAddCtlText("MyCheckButton", "C:/MyIcon.ico")Note: Use forward (not back) slashes to separate the directory names.
Change a CHECK button's check
You can dynamically check or uncheck a CHECK button by calling GuiSetCtlValue. You first set its associated REXX variable to the desired value, and then call GuiSetCtlValue, passing that variable name. For example, here we uncheck the above button (ie, set its value to 0):
MyCheckButton = 0 error = GuiSetCtlValue("MyCheckButton")
Query a CHECK button's check
You can query whether a CHECK button is currently checked or unchecked by calling GuiGetCtlValue. This will set its associated REXX variable to the control's current value. For example, here we query the above button:
error = GuiGetCtlValue("MyCheckButton") IF error == "" THEN DO IF MyCheckButton == 0 THEN SAY "It's unchecked." ELSE SAY "It's checked." END