Any topic

Liberty BASIC Help Online

Graphical User Interface

The term "graphical user interface" is often expressed as the acronym GUI. It refers to a window and all of its controls. These are the graphical elements that interact with the user. The user may click a button, or type into a textbox, for instance. The possible TYPES of windows available in Liberty BASIC programs are listed in Window Types. The commands that can be sent to windows are listed in Window and Dialog Commands. See also, Size and Placement of Windows and Trapping the Close Event. The controls available for placement on windows are listed in Controls - Menus, Buttons, etc. Information about handling user-generated events is given in Controls and Events. Coloring of windows and controls is discussed in Colors and the Graphical User Interface. An explanation of the methods for sending commands is discussed in Understanding Syntax, as well as in Sending Commands. Changing the handle of a window dynamically at runtime can be accomplished with the MAPHANDLE command.

Here is an image of a window that contains many controls:

Liberty BASIC leverages the familiar statements OPEN, CLOSE, PRINT (and optionally INPUT) for working with graphical user interface elements. For example:

open "My Text Window" for text as #txtWin

print #txtWin, "The fox jumped over the dog."

print #txtWin, "!trapclose [quit]";

wait

[quit]

close #txtWin

end

The OPEN statement is used to open a window. The window can receive commands via the PRINT statement, and it is closed with the CLOSE statement. The second print statement above starts with an exclamation point. This is required when printing commands to text controls in order to tell Liberty BASIC to execute a command instead of printing the text to the control.

New to Liberty BASIC 3: it is no longer necessary to use the PRINT statement when issuing commands to a window or control. The word "print" is optional, as is the comma after the window or control handle. The following version of the code above functions identically, and requires less typing:

open "My Text Window" for text as #txtWin

#txtWin "The fox jumped over the dog."

#txtWin "!trapclose [quit]";

wait

[quit]

close #txtWin

end

Printing "!trapclose [quit]" to the window tells it to use the event handler code at [quit] to decide what action to take when the user tries to close the window. This is important. Each window OPENed should also have a handler set up for trapping the close event.

Windows can have other user interface elements. Here is an example:

statictext #dialog.static, "What is your name?", 10, 10, 100, 20

textbox #dialog.tbox, 10, 30, 100, 20

button #dialog.accept, "Accept", [gotIt], UL, 10, 55

open "Name getter" for dialog as #dialog

print #dialog.tbox, "Type your names in here."

print #dialog, "trapclose [quit]"

wait

[gotIt]

print #dialog.tbox, "!contents? name$"

notice "Hi "; name$

wait

[quit]

close #dialog

end

The "trapclose [quit]" printed to the window in this example does not need an exclamation point in front of it. This is because the window is a dialog box, and isn't a text widget that displays text PRINTed to it. For this reason it accepts PRINTed commands that do not start with the exclamation point.

The controls added to the window include a statictext (a non-editable label), a textbox (an editable field), and a pushbutton. They are listed before the OPEN statement, which opens a dialog window. The button statement's declaration includes the branch label [gotIt]. The code at [gotIt] is the button's event handler. When the button is clicked it generates an event, and [gotIt] is invoked. The code t [gotIt] prints a command to the textbox asking for its contents to be assigned to the string variable name$. The program then pops up a notice window displaying a greeting to the user.

The window in the example above receives a "trapclose" command. This sets a handler for the window's close event to be the branch label designated by "trapclose". There, the window can be closed, if appropriate, perhaps after querying the user about what to do, for example:

[quit]

confirm "Quit. Are you sure?"; yesOrNo$

if yesOrNo$ = "yes" then [quitForSure]

wait

[quitForSure]

close #dialog

end

Graphical elements which display text will accept and display text that is PRINTed directly into them:

texteditor #main.txtEdit, 3, 3, 250, 300

open "Edit some text, man!" for window as #main

print #main, "trapclose [quit]"

print #main.txtEdit, "C'mon and edit me." ;

print #main.txtEdit, " I dare you!"

print #main.txtEdit, "Or just start typing to replace me."

print #main.txtEdit, "!selectall";

wait

[quit]

close #main

end

The text PRINTed to the texteditor control is displayed on the control. Because it accepts text to display, it is necessary to prefix any commands with a ! when they are PRINTed to a text control, as the "!selectall" command shows.