Directives 

Formats

Where:

Description

Use the CHECK_BOX directive to create check box control objects on the screen. The user can toggle check boxes between two states: ON to check the option or OFF to uncheck it. If you need a third state for a check box, see TRISTATE_BOX directive.

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.

See CHECK_BOX Properties for the list of properties available for manipulating a check box object.

CHECK_BOX OPT= Settings

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

Opt.	Description
"<"	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.
"A"	Default Font Settings. The default font settings of the control will be used. Since the default font setting of a check box control is left justified, the "A" setting will result in left justification in most cases. To force a right, left or center justification, use the FNT= setting and make sure that you have a '4D' mnemonic enabled. Right justification of check boxes with a graphic are possible only with the '4D' mnemonic turned On. See also '2D' and '3D' mnemonics. Example:      print '2D';      check_box 10,@(60,5,20,1.5)="{!Stop}Test",opt="A",fnt="Arial,,R"      print '3D';      check_box 11,@(60,7,20,1.5)="{!Stop}Test",opt="A",fnt="Arial,,R"      print '4D';      check_box 12,@(60,9,20,1.5)="{!Stop}Test",opt="A",fnt="Arial,,R"      escape Right justification works in '2D' or '3D' mode if the graphic is removed from the check box.      print '2D';      check_box 10,@(60,5,20,1.5)="Test",opt="A",fnt="Arial,,R"      print '3D';      check_box 11,@(60,7,20,1.5)="Test",opt="A",fnt="Arial,,R"      escape
"B"	Bitmap Button. Has a bitmap whose width is divided into four images. Use this attribute to custom design buttons of any color, 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. Note: Quarters are horizontal quarters, meaning that if a bitmap is 100 pixels wide, the first quarter of the image is the first 25 pixels wide full height, as in [1][2][3][4], rather than as top left/right and bottom left/right, as in .
"C"	Bitmap Centered. Places the bitmap centered and scaled to fill the button. Button text, if present, will be centered and overlay the image. (The "C" option was added in PxPlus 2018 Update 1.)
"D"	Disabled. Check box is grayed out and is not accessible to the user.
"d"	Check box is permanently disabled (cannot be enabled).
"F"	Flat. 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. PxPlus 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.

Example:

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

CHECK_BOX Contents$

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 PxPlus executable, and PxPlus 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, see Displaying Bitmaps/Icons.

Note:
PxPlus supports alpha channel transparency processing of bitmap images for check boxes (for console output only, not printer and PDF).

(Alpha channel support was added in PxPlus 2017.)

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 or 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):

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

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

Format 1

Define/Create

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:

rem Create check box, CTL=100, Text="Post Month End", ALT-P to select box
     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).

Format 2

Delete

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 that are not global are deleted when a window is removed or dropped, and on a BEGIN:

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.

Format 3

Disable/Enable

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:

0030 check_box enable 100

Format 4

Set Focus To

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:

0030 check_box goto 110

Format 5

Logical On/Off

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:

0030 check_box off 110,err=0040

Note:
This does not alter its state; i.e. "checked" or "unchecked". Use CHECK_BOX WRITE for that function.

Format 6

Read Activation Status

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 PxPlus return the user's method of toggling the check box. Once read, this field is reset to $00$. Possible values are:

$01$ for MOUSE-CLICK
$02$ for DOUBLE MOUSE-CLICK
$0D$ for Enter
$20$ for SPACEBAR (and keyboard Hot Key, as in the CHECK_BOX Example below)
$00$ when the user exits the check box

Read the user's selection(s) to make them available to your applications. In the example below, the ON_OFF$ variable receives the current ON/OFF state, and for STROKE$, PxPlus returns $20$ when the user makes the selection using either SPACEBAR or the &T hot key Alt -T.

Example:

! CHECK_BOX Example
     print 'CS';
     list
     check_box 90,@(40,17,25,3)="&Toggle for Status"
     C_BX=90;
     C_BX'BACKCOLOUR$="LIGHT CYAN"
     setctl C_BX:READ_BOX
     check_box goto C_BX
     print @(40,24),"HotKey=<Alt-T>. Try Mouse and keyboard too. END=<F4>"
GETINPUT:
     obtain (0,siz=1,err=GETINPUT)@(0,0),'cursor'("off"),'ME',IN_VAR$,'MN';
     CT=ctl
     if CT=4 \
          then goto END
READ_BOX:
     check_box read C_BX,ON_OFF$,STROKE$
! WRITE_BOX
     check_box write C_BX,ON_OFF$
     print @(40,20),"Current Status: ",ON_OFF$
     print @(40,21),"Key Stroke : ",hta(STROKE$)

Format 7

Update

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

Use the CHECK_BOX WRITE format to update the check box's state:

! WRITE C_BX
     ON_OFF$="0"
     check_box write C_BX,ON_OFF$

How the value written to the check box will be interpreted is 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.

Format 8

Notify re: Focus

CHECK_BOX SET_FOCUS ctl_id,ctl_val[,ERR=stmtref]

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

Format 9

Hide/Show

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.

See Also

CHECK_BOX Properties
TRISTATE_BOX Create/Control Tristate Box
BUTTON Create/Control Button
RADIO_BUTTON Create/Control Radio Button