Where

CHECK_BOX OPT= Settings

The single character parameters for OPT=char$ are listed below:

"<"	Bitmap Left. Places bitmap left of text.
">"	Bitmap Right. Places bitmap right of text.
"_"	Bitmap Below. Places bitmap below text.
"~"	Bitmap Above. Places bitmap above text.
"^"	Dropdown. Creates a drop-down style Check box. When the Drop-down portion of the button is clicked the system will generate the CTL value associated with the MNU=ctl option. Generally, the program (or NOMADS) will then display a POPUP_MENU associated with the button.
"*"	Default. Defines check box as default push button.
"B"	Bitmap Button. Has a bitmap whose width is divided into four images. Use this attribute to custom design buttons of any colour, style or shape by controlling the bitmap image that appears. Each of the four divisions represents what a button will look like in a particular state: 1st quarter: Bitmap image when button is disabled. 2nd quarter: Bitmap image when button is in normal (released) state. 3rd quarter: Bitmap image when the mouse is over the button. 4th quarter: Bitmap image when the button is pressed.
"D"	Disabled. Check box is grayed out and is not accessible to the user.
"F"	Flat Box. Check box shows no raised outline unless the mouse is over the button or the button is pushed.
"f"	Flat-No Border. Same as "F", but has no border.
"H"	Hide. Check box is not displayed but is accessible programmatically.
"O"	Steal Focus. Check box will steal focus from other controls when the mouse moves over the button.
"P"	Sticky - Pressed. Check box remains in the "pressed" position until next selection.
"S"	Signal Only. ProvideX generates a CTL value, but does not shift focus to the check box automatically (the default), but only when focus is explicitly passed to it. Use this to have a button act like a function key.
"s"	Scroll. Button can scroll within a resizable/scrollable dialogue box.
"T"	Transparent. Button is "see-through" to window contents below button area.
"U"	Hyperlink - Underscore. Text is underscored, displayed in hyperlink colour, and highlighted on mouse-over.
"u"	Hyperlink - No Underscore. Same as "U", but without the underscore.
"V"	Hovertext. Indicates that text will change color when mouse is over the button.

Options can be combined to create several different button types. The "f", "T", "U", "u", and "O" options provide the ability to turn buttons into hotspots. This allows for clickable areas on bitmaps, or items such as HTTP URL links on dialogues; e.g.,

"VTf"	Creates a general hotspot.
"VUTf"	Creates an HTML-like hotspot.
"F^"	Creates a word-style toolbar with drop list

The contents$ string expression defines the text or picture to appear on the check box. In the text, you can use an ampersand "&" preceding a character to identify it as a hot key the user can press in conjunction with the Alt key to activate the check box from the keyboard. By default, the text is displayed to the right of a check box. Add a colon ( : ) to the end of the text field to force the text to display to the left side.

Bitmaps and Icons

When adding an image to a check box, enclose the image name in curly braces. Use a leading exclamation point (!) to identify the image as internal, or specify the relative path and filename to access an image file that is external. There are no icons in the ProvideX executable and ProvideX does not support retrieving icons from either resource libraries or other system DLLs /executables. For more information on internal/external images and recognized image file types, refer to Displaying Bitmaps/Icons.

When you use text as well as images, the relative positions of the image and the text set their relative placement. The following are examples of contents$ expressions:

"{!Add}Add" ! Displays the {!Add} bitmap in front of the text "Add"
"Delete{!Del}" ! Displays the {!Del}bitmap after the text "Delete"

If you enclose two images separated by a pipe | vertical bar in a single set of curly braces, the first will be displayed when the CHECK_BOX state is 0 (zero for OFF/normal state), the second when the CHECK_BOX state is 1 (ON); e.g.,

"{!Stop|C:\MYBMP\Go}"

You can also use the OPT="B"clause for a Bitmap Button to display different images for different states.

Check Box Properties

The Apostrophe Operator can be used with the unique logical identifier (ctl_id) to dynamically read and alter a wide variety of control attributes (properties) directly from the programming language. The list of properties available for manipulating a check box object are described in Control Object Properties.

CHECK_BOX [*]ctl_id,@(col,ln,wth,ht)=contents$[,ctrlopt]

Use this format to create a check box. The ctl_id is a unique value that is used to generate a CTL value whenever the user toggles the box; e.g.,

