RTR logo

LBB

LB Booster



Introduction

LB Booster is a powerful utility for Liberty BASIC programmers. With LBB you can: LB Booster is Freeware; you are encouraged to purchase the full version of Liberty Basic on which to develop, test and debug your programs prior to 'boosting' them.

Benefits

Here are some examples of the benefits offered by LB Booster:

Performance

Bugs fixed

New features

Installation

Create a suitable directory (e.g. C:\Program Files (x86)\LBB\) and copy the LBB.exe file there. You will need administrative privileges to copy the file and when you execute it for the first time (in Windows Vista™, Windows 7™ and Windows 8/8.1™, with UAC enabled, use Run as administrator); however it can be run from a normal user account thereafter.

You can, if you wish, create a desktop shortcut to the program by right-dragging the LBB.exe file to your desktop and selecting 'Create shortcut here' from the menu that appears when you release the mouse button. You can create a shortcut in your Start Menu in a similar way.

LBB requires Windows 2000 or later. It is not compatible with Windows 95, Windows 98 or Windows Me. Sprites require a CPU with 'integer SSE' support, i.e. an Intel Pentium III or an AMD Athlon or later.

Compatibility

Although LBB can successfully boost most Liberty BASIC 4 programs, there are a few incompatibilities, including:
  1. There are no graphics segments; the 'delsegment' and 'segment' commands are ignored. However, on the plus side no special measures are required to make graphics 'stick'; if your program suffers from this problem under LB4 it won't when run under LBB!

  2. LBB does not support arbitrary precision arithmetic; integers (whole numbers) are limited to the range −18,446,744,073,709,551,615 to +18,446,744,073,709,551,615. Values outside this range will be stored as floating-point numbers and accuracy may suffer. In addition, the bitwise operations AND, OR and XOR work only with 64-bit integer values.

  3. The EVAL function works only with simple expressions containing 'standard' BASIC functions, and may fail if the expression contains variable names starting with a keyword. EVAL doesn't work if the expression contains a structure member, or a function name in mixed-case (e.g. Sqr).

  4. Child control handles must be mapped explicitly, e.g. MAPHANDLE #old.te,#new.te; mapping the parent window's handle is not sufficient.

  5. When printing a window, the resulting quality on the printer is no better than it is on the screen (but see here).

  6. The size of the 'canvas' onto which you can draw in a graphics box is limited (the width is limited to the width of your screen display). You can increase it using the horizscrollbar and/or vertscrollbar commands.

  7. The mainwin can hold only about 84 lines of text; if more lines are output the remainder will be 'scrolled off' the top of the window and lost. Also, the mainwin has no menu. You can copy the contents of the mainwin onto the clipboard by typing Ctrl+Tab.

  8. If one of the keypad number keys is pressed, two 'when characterInput' events are generated. One is the regular event that LB4 generates, and the other is a 'special key' event (LEN(Inkey$)=2). This makes it possible to distinguish the keypad from the regular number keys.

  9. The syntax for serial port parameters is slightly different. The basic options are the same, so for example this works:
    open "COM1:9600,n,8,1" for random as #comm
    
    but when specifying 'handshaking' parameters the syntax accepted by LBB is as follows:
    open "COMn: [baud=b] [parity=p] [data=d] [stop=s]
          [to=on|off] [xon=on|off] [odsr=on|off] [octs=on|off]
          [dtr=on|off|hs] [rts=on|off|hs|tg] [idsr=on|off]"
    
    A full description of these parameters can be found here.

  10. In a single-line IF statement LBB may behave differently from LB4 if there are multiple (cascaded) IFs and an ELSE clause. To resolve this recast the code as nested multi-line IFs.

  11. RESUME resumes execution at the line (not statement) where the error occurred; if in doubt use only one statement per line. Also, RESUME must be used within the scope of the SUB or FUNCTION (if any) in which the error occurred.

  12. Opening a file in BINARY mode does not prevent PRINT outputting a newline (CRLF). To suppress the newline add a trailing semicolon (;) to the PRINT statement; this will not affect the operation of the program in LB4.

  13. The maximum length of a DATA statement is approximately 250 characters.

  14. There is a limit of 8 on the number of simultaneously-open RANDOM files; however this may be worked around by opening and closing the files for every transaction (GET or PUT).
In general, LBB may not always tolerate coding errors or weaknesses even if Liberty BASIC itself does. However in the case of an incompatibility from this cause it will usually be possible to modify the program so that it works under LBB as well as LB4. See Troubleshooting for some examples.

If, exceptionally, the only way to achieve compatibility is to use different code for LB4 and LBB you can test which platform your program is running under as follows:

if instr(Platform$, "LBB") then
  print "Running under LBB"
else
  print "Running under LB"
end if 

Directives

LB Booster accepts the following Compiler Directives in the source code of the BASIC program; they are case-sensitive:

'include filename.bas

This directive, which takes the form of a special comment, includes the specified file at the point in the program where the directive is inserted; note that the apostrophe must be in the first column and there must not be a space after it. This allows you to develop and test separate code modules which can then be incorporated in programs whenever they are required.

For maximum compatibility with Liberty BASIC Workshop the 'include directive is ignored when it is at the very beginning of the program. See this Wiki article for more information, and for details of how to integrate LBW with LBB.

%mode std

This directive causes LBB to evaluate the INT() function, and expressions containing both AND and OR operators, in a standard way; note that there must not be a space after the percent sign. Specifically the INT function truncates towards minus infinity (e.g. INT(−3.5) is −4) and OR has a lower precedence than AND (e.g. 1 OR 2 AND 4 is 1).

%mode lb4

This directive (which is the default) causes LBB to evaluate the INT() function, and expressions containing both AND and OR operators, in the non-standard Liberty BASIC 4 way. Specifically the INT function truncates towards zero (e.g. INT(−3.5) is −3) and OR has the same precedence as AND, i.e. they are evaluated strictly left-to-right (e.g. 1 OR 2 AND 4 is 0).

! BBC code

If a line starts with an exclamation mark (!) the rest of the line is assumed to consist of BBC BASIC code and is passed, unmodified, to the output of the translator. This facility should be used with care since only a subset of BBC BASIC statements may be safely used. For example red text may be output to the mainwin as follows:
!COLOR 1
print "This is red"

Operation

When you start LBB you are presented with a conventional window containing the normal features which make up the Windows™ Graphical User Interface: a title bar, a set of drop-down menus, a toolbar and a status bar. The main part of the screen is an editing pane in which the BASIC program appears and can be edited. This pane can be scrolled horizontally and vertically as necessary.

Command line options

LBB will accept parameters on the command line in a similar fashion to Liberty BASIC. If a filename is specified, it is automatically loaded; this allows you to drop a .BAS file onto the LBB icon, or to associate the .BAS file extension with LBB.exe.

The following command line switches are accepted:

-RRun a BAS file on startup
-DDebug a BAS file on startup
-TTranslate and tokenise a BAS file to an LBB file
-CTranslate and compile a BAS file to an EXE file
-AAutomatically exit LBB on completion
-MMinimise LBB on startup

Examples:

LBB program.bas           (loads the program)
LBB -R -A -M program.bas  (runs the program)
LBB -T -A -M program.bas  (generates program.lbb)

The title bar

The title bar contains the name of the application and its version number, the name of the current BASIC program (or 'untitled' if the New command has been issued), a minimise button, a maximise button and a close button. If you right-click in the title bar you will get a context menu containing the Restore, Move, Size, Minimize, Maximize and Close items.

The menu bar

The menu bar contains the drop-down menus File, Edit, Run, Options and Help. These menus may be activated by clicking on the appropriate menu name or by using a keyboard shortcut (hold down Alt and press the key corresponding to the underlined character). When a menu is opened a brief description of the highlighted item is displayed in the status bar. Menu items are 'greyed out' if they are not functional in the current circumstances.

The toolbar

The toolbar provides easy access to the most common commands, without having to select them from the drop-down menus, simply by clicking on the appropriate button. The commands for which buttons are provided are as follows:

From the File menu: New, Load, Save and Print.
From the Edit menu: Undo, Redo, Cut, Copy, Paste, Find and Replace.
From the Run menu: Run Program, Debug Program and Make Executable.

Toolbar buttons are 'greyed out' if they are not functional in the current circumstances.

The status bar

When a menu item is highlighted, the status bar displays a brief description of the function of that command. Otherwise, the status bar displays the version number and copyright information for LB Booster.

At the right-hand end of the status bar are displayed the current Encoding (ANSI or Unicode), the Insert/Overtype status, the Caps Lock setting, the Num Lock setting and the Line number of the line containing the text cursor (caret), starting at line 1.

