A CHECK-BOX control provides a box that the user can check or uncheck. These controls typically present a series of options that can be independently enabled.
The set of CHECK-BOX properties includes:
Common Properties
TITLE
Check boxes may have titles. The title typically appears to the right of the check box. The "TITLE" phrase is used to specify the title. A key letter may be specified in the title (see Book 3, Chapter 6, section 6.4.9, "Common Screen Options").
VALUE
Check boxes have numeric values. A value of "0" indicates the absence of a check mark. A value of "1" indicates the presence of a check mark.
SIZE
The LINES and SIZE values describe the size of the check box's title area. The LINES value specifies the number of lines tall the title area will be. The SIZE value specifies the width of the title area, using the width of the "0" (zero) character as the base unit. Added to the title area is overhead needed for the actual check box. This usually adds several character positions to the width, and may affect the height if the check box is taller than the title's font.
When the program executes on a non-graphical system, the values specified in the CLINES and CSIZE phrases, if present, replace the values specified by the LINES and SIZE phrases.
LINES has a default value of "1". The default value of SIZE is computed by measuring the length of the title using the check box's font and dividing by the width of the "0" (zero) character. Thus, the default width of a check box exactly occupies the space its text takes up on the screen.
When the BITMAP style is used, the LINES and SIZE values have a different meaning. The values are the number of pixels in the height and width of the bitmap image (see Chapter 3, section 3.8, for details). If omitted, the default values depend on the host system. Under Microsoft Windows, the default LINES value is "15" and the default SIZE value is "16". These correspond to the size of buttons typically found on a toolbar.
COLOR
Check boxes use both the foreground and background colors specified. If either is omitted, the corresponding color of the check box's owning subwindow is used.
Bitmap check boxes do not use the specified colors. Instead the colors are derived from the bitmap and the system defaults for push buttons.
STYLES
BITMAP This style causes the check box to be drawn with a bitmap instead of its normal appearance. See Chapter 3, section 3.8 for a complete description.
FRAMED This style is used only with bitmap buttons. It requests that a thin frame be drawn around the button. Typically this appears as a thin black line. Not all systems support frames, in which case the request is ignored. By default, buttons are framed under Windows 3.1, Windows for Workgroups, and Windows NT.
UNFRAMED This style is used only with bitmap buttons. It requests that the button be drawn without a frame. Not all systems support unframed buttons, in which case the request is ignored. By default, buttons are not framed under Windows 95.
SQUARE This style is used only with framed bitmap buttons. It forces the button to have square corners. Without this style, the button will have slightly rounded corners.
SELF-ACT This style creates a self-activating check box. A SELF-ACT check box behaves in the same way as a SELF-ACT push button (see the Push-Button section above for details). Self-activating check boxes return control to the previously active control or window when they are clicked. Typically, you will want to use the NOTIFY style (below) in conjunction with SELF-ACT, so that your program is informed whenever the check box is clicked.
NOTIFY This style tells the runtime to generate a CMD-CLICKED event whenever the value of the check box is changed by the user. This allows your program to respond immediately to the change. In essence, the check box acts like a combination check box and push button. Without the NOTIFY style, the check box remains active after it has been changed (exception: see SELF-ACT above).
LEFT-TEXT Check boxes with this style display their text to the left of the box instead of to the right. Note that if you use this style and try to vertically align several check boxes, the boxes may not align vertically. This is because the default behavior of the runtime is to place the right edge of the check box at the minimum distance needed from its left edge to accommodate the control's text. This results in the boxes being placed in different columns depending on the text of each control. Supplying a uniform width using the SIZE property overrides this behavior. (create, modify)
FLAT This style is used only with bitmap buttons. It creates a check box without visible borders on Windows systems. On non-Windows systems, this style has no effect.
Special Properties
BITMAP-NUMBER (numeric) This property identifies the particular bitmap image to use with the check box (see the Chapter 3, section 3.8 for details). If you explicitly name this property when creating the control, the BITMAP style is automatically applied by the compiler. Note that this does not occur if you use the PROPERTY phrase to specify this property (by giving its identifying number).
BITMAP-HANDLE (handle) This property identifies the bitmap image strip to use with the check box. See Chapter 3, section 3.8 for details.
TERMINATION-VALUE (numeric) This property works in a manner identical to the push button property of the same name (see section 5.4). This property is used only when the NOTIFY style is also used. The compiler applies the NOTIFY style automatically if this property is named when the control is created. Note that the NOTIFY style is not automatically applied if you use the PROPERTY phrase to specify this property (by giving its identifying number).
EXCEPTION-VALUE (numeric) This property works in a manner identical to the push button property of the same name. This property is used only when the NOTIFY style is also used. The compiler will apply the NOTIFY style automatically if you explicitly name this property when you create the control. Note that the NOTIFY style is not automatically applied if you use the PROPERTY phrase to specify this property (by giving its identifying number).
Events
CMD-CLICKED
CMD-GOTO
CMD-HELP
MSG-VALIDATE
Examples
The following creates a simple check box:
DISPLAY CHECK-BOX, TITLE "Option &1",
HANDLE IN CHECK-BOX-1.
Here is the Screen Section equivalent:
03 CHECK-BOX, "Option &1".
In this example, the check box starts out with a check mark in it:
DISPLAY CHECK-BOX "Option &2", VALUE 1,
HANDLE IN CHECK-BOX-2.
It is common in Screen Section entries to assign a VALUE data item to the box so that you can set and test the check box:
03 CHECK-BOX, "Option &3", USING OPTION-3-FLAG.
Here is a check box that can be dynamically disabled (grayed-out):
03 CHECK-BOX, "Option &4", USING OPTION-4-FLAG,
ENABLED = BOX-4-ENABLED-FLAG.