Where

TRISTATE_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 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; 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 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 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 example contents$ expressions:

"{!Add}dd" ! 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.

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. The list of properties available for manipulating a tristate box are described in Control Object Properties, .

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).

Examples:

0120 TRISTATE_BOX 102,@(2,19,12,3)="{!File_Save}&Save"
0130 TRISTATE_BOX103,@(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 IFCTL>100 AND CTL<105THEN TRISTATE_BOXREADCTL,B$;PRINT @(40,19),"Sele
0160:ction:",CTL,":",B$,'CL',; GOTO 0150
0170 IF CTL=0 OR CTL>=3 THEN STOP ELSE GOTO 0150

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.

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.

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

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

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.

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.

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

Use the TRISTATE_BOX format above to write/update new values for the tristate box. How the value written to the Tristate box will be interpreted are as follows:

• If the value is one of the translation table values, it's 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)