Incorporating+bookmarks+in+a+program

//by Richard Russell and Michael Hutton, July 2009//

The right-click [|context menu] in the //BBC BASIC for Windows// IDE allows you to navigate around your program quickly and easily, by providing a means to 'jump' to the beginning of a specified function or procedure with just a couple of mouse clicks. However there may be circumstances when you would like to jump not to the beginning of a **PROC** or **FN**, but to some other significant point in your code.

You can do that by inserting a **bookmark** in your code at the appropriate point, which will also appear in the context menu. Just as with **PROC**s and **FN**s (and other context menu items such as **ON CLOSE** or **ON ERROR**) clicking on the name of the bookmark will take you there. If you want to return to where you were before, the **Go back** menu item does that.

Another use for bookmarks is to act as **separators** in the context menu. For example you might want to organise your procedures and functions into groups of related routines, in order to make the program structure clearer.

Bookmarks inserted 'inline' within your code will be ignored when the program is executed, although they may slow it down //very slightly//. Bookmarks used as separators between blocks of FNs or PROCs should have no significant impact, other than making your program a little bigger than it would otherwise be.

There are two ways in which you can insert bookmarks into your program:

Bookmarks using DEF
Normally you use **DEF** with the keywords **PROC** (to define a procedure) or **FN** (to define a function). However, if you include a line in your program which begins with **DEF** but is //not// followed by **PROC** or **FN** that line will act as a bookmark. For example:

code format="bb4w" DEF _this_is_important_ REM important code starts here... code The name of the bookmark must follow normal procedure and function naming conventions, that is it must consist only of alphabetic characters (**A-Z**, **a-z**), digits (**0-9**) or the characters **_** (underscore), **@** (commercial-at) and **`** (backwards quote or grave accent).

If you incorporate a space character in the bookmark the context menu will show only what precedes it, for example:

code format="bb4w" DEF take me here code will result in **take** appearing in the menu.

Bookmarks using labels
You can incorporate [|labels] in your program, which are primarily intended to be used as the targets for **GOTO**, **GOSUB** or **RESTORE** statements (although their use is deprecated). However you can also use labels as bookmarks, for example:

code format="bb4w" (_this_is_important_) REM important code starts here... code The same naming restrictions apply as with the previous method, and again if you incorporate a space character the context menu will show only what precedes it (in this case **take**):

code format="bb4w" (take me here) code Using labels as bookmarks does have one minor disadvantage in that if you also use 'genuine' labels in your program (which hopefully you won't!) the bookmarks will use up some space on the heap, and could corrupt the value of a normal variable that happens to have the same name as the bookmark. A similar thing can happen if your program deliberately generates a **No such variable** error which is trapped, therefore allowing execution to continue.

However these are unlikely circumstances and in most respects there is little to choose between the two methods of incorporating bookmarks.