Where

BUTTON 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 button. 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.
"="	Sizer. Creates a special Sizer style button. This buttons ar capable of being dragged across or up/down the screen to enable re-sizing of windows regions. See Sizer Buttons. Sizer buttons are a +PxPlus Exclusive
"*"	Default. Defines button as default.
"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. Button is grayed out and is not accessible to the user.
"F"	Flat. Button 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. Button is not displayed but is accessible programmatically.
"O"	Steal Focus. Button will steal focus from other controls when the mouse moves over the button.
"S"	Signal Only. ProvideX generates a CTL value, but does not shift focus to the button 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.
"W"	Web link. This style of button emulates standard Web page text hyperlinks. The button consists of underscored text aligned to the top left corner that highlights when the mouse is positioned over the button. The button font may contain "C" or "R" to center / right justify the text. Web link style buttons are a +PxPlus Exclusive
"Y"	System Tray. Indicates that button will actually appear in the System Tray System tray buttons are a +PxPlus Exclusive

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

BUTTON contents$

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

Using Bitmaps and Icons

When adding an image to a button, 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 the options available for displaying internal/external images and the 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}Add" ! Displays the {!Add} bitmap in front of the text "Add"
"Delete{!Del}" ! Displays the {!Del}bitmap after the text "Delete"

If the string expression includes two images separated by a vertical bar inside a single set of curly braces, the first is displayed when the button is released (normal state), the second when the button is pressed; 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. See BUTTON OPT= Settings.

Button 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 button object are described in Control Object Properties, .

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

Use this format to create a button control object, and give it a unique identifier in ctl_id. The ctl_id is used to generate a CTL value whenever the user presses the button; e.g.,

0010 REM Create button: CTL=4000 when pressed, 'Stop Sign' picture, "Exit" text
0020 BUTTON 4000,@(2,14,12,2)="{!Stop}Exit"

If the ctl_id has a leading asterisk, the button is considered global (not tied to a specific window); e.g.,

0010 REM To add a global button to the Toolbar with the text "Help":
0020 BUTTON *1000,@(0,-1,10,1)="Help"

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

Use BUTTON REMOVE to delete a button; e.g., to remove the button created previously,

0030 BUTTON REMOVE 4000

By default, non-global buttons are deleted when a window is removed/dropped or when the application issues a BEGIN. Global buttons can be removed using BUTTON REMOVE syntax, or cleared using the START directive.

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

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

0030 BUTTON DISABLE 4000
...
0500 BUTTON ENABLE 4000

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

Use BUTTON GOTO to set the focus on a button:

0030 BUTTON GOTO 4000

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

Use BUTTON ON/OFF to make it look like the button was pressed/released though no signal is generated; e.g.,

0030 BUTTON ON 4000

BUTTON READ [*]ctl_id,mode$[,ERR=stmtref]

Use BUTTON READ to receive the user's method of selecting the button. ProvideX returns a hex value in the mode$ variable to tell you what keystroke last activated the button. Once read, this field is reset to $00$. Possible values are described below:

$01$ for MOUSE-CLICK.
$02$ for DOUBLE MOUSE-CLICK.
$0D$ for Enter .
$20$for SPACEBAR (and keyboard Hot Key, as in the example below).
$09$ for Tab to go to the button.
$00$ when the user exits the button control.
Other specific characters include: $81$ for F1 $82$ for F2 ...

You must read the user's selection(s) to make them available to your applications. In the example below, the STROKE$variable returns the user's method of selection (by mouse, carriage return or space bar).

The value returned for keyboard strokes (the hot key Alt -B and the SPACEBAR for the following example, is $20$).

0010 ! BUTTON Example
0020 PRINT 'CS'
0030 LIST
0040 BUTTON 2000,@(24,17,7,3)="{!BUG|!STOP}it the &Bug"
0050 LET BTN=2000
0060 SETCTL BTN:READ_BOX
0070 BUTTON GOTO BTN
0080 PRINT @(24,24),"HotKey=<Alt-B>. Try Mouse and keyboard too. END=<F4>"
0090 OBTAIN (0,SIZ=1,ERR=0090)@(0,0),'CURSOR'("off"),'ME',IN_VAR$,'MN'
0100 IF CTL=4 THEN GOTO END
0110 READ_BOX:
0120 BUTTON READ BTN,STROKE$
0130 PRINT @(24,20),"Your HTA(selection)=",HTA(STROKE$),",CTL=",CTL:"#####"
0150 GOTO 0090
0160 END:
0170 BUTTON REMOVE BTN; PRINT 'CS'

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

Use the BUTTON HIDE format to hide the display of an active button. (The user can't see or use the button when it's hidden. Use the BUTTON SHOW format to restore the button's display and access.

When a Sizer button is used, the system will generate the button CTL signal only at the end of the drag operation. At that point the application can read the controls line or column in order to determine where the drag terminated. The determination of whether a sizer can be dragged vertically or horizontally is based on the size of the Button. If the button is wider than it is high, the control can be dragged vertically (up/down). If the button is higher than it is wide, the control can be dragged horizontally (left/right).

By default a Sizer control can be dragged the full width or height of the window. The range can be narrowed by using the 'MaxValue and 'MinValue properties.

Another use of a Sizer style button is as a control bar in a slider controal that could be used to adjust a value such as a volume control.

Sizer buttons are a +PxPlus Exclusive feature.