BBC BASIC for SDL 2.0

Integrated Development Environment

Introduction to the IDE

BBC BASIC for SDL 2.0 comes with two Integrated Development Environments (IDEs): BBCEdit (written by Andy Parkes) and SDLIDE (written by Richard Russell). They have similar capabilities, although the detailed interfaces are significantly different. You are initially presented with a selector window to choose which you prefer, you should probably try both before making a decision. Once you are sure which you want to use, you can disable the selector window.

This document describes SDLIDE which, of the two, is the one more similar to the IDE supplied with BBC BASIC for Windows. It has the normal features which make up a modern Graphical User Interface (GUI): a title bar, a set of drop-down menus, a toolbar, an editing pane and a status bar.

You can move this window wherever you like on your desktop, and you can re-size it by dragging one of the corners or sides; you can also maximise it by clicking on the relevant button in the title bar. SDLIDE will remember the size of the window and set it to the same size when it is next started.

The title bar

The detailed appearance of the title bar varies between platforms, but it will always contain the name and version number of the application (SDLIDE), the name of the currently loaded BASIC program (or 'untitled' if the New command has been issued), a minimise button, a maximise button and a close button.

If you close the window (or choose the File... Exit menu selection) you will be prompted to save the current program if any changes have been made.

The menu bar

The menu bar contains the drop-down menus File, Edit, Utilities, Options, Run 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). If any of the menu items are unavailable, they will be 'greyed out' and clicking on them will have no effect.

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. If any of the commands are unavailable the button will be 'greyed out' and clicking on it will have no effect. 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 Utilities menu: Renumber and Compile.
From the Run menu: Run, Debug, Stop, Pause, Step Into, Step Over and Immediate.
From the Help menu: About.

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 is split into five regions: a message region, the current character encoding, the current length of the BASIC program, the current position of the text cursor (caret) in the editing pane and the current Insert/Overtype status.

Character encoding

The character encoding (ANSI or Unicode) assumed for the current BASIC program, as selected in the Options menu.

Program length

The length, in bytes, of the currently-loaded BBC BASIC program. This corresponds to the size of the file if the program is saved in tokenised (.bbc) format, and (usually) to the value of TOP− PAGE when the program is running.

Cursor position

The current text cursor (caret) position is displayed in the form x,y where x is the horizontal position (the leftmost column is 0) and y is the vertical position (the topmost line is 0).

Insert/Overtype

Pressing the Insert key on the keyboard toggles between insert mode and overtype mode. Overtype mode is indicated by OVR being displayed in the status line; in this mode any character typed will over-write the existing character in that position on the line. The normal editing mode is insert mode, in which any characters typed 'push' the rest of the line to the right to make room.

File menu

The file menu is concerned with loading, saving and comparing BBC BASIC programs, and with exiting from BBC BASIC for SDL 2.0. 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 type or paste a new program. If the previous program was not saved, you are first prompted to save it.

Load

The Load command (keyboard shortcut Ctrl+L) loads a BBC BASIC program into memory. It will accept files in BBC BASIC internal (tokenised) format, in Acorn (BBC Micro or Archimedes) internal format, or in ASCII (plain text) format. The command calls up the Load File dialogue box:

Load dialogue

If the previous program was not saved, you are first prompted to save it.

Save

The Save command (keyboard shortcut Ctrl+S) saves the BBC BASIC program currently in memory to a file. The filename used is the same as that from which the program was loaded (i.e. the contents of the file are replaced). If the program was loaded from a tokenised (internal format) file it will be saved as a tokenised file with the extension .bbc; If the program was loaded from a plain text (ASCII) file it will be saved as a plain text file with the extension .bas. You can use the Save As command to override these defaults (a program must be saved in internal format if it is to be loaded at run-time with the CALL, CHAIN or INSTALL statement).

If the program was not loaded from a file (i.e. it was typed in or imported via the clipboard) or it was loaded from an Acorn-format file, the Save command will display the Save As dialogue box so you can enter the desired filename and format. If the current BASIC program is unchanged, so it doesn't need to be saved, the Save command is inhibited.

Save As

The Save As command saves the BBC BASIC program currently in memory to a file. You are prompted to select a file name and a file format: BBC BASIC internal (Tokenised) format or ASCII (Text File) format. Use Save As rather than Save if you need to change the directory (folder), filename or format to something different from their current values.

Insert