The File menu

The File menu contains the items New, Load, Save, Save As, Insert, Compare, Page Setup, Print, Recent files and Exit. The File menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-F.

New

The New command (keyboard shortcut Ctrl+N) deletes the current BASIC program from memory, giving you a 'clean sheet' into which to load, paste or type a new program. If the current program has been modified and not saved, you are first prompted to save it.

Load

The Load command (keyboard shortcut Ctrl+L) loads a Liberty BASIC program into memory. The file should be in plain text (ANSI/ASCII) or Unicode (UTF-8) format; LBB will attempt to detect the format and enable or disable the Unicode Support option as required, although this may not be totally reliable. The file will normally have the extension .BAS.

You can alternatively load a .TKN file created by Liberty BASIC. This can be very useful if you have deleted or mislaid a program, but still have a TKN file generated from it. Note that you must know the original user's Name and LB Password; it is not possible to load a TKN file created by Just BASIC or an unregistered copy of Liberty BASIC.

If the current program has been modified and not saved, you are first prompted to save it.

Save

The Save command (keyboard shortcut Ctrl+S) saves the current BASIC program, replacing the original file; it is enabled only if the program has been modified since it was loaded. If you have made changes which might be incompatible with Liberty BASIC 4 you are advised to save the program under a new name (see Save As below).

Save As

The Save As command saves the current BASIC program under a new name, or in a new location. It is useful for making a backup copy, or to avoid modifying the original program if a change has been made which might be incompatible with Liberty BASIC 4.

The program is saved either as ANSI/ASCII text or with UTF-8 encoding, depending on the current setting of the Unicode Support option.

Insert

The Insert command inserts the contents of the selected file at the current position of the text cursor (caret); the file should normally contain BASIC code in plain-text (ANSI/ASCII) or Unicode (UTF-8) format. If any text is selected, it is replaced by the inserted text (in the same way as the Paste command).

Compare

The Compare command compares the currently-loaded program with the selected file (which should usually be an earlier version of the program) and lists the differences in the right-hand pane. Lines which are identical in the two versions are displayed with the default background color and an equals sign (=) in the first column. Lines in the old version which are different from the new version are shown in red, with a < sign in the first column. Lines in the new version which are different from the old version are shown in green with a > sign in the first column.

To scroll down to the next difference press F8; to scroll up to the previous difference press F7. Note that if your program contains Unicode text this will not display correctly. When you have finished studying the differences you can hide the right-hand pane using the Show LBB pane selection in the Options menu.

Page Setup

The Page Setup command allows you to configure the paper size, orientation (portrait or landscape) and margins used when you print out the BASIC program. You can also use this command to select a different printer.

Print

The Print command (keyboard shortcut Ctrl+P) creates a hardcopy printout of the current BASIC program.

Recent files

The nine most-recently loaded programs are listed, and can be re-loaded simply by clicking on the appropriate entry or by using the keyboard shortcut Alt-F followed by the digit 1 to 9. When one of the entries is highlighted, the full pathname of the file is displayed in the Status Bar. If the previous program was not saved, you are first prompted to save it.

Exit

The Exit command quits from LB Booster and closes its window. If modifications have been made to the program and not saved, you are first prompted to save it. If BASIC programs are still running (and therefore using up Windows resources and potentially wasting CPU time) you are prompted to terminate them.

The Edit menu

The Edit menu contains the items Undo, Redo, Cut, Copy, Paste, Delete, Select All, Find, Find Next, Find Previous, Replace and Go To . The Edit menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-E.

Undo

The Undo command (keyboard shortcut Ctrl+Z) reverses the effect of the last editing operation. Multiple operations can be undone.

Redo

The Redo command (keyboard shortcut Ctrl+Y) reverses the effect of the last undo (if any). Multiple operations can be redone.

Cut

The Cut command (keyboard shortcut Ctrl+X) transfers any selected text to the clipboard, and deletes it from the program. If no text is selected, the Cut command is inhibited. Once the selected text is in the clipboard, you can Paste it either elsewhere in your BASIC program or into any other application which supports pasting of text from the clipboard. Any previous contents of the clipboard are discarded. Selected text is highlighted in reverse-video.

Copy

The Copy command (keyboard shortcut Ctrl+C) transfers any selected text to the clipboard, but unlike Cut it leaves the text in the BASIC program. If no text is selected, the Copy command is inhibited. Once the selected text is in the clipboard, you can Paste it either elsewhere in your BASIC program or into any other application which supports pasting of text from the clipboard. Any previous contents of the clipboard are discarded.

Paste

The Paste command (keyboard shortcut Ctrl+V) inserts the contents of the clipboard into the BASIC program at the current position of the text cursor (caret). If the clipboard contains no text, the Paste command is inhibited. You can use Paste to transfer a block of code from elsewhere in your BASIC program, or to insert a block of code which has been placed in the clipboard by any other application.

Delete

The Delete command deletes any selected text, without copying it into the clipboard. Text which is deleted can only be recovered by using the Undo command.

Select All

The Select All command (keyboard shortcut Ctrl+A) selects the entire BASIC program. It is useful if you want to transfer the program into another application (e.g. a word processor) via the clipboard

Find

The Find command (keyboard shortcut Ctrl+F) allows you to search your program for the occurrence of some specified text. The command opens the Find dialogue box into which you can type the text you wish to search for. You can also specify whether the case (capitals or lower-case) is significant and whether to match only an entire word. The search begins at the position of the text cursor (caret) when the Find command was issued. If you want to search the entire program, ensure that you move the cursor to the start of the program before issuing the command.

Find Next

Once the Find dialogue box has been dismissed, you can continue to search for the next and subsequent occurrences of the search string by using the Find Next command or by pressing F3. If the text is not found before the end or beginning of the program the message "Text not found" is displayed; selecting Find Next again causes the search to restart from the beginning or end of the program.

Find Previous

The Find Previous command (keyboard shortcut Shift+F3) searches in the reverse direction from the Find Next command. If the current search direction is downwards, Find Previous searches upwards. If the current search direction is upwards, Find Previous searches downwards.

Replace

The Replace command (keyboard shortcut Ctrl+R) allows you to search your program for the occurrence of some specified text and then, optionally, replace it with some different text. The command opens the Replace dialogue box into which you can type the text you wish to search for and the text you want it to be replaced with. The search begins at the position of the text cursor (caret) when the Replace command was issued.

Go To

The Go To command (keyboard shortcut Ctrl+G) opens a dialogue box into which you can enter a line number. On selecting OK, or pressing Enter, the text cursor (caret) is positioned at the start of the specified line (the editor scrolls if necessary). This can be particularly useful if an error message indicates a problem in a specific line.

The Run menu

The Run menu contains the items Run Program, Debug Program, Profile Program, Make Executable, Make *.LBB file and Kill BASIC Programs. The Run menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-R.

Run Program

The Run Program command firsts 'boosts' (translates) the current BASIC program and then runs it. If an error occurs during the translation process, a message is reported and the process is aborted (once the error message is dismissed the line which resulted in the error is highlighted). If the program has already been translated, it is simply run. If no program is loaded, the command is inhibited.

Debug Program

The Debug Program command firsts 'boosts' (translates) the current BASIC program, if necessary, and then runs it with debugging aids enabled and any breakpoints activated. See Debugging for details.

Profile Program

The Profile Program command firsts 'boosts' (translates) the current BASIC program, if necessary, and then runs it with profiling enabled. Whilst profiling, the currently-executing line is highlighted in the editing pane (as when debugging). When the program terminates, a Profiler Report is generated and displayed in your default text-file viewer; this shows the approximate number of milliseconds, and percentage of the total time, spent in each program line.

Make Executable

The Make Executable command firsts 'boosts' (translates) the current BASIC program (if necessary) and then 'compiles' the program to a compact, standalone executable file (typically less than 150 Kbytes in size). The executable may run a little faster than when using the Run Program command. If no program is loaded, the command is inhibited.

You are prompted to supply a filename and location for the executable; by default it will be stored in the same directory as the Liberty BASIC program but with the extension '.exe'. LBB incorporates a manifest in the executable, to enable the use of Windows XP Visual Styles and improve compatibility with Windows™ Vista, Windows™ 7 and Windows™ 8/8.1.

The following additional options are available:

Make *.LBB file