0010 REM Create check box, CTL=100, Text="Post Month End", ALT-P to select box
0020 CHECK_BOX 100,@(60,20,20,2)="&Post Month End"

If the ctl_id has a leading asterisk, the check box is considered global (not tied to a specific window).

CHECK_BOX REMOVE [*]ctl_id[,ERR=stmtref]

Use the CHECK_BOX REMOVE format to delete a check box. Note that, by default, all check boxes which are not global are deleted when a window is removed or dropped, and on a BEGIN; e.g.,

0030 CHECK_BOX REMOVE *17000 ! Removes global check-box 17000

Global check boxes can be removed using the above syntax, or cleared using the START directive.

CHECK_BOX {DISABLE | ENABLE}[*]ctl_id[,ERR=stmtref]

Use the CHECK_BOX DISABLE format to gray out a check box so that it will be visible but inaccessible to users. To reactivate it, use CHECK_BOX ENABLE; e.g.,

0030 CHECK_BOX ENABLE 100

CHECK_BOX GOTO [*]ctl_id[,ERR=stmtref]

Use the CHECK_BOX GOTO format to set the focus on a check box, ready for the user's next input; e.g.,

0030 CHECK_BOX GOTO 110

CHECK_BOX {ON | OFF}[*]ctl_id[,ERR=stmtref]

Use the CHECK_BOX {ON | OFF} format to make it appear that a check box is depressed or released; e.g.,

0030 CHECK_BOX OFF 110,ERR=0040

CHECK_BOX READ [*]ctl_id,state$[,mode$][,ERR=stmtref]

Use the CHECK_BOX READ format to receive the current state of the check box ("0"= off and "1"= on). Use the second (optional) string variable to have ProvideX return the user's method of toggling the check box. Once read, this field is reset to $00$. Some of the possible values are:

• $01$ for MOUSE-CLICK.
• $02$ for DOUBLE MOUSE-CLICK.
• $0D$ for Enter.
• $20$ for SPACEBAR (and keyboard HotKey, as in the example below.)
• $00$ when the user exits the check box.

Read the user's selection(s) to make them available to your applications. The ON_OFF$ variable, in the example, below receives the current on/off state. For STROKE$, in the example below, ProvideX returns $20$ when the user makes the selection using either SPACEBAR or the &T hot key Alt -T.

0010 ! CHECK_BOX Example
0020 PRINT 'CS'; LIST
0030 CHECK_BOX 90,@(40,17,25,3)="&Toggle for Status"
0040 LET C_BX=90; LET C_BX'BACKCOLOUR$="LIGHT CYAN"
0050 SETCTL C_BX:READ_BOX
0060 CHECK_BOX GOTO C_BX
0070 PRINT @(40,24),"HotKey=<Alt-T>. Try Mouse and keyboard too. END=<F4>"
0080 GETINPUT:
0080:OBTAIN (0,SIZ=1,ERR=GETINPUT)@(0,0),'CURSOR'("off"),'ME',IN_VAR$,'MN';
0080:LET CT=CTL
0090 IF CT=4 THEN GOTO END
0100 READ_BOX:
0110 CHECK_BOX READ C_BX,ON_OFF$,STROKE$
0120 ! WRITE_BOX
0130 CHECK_BOX WRITE C_BX,ON_OFF$
0140 PRINT @(40,20),"Current Status: ",ON_OFF$
0150 PRINT @(40,21),"Key Stroke : ",HTA(STROKE$)

CHECK_BOX WRITE [*]ctl_id,state$[,ERR=stmtref]

Use the CHECK_BOX WRITE format to update the check box's state; e.g.,

0100 ! WRITE C_BX
0110 LET ON_OFF$="0"
0130 CHECK_BOX WRITE C_BX,ON_OFF$

How the value written to the Check box will be interpreted are as follows:

• If the value is one of the translation table values, its position in the table defines the state (First=off, Second=on)
• If the value is "1" set on
• If the value is "0", "N" or NULL ("") set off
• Any other value sets the check box ON

CHECK_BOX SET_FOCUS ctl_id,ctl_val[,ERR=stmtref]

This format generates a CTL value whenever focus shifts to the input region.

CHECK_BOX {HIDE | SHOW}[*]ctl_id[,ERR=stmtref]

Use the CHECK_BOX HIDE format to keep a check box from being displayed. Use the CHECK_BOX SHOW format to restore the display of a hidden check box.