BUTTON

Description

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

Syntax

Normal Button

BUTTON #handle.ext "caption", [branchLabel], cor, x, y {, w, h}
BUTTON #handle.ext "caption", subName, cor, x, y {, w, h}
BUTTON #handle "caption", [branchLabel], cor, x, y, {, w, h}
BUTTON #handle "caption", subName, cor, x, y, {, w, h}
BUTTON #handle.ext, "caption", returnVar, cor, x, y {, w, h}

Default Button

Use with windows of type DIALOG only.

BUTTON #handle.default "caption", [branchLabel], cor, x, y {, w, h}
BUTTON #handle.default "caption", subName, cor, x, y {, w, h}

Syntax Notes

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.
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.
Without a unique .extension, the button cannot receive commands after window is opened.
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.
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

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:

#handle.ext {"string" or stringVar}

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.

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.

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.

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

Using a branch label button handler

'This is a Normal button example that requires the user
'to click the button with a mouse click.
Nomainwin
button #main.exit, "Exit", [exitClicked], UL, 10, 10
open "Button Example" for window as #main

[loop]
    wait

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

Using a subroutine button handler

Nomainwin
button #main.exit, "Exit", exitClicked, UL, 10, 10
open "Button Example" for window as #main

[loop]
    wait

sub exitClicked buttonhandle$

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

Using a Default button in a DIALOG window

Nomainwin
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

[loop]
    wait

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

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

An example that retrieves a value with an input statement

Does not work in LB5

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]"

[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

Useful Procedures

' Place a useful function using this keyword here