Directives 

Formats

Where

Description

Use the TRISTATE_BOX directive to create and control a tristate box control object. A tristate box is a check box in which the user can toggle between three states: ON to select an option, OFF to disable it, or your choice of a third state. See Format 1: Create for an example.

Tristate 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 TRISTATE_BOX Properties for the list of properties available for manipulating a tristate box control object.

TRISTATE_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.
"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 .
"D"	Disabled. Check box is grayed out and is not accessible to the user.
"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"	Hover text. Indicates that text will change color when mouse is over the button.

Options can be combined to create several different tristate box types. The "f", "T", "U", "u" and "o" options provide the ability to turn tristate boxes 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.

TRISTATE_BOX Contents$

The contents$ string expression defines the text or picture to appear on the tristate 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 tristate box from the keyboard.

Bitmaps and Icons

When adding an image to a tristate 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.

When you use text as well as images, the relative positions of the image and the text set their relative placement. The following are example 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 your string expression includes three bitmaps separated by a vertical bar inside a single set of curly braces, the first will be displayed when the tristate box is in its normal state OFF, the second while the tristate box is ON, and the third when the tristate box is in a third other state.

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

Format 1

Create

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

Use the value in ctl_id to give your tristate box a unique identifier. This value generates a CTL value whenever the tristate box is toggled. If ctl_id has a leading * (asterisk), the tristate box is considered global (not tied to a specific window).

Example:

0120 tristate_box 102,@(2,19,12,3)="{!File_Save}&Save"
0130 tristate_box 103,@(22,15,12,2)="&Destroy{!Trash|!Trash_open|!Bomb_blast}"
0140 tristate_box 104,@(22,19,12,3)="{!Lite_Green|!Lite_Yellow|!Lite_Red}"
0150 input (0,hlp="Tristate_Box")@(40,18),"Select...: ",'CL',X$
0160 if ctl>100 and ctl<105 then tristate_box read ctl,B$;print @(40,19),"Selection:",ctl,":",B$,'CL',; goto 0150
0170 if ctl=0 or ctl>=3 then stop else goto 0150

Format 2

Delete

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

Use the TRISTATE_BOX REMOVE format to delete a tristate box. By default, if tristate boxes are not global, they are deleted when a window is removed/dropped or the application issues a BEGIN. Global tristate boxes can be removed manually or cleared by a START.

Format 3

Disable/Enable

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

Use the TRISTATE_BOX DISABLE format to gray out a tristate box so that it will be visible but inaccessible to users. To reactivate it, use TRISTATE_BOX ENABLE.

Format 4

Set Focus

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

Use the TRISTATE_BOX GOTO format to set the focus on the tristate box so that it is ready to receive the next user input.

Format 5

Logical Push/Release

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

Use the TRISTATE_BOX ON format to make it appear that a tristate box selection has been made. Use the OFF format to make it appear that it has been released.

Format 6

Read Activation State

TRISTATE_BOX READ [*]ctl_id,state$[,ERR=stmtref]

The TRISTATE_BOX READ format returns the current state of the tristate box. If no translation table is defined, the default values are "0" for OFF, "1" for ON, or "2" for Other.

Format 7

Update

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

The TRISTATE_BOX WRITE format is used to write/update new values for the tristate box. How the value written to the tristate 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, Third=Other).
• If the value is "0", "N" or NULL (""), set OFF.
• If the value is "1", set ON.
• If the value is "2", set to the Third/Other state.
• Any other value sets the check box ON ("1" state).

See Also

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