Any topic

Liberty BASIC Help Online

BUTTON

BUTTON #handle.ext, "label", returnVar, corner, x, y {, width, height}

Description:

This statement adds a button that has a text label to a window created with the OPEN command. The width and height parameters are optional.

Usage:

The BUTTON statement must be listed before the statement to OPEN the window that will contain it. Here is a brief description for each parameter as listed above:

#handle.ext

The #handle must be identical to the handle of the window which will contain the button. The button may have an optional, unique extension which allows it to receive commands during program execution. The extension begins with a dot and may include any alpha-numeric characters. A button contained on a window whose handle is #win will have #win as the first part of its handle. Examples of button handles are as follows:

#win (no extension)

#win.okay

#win.1

#win.cancel

#win.bmpbutton2

"label"

This parameter specifies the caption that will appear on the button. It may be expressed as a literal text string, or as a string variable. See String Literals and Variables.

returnVar

returnVar is expressed as one word and it is not enclosed in quotes. It cannot be expressed as a string variable. It must begin with a letter, but it can contain numerals as well. If returnVar is set to a valid branch label enclosed in square brackets, then a button click will cause program execution to continue at the specified branch label. The code that follows the branch label will be executed when the button is pressed. If returnVar is the name of a subroutine, then that subroutine will be activated when the button is clicked, and the button handle will be passed into the subroutine as an argument. See also: Controls and Events

If returnVar is not a valid branch label or subroutine name, 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. An example appears below.

corner

This parameter must be one of the following: UL, UR, LL, or LR. It specifies which corner of the window acts as an anchor for the button. For example, if LR is used, then the button will be located relative to the lower right corner. If the window size is changed during execution of the program, the button will always appear at the same position, relative to the corner specified as the anchor.

UL = upper left

UR = upper right

LL = lower left

LR = lower right

posx, posy

These parameters set the location for the button relative to the anchor corner. posx and posy are expressed in pixels. Anchor values of less than one may also be used for posx and posy. For example, if the anchor corner is UL, posx is .9, and posy is .9, then the button will be positioned 9/10ths of the distance of the window in both x and y from the upper left corner. This method of positioning buttons places them in positions that are relative to the size of the window, rather than anchoring them to a specified corner.

width, height

These optional parameters specify how wide and high the button will be, measured in pixels. If these parameters are not used in the BUTTON statement, then Liberty BASIC will set the size of the button to be large enough to display the text label specified.

Detecting Button Presses

Button presses are read and acted upon when a SCAN statement is issued. If SCAN is not used, then program execution must be halted at an INPUT or WAIT statement in order for a button press to be read and acted upon.

This example uses a branch label button handler:

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

This example uses a subroutine button handler:

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

This example retrieves a value with an input statement:

button #main.ok, "Okay", yes, UL, 10, 10
button #main.cancel, "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

Default Button

A window of type DIALOG can contain a button with the extension ".default". If the user presses the ENTER key while the dialog window has focus, it is the same as if the button whose extension is "default" is pressed and program execution will continue at the event handler [branchLabel] for that button. In the example below, the program will branch to the [okay] routine when the user presses ENTER.

button #win.default, "Okay",[okay],UL,200,100

open "Test" for dialog as #win

Change in behavior for LB3: If any button has focus, it acts as the default button in a DIALOG window. If a control other than a button has the focus, the button whose extension is ".default" is the default button, if such a button exists.

Button commands):

print #handle.ext, "string"

This command changes the text displayed on the caption of the button. "string" may be a literal string of text enclosed in quotes, or a string variable.

print #handle.ext, "!setfocus"

This command causes the button to receive the input focus. This means that any keypresses will be directed to the button.

print #handle.ext, "!locate x y width height"

This command repositions the button control in its window. This only works if the control is placed inside window of type window or dialog. The control will not update its size and location until a refresh command is sent to the window. See the RESIZE.BAS example program.

print #handle.ext, "!font facename pointSize"

This command sets the button's font to the specified face and point size. If an exact match for the font face and size is not available on the user's system, then Liberty BASIC will try to find a close match, with size taking precendence over face.