Unlike Liberty BASIC, LBB compiles directly to an EXE so it isn't normally necessary to create a 'tokenised' program file; however the Make *.LBB file command allows you to do so if you wish. A tokenised LBB file must be executed using the run-time engine LBBRUN.exe (rather as LB's TKN files must be executed using RUN404.exe). Note that tokenised files are less secure than compiled executables so it is best not to use them if you want to keep your program confidential.

Kill BASIC Programs

The Kill BASIC Programs command terminates any BASIC programs which are still executing in memory after having been run during this LBB session. If a BASIC program doesn't properly exit (e.g. because of omitting a TRAPCLOSE command) it may have no visible window yet be using up Windows resources and CPU time. If no programs are still running, the command is inhibited.

In the current version of LBB you cannot choose which programs to kill.

The Options menu

The Options menu contains the items Show LBB Pane, Emulate Slicing, Unicode Support, Syntax Coloring, Set Font, Set Printer Font and Set Colors. The Options menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-O.

Show LBB Pane

The Show LBB Pane command alternately enables and disables a 'split window' mode in which the original Liberty BASIC program is displayed in the left-hand pane and the translated program is shown in the right-hand pane. This may be useful for diagnostic purposes or simply for interest.

This option is also used to dismiss the differences listing generated by the File... Compare command.

Emulate Slicing

The Emulate Slicing command alternately enables and disables the full emulation of Liberty BASIC's LEFT$, MID$ and RIGHT$ functions when the length parameter is negative. In that case LB4 returns an empty string. Since emulating the negative-length case significantly slows execution of the functions, and since very few programs rely on this behaviour, it is not enabled by default.

Unicode Support

The Unicode Support command alternately enables and disables partial support for Unicode output. When this option is selected foreign-alphabet literal (quoted) strings may be included in a program, and will display correctly in the mainwin and when output to a printer using LPRINT. Unicode strings may also be displayed in GUI controls (except TEXTEDITOR controls), with the assistance of a little API code.

Syntax Coloring

The Syntax Coloring command alternately enables and disables the highlighting of elements of your program in different colors. Note that if your program contains Unicode text, and the selected font does not support the required characters, it may display incorrectly. In that case either disable Syntax Coloring or select a different font (Courier New contains a wide selection of Unicode glyphs and will usually be suitable).

Set Font

The Set Font command selects the font used to display the BASIC program on the screen. The default is the System Fixed Font (FixedSys).

Set Printer Font

The Set Printer Font command selects the font used when a hardcopy printout of the BASIC program is generated.

Set Colors

The Set Colors command opens a dialogue box allowing you to select which colors are used for the various syntax elements: labels, keywords, quoted strings, handles, comments (delimited with an apostrophe) and everything else. You may choose either from a selection of 48 preset colors, or click on Define Custom Color to make full adjustments available. You can preview the current selection by clicking on Apply and when you are happy click OK. If you click on Cancel any changes will be discarded.

Note that the window background color is set, as usual, in your Windows display preferences (for example right-click on the desktop and select Properties or Personalize).

The Help menu

The Help menu contains the items Help Topics, Email, Website, Discussion Group, Message Board, Wiki and About LB Booster. The Help menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-H.

Help Topics

The Help Topics command (keyboard shortcut F1) displays this Help documentation.

Email

The Email command opens your default mail program (if any) so that you can send a message to request help or information about LB Booster.

Website

The Website command opens your default web browser (if any) and automatically directs it to the LB Booster home page.

Discussion group

The Discussion Group command takes you to the LBB Yahoo!™ group, where you can seek help and advice, report bugs, download (or upload) useful utilities and learn about new developments in LB Booster.

Message board

The Message Board command takes you to the LBB Conforums message board, where you can take part in discussions about LB Booster.

Wiki

The Wiki command takes you to the LB Booster Wiki, where you will find articles on all aspects of using LBB.

About LB Booster

The About LB Booster command displays information about LBB, including the version number and copyright information.


The Editing Pane

The editing pane is where the BASIC program currently loaded into memory (if any) is displayed for viewing or editing, or where a new program is entered. All of the normal features which you expect from a Windows™ text editor are available. You can manipulate and edit the program using the keyboard, mouse and touch screen (if applicable).

Keyboard commands

The following operations are available using the keyboard. Note that references to left and right apply to normal left-to-right text, and may be reversed when editing right-to-left text such as Arabic or Hebrew:

