BB___BUTTON

=BUTTON= toc

Description
> A BUTTON is a //control// that a user clicks to initiate an action in a program that has a Graphical User Interface (GUI).

Default Button
//Use with windows of type DIALOG only//.

Syntax Notes

 * 1) //Parameters w and h, (width and height), are optional. "cor" is usually UL (UpperLeft), which places the button's upper left corner at the specified x,y offsets. However, "cor" can be UR, LL, or LR, which refer to the button's placement from the specified window corner a distance x over, and y down (or y up from LL or LR). Using a "cor" other than UL can produce unexpected results for the button's placement//.
 * 2) //In a window of type DIALOG, a button can be labeled as the "default". This button can be activated by the user pressing the Enter key, even if another control on the window - but not another button - has the input focus.//
 * 3) //Without a unique .extension, the button cannot receive commands after window is opened//.
 * 4) //**returnVar**// The returnVar may be an unquoted word that begins with a letter, but can contain numerals. It cannot be a string variable. If this form is used, then the value of returnVar is available to be read when the program is halted at an **input var$** statement. The value will be placed into the specified variable. See Examples.
 * 5) //The " & " character placed in the button caption specifies the accelerator key for a button. The letter directly following the " & " character will act as a hotkey for that button, when it is pressed while the user presses and holds down the ALT key. Depending on Windows settings, the hotkey could appear underlined (all the time, or only then ALT key is held).//

Button Features
>> #handle.ext {"string" or stringVar} > The user can click a button, and the button can receive the input, when a SCAN statement is encountered in the program, or when the program is halted with either an INPUT or a WAIT statement.
 * //**Changing the Caption.**//The "caption" can be expressed as a literal string or a string variable. The caption text can be changed after the GUI window is opened by printing the new text to the button:
 * //**Clicking the BUTTON.**// A button is clicked (acted on) either by mouse click or by pressing an Enter key or Space key, when the button has the input focus.
 * //**Program flow.**// Clicking a button causes program flow to branch to the branchLabel or subName listed in the BUTTON declaration. If the unquoted single word form is used for the returnVar, then program flow is halted at an **input var$** statement where the value associated with the button being clicked will be placed in **var$**. See Examples.

Button Commands
The following commands (Methods) can be used with buttons. See the individual pages for discussion. print #handle.ext, "!disable" print #handle.ext, "!enable" print #handle.ext, "!font facename pointSize" print #handle.ext, "!setfocus" Notice that the commands all have an exclamation point (!) preceding them. This is because buttons can have text written on them, which is the "Caption". The exclamation point distinguishes a command from a Caption.

Example
code format="lb" 'This is a Normal button example that requires the user 'to click the button with a mouse click. button #main.exit, "Exit", [exitClicked], UL, 10, 10 open "Button Example" for window as #main
 * Using a branch label button handler:**

[loop] wait

[exitClicked] notice "The Exit button was clicked. Goodbye." close #main end code

code format="lb" 'This is a Normal button example that adds a "setfocus" command which 'allows the user to click the button by pressing the Enter key. button #main.exit, "Exit", [exitClicked], UL, 10, 10 open "Button Example" for window as #main

[loop] #main.exit "!setfocus" wait

[exitClicked] notice "The Exit button was clicked. Goodbye." close #main end code

code format="lb" button #main.exit, "Exit", exitClicked, UL, 10, 10 open "Button Example" for window as #main
 * Using a subroutine button handler:**

[loop] wait

sub exitClicked buttonhandle$

notice "The button handle is ";buttonhandle$;" Goodbye." close #main end end sub code

code format="lb" button #win.default, "Press Enter Key",[okay],UL,10,10 button #win.exit, "Click to Exit", [exitClicked], UL, 180, 100 textbox #win.ext, 10, 50, 150, 25 open "Test" for dialog as #win
 * Using a Default button in a DIALOG window.**

[loop] wait

[okay] notice "You pressed the Enter key." wait

[exitClicked] notice "The Exit button was clicked. Goodbye." close #win end code

code format="lb" nomainwin WindowWidth = 300 WindowHeight = 370 button #main, "Okay", yes, UL, 10, 10 button #main, "Cancel", no, UL, 70, 10 open "Use Input Example" for window as #main #main "trapclose [quit]"
 * An example that retrieves a value with an input statement.**

[loop] input answer$ if answer$ = "yes" then notice "You clicked Okay." if answer$ = "no" then notice "You clicked Cancel." goto [loop]

[quit] close #main end code

Useful Functions
code format="lb" Place a useful function using this command here code