The Insert command (keyboard shortcut Ctrl+I) loads a BBC BASIC program into memory, but instead of it replacing the current program it is inserted in the program before the line containing the cursor (caret). This line, and subsequent lines, are 'moved down' to make space for the inserted lines.

The effect is similar to the Paste command, except that the inserted lines are read from a file (and may be in any of the formats accepted by the Load command).

Compare

The Compare command lists the differences between the BASIC program loaded into memory and a selected program, usually an earlier version. Lines which are in the old version but not in the new version are listed in red, lines which are in the new version but not the old version are listed in green. Pressing F8 advances to the next difference, pressing F7 moves to the previous difference.

If there are a large number of changes, or the programs are totally dissimilar, it can take a long time before the differences are displayed. Pressing the Escape key will abort the process.

Page Setup

The Page Setup command is disabled and does nothing in SDLIDE.

Print

The Print command (keyboard shortcut Ctrl+P) lists the program currently loaded into memory to your default printer.

You can force a 'new page' by including the following statement in your program:

REM!Eject

When the statement is encountered printing will continue at the top of the next page (this feature may not work with all printers).

Recent files

The nine most-recently loaded files are listed in the File menu, and can be re-loaded simply by clicking on the appropriate entry or by pressing 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 SDLIDE. If the currently loaded program, if any, has not been saved, you are first prompted to save or discard it.

Edit menu