KeyOperation
Insert Toggle between insert and overtype mode. In overtype mode any character typed will over-write the existing character at that position on the line. In insert mode any character typed will 'push' the rest of the line to the right to make room.
Delete Delete the character to the immediate right of the cursor (caret) and move the rest of the line left to fill the gap.
Home Move the cursor (caret) to the start of the current program line, and scroll the display horizontally (if necessary) to ensure that the cursor is visible.
Ctrl+Home Move the cursor (caret) to the start of the program, and scroll the display horizontally and/or vertically (if necessary) to ensure that the cursor is visible.
End Move the cursor (caret) to the end of the current program line, and scroll the display horizontally (if necessary) to ensure that the cursor is visible.
Ctrl+End Move the cursor (caret) to the end of the program, and scroll the display horizontally and/or vertically (if necessary) to ensure that the cursor is visible.
Page Up Display the previous 'page' of the program by scrolling the display down by one screenful (less one line) or until the first line of the program is visible, whichever is less. If the first line of the program is already in view, Page Up has no effect.
Page Down Display the next 'page' of the program by scrolling the display up by one screenful (less one line) or until the last line of the program is visible, whichever is less. If the last line of the program is already in view, Page Down has no effect.
Left Move the cursor (caret) one character to the left, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a character.
Right Move the cursor (caret) one character to the right, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a character.
Up Move the cursor (caret) up one line, and scroll the display vertically (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a line. If the cursor is already on the first line, the key has no effect.
Down Move the cursor (caret) down one line, and scroll the display vertically (if necessary) to ensure that the cursor remains visible. If Shift is held down, select (or de-select) a line. If the cursor is already on the last line, the key has no effect.
Backspace Delete the character immediately to the left of the cursor (caret), and move the cursor left one position. The rest of the line, to the right of the cursor, is moved left to fill the gap. If the cursor is at the beginning of a line, delete the preceding 'new line' and concatenate the contents of the present line onto the end of the previous line.
Return (Enter) Insert a 'new line' at the current position of the cursor (caret). Everything to the right of the cursor will be moved onto the next line, and the rest of the program is moved down one line to make space. By this means you can split an existing line into two or more lines
Ctrl+Left Move the cursor (caret) one word to the left, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is also held down, select (or de-select) a word.
Ctrl+Right Move the cursor (caret) one word to the right, and scroll the display horizontally (if necessary) to ensure that the cursor remains visible. If Shift is also held down, select (or de-select) a word.
Tab Enter space characters so as to move the text cursor (caret) to the next multiple-of-four column. For correct alignment on the screen and/or the printer a fixed-pitch (monospaced) font must be selected.
Ctrl+Backspace Delete the previous word (i.e. to the left of the cursor) and move the rest of the line left to fill the gap.
Ctrl+Delete Delete the next word (i.e. to the right of the cursor) and move the rest of the line left to fill the gap.

The 'printing' keys (letters, numbers and symbols) cause the appropriate character to be entered at the position of the cursor (caret), and the cursor position is then updated. If any text is selected (highlighted) when the key is pressed, it is first deleted.

Mouse commands

The following operations are available using the mouse:

ActionOperation
Left click Clicking in the editing pane with the left mouse button causes the text cursor (caret) to be moved to the character position nearest to the mouse pointer. If Shift is held down, the region between the previous position of the text cursor and the new position will be selected.
Left double-click Double-clicking in the editing pane with the left mouse button causes the word under the mouse pointer (and the following space, if any) to be selected. The selected word can then be cut, copied, deleted or dragged.
Left triple-click Triple-clicking in the editing pane with the left mouse button causes the entire line under the mouse pointer to be selected. The selected line can then be cut, copied, deleted or dragged.
Left drag Holding down the left mouse button and 'dragging' the mouse pointer over the program displayed in the editing pane causes a section of the program to be selected.
Right click Clicking in the editing pane with the right mouse button causes the Context Menu to be displayed.
Wheel Operating the mouse wheel causes the editing pane to scroll vertically, usually by three lines per 'notch'.
Ctrl+Wheel Holding down the Ctrl key and operating the mouse wheel causes the editing pane to zoom; note that this will not work if you have selected the System Fixed Font (FixedSys).

Drag and Drop

If you move the mouse pointer over a selected (highlighted) region of your program, the pointer shape changes to an arrow. In this situation holding down the left mouse button and 'dragging' the mouse pointer initiates a Drag and Drop operation. If you drag the mouse pointer to a different point in your program (outside the selected region), and then release the left button, the selected text will be deleted from its original place and inserted where the button was released. This is equivalent to a cut-and-paste operation via the clipboard.

Alternatively, if you hold down the Ctrl key before releasing the left button the selected text is copied to the location where the button was released (a plus sign appears next to the mouse pointer indicating a copy rather than a move). This is equivalent to a copy-and-paste operation via the clipboard. If you want to cancel the Drag and Drop operation you can do that by pressing the ESCape key before you release the left button, or by releasing the button when the pointer is inside the selected area.

Context Menu

Clicking in the editing pane with the right mouse button causes the 'floating' context menu to be displayed at the position of the mouse pointer. Alternatively pressing Shift+F10 causes the context menu to appear at the position of the text cursor (caret). If you have a touch screen you can display the context menu by pressing-and-holding until the square or circle appears.

The context menu contains the same items as the Edit menu except in the following circumstances:

Scroll bars

If the current program cannot be displayed in its entirety within the editing pane, vertical and/or horizontal scroll bars are displayed. These allow you to scroll the display until the part of the program in which you are interested is in view. The scroll bars can be operated in the following ways:

Keyword summary

Below are alphabetical lists of statements, functions and GUI commands with a brief description of each. In the informal syntax definitions square brackets [] indicate optional items, braces {} indicate items which may be repeated zero or more times, and the pipe symbol | indicates alternatives.

Statements

BEEP

Causes an alert sound to be output from the PC's speakers.

BMPBUTTON #window[.ext], bmpfile$, handler, anchor, posx, posy

Creates a pushbutton containing a bitmap image. The handler may be a label or a SUB. The anchor must be UL, LL, UR or LR.

BMPSAVE "bitmap", bmpfile$

Saves the specified bitmap as a Windows BMP file.

BUTTON #window[.ext], "text", handler, anchor, xpos, ypos [, width, height]

Creates a pushbutton. The handler may be a label or a SUB. The anchor must be UL, LL, UR or LR.

CALL subname [parameter {, parameter}]

Calls a user-defined subroutine, passing optional parameters (numerics, strings or arrays). These are automatically copied into the formal parameters specified in the SUB definition.

CALLBACK addressvar, funcname(type {, type}), returntype

Assigns a memory address to a FUNCTION so that it may be called by Windows. The parameter types passed to the function, and the expected return type, must be specified.

CALLDLL #dllhandle, "FunctionName" {, param AS type}, returnvar AS type

Calls a Windows API routine or a function exported from a DLL. The returned value is copied into the specified variable (unless the type is VOID).

CASE ELSE | expression {,expression}

Part of the SELECT CASE clause. CASE ELSE specifies a default action, if none of the previous values have matched, and should be the last in the clause.

CATCH

Part of the TRY...CATCH...END TRY clause.

CHECKBOX #window[.ext], "Caption", sethandler, resethandler, xpos, ypos, width, height

Creates a checkbox. The handlers may be labels or SUBs.

CLASS classname [INHERITS parentclass]

Begins a class definition, optionally inheriting methods and properties from a parent class.

CLOSE #handle

Closes a file, serial port, DLL or window.

CLS

Clears the mainwin and moves the text cursor (caret) to the top-left corner.

COLORDIALOG color$, chosen$

Displays the Choose Color dialog and initialises it with the specified color. On return, chosen$ contains the selected color as an RGB triplet, or an empty string if the user clicked on Cancel.

COMBOBOX #window[.ext], array$(), handler, xpos, ypos, width, height

Creates a combobox and loads it with the contents of string array array$(). The handler may be a label or SUB.

CONFIRM question$; replyvar$

Displays a box containing a question and requesting a yes/no response. On return replyvar$ contains either the string "yes" or the string "no".

CURSOR cursortype

Changes the mouse pointer (cursor) shape; options are NORMAL, ARROW, CROSSHAIR, HOURGLASS or TEXT.

DATA [constant {, constant}]

Specifies a list of numeric or string constants to be read by a READ statement.

DIM array(size{,size}) {, array(size{,size})}

Dimensions one or more numeric or string arrays. In LBB arrays may have any number of dimensions. The allowed suffices run from zero to the value of size. DIM is also used to specify class properties in Object Oriented Programming.

DISCARD object

Deletes the specified object (instance of a class) and frees the memory it occupied.

DO [WHILE | UNTIL condition]

Begins a DO loop; optionally followed by a condition determining whether the loop is executed or not.

DUMP

Ejects the page currently being printed. Used in conjunction with LPRINT (and, in LBB, optionally the graphics PRINT command).

ELSE

A delimiter which specifies an alternative course of action in a single-line or multi-line IF statement. Also used in the CASE statement.

END

Terminates the current program. If the mainwin is hidden, or if the program is running as a compiled executable, also terminates the process.

END CLASS | FUNCTION | IF | SELECT | SUB | TRY

Marks the end of the specified clause.

EXIT FOR | WHILE | DO | FUNCTION | SUB

Forces a premature exit from a FOR loop, WHILE loop, DO loop, FUNCTION or SUB.

FIELD #file, length AS var {, length AS var}

Specifies the record structure of a random-access file. The variables may be numeric or string.

FILEDIALOG "Title", template$, returnvar$

Displays a file selector dialog. The template$ determines which files are initially listed, e.g. "*.bas;*.bbc". On return returnvar$ contains the selected file, or an empty string if the user pressed Cancel.

FILES path$, [filter$,] array$()

Fills array$() with a list of files and directories at path$, optionally specifying a filter (e.g. "*bas").

FONTDIALOG fontspec$, returnvar$

Displays a Choose Font dialog, initialised with the specified font. On return returnvar$ contains the selected font, or an empty string if the user pressed Cancel. See FONT.

FOR loopvar = start TO finish [STEP increment]

Begins a FOR...NEXT loop. If finish is less than start (and the increment is positive) the body of the loop is not executed at all.

FUNCTION name([[BYREF] parameter {, [BYREF] parameter}])

Begins a user-defined function definition, with optional numeric, string or array formal parameters. If the BYREF qualifier is used the parameter is passed 'by reference' and the variable specified in the function call may be modified by the function.

GET #file, recordnumber

Reads the specified record of a random-access file. The first record in the file is record number 1.

GETTRIM #file, recordnumber

Reads the specified record of a random-access file, and trims leading and trailing whitespace from each field.

GOSUB destination

Calls a subroutine. The destination may be a label or a line number.

GLOBAL variable {, variable}

Declares one or more variables as being accessible both outside and inside SUBs and FUNCTIONs.

GOTO destination

Jumps to the specified destination, which may be a label or a line number.

GRAPHICBOX #window.ext, xpos, ypos, width, height

Creates a child control that can contain colored graphics and text, or sprites.

GROUPBOX #window[.ext], "label", xpos, ypos, width, height

Creates a groupbox to contain other controls (especially RADIOBUTTONs).

IF condition THEN

Executes the code after THEN if condition, truncated to an integer, is non-zero. May be either a single-line IF statement or, if nothing follows the THEN, a multi-line IF statement.

INPUT ["prompt";] returnvar {, returnvar}

Requests the user to supply numeric or string input in the mainwin.

INPUT #handle, returnvar {, returnvar}

Inputs data from a file or a GUI control; the return variables may be numeric or string.

KILL filespec$

Deletes the specified file; if the file doesn't exist or cannot be deleted an error is reported.

LET variable = expression

Assign the value of expression to the specified variable, array element, structure member etc. LET is optional and may be omitted.

LINE INPUT ...

As INPUT except that an entire line (including any commas and spaces) is returned.

LISTBOX #window.ext, array$(), handler, xpos, ypos, width, height

Creates a listbox and loads it with the contents of array$(). The handler may be a label or SUB.

LOADBMP "bitmap", bmpfile$ | handle

Loads the named bitmap from the specified BMP file. Alternatively a native Windows bitmap handle may be specified as the source.

LOCATE column, row

Moves the mainwin text cusor (caret) to the specified coordinates. The rows and columns are numbered starting from 1.

LOOP [WHILE | UNTIL condition]

Marks the end of a DO loop. Optionally, looping continues only WHILE or UNTIL the specified condition (truncated to an integer) is non-zero.

LPRINT [[TAB(n);] expression {, | ; [TAB(n);] expression} [, | ;]]

Outputs the specified numeric or string expression(s) to the current printer followed by a newline. TAB(n) advances to the specified column and a comma advances to the next multiple-of-14 column; a trailing comma or semicolon suppresses the newline.

MAINWIN columns [rows]

Sets the mainwin width to the specified number of character columns, and optionally also sets the height to the specified number of character rows.

MAPHANDLE #oldhandle, #newhandle | newhandle$

Assigns a new handle to a window or control after it has been created. The new handle may be a string such as "#newhandle".

MENU #handle, "title", "text", handler {, "text", handler}

Creates a pop-up menu. Each item activates a handler, which may be a label or a SUB.

NAME oldspec$ AS newspec$

Renames a file. If the file is not found or the rename fails, an error is reported.

NEW object[(dim [,dim])] AS class [parm {, parm}]

Create a new instance (or array of instances) of the specified class, optionally passing parameters to the constructor.

NEXT [loopvar]

Marks the end of a FOR loop, optionally specifying the loop variable.

NOMAINWIN

Hides the 'main window'. When debugging, this statement is ignored.

NOTICE string$ | number

Displays a message box containing a warning triangle and the specified string or number.

ONCOMERROR [handler]

Sets up a handler (which may be a label or a SUB) to be called if an error occurs when opening a serial port. If the handler is omitted error trapping is disabled.

ON ERROR GOTO destination | 0

Sets up an error handler; if a trappable error occurs control will be passed to the destination, which may be a label or a line number. If zero is specified as the destination, error trapping is restored to its previous or default state. For an alternative approach see Structured Exception Handling.

OPEN device$ FOR purpose AS #handle [LEN=reclen]

Opens a DLL, file, port or window. If a file is opened, a record length may be specified.

OUT port, data

Outputs data to an I/O port (deprecated).

PAGESETUPDIALOG

Displays the standard Page Setup dialog box, allowing the user to specify the paper orientation, margins etc. used by subsequent LPRINT statements.

PLAYMIDI midifile$, length

Plays a MIDI file; the variable length is set to the length of the music (in arbitrary units, see MIDIPOS).

PLAYWAVE wavfile$ [, mode ]

Plays the specified WAV file, optionally specifying ASYNC, SYNC or LOOP modes.

POPUPMENU "text", handler {, "text", handler}

Displays a pop-up menu at the current position of the mouse pointer (cursor). The handlers may be labels or SUBs.

PRINT [[TAB(n);] expression {, | ; [TAB(n);] expression} [, | ;]]

Outputs the specified numeric or string expression(s) to the mainwin folowed by a newline. TAB(n) advances to the specified column and a comma advances to the next multiple-of-14 column; a trailing comma or semicolon suppresses the newline.

PRINT #handle, expression [;]

Outputs the specified numeric or string expression to a file, followed by a newline (CRLF). A trailing semicolon suppresses the newline.

PRINTERDIALOG

Displays the standard Print Dialog, allowing the user to select the printer and number of copies. The printer is initialised to the value of PrinterName$ (if any) and on return the PrinterName$ and PrintCopies variables are set. If the user preses Cancel, PrinterName$ is empty.

PrinterFont$ = "Font_Name points style"

Changes the font, size and style used by LPRINT; this has immediate effect, even within a page.

PrinterName$ = "New printer name"

Changes the printer used for subsequent output using LPRINT or the graphics PRINT command. Also determines which printer is initially selected in the PRINTERDIALOG.

PRIVATE

Precedes a method definition, to specify that it may be called only from within the same class.

PROMPT "prompt string"; replyvar$

Displays a message box prompting the user to supply a response. If Cancel is selected replyvar$ contains an empty string.

PUT #file, recordnumber

Writes the specified record of a random-access file. The first record in the file is record number 1.

RADIOBUTTON #handle.ext, "label", sethandler, resethandler, xpos, ypos, width, height

Creates a radiobutton; if there is more than one group of radiobuttons each group must be placed in a separate group box. The handlers may be labels or SUBs.

RANDOMIZE [seed]

Causes subsequent random numbers to be predictable, depending on the value of seed (0.0 < seed < 1.0).

READ variable {, variable}

Reads one or more numeric or string variables from constants in a DATA statement or statements.

READJOYSTICK 1 | 2

Reads the specified joystick and returns values in Joy1x, Joy1y, Joy1z, Joy1button1, Joy1button2 or Joy2x, Joy2y, Joy2z, Joy2button1, Joy2button2.

REDIM array(size{,size}) [, array(size{,size}]

Clears the contents of an array to zeroes or empty strings, and optionally changes its dimensions. Note that you cannot change the dimensions of a three-or-more-dimensional array.

REM remark

Allows a comment to be inserted into a program (similar to starting a statement with an apostrophe).

RESTORE [destination]

Sets the DATA pointer to the first DATA statement, or to the first DATA statement after the specified destination (which may be a label or a line number).

RESUME

Used after an ON ERROR GOTO statement has been executed, causes execution to continue at the line in which the error occurred. Only useful if the cause of the error has been cleared. For an alternative approach see Structured Exception Handling.

RETURN

Returns from a subroutine called with GOSUB.

RUN command$ [, state]

Runs the specified external command (which may include 'command-line' parameters), optionally initialising the window to the specified state (e.g. HIDE or MINIMIZE). If the state is WAIT, does not return until the external program has finished.

SCAN

Gives an opportunity for a pending event (for example a TIMER or mouse event) to be handled.

SEEK #handle, position

Moves the file pointer to the specified position (in bytes, not records).

SELECT CASE [testexpression]

Evaluates the specified (numeric or string) expression, and compares it with the values specified in subsequent CASE statements. If equal, the code following the CASE statement is executed. If the expression is omitted, each CASE statement must specify a Boolean expression.

SORT array(), start, end [, column]

Sorts the specified range of array elements (numeric or string); if end is less than start the array is sorted into reverse order. If the array is two-dimensional, start and end indicate the range of rows to be sorted, and column indicates which column to use as the sort key.

STATICTEXT #handle[.ext], "title", xpos, ypos, width, height

Creates a static text control, typically used to label another control or to give instructions.

STOP

Identical in effect to END.

STOPMIDI

Stops any currently playing MIDI file (see PLAYMIDI).

STRUCT name[(size{,size})], member AS type {, member AS type}

Creates a user-defined structure, or array of structures. Valid data types are CHAR[n], DOUBLE, LONG, BOOLEAN (same as LONG), ULONG, HANDLE (same as ULONG), PTR, STRUCT, SHORT, USHORT and WORD (same as USHORT).

STYLEBITS #handle[.ext], addbits, removebits, addextendedbits, removeextendedbits

Adds or removes bits from the style and/or extended-style of the specified window or control. Must be used before the window is opened.

SUB name [[BYREF] parameter {, [BYREF] parameter}]

Begins a user-defined subroutine definition, with optional numeric, string or array formal parameters. If the BYREF qualifier is used the parameter is passed 'by reference' and the variable specified in the CALL statement may be modified by the SUB.

TEXTBOX #handle.ext, xpos, ypos, width, height

Creates a textbox (usually single-line, unless modified by STYLEBITS), into which the user can type information.

TEXTEDITOR #handle.ext, xpos, ypos, width, height

Creates a multi-line texteditor control.

THROW errnumber [, errstring$]

Causes a user-defined error to be generated. Err is set equal to errnumber and, optionally, Err$ is set equal to errstring$. User-defined error numbers should be limited to the range 70 to 180.

TIMER milliseconds, handler | 0

Starts an event timer; the specified handler (which may be a label or a SUB name) is called repetitively with the specified period in milliseconds. If zero is specified as the handler, the timer is disabled.

TITLEBAR title$

Changes the contents of the mainwin's title bar.

TRACE 0 | 1 | 2

Enables or disables run-time tracing; normally used in conjunction with the debugger. TRACE 2 pauses the program and enables single-step mode, TRACE 1 prints line numbers to the mainwin as they are executed, TRACE 0 restores normal operation.

TRY

Begins a TRY...CATCH...END TRY clause.

UNLOADBMP "bitmap"

Deletes the specified bitmap and releases the memory it occupied.

UNTIL

Part of the DO...LOOP clause.

WAIT

Waits for an event (e.g. a TIMER, keyboard or mouse event). Execution never continues beyond this statement.

WEND

Indicates the end of a WHILE loop.

WHILE condition

Begins a WHILE...WEND loop. Looping continues whilst the specified condition, truncated to an integer, is non-zero.


Functions

ABS(numeric)

Returns the absolute value, i.e. if the parameter is negative it is returned as positive.

ACS(numeric)

Returns, in radians (0 to +PI), the angle with the specified cosine.

ASC(string$)

Returns the ASCII/ANSI value of the first character in the string. If the string is empty, zero is returned

ASN(numeric)

Returns, in radians (-PI/2 to +PI/2), the angle with the specified sine.

ATN(numeric)

Returns, in radians (-PI/2 to +PI/2), the angle with the specified tangent.

CHR$(numeric)

Returns a string of length one containing the character with the specified ASCII/ANSI value.

COS(numeric)

Returns the cosine of the specified (radian) angle.

DATE$([format$ | dayno])

Returns the current date in various formats, or converts a day number to a date.

DECHEX$(numeric)

Converts an integer value to its hexadecimal equivalent.

EOF(#handle)

Returns non-zero if the end of the file has been reached and zero otherwise.

EVAL(string$)

Evaluates the specified expression and returns the result as a number.

EVAL$(string$)

Evaluates the specified expression and returns the result as a string.

EXP(numeric)

Returns e (2.718281828459045236) raised to the power of the specified value.

HBMP("bitmap")

Returns the native Windows handle of the specified bitmap.

HEXDEC(hex$)

Converts the specified hexadecimal number to a numeric value. The hex number may optionally be prefixed with "&H".

HWND(#handle[.ext])

Returns the native Windows handle of the specified window, control, file or serial port.

INP(numeric)

Inputs a value from the specified I/O port (deprecated).

INPUT$(#handle, count)

Reads the specified number of characters (bytes) from the specified file.

INPUTTO$(#handle, char$))

Reads from the specified file up to the specified delimiter character or CR (carriage return), whichever comes first.

INSTR(searchin$,searchfor$[,startat])

Searches a string for the specified sub-string, optionally starting at a specified place, and returns the position of the first match. If the string was not found, zero is returned.

INT(numeric)

Converts a numeric value to an integer. By default LBB works in the same non-standard way as LB 4.04 (it truncates towards zero). If the %mode std directive has been issued, it works in the standard way (it truncates towards minus infinity).

LEFT$(string$,count)

Returns the first count characters from the string. By default if count is negative the entire string is returned; if the Emulate Slicing option has been enabled, an empty string is returned.

LEN(string$ | structname.struct)

Returns the length of the specified string, or the size of the specified structure (in bytes).

LOC(#handle)

Returns the current position of the file pointer (in bytes).

LOF(#handle)

Returns the length of the file, in bytes.

LOG(numeric)

Returns the natural (base-e) logarithm of the specified value.

LOWER$(string$)

Converts the specified string to lower-case characters.

MAX(numeric,numeric)

Returns the maximum (most positive) of the two specified values.

MID$(left$,start[,count])

Returns a sub-string, starting at start and containing a maximum of count characters. If the third parameter is omitted, it returns the rest of the string. By default if count is negative the rest of the string is returned; if the Emulate Slicing option has been enabled, an empty string is returned.

MIDIPOS()

Returns the current position of a playing MIDI file, in the same units as returned by PLAYMIDI.

MIN(numeric,numeric)

Returns the minimum (most negative) of the two specified values.

MKDIR(path$)

Attempts to create the specified directory (folder) and returns zero if it was sucessful; a non-zero return indicates a failure.

NOT(numeric)

Boolean negation: returns zero if the specified value (truncated to an integer) is non-zero, and ‑1 if the specified value is zero.

RIGHT$(string$,count)

Returns the rightmost count characters of the specified string. By default if count is negative the entire string is returned; if the Emulate Slicing option has been enabled, an empty string is returned.

RMDIR(path$)

Attempts to remove the specified directory (folder) and returns zero if it was sucessful; a non-zero return indicates a failure.

RND([n])

Returns a pseudo-random number in the range 0 to 1.000. The parameter n, if supplied, is ignored. The sequence length is 233‑1.

SIN(numeric)

Returns the sine of the specified (radian) angle.

SPACE$(n)

Returns a string consisting of n spaces.

SQR(numeric)

Returns the square-root of the specified (non-negative) value.

STR$(numeric)

Converts the specified value to a string representation. For floating-point numbers this returns a maximum of 9 significant figures; for more precision use USING() instead.

TAN(numeric)

Returns the tangent of the specified (radian) angle.

TIME$([format$])

Returns the current time. If the format string is omitted the time is returned as "hh:mm:ss". If the format string is "seconds" or "ms" the number of seconds or milliseconds, respectively, since midnight is returned.

TRIM$(string$)

Removes 'whitespace' (spaces and non-printing characters) from the beginning and end of the specified string.

UPPER$(string$)

Converts the specified string to upper-case (capitals).

USING(template$, numeric)

Converts the specified value to a string representation, using the format specified in the template (e.g. "#.##", "###,###,###", "#.###^^^^"). For floating-point numbers, up to 19 significant figures may be returned.

VAL(string$)

Convert the specified string to a numeric value. If the string does not represent a numeric constant, zero is returned.

WINSTRING(pointer)

Returns the NUL-terminated string stored in memory at the specified address.

WORD$(string$, number [, delim$])

Splits the specified string into words separated by the specified delimiter (if supplied) or otherwise by whitespace (spaces and non-printing characters). Returns the word indexed by number.


Operators

numeric AND numeric

Returns the bitwise AND of the two operands, truncated to 64-bit integers. In other words a bit is set in the output only if that bit is set in both operands. Commonly used in Boolean expressions.

numeric MOD numeric

Returns the remainder after division of the first operand by the second operand. If the second operand is zero a Division by zero error will result.

numeric OR numeric

Returns the bitwise OR of the two operands, truncated to 64-bit integers. In other words a bit is set in the output if that bit is set in either or both of the operands. Commonly used in Boolean expressions.

numeric XOR numeric

Returns the bitwise XOR of the two operands, truncated to 64-bit integers. In other words a bit is set in the output only if that bit is set in just one of the operands, but not both.


Graphics commands

BACKCOLOR color

Sets the color used to fill a solid shape. The color may be specified either as a name or an RGB triplet (see COLOR).

BOX xpos ypos

Draws an outline axis-aligned rectangle with one corner at the current graphics (pen) position and the opposite corner at the specified coordinates.

BOXFILLED xpos ypos

Draws a filled axis-aligned rectangle with one corner at the current graphics (pen) position and the opposite corner at the specified coordinates.

CIRCLE radius

Draws an outline circle with its centre at the current graphics (pen) position and with the specified radius.

CIRCLEFILLED radius

Draws a filled circle with its centre at the current graphics (pen) position and with the specified radius.

CLS

Clears the entire GRAPHICBOX or graphics window to white (or whatever your default window color is set to be in Display Properties).

COLOR color

Sets the color used to draw lines or text. The color may be specified either as a name (black, blue, brown, buttonface, cyan, darkblue, darkcyan, darkgray, darkgreen, darkpink, darkred, green, lightgray, palegray, pink, red, white, yellow) or an RGB triplet (e.g. 0 128 255).

DISCARD

Discards anything drawn since the last FLUSH (deprecated).

DOWN

Enables graphics drawing.

DRAWBMP bitmap x y

Plots the specified bitmap with its top-left corner at the specified coordinates.

ELLIPSE width height

Draws an outline axis-aligned ellipse with its centre at the current graphics (pen) position and with the specified width and height.

ELLIPSEFILLED width height

Draws a filled axis-aligned ellipse with its centre at the current graphics (pen) position and with the specified width and height.

FILL color

Fills the entire GRAPHICBOX or graphics window with the specified color, specified either as a name or an RGB triplet (see COLOR).

FLUSH [segment]

Makes a temporary copy of the current contents of the GRAPHICBOX or graphics window, which may later be restored using REDRAW; if a segment is specified it is ignored (deprecated).

FONT typeface [width] height {style}

Sets the current text font to the specified typeface, size and optional style(s). The size may be specified either in points or as a width and height in pixels (if the width is set to zero the default width is used). The styles are italic, bold, strikeout, and underscore.

GETBMP bitmap xpos ypos width height

Copy the specified region of the GRAPHICBOX or graphics window to the specified bitmap.

GO distance

Move the pen 'forwards' the specified distance, drawing if it is DOWN.

GOTO xpos ypos

Move the pen to the specified coordinates, drawing if it is DOWN.

HOME

Centers the pen in the GRAPHICBOX or graphics window.

HORIZSCROLLBAR on | off [min max]

Enables or disables the horizontal scrollbar, and optionally specifies the scroll range.

LINE x1 y1 x2 y2

Draws a line between the specified coordinates; the pen is moved to the end point.

NORTH

Sets the current pen direction to 'upwards' (270 degrees).

PIE width height start sweep

Draws an outline sector, with the centre at the current graphics (pen) position. The start angle is in degrees, with zero representing 'east', and a positive value of sweep indicates a clockwise direction.

PIEFILLED width height start sweep

Draws a filled sector, with the centre at the current graphics (pen) position. The start angle is in degrees, with zero representing 'east', and a positive value of sweep indicates a clockwise direction.

PLACE xpos ypos

Moves the pen to the specified coordinates; no line is drawn, even if the pen is DOWN.

POSXY xvar yvar

Copies the current graphics (pen) coordinates to the specified variables.

PRINT [size [nodump]]

Sends the contents of the GRAPHICBOX or graphics window to the printer, scaling them so that a width of size pixels fills the printed page. Normally the page is automatically ejected, but by specifying nodump you can LPRINT text on top of the graphics and then issue a DUMP command.

REDRAW [segment]

Replaces the current graphics with the temporary copy saved using FLUSH; if a segment is specified it is ignored (deprecated).

RULE code

Sets the drawing method to normal (OVER) or exclusive-or (XOR). Alternatively one of the Windows _R2_ constants may be specified.

SET xpos ypos

Draws a single point at the specified coordinates.

SIZE thickness

Sets the line thickness, in pixels.

STRINGWIDTH? string$ retvar

Measures the width of the specified string, in pixels, and returns it in the specified variable.

TURN degrees

Rotate the drawing direction by the specified number of degrees (clockwise).

UP

Disable graphics drawing (some drawing commands still work even if the pen is 'up').

VERTSCROLLBAR on | off [min max]

Enables or disables the vertical scrollbar, and optionally specifies the scroll range.

WHEN event handler

Calls the specified handler (which may be a label or a SUB) when the specified mouse or keyboard event occurs (e.g. leftButtonDown).

\text string

Displays the specified text followed by a newline. Additional \ characters cause newlines to be printed. | may be used instead of \ if the backslash character needs to be printed.


Text commands

!BACKCOLOR color

(TEXTEDITOR or TEXT window only) Sets the background color; the color may be specified either as a name or an RGB triplet (see COLOR).

!CLS

Clears the window.

!CONTENTS string$ | #filehandle

Loads the window with the contents of the specified string or open file.

!CONTENTS? string$

Copies the text contents into the specified variable.

!COPY

Copies the current selection (if any) to the clipboard. If nothing is selected the clipboard is emptied.

!CUT

Cuts the current selection (if any) to the clipboard. If nothing is selected the clipboard is emptied.

!FIND string$

Searches downwards to find the text contained in the specified variable.

!FINDBACK string$

Searches upwards to find the text contained in the specified variable.

!FONT typeface [width] height {style}

Sets the current text font to the specified typeface, size and optional style(s). The size may be specified either in points or as a width and height in pixels (if the width is set to zero the default width is used). The styles are italic, bold, strikeout, and underscore.

!FORECOLOR color

(TEXTEDITOR or TEXT window only) Sets the color of all the text; the color may be specified either as a name or an RGB triplet (see COLOR).

!INSERT string$

Inserts the contents of the specified variable at the current text cursor (caret) position.

!LINE n string$

(TEXTEDITOR or TEXT window only) Copies the specified line into the string variable (the top line is line 1).

!LINES retvar

Returns the total number of lines in the specified numeric variable.

!MODIFIED? answer$

If the text has been modified sets the specified variable to "true", otherwise sets it to "false".

!ORIGIN column row

Scrolls the text so that the first visible character is as specified (the first row and column are number 1).

!ORIGIN? colvar rowvar

Sets the specified variables to the text coordinates of the first visible character (the first row and column are number 1).

!PASTE

Pastes the text contents of the clipboard (if any) at the current text cursor (caret) position.

!RESETFIND

Starts the next search from the beginning or end of the text.

!SELECT column row

(TEXTEDITOR or TEXT window only) Moves the text cursor (caret) to the specified column and row (this command is confusingly named!).

!SELECTALL

Selects all the text.

!SELECTION? string$

(TEXTEDITOR or TEXT window only) Copies the currently-selected text, if any, into the specified string variable.


Other GUI commands

AUTORESIZE

Automatically resizes the control if the user resizes the window.

BITMAP bitmap

Displays the specified bitmap on the button (BMPBUTTON).

DISABLE

Disables the control.

ENABLE

Enables the control.

HIDE

Hides the control.

LOCATE xpos ypos width height

Repositions and resizes the control according to the specified values.

REFRESH

Redraws the control.

RELOAD

Reloads the control from the associated array (COMBOBOX or LISTBOX).

RESET

Unchecks the specified box (CHECKBOX or RADIOBUTTON).

SELECT string

Searches for the specified literal string and if found selects that item (COMBOBOX and LISTBOX).

SELECTINDEX index

Selects the item at the specified index (COMBOBOX or LISTBOX).

SELECTION? string$

Copies the currently selected item to the specified string variable (COMBOBOX and LISTBOX).

SELECTIONINDEX? retvar

Returns the index of the currently selected item in the specified numeric variable (COMBOBOX and LISTBOX).

SET

Checks the specified box (CHECKBOX or RADIOBUTTON).

SHOW

Makes the control visible.

SINGLECLICKSELECT

Causes the control's handler to be activated by a single-click rather than a double-click (COMBOBOX or LISTBOX).

TRAPCLOSE handler

Activates the specified handler (which may be a label or a SUB) when the window is closed.

VALUE? retvar$

Returns the current state ("set" or "reset") in the specified string variable (CHECKBOX or RADIOBUTTON).


Sprite commands

ADDSPRITE sprite bitmap { bitmap}

Adds a named sprite. Multiple bitmaps may be specified for animated sprites.

BACKGROUND bitmap

Use the specified bitmap as the sprites' background. The bitmap is stretched as necessary.

BACKGROUNDXY x y

Scroll the background so the specified coordinates are in the top-left corner. The bitmap is tiled as necessary.

CENTERSPRITE sprite

Offsets the sprite so that its reference point is centered.

CYCLESPRITE sprite dir [once]

Automatically cycles the sprites through its image list at each DRAWSPRITES command. dir specifies whether the images are cycled forwards (1) or backwards (-1). If the optional once parameter is specified, the sprite cycles through its image list just once.

DRAWSPRITES

Updates the display: draws the background and all the sprites. Animates and/or moves sprites to which the CYCLESPRITE, SPRITEMOVEXY or SPRITETRAVELXY command has been issued.

REMOVESPRITE sprite

Deletes the specified sprite.

SPRITECOLLIDES sprite list$

Copies into the specified string variable a list of other sprites which the specified sprite currently overlaps (if any).

SPRITEIMAGE sprite bitmap

Selects the specified bitmap from the sprite's image list.

SPRITEMOVEXY sprite xshift yshift

Moves the sprite by the specified amount at each DRAWSPRITES command.

SPRITEOFFSET sprite xoff yoff

Offsets the sprite from its nominal coordinates.

SPRITEORIENT sprite orientation

Displays the sprite according to the specified orientation (normal, flip, mirror, rotate180).

SPRITEROUND sprite

When testing for sprite collisions, assumes the sprite is elliptical not rectangular.

SPRITESCALE sprite scale

Scales the sprite by the specified amount in percent.

SPRITETOBACK sprite

Displays the sprite behind all the others.

SPRITETOFRONT sprite

Displays the sprite in front of all the others.

SPRITETRAVELXY sprite x y speed handler

Automatically moves the sprite towards the specified coordinates at the specified speed, at each DRAWSPRITES command. When the sprite has reached its destination, activates the specified handler, which may be a label or SUB.

SPRITEVISIBLE sprite on | off

Makes the sprite visible or invisible.

SPRITEXY sprite xpos ypos

Moves the sprite directly to the specified coordinates.

SPRITEXY? sprite retx rety

Returns the sprite's current coordinates in the specified numeric variables.

Object Oriented Programming

LB Booster (version 3.00 and later) supports Object Oriented Programming (OOP). Whilst this is an entirely optional feature, which does not affect compatibility with earlier versions of LBB or LB4, it is a powerful modern capability. Four new statements are defined: CLASS, DISCARD, NEW and PRIVATE.

Below is a brief syntax description, but for more details and examples see this article at the LBB Wiki.

Instantiating an object

An object is created as an instance of a class. Objects may either be created individually, or an array of identical objects may be created. When an individual object is created, parameters may optionally be passed to its constructor (having the correct signature). If an array of objects is created, only the default constructors are called:
NEW object AS class [parm {, parm}]                ' calls constructor [with parameters]
NEW objarr(dimensions) AS class                    ' calls default constructors (if any)

Calling object methods

Object methods behave either like SUBs or like FUNCTIONs, and they are called in the same way. The target is specified as the name of the object followed by two colons :: (known as the scope resolution operator) and then the name of the method. If the object is an element of an array, the index or indices come before the colons:
CALL object::method [parameter {, parameter]}]     ' subroutine-like method
lvalue = object::method([parameter {, parameter}]) ' function-like method
CALL objarr(indices)::method [parm {, parm]}]      ' subroutine-like method
lvalue = objarr(indices)::method([parm {, parm}])  ' function-like method

Discarding an object

When an object, or array of objects, is no longer required it should be DISCARDed. This automatically calls the object's destructor (if any) and then frees the memory occupied by the object:
DISCARD object                                     ' calls destructor (if any)
DISCARD objarr()                                   ' calls destructor in each (if any)

Defining a class

A class definition should be placed after the end of the main program, in the same way as SUB and FUNCTION definitions are. If a class inherits properties and/or methods, its parent class must be defined first.

The class properties (variables and arrays) are private to the class: they can be accessed only from the methods in the same class; this is similar to the scope of variables within ordinary SUBs and FUNCTIONs except that class properties 'remember' their values from one call of a method to the next. Unlike conventional arrays, class property arrays are not global.

The properties should be declared first, using a special form of the DIM statement, followed by the methods. The default constructor(s), if any, have the same name as the class; the destructor (if any) has the name of the class prefixed with a tilde ~.

To call a method in the same class, prefix its name with this::, a PRIVATE method can only be called this way.

CLASS class [INHERITS class]
  ' class properties are automatically private
  DIM var | var$ | array(n) | array$(n) | child AS class {, ....}

  SUB class
    ' default constructor (optional)
  END SUB

  SUB ~class
    ' destructor (optional)
  END SUB

  SUB class parm {, parm]}
    ' constructor with parameter(s)
  END SUB

  [PRIVATE] SUB method [parm {, parm}]
    ' subroutine-like or setter method
    CALL this:method [parameter {, parameter]}]     ' call another method in this class
    lvalue = this:method([parameter {, parameter}]) ' function-like method in this class
    CALL child::method [parameters]                 ' call method in child class
    lvalue = child::method [parameters]             ' function in child class
    lvalue = property                               ' read property variable
    property = rvalue                               ' write property variable
  END SUB

  [PRIVATE] FUNCTION method [parm {, parm}]
    ' function-like or getter method
  END FUNCTION
END CLASS

OOP notes

Structured Exception Handling

LB Booster (version 3.00 and later) supports Structured Exception Handling (SEH). This is a way of handling errors which is easier to use, and more flexible, than ON ERROR GOTO. Three new statements are defined: TRY (and END TRY), CATCH and THROW.

This is the structure of the TRY clause:

TRY
  ' Code which might fail
CATCH
  ' Code to execute if an error occurs in the TRY clause
END TRY
Here is a practical example:
for n = -3 to 3
  try ' code to try
    print "The reciprocal of "; n ; " is ",
    print 1/n, 
    print "(successful)"
  catch ' code to run on an error
    print Err$;
    print " (failed: code "; Err; ")"
  end try ' end of try clause
next n
which produces the following output:
The reciprocal of -3 is     -0.333333333  (successful)
The reciprocal of -2 is     -0.5          (successful)
The reciprocal of -1 is     -1            (successful)
The reciprocal of 0 is      Division by zero at line 4 (failed: code 11)
The reciprocal of 1 is      1             (successful)
The reciprocal of 2 is      0.5           (successful)
The reciprocal of 3 is      0.333333333   (successful)
THROW is used to trigger a user-defined error:
throw 88, "My custom error"
This generates an error which sets Err to 88 and Err$ to "My custom error". The string may be omitted, in which case a default message is generated:
throw 88
Custom error codes should be limited to the range 70 to 180 to avoid a clash with pre-defined LBB error numbers.

Debugging

LB Booster incorporates a debugger, to help you locate faults in your programs. To activate the debugger either click on the 'beetle' button in the toolbar or select 'Run... Debug Program' from the menu (keyboard shortcut Alt+RD). This will translate (if necessary) and then run your program, but execution will pause at the first statement (which will be highlighted in the editing pane). Any NOMAINWIN statement in your program will be ignored when debugging, since the mainwin is a useful place for your program to send diagnostic information.

A small, resizable, debugging window will open, having a toolbar and a scrollable listbox. The listbox displays the variables in your program, updating as their values change and new ones are created. Initially it will contain the 'reserved' variables (e.g. DefautDir$ and Drive$) and any globals defined in your program. If you want to monitor the value of a specific variable you can click on it; it will then be highlighted and the list will be scrolled automatically to keep it in view. To deselect that variable click in the title bar of the debugging window.

The toolbar contains 'Resume', 'Pause', 'Step into' and 'Step over' buttons (hovering your mouse over a button will indicate its function in a tooltip). 'Resume' causes execution of the program to continue at full speed until it encounters a WAIT or TRACE 2 statement, stops to receive user input (e.g. INPUT or PROMPT), hits a breakpoint (see below) or the 'Pause' button is clicked. If your program executes a WAIT statement whilst in a paused state, you may need to 'unpause' it (click on 'Resume') and pause it again before it will respond to an event such as a TIMER tick, button press etc.

The 'Step into' and 'Step over' buttons are active only when the program is paused. 'Step into' causes a single statement to be executed; you may find that some statements require it to be clicked more than once. If the statement transfers control into a function or subroutine 'Step into' will cause execution to pause within that module. 'Step over' causes execution to pause again only on the next line, so if the statement transfers control into a function or subroutine it will run at full speed until it returns, and if the statement terminates a loop (e.g. a NEXT or WEND) execution will continue at full speed until the loop is complete. It is not usually desirable to use 'Step over' on an END FUNCTION, END SUB or RETURN statement.

You can insert temporary breakpoints in your program by double-clicking in the left margin of the editing pane, a small square will appear there as a marker; to remove the breakpoint double-click again (to clear all breakpoints right-click in the margin and select the appropriate menu item). When a breakpoint is encountered during execution the program will pause, as if you had clicked on the 'Pause' button in the debugging window's toolbar; breakpoints have no effect if you use Run rather than Debug. Breakpoints are linked to the line number, so if you insert or delete any lines above a breakpoint it will move in relation to the code. You cannot add or remove breakpoints once the program is running.

A 'permanent' breakpoint can be inserted by means of a TRACE 2 statement; this has the same effect as a temporary breakpoint but can be saved as part of the program. It will only pause the program when you are debugging it, but you are recommended to remove TRACE 2 statements once your program is fully tested since their presence may cause execution to be slowed slightly. Note that TRACE 1 has a different function in LB Booster from that in LB 4.04: it causes line numbers to be logged to the mainwin during execution. LBB has no equivalent of LB's animate mode, since the variable list and statement highlighting continue to be refreshed even when the program is running at full speed.

Troubleshooting

Here are some hints for how to get the best from LB Booster:

How It Works

For those who may be interested, here is a technical description of how LB Booster works.

LBB is a hybrid translator and emulator. The translator automatically converts Liberty BASIC syntax to the equivalent BBC BASIC syntax. This translation takes place when you first issue the Run Program or Make Executable command.

The emulator (LBLIB) implements at run-time those aspects of Liberty BASIC which aren't part of the standard BASIC language and which have no direct equivalent in BBC BASIC; principally these are the Graphical User Interface elements (windows, controls, graphics and sprites). The emulator is itself written in BBC BASIC.

When you issue the Make Executable command LBB creates a single-file standalone executable containing the BBC BASIC for Windows run-time engine, the LBLIB emulator and a tokenised/compressed version of the translated BASIC program.

Formal Stuff

LB Booster is thought to be free from serious bugs, and it is highly unlikely that it could do any harm to other software or systems. However there is NO warranty that it will not and its use is at your own risk.

LB Booster is the Copyright © 2015 of R. T. Russell.

BBC BASIC for Windows is the Copyright © 2001-2015 of R. T. Russell. The name BBC BASIC is used with the permission of the British Broadcasting Corporation.

Liberty BASIC is the trademark of Carl Gundel trading as Shoptalk Systems.

Liberty BASIC Workshop is the Copyright © 2010 of Alyce Watson.

The aPLib compression library is used with permission. Copyright © 1998-2014 by Joergen Ibsen, All Rights Reserved.


Best viewed with Any Browser Valid HTML 3.2!
© Richard Russell 2015