The edit menu is concerned with editing or searching the current BBC BASIC program (i.e. the program loaded into memory). 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 (typing, delete, paste, renumber, insert file or replace. If there is nothing that can be undone, Undo is greyed out.

Redo

The Redo command (keyboard shortcut Ctrl+Y) reverses the effect of a previous undo command. If there is nothing that can be re-done, Redo is greyed out.

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. You can select text in the following ways:

Double-clicking on a word selects that word; other occurrences of the same word are highlighted with a light blue background.
Holding down the left mouse button and 'dragging' it selects a block of text. Dragging the mouse horizontally selects part or all of a line. Dragging the mouse vertically selects a block of lines (only entire lines may be selected).
Holding down the Shift key and moving the cursor with the arrow (or other cursor-movement) keys selects a block of text. Moving the cursor horizontally selects part or all of a line. Moving the cursor vertically selects a block of lines (only entire lines may be selected).

Once a block of text has been selected, you can alter the selection by holding down Shift and moving the cursor. If you want to change the start point of a selection, make the initial selection from right to left or from bottom to top. If you want to change the end point of a selection, make the initial selection from left to right or from top to bottom.

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.

See Cut for details of how text may be selected.

Paste

The Paste command (keyboard shortcut Ctrl+V) inserts the contents of the clipboard into the BBC 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. For example you can transfer code examples in the BASIC documentation files into your program by first copying them to the clipboard from the Help window then pasting them at the required place.

Delete

The Delete command deletes any selected text, without copying it into the clipboard. See Cut for details of how text may be selected. When there is a selection, the delete command has an identical effect to pressing the Delete key on the keyboard. 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 BASIC 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 (i.e. the text must be preceded and followed by non-alphabetic characters):

Find dialogue

To start the search click on Find Next or press the Return (Enter) key. 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.

If the specified text is found it is highlighted (i.e. selected) and the cursor is moved to the end of the highlighted region. The display is automatically scrolled so that the selected text is visible. Clicking on Find Next again causes the search to resume from this point and the next occurrence of the text (if any) to be found. If the text is not found before the end of the program the message "String not found" is displayed; clicking Find Next again causes the search to restart from the beginning of the program.

You can click on Cancel at any time to abort the search and dismiss the dialogue box.

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 of the program the message "String not found" is displayed; selecting Find Next again causes the search to restart from the beginning of the program.

Replace

The Replace command (keyboard shortcut Ctrl+R) allows you to search your BASIC 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. You can also specify whether the case (capitals or lower-case) is significant and whether to match only an entire word (i.e. the text must be preceded and followed by non-alphabetic characters):

Replace dialogue

To start the search click on Find Next or press the Return (Enter) key. The search begins at the position of the text cursor (caret) when the Replace 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.

If the specified text is found it is highlighted (i.e. selected) and the cursor is moved to the end of the highlighted region. The display is automatically scrolled so that the selected text is visible. To confirm that you want the text to be replaced click on Replace; this will replace the text and search for the next occurrence (if any).

Alternatively if you do not wish to replace this occurrence of the text click on Find Next. This will skip the replace operation and search for the next occurrence of the text (if any). If the text is not found before the end of the program the message "String not found" is displayed.

If you are certain that you want every occurrence of the text (from the current point to the end of the program) to be replaced, click on Replace All.

You can click on Cancel at any time to abort the search and dismiss the dialogue box.

Go To

The Go To command (keyboard shortcut Ctrl+G) enables you to move the text cursor (caret) directly to a specified line in the program; the lines are numbered consecutively with the topmost line being line zero. The command opens the Go To Line dialogue box into which you can type the line number to which you want to jump:

Go To dialogue

Utilities menu

The utilities menu contains commands to aid debugging of your BASIC program, to renumber your program and to convert your program to a distributable bundle. The utilities menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-U.

Renumber

The Renumber command allows you to renumber the lines of your program, or alternatively to remove all the line numbers (except those needed as the destination of a GOTO, GOSUB or RESTORE statement). The command opens the Renumber dialogue box into which you can type the line number for the first line of your program and the increment (step) between consecutive line numbers. Both values default to 10:

Renumber dialogue

Renumbering your program can be useful when debugging, because if an (untrapped) error occurs the line number at which the error occurred is displayed. Once your program is complete and debugged, you may prefer to remove the line numbers so as not to clutter the program listing.

The Renumber command will fail if the specified increment is zero or if the specified values would result in a line number greater than the maximum allowed (65535).

Compile

The Compile command allows you to create a distributable application bundle from your BBC BASIC program; the format of this bundle depends on the platform: by default a .exe file in Windows, a .dmg file in MacOS and a .zip archive in Linux (including the Raspberry Pi). You can distribute such bundles freely without any royalty being due. Note that this is not a true compiler in the traditional sense, your BASIC program is still interpreted.

You can alternatively create an application bundle which can be hosted online and run in a suitable web browser (that is, a browser which supports the Web Assembly Threads feature). At the time of writing most desktop browsers are compatible, except Internet Explorer. Some Android browsers are also compatible (e.g. Chrome and Firefox) plus Safari on iOS.

The Compile command opens a dialogue box which allows you to choose the name and file path of the application bundle, select an appropriate icon and choose whether or not to 'crunch' the program:

Compile dialogue

Application

By default the filename of the application bundle is set to be the same as the name of your BASIC program, but with the extension '.exe', '.dmg', '.zip' or '.bbb' rather than '.bbc' (or '.bas'). However you can change the name and/or the directory path (folder) by entering them directly, by clicking on the Browse button or by using the REM!Exefile compiler directive. In Windows you can create a '.zip' archive as an alternative to '.exe'.

By default the application bundle is stored in the exe subdirectory of the directory (folder) containing the BASIC program. This ensures that it is safe to run the 'compiled' program without any risk of embedded files, when extracted, overwriting wanted original files in the source directory.

The name of the application may be entered directly or set by using the REM!Appname compiler directive. This is the name which will normally be associated with the application's desktop icon.

You can change the icon asssociated with the application bundle by using the REM!Icon compiler directive or by clicking on the Change Icon button. The icon must be a file in PNG format (which may include transparency), ideally in a square format and a resolution of at least 256x256 pixels (in the case of MacOS, exactly 256x256 pixels). Please respect Copyright, and use only an icon which you have generated yourself or have legitimately obtained for this purpose.

Selecting the Deploy as a web application checkbox causes the compiler to generate a web bundle (.bbb file) which may be hosted online and run in a suitable web browser using this URL:

https://wasm.bbcbasic.co.uk/bbcsdl.html?app=URL-of-bbb-file

replacing URL-of-bbb-file with the URL of your uploaded web bundle (this may be a Dropbox link). There is a backup server in case of downtime, to use it substitute .net for .co.uk in the above URL.

Crunch

You can choose to crunch your program when it is incorporated into the application bundle. This reduces the size of the file, often by a significant amount, and increases the speed of execution of your program somewhat. It also makes it much more difficult for somebody to 'reverse engineer' your program to discover how it works. The following options are provided:

Discard spaces. All superfluous spaces in your program are removed.
Concatenate lines. Short lines are concatenated (joined end-to-end) to make fewer long lines, where this is possible.
Remove REMs. All REM statements are removed (unless referenced by a GOTO, GOSUB or RESTORE statement).
Abbreviate names. Variable, procedure and function names are replaced with internal 'fast' tokens, or sometimes with short names, distributed across the alphabet.

When any of these options are selected, blank lines are also removed from your program.

When using the Remove REMs and Abbreviate names options you can include verbose comments in your program, and use long descriptive variable names, without the size or performance of the final compiled program being affected. In this way you can accord with good programming practice and make your 'source' program easier to understand and modify.

Although you can normally 'crunch' a program without it having any unwanted side effects, there are a few circumstances when it is incompatible with correct program operation:

If the program relies on variables having a specific name, for example a variable is referenced by name in a DATA statement or in an EVAL function, you should either disable the Abbreviate names option or use the REM!Keep compiler directive.
If the program performs calculations on line numbers to determine the destination of a GOTO, GOSUB or RESTORE, the Concatenate lines option should not be used.

Embedded files

If your program uses the CALL or INSTALL statement to load modules, or loads other files at run time (such as graphics files, sound files, font files etc.) you must ensure that the files are available to the 'compiled' program where it expects to find them. This is particularly important if you want to run the program on a computer on which BBC BASIC for SDL 2.0 is not installed. You can achieve this by ensuring the files are in either the library directory (as identified by the @lib$ system variable) or in the same directory as the program itself (as identified by the @dir$ system variable) and loading them as follows:

INSTALL @lib$+"dlglib"
OSCLI "DISPLAY """+@dir$+"graphics.png"""

Files loaded this way will automatically be incorporated in the compiled application bundle and extracted to appropriate locations on the target machine; alternatively you can specify which files should be embedded by using the REM!Embed compiler directive.

You can manually edit the list of embedded files using the Add @dir$, Add @lib$ and Remove buttons; the remove button deletes a selected (highlighted) entry in the list. But since you would need to do this every time the Compile command is issued it is not recommended.

Embedded files may come from the @dir$ or @lib$ folder, or a subfolder of either of these. This can be useful if your program uses many resource files, perhaps sound files or graphics files, and you prefer not to clutter up your program's folder with them. By creating subfolders called, for example, sounds and images you can keep your files organised. In your program you could access these files as follows:

OSCLI "DISPLAY "+@dir$+"resources/images/picture.jpg"

You can choose to crunch embedded BBC BASIC (tokenised) program files, as well as the main program. If this option is selected any embedded files with a .bbc extension are crunched as if they were part of the main program. The same crunch options are used, and in the case of the abbreviate names option the same abbreviations are used. This ensures that any variables or structures shared between the main program and external modules, imported using INSTALL or CALL, will remain consistent. You must ensure that all imported modules are embedded, otherwise function and procedure names, and global variables, will not be consistent (unless you use the REM!Keep compiler directive to prevent the names being abbreviated).

Note that it is not intended that this facility should substitute for a proper installer. If you need to do anything more complicated on installation than copying 'resource' files to the destination PC you should consider using an installer utility, for example the free Inno Setup program in Windows.

Test

The Test button tests whether your program will work as an app bundle, without actually creating the bundle file. It is useful in detecting any incompatibilities caused, for example, by the crunch process.

If Deploy as a web application has been selected this will automatically upload your 'compiled' program to a web server and run it using your default browser (this will not work if your default browser is Internet Explorer).

Create Application

The Create Application button creates an application bundle file from your program.

Compiler directives

You may incorporate compiler directives in your BASIC program, using specially formatted REM statements.

The compiler directives must be entered exactly as shown; they are case-sensitive. They may be included anywhere in your program. In the following list square brackets indicate optional parameters:

```
REM!Exefile bundlefile
```
This directive allows you to specify the path and filename for the application bundle, if it is different from the default. If you omit the extension, an appropriate extension will be added for the platform you are using (.exe for Windows, .dmg for MacOS, .zip for Linux). If you specify a .bbb extension, a web bundle will be created for running in a browser. If you specify .zip in Windows, a Zip archive will be created rather than the default standalone executable.
```
REM!Appname application name
```
This directive allows you to specify the application's name.
```
REM!Icon iconfile
```
This directive allows you to specify the path and filename of a PNG file containing the image which should be used as the application's icon.
```
REM!Crunch [spaces][,lines][,rems][,names][,embedded]
```
This directive allows you to specify whether the program will be crunched, and if so which crunch options are used. You can also specify that any embedded .bbc (program or library) files should also be crunched.
```
REM!Embed [file1][, file2...]
```
This directive allows you to specify which files should be embedded in the executable. The files must be specified in the form @dir$+"filename" or @lib$+"filename". You may include more than one REM!Embed line if there are many such files or (in version 1.39a or later only) you may use wildcards. The presence of one or more REM!Embed directives overrides the selection of embedded files by other means, so every file that you need to be embedded must be specified using the directive.
```
REM!Keep var1[, var2, var3...]
```
This directive allows you to specify a list of variable, array or structure names which will not be abbreviated, even when the REM!Crunch names option has been selected. This is useful if you refer to named variables in a DATA statement or using EVAL but you still want to abbreviate the remaining variable names for best performance. Note that such variable names must have at least three characters (excluding the type character, if any) to minimise the risk that they will clash with one of the automatically-generated abbreviated names. You may include more than one REM!Keep line if there are many such variables.
You can also specify that a procedure or function name should not be abbreviated:
```
REM!Keep PROCmyprocedure, FNmyfunction()
```
Note that in this context PROC and FN must be in capital letters, even if you use the Lowercase keywords option.

Apart from REM!Embed and REM!Keep it is not useful to have more than one directive of the same kind; if you do the one that is latest in the program will be used.

Here is an example set of compiler directives:

REM!Exefile /temp/myapp
REM!Appname My Application
REM!Icon /icons/myapp.png
REM!Crunch spaces, lines, rems, names, embedded
REM!Embed @dir$+"images/owl.bmp", @lib$+"ogllib"
REM!Keep header$, footer$

List FNs/PROCs

The List FNs/PROCs command displays a list of all the functions and procedures in your program. Clicking on one of the entries causes the editing pane to scroll to that function or procedure. This list may alternatively be displayed by clicking in the box at the right-hand end of the toolbar.

Include ONs

The Include ONs setting controls whether or not ON CLOSE, ON ERROR, ON MOUSE, ON MOVE, ON TIME and ON SYS statements are included in the list of functions and procedures. In any case they only appear when at the very beginning of a program line.

Include Labels

The Include Labels setting controls whether or not labels are included in the list of functions and procedures.

Sort List

The Sort List setting controls whether or not the list of functions and procedures is sorted alphabetically.

Add-in Utilities

Up to nine add-in (or plug-in) utilities may be available in this menu. The following are installed by default:

crossref.bbc - report variable and function usage, and warn about possible errors.
searchin.bbc - search for a specific string in BASIC (.bbc and .bas) programs.
memmon.bbc - monitor your program's memory usage at run-time.
macrorec.bbc - create function key shortcuts for use when developing programs.
addconst.bbc - scan for undeclared SDL constants and put declarations on the clipboard.

Options menu

The options menu allows you to configure SDLIDE to suit your own preferences. These preferences are saved on exit, and are re-established whenever you run SDLIDE in the future. The options menu can be accessed by clicking on its name in the menu bar or by means of the keyboard shortcut Alt-O.

Syntax Colouring

Clicking on Syntax Colouring toggles this feature on and off. When Syntax Colouring is enabled all the keywords, REMarks, text strings and line numbers in your program are highlighted in colour. You can change the colours by means of the Set Colours command.

When Syntax Colouring is disabled, all the program is listed in black.

Lowercase Keywords

Clicking on Lowercase Keywords toggles on and off the acceptance of BASIC keywords in lower-case letters. When this mode is enabled all keywords are listed in lower-case (both on the screen and on the printer). A keyword will be accepted on input from the keyboard, or from a file, either in all capital letters or in all lower-case letters. A word consisting of a mixture of upper and lower-case letters will never be mistaken for a keyword.

When Lowercase Keywords mode is disabled, keywords are only accepted in all capitals and are listed in capitals. This mode is the default and is compatible with earlier versions of BBC BASIC.

Indentation

Clicking on Indentation toggles on and off the automatic indentation of FOR...NEXT loops, REPEAT...UNTIL loops, WHILE...ENDWHILE loops, CASE...ENDCASE statements and multi-line IF...ELSE...ENDIF clauses. The program blocks are indented by two spaces with respect to the surrounding code. This can make the program structure much clearer, and make it easier to spot mistakes.

Be aware that if you contrive to have (for example) two NEXT statements which match the same FOR statement, or vice versa, the resulting indentation will not be correct. In a well-structured program you would hopefully never do this anyway!

Unicode

Clicking on Unicode alternately enables and disables support for Unicode characters in string constants (i.e. enclosed in double-quotes) and REMarks (comments). When enabled, you can directly enter and edit non-ANSI text within the editor.

Note that Unicode text is encoded as UTF-8 within your program; if you want to display it at run time you will need to use the UTF-8 option provided by the VDU 23,22 command. You may also need to make use of the functions supplied in the utf8lib library.

The editor supports languages written Right-to-Left (e.g. Hebrew) and Complex Script languages (e.g. Arabic), in string constants (i.e. enclosed in double-quotes) and REMarks, but for this to work the version of SDL2_ttf in use must be at least 2.20.0.

Abbreviations

Clicking on Abbreviations alternately enables and disables support for keyword abbreviations on entry, for example P. representing PRINT; the abbreviation is immediately expanded. This feature is initially disabled and should be used with care, because abbreviations can be confused with the syntax for structure members. This is particularly an issue when Lowercase Keywords are enabled.

Set Font

The Set Font command allows you to select the font style and size for use in the editing pane. The command opens the Set Font dialogue box:

Set Font dialogue

The fonts listed are those in the BBC BASIC for SDL 2.0 lib/ folder.

Set Printer Font

The Set Printer Font command is unavailable in SDLIDE and is permanently greyed-out.

Set Colours

The Set Colours command allows you to select the colours which will be used for highlighting the various syntactical elements in your program (keywords, strings, remarks etc.), if the Syntax Colouring option has been enabled. The command opens the Set Colours dialogue box:

Set Colours dialogue

Selecting the appropriate syntactical element causes the current colour for that element to be identified by means of a box around the colour sample. You can change the colour for that element simply by clicking on the appropriate coloured rectangle, and then clicking on OK or Apply (OK closes the dialogue box, whereas Apply leaves it open so that further changes can be made).

Dark Mode

The Dark Mode selection toggles between the normal SDLIDE colour scheme, with dark text on a light background, and an alternative colour scheme with light text on a dark background.

Run menu

The run menu is concerned with running and debugging your BBC BASIC program. 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

The Run command (keyboard shortcut F9) executes the BASIC program currently in memory. It opens a new window where any output from the program appears, and into which you type any keyboard input the program requires. Error messages also appear in this window. If there is no program currently in memory, Run has the same effect as the Immediate command.

Debug

The Debug command executes the BASIC program currently in memory in debug mode; in this mode the line being executed is highlighted in the program editor, and the List Variables window is displayed. Also, the Stop, Pause, Step Into and Step Over commands and buttons are active.

The List Variables window

The List Variables window is automatically displayed in debug mode. In this window are listed the current values of the variables in your program (variables which have not yet been accessed are not displayed, except for the static integer variables which are always listed); the displayed values change as your program runs. You can change the size of and/or scroll the List Variables window.

In the case of arrays and structures, only the name is displayed; the values of the individual elements or members are not. If you need to monitor them, add an appropriate statement or statements to your program to copy the value to a conventional variable.

If you click on a variable name it will be highlighted and the List Variables window will keep that variable in view when it scrolls. To clear the highlight, and restore free scrolling, right-click in the window.

Profile

The Profile command profiles the BASIC program currently loaded into memory; in this mode the line currently being executed is highlighted in the program editor, and the time spent in each line is recorded. When the program terminates a report is displayed showing these times, in milliseconds and as a percentage of the total execution time.

If you want to keep a copy of the profiler report, or print it out, you can find it as the plain text file profiler.rpt in your temporary directory (if you don't know where that is, enter PRINT @tmp$ at the immediate mode command prompt).

Stop

The Stop command stops the program currently running and closes its window. Stop will normally close the program immediately, whatever it is doing, but if your program is waiting for a SYS function to return, or is executing some assembler code, it may not respond.

Note that any ON CLOSE routine in your program will not be executed. It is therefore better to use the normal methods of ending your program (e.g. clicking on the Close button) when possible and to use the Stop command only as a last resort.

If the program is not currently running in debug mode the Stop command is inhibited.

Pause

The Pause command (keyboard shortcut F8) pauses the currently-executing BASIC program at the start of the next statement. If the program is currently waiting for input (e.g. is executing a GET or INPUT statement) it will enter the paused state once the input has been provided. When paused, the program will produce no output nor accept any input (keypresses will still be put in the keyboard buffer).

If the program is not currently running in debug mode the Pause command is inhibited.

Step Into

The Step Into command (keyboard shortcut F7) allows you to single-step a paused program, one statement at a time. You can monitor the execution by noting which statement is highlighted in the editor and/or following the changing values of the program's variables in the List Variables window.

If the program is not currently paused, the Step Into command is inhibited. If you want to single-step through only a specific part of your program, add a breakpoint where you want to start stepping. Alternatively add a TRACE STEP ON statement at that point or use the Run To Cursor command.

Step Over

The Step Over command (keyboard shortcut F5) is similar to the Step Into command except that all the remaining statements in the current line (and the first statement in the next line) are executed before pausing. This is particularly useful in allowing you to 'step over' a procedure or function call without having to single-step through all its statements, or to 'step out' of a loop without having to single-step through every iteration.

If the program never executes a statement in the next line, it will not pause. If the program is not currently paused, the Step Over command is inhibited.

Run To Cursor

The Run To Cursor command (keyboard shortcut F6) behaves the same as the Debug command except that the program automatically pauses (as if the Pause command was issued) when it reaches the line containing the text cursor (caret). This is useful if you need to single-step through part of the program but don't want to start at the beginning.

The first (or only) statement in the line containing the cursor is executed before the program pauses. If the program never executes a statement in the line containing the cursor, it will not pause. Once the program is paused, issuing the Run To Cursor command again (or pressing F6) will cause execution to continue from that point; the program will pause again if there are more statements in the line, or if the line is reentered later.

Note that the program will not pause on any of the following lines:

A blank line.
A REM statement.
A 'star' command.
A CALL filename$ statement.
A GOTO or GOSUB statement.
An IF statement where the condition is false and there is no ELSE clause.

Immediate Mode

The Immediate Mode command opens the output window but does not execute the BASIC program; instead the BASIC command prompt is displayed. At this prompt you can type BASIC statements which are executed immediately on pressing Return (Enter). For example you can use this facility as a calculator by typing PRINT followed by a sum:

>PRINT 2+2

Immediate Mode can also be useful for doing things like deleting a file (*DELETE), or displaying a disk directory (*DIR). When in immediate mode you can execute the current program by typing RUN.

Toggle Breakpoint

The Toggle Breakpoint command (keyboard shortcut Ctrl+B) has the same effect as double-clicking in the left margin (to the left of the editing pane) which alternately adds and removes a breakpoint at the corresponding program statement. When the program is run in debug mode, execution will automatically pause at that statement and enter single-step mode.

You cannot dynamically add or remove breakpoints while the program is running, any changes willl take effect only when you run the program again.

Clear Breakpoints

The Clear Breakpoints command (keyboard shortcut F4) clears any breakpoints currently set.

Help menu

The help menu gives access to the BBC BASIC for SDL 2.0 documentation, provides links to information via email or from the web, and displays version information. 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 opens the BBC BASIC for SDL 2.0 Help documentation in your default browser, an internet connection is necessary. This command can also be accessed by pressing F1.

Tutorial

The Tutorial command opens the beginners' tutorial in your default browser, an internet connection is necessary.

Email

The Email command calls up your default mail program (if any) so that you can send a message to request help or information about BBC BASIC.

Website

The Website command opens the BBC BASIC home page in your default browser.

Discussion Group

The Discussion Group command takes you to the online discussion group, where you can seek help and advice, report bugs, download (or upload) useful utilities and learn about new developments in BBC BASIC for Windows and BBC BASIC for SDL 2.0.

Forum

The Forum command takes you to the BBC BASIC forum, where you can discuss with other users all aspects of programming in BBC BASIC for Windows and BBC BASIC for SDL 2.0.

Wiki

The Wiki command takes you to the BBC BASIC Programmers' Reference Wiki. This is an ever-growing resource of articles on all aspects of programming in BBC BASIC for Windows and BBC BASIC for SDL 2.0.

About BBC BASIC

The About command displays the version number of SDLIDE.

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. Most of the normal features which you expect from a 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. References to 'left' and 'right' may be reversed if you are editing RTL text such as Arabic or Hebrew:

Key Operation

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. The insert/overtype status is indicated in the status bar.

Delete If any text is selected (highlighted) it is deleted, without being copied to the clipboard. Otherwise, the character to the immediate right of the cursor (caret) is deleted and the rest of the line is moved 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.

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. If the cursor is already at the beginning of a line, the key has no effect.

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.

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.

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+ 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+ 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 Normally has no effect, but can be programmed to execute a macro. See the macrorec.bbc add-in utility supplied.

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.

Key	Operation
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. The insert/overtype status is indicated in the status bar.
Delete	If any text is selected (highlighted) it is deleted, without being copied to the clipboard. Otherwise, the character to the immediate right of the cursor (caret) is deleted and the rest of the line is moved 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.
	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. If the cursor is already at the beginning of a line, the key has no effect.
	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.
	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.
	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+	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+	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	Normally has no effect, but can be programmed to execute a macro. See the macrorec.bbc add-in utility supplied.
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 is then moved right by one position. If anything is selected (highlighted) when the key is pressed, it is first deleted.

Mouse commands

The following operations are available using the mouse:

Action Operation

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 to be selected; if the same word is present elsewhere in the program it is highlighted with a light blue background. The text cursor (caret) is moved to the end of the selected region. The selected word can then be cut, copied or deleted. If the Find or Replace command is issued, the selected word is copied to the Find What field.

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. Dragging the mouse horizontally selects part or all of a line; dragging the mouse vertically selects a block of lines (only entire lines may 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 one line per 'notch'.

Action	Operation
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 to be selected; if the same word is present elsewhere in the program it is highlighted with a light blue background. The text cursor (caret) is moved to the end of the selected region. The selected word can then be cut, copied or deleted. If the Find or Replace command is issued, the selected word is copied to the Find What field.
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. Dragging the mouse horizontally selects part or all of a line; dragging the mouse vertically selects a block of lines (only entire lines may 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 one line per 'notch'.

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. The context menu contains one or more of the following items:

If any part of the program is selected, the context menu contains the Cut, Copy and Add REMs commands. Clicking on Cut or Copy has an identical effect to that obtained by selecting the command from the edit menu, clicking on the appropriate button on the toolbar or using the associated keyboard shortcut (Ctrl+X and Ctrl+C respectively).
Clicking on Add REMs automatically adds a REM to the start of each line in the selected block. If every line already starts with a REM, the context menu contains the Remove REMs command.
If there is any text on the clipboard, the context menu contains the Paste command. Clicking on this command has an identical effect to that obtained by selecting the command from the edit menu, clicking on the appropriate button on the toolbar or using the associated keyboard shortcut (Ctrl+V).
If a 'jump' to a function or procedure (see below) was previously made, the context menu contains the "Go back" item. Clicking on this item scrolls the display to the position it had before the last jump was made.
If you right-clicked on a PROC or FN the procedure or function name is included in the menu. Selecting this item causes the display to 'jump' (scroll) directly to that procedure or function.

If you have a touch screen you can display the context menu by pressing-and-holding until the square or circle appears. You can also access it by pressing F10.

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:

Dragging the scroll box (thumb) along the bar causes the display to scroll accordingly. The size of the scroll box indicates the proportion of the entire program which is displayed within the editing pane - the larger the scroll box the more of the program which is visible.
Clicking on one of the arrow buttons causes the display to scroll in units of one character (horizontally) or one line (vertically).
Clicking in the shaded regions between the scroll box and the arrow buttons causes the display to scroll by one page (less one line) vertically, or by eight characters horizontally.
If your mouse has a 'wheel', rotating the wheel causes the display to scroll vertically, usually by one line per 'notch'.
If you have a touch screen, you can scroll by dragging with two-fingers.

High DPI scaling

SDLIDE is designed to work optimally with High DPI scaling provided by the Operating System, which is the default in Windows and MacOS, but must be explicitly enabled in Linux. However if you prefer to use it at your display's native resolution that can be achieved by editing the sdlide.ini file. This file can be found in the @usr$ directory, usually at %appdata%\bbcbasic\sdlide.ini in Windows or at ~/.local/share/bbcbasic/sdlide.ini in Linux.

These are the settings that you will most likely want to modify (they may not be consecutive in the file); do not edit the file while SDLIDE is open, since your changes will be overwritten when it is closed:

windowwidth=960
windowheight=600
editfont="..../lib/DejaVuSansMono",12
guifont="..../lib/DejaVuSans",12
guiscale=2

Change the sizes approximately in proportion to how your resolution compares with the standard 96 dpi. For example if your display resolution is around 192 dpi change the font sizes from 12 to 24 and the guiscale from 2 to 4. You may need to experiment for optimum results.

Please note that whilst these changes will scale the SDLIDE window they will not affect the immediate mode output window nor the output from your BBC BASIC programs. You will need to write your programs to work acceptably over the range of DPI values that they may encounter in use. The @zoom% system variable may be particularly useful for this.

CONTENTS

CONTINUE