Chapter 3 The Editor Introduction HiSOFT Basic 2 is a complete package which allows you to create, edit and debug Basic programs on your Amiga¨ computer, either from a friendly integrated environment based on the editor or from the CLI or Shell. This chapter looks at using the editor that is supplied as the heart of HiSOFT Basic 2 and aims to give you a introduction to most aspects of the package - it does not detail the compiler, debugger or other tools, nor the technical aspects of the compilation process; these are covered in later chapters. The Editor The editor supplied with HiSOFT Basic 2 is fully integrated with the system which means that you can develop programs in an intuitive and interactive manner, creating and editing your programs in the same environment as running and debugging your finished masterpiece. Moreover, those of you with strong preferences for your own editor can dispense with the HiSOFT editor and use your own favourite package along with the stand-alone version of HiSOFT Basic 2, although you will lose the benefits of interactive development. The editor for HiSOFT Basic 2 is a multi-window screen editor which allows you to enter and edit text and save and load from disk. It also lets you print some or all of your text, search and replace text patterns and set bookmarks throughout the text so that you can find key points in your program quickly. In addition, you can define and use macros. The editor is Intuition-based, which means it uses all the user-friendly features of Amiga¨ programs that you have become familiar with such as windows, menus and mice. However, if you're a die-hard used to the hostile world of computers before the advent of WIMPs, you'll be pleased to know you can do practically everything you'll want to do from the keyboard without having to touch a mouse. The editor is also 'RAM-based'; the file you are editing stays in memory for the whole time, so you don't have to wait while your disk grinds away loading different sections of the file as you edit. As all editing operations, including things like searching, are RAM-based they act extremely quickly. The file size is only limited by the amount of memory in your computer. Once you have typed in your programs it is not much use if you are unable to save them to disk, so the editor has a comprehensive range of save and load options, allowing you to save all or part of the text and to load other files into the middle of the current one, for example. To get things to happen in the editor, there are various methods available to you. Features may be accessed in one or more of the following ways: * Using a single key, such as a Function or cursor key; * Clicking on a menu item, such as Save; * Using a menu shortcut, by pressing the right A key in conjunction with another, such as AF for Find; * Using the Control key (subsequently referred to as Ctrl) or Alternate key (called Alt from now on) in conjunction with another, such as Alt-¬ for cursor word left; * Clicking on the screen, such as in a scroll bar. The menu shortcuts have been chosen to be, hopefully, easy to remember and to be compatible with many other Amiga¨ programs. Two versions of the HiSOFT Basic 2 editor are supplied. One is specifically designed to take advantage of Release 2 of the operating system and its many new features. This version also uses the new features of Workbench 3 where available. In the later sections of this manual the features that are available under Workbench 2 are also available under Workbench 3.0 and above. There is also a 1.3 version which gives you the same look and feel on an Amiga¨ running earlier versions of the operating system. The installation process will install the appropriate version for your machine. Starting the Editor From the Workbench simply double-click on the HBasic2 icon to load it and display an empty window. If you have selected other icons as well as the editor icon (by Shift-clicking), these files will be opened as projects for editing when you run the editor. To run the editor from the CLI, type its name (HBasic2) followed by an optional list of file pathnames - a file extension of .bas will be appended to filenames where necessary. To find its startup settings, the editor searches for a file called HBasic.prefs, firstly in the current directory then in the editor's directory and finally in ENV:HBASIC - if it cannot find this file it will use its built-in defaults. You may override this search from the Workbench by adding a SETTINGS= tooltype to a project icon or to the HBasic2 icon. Default icons may be provided by placing them in the ENV:HBASIC directory. An icon named def_bas will be used as the default for all files ending in .bas - if no such icon is found for a particular file type the def_project icon will be used instead. We will return to a full description of projects, windows etc. after some general information about HiSOFT Basic 2's use of gadgets and the like. Requesters and gadgets The editor makes extensive use of requesters which employ the Workbench 2 user interface (even if you are running under AmigaDOS 1.3) so it is worth recalling how to use these requesters and their associated gadgets. Note that most HiSOFT Basic 2 requesters do not restrict you from further editing. If you require more detail than is given below, you should look in the Amiga User Interface Style Guide or the Using the System Software user guide supplied with your Amiga¨. Keyboard shortcuts Before we describe the different types of gadgets available, we should mention that most of them can be accessed either using the mouse or the keyboard. Keyboard shortcuts may be used whenever a text gadget is not active and the key that addresses the gadget is shown underlined in the descriptive text next to the particular gadget. For example, in the Find requester shown below, you can use N or n to find the next occurrence of the defined string or C (or c) to cancel the operation. As we have said, the editor's requesters contain various gadgets of differing types and we shall now describe them. Action gadgets or buttons Action gadgets are boxes containing a description of the action that will take place should you left-click on the box or button. action gadgets or buttons To activate the action displayed by the button, point at it and left-click - the action will be triggered when you let go of the mouse button; this allows you to move off the gadget while still keeping the mouse button depressed if you change your mind. Sometimes, clicking on a button will cause another requester or window to be displayed. If this is the case, the action gadget's text will end in an ellipsis (three periods): the Set... buttons lead to a file requester The Cancel button will always be positioned at the bottom right of the requester with a keyboard shortcut of C and will abort the requester, leaving everything as it was before the requester was activated. Check box gadgets A check box is a small square that is either empty or contains a check mark or tick. This type of gadget allows you to turn some action on (checked) or off (blank) - simply click on it, with the left mouse button, to change its state. check box gadgets with keyboard shortcuts Cycle gadgets Cycle gadgets allow you to choose one option from a list of several related items. To change to another option you must left-click anywhere in the gadget which will cycle forward through the list. If you hold the Shift key down while left-clicking, the list will cycle backwards. Here's an example: cycle gadgets allow selection from a list As usual, you can use any keyboard shortcut instead of the mouse - again use Shift and the shortcut to go backwards through the list. When you reach the end of the list, it will wrap round to the first item. Text gadgets Text gadgets allow you to enter strings of characters or numeric values. text gadgets To type into a text gadget you must activate it to obtain a cursor. Simply left-click inside the text gadget or press its keyboard shortcut to activate the gadget. Some commonly used requesters automatically activate a text gadget so that you can type directly into it as soon as the requester pops up. As you are entering text, certain keys allow editing of the string: ¬, ® move the cursor left or right through the text Shift-¬, Shift-® move the cursor to the start of the line or to the end of the line Backspace delete the character behind the cursor Shift-Backspace,Shift-Del (release 2 only) delete from the cursor to the start or end of line. Del delete the character under the cursor AX delete the entire line AQ restore the text to its former state Tab, Shift-Tab (release 2 only) activate the next or previous text gadget Return exit the text gadget key commands available within text gadgets To exit a text gadget simply press Return or left-click somewhere else in the requester. File requesters Whenever a file or directory name is needed, the HiSOFT Basic 2 editor will produce a File Requester which allows you to locate the desired object and select it. The Workbench 2 version uses the standard ASL file requester whilst the 1.3 version utilises the ARP requester. The operation of each File Requester is similar and straightforward. However, a brief summary is given below. the ASL file requester The requester title bar shows the type of object which you are required to select and the operation that will be performed on it. Save requesters appear in a different colour. By using the scroll gadgets you may move about the list of files and directories; clicking on a name will enter it into the appropriate text gadget. You may also choose to type into these gadgets to select a known file quickly. The four action gadgets at the base of the requester allow you to proceed with the operation (this button will be labelled accordingly), show all available volume names and AmigaDOS assignments, move into the parent of the current drawer and cancel the operation (the window close gadget is also available for this purpose). Double-clicking over a name will both select the file and proceed, which normally passes the filename back to the calling program. If the object you select does not exist or is of the wrong type you will be given a chance to reselect. Any errors are reported in another requester. The ASL file requester also has the added benefit of a sizing gadget (the requester size and position will be remembered when you Save Settings) and a pull down menu containing useful Amiga¨ key shortcuts. When you are saving a file, typing a drawer name which does not exist gives you the chance to create that drawer. the simple File Requester There is also a simple file requester which will appear in a number of situations. Firstly, if the editor is unable to open the ARP or ASL library (according to the version) from your LIBS: drawer, the simple requester will be used instead. It will also be used if there is insufficient free memory to open the full file requester. Note that, in extreme low memory situations, it may not be possible to open a requester at all, in which case you may need to close some unmodified projects or quit any other applications which are running. Confirmation requesters One other type of requester which you will see appears when it is necessary for you to make a choice before proceeding. Perhaps the most common occurrence of this is the modified project requester: This is produced if you select some action which would lose any changes made to a project. By clicking on the gadgets or pressing the first letter of their titles you can choose to save the project, to abandon the changes and go ahead with the action or to back out, leaving everything as it was before you selected the action. Another way of choosing an action is to hold down the left-Amiga key and press either V for the leftmost button or B for the rightmost button which is always Cancel. Remember that the continue action is placed at the left and Cancel at the right. The middle button often causes an action which would lose or overwrite some data. Note that, unlike most HiSOFT Basic 2 requesters, these will block any further input to the editor until you have chosen an action. Menus and sub-menus Menus allow you to use editor commands quickly and easily while giving you the opportunity to browse through the various choices. To access the HiSOFT Basic 2 menus simply press the right mouse button and hold it down. a typical HiSOFT Basic 2 menu To select from the menu, still holding the right button down, move the pointer over one of the menu titles which appear at the top of the screen. Once the menu pops up, drag the selection bar to the required choice and let go of the mouse button. Many menu commands have keyboard shortcuts accessed by holding the right-Amiga key down and pressing the relevant command key as shown on the menu. Some commands have keyboard shortcuts in conjunction with the Ctrl key; these are shown under Workbench 1 and Workbench 3 but not Workbench 2. To select a sequence of menu items while still viewing the menu, keep your finger on the right mouse button and click on the left mouse button when you are over the relevant choice - you will then still be able to move up and down the menu and perhaps select another item. Some options are accessed via Ôsub-menus' which are shown by the È symbol to the right of the menu item; for example, if you move the mouse over the Window Layout selection on the Window menu, a sub-menu like this will appear: A sub-menu You can then move the mouse to the right to select the particular item that you want. To cancel the operation just let go of the mouse without selecting a sub-item or move to another item on the main menu. Some menu items can have a Ôtick' or check mark next to them. Selecting such an item will select or de-select that choice. Once again you may use left-clicking to select a number of these options. The Window Layout sub-menu uses such items to give you a choice between the various layout styles. If a menu item leads to a requester containing further choices, the text of the menu item will be followed by an ellipsis (three dots) as shown below: Print As... leads to a requester The Editor's windows Having loaded HiSOFT Basic 2, you will be presented with an empty window and a graphic block, which is the cursor, in the top left-hand corner. The window used by the editor is a standard Intuition window, so you can move it around by using the Title bar on the top of it, you can change its size by dragging on the Sizing gadget, close it with the Close gadget, bring it to the front or send it to the back with the Depth gadget(s) and make it full size (and back again) by clicking on the Zoom gadget (Workbench 2 and above only). You can also move the view on the text by using the Scroll gadgets. the HiSOFT Basic 2 window under Workbench 2 Windows and Projects We make the distinction between windows and projects: a project is a file with any number of windows open on it. You can also edit many different projects at any one time, each of which may have many windows. To start a new project select New from the Project menu or type AN - this will give you an empty, untitled window. To open an existing project from disk you should use the Open command (AO) on the Project menu which will bring up a file requester allowing you to select a file to edit. The Load command (AL) will replace the project that you are current editing with the project that you select from the file requester. the Project menu Once you have selected a file to edit you can open another window on that file by using AW (New Window on the Window menu); subsequently close a window by left-clicking on its close gadget, selecting the Close item from the Window menu or by typing AK. When you have closed all the windows of a project, the project will be freed from memory. Closing the last project will exit the editor. The other selections on the Project menu will be discussed below under the appropriate heading. Switching Windows The editor has support for any number of windows, memory permitting, you can even have many windows (views) open on one file. Once you have some windows open, you can move between them in a variety of ways: Firstly, you can select a window (if you can see it) by clicking on it with the mouse but this will not bring it to the front - you must use the window depth gadgets or Shift-A> to achieve that. Under AmigaDOS 1.3 there are two window depth gadgets; one of these sends a window to the back and the other brings it to the front. We have implemented two keyboard shortcuts for these actions - A> (Shift-A.) for bring to front and A< (Shift-A,) for send to back. With AmigaDOS 2 there is only one depth gadget which you can Shift-click to send the window to the back. These commands leave the window upon which the action was performed selected, so that, if you send a window to the back revealing another window, this new window will not be selected (and therefore you will not be able to type into it) until you click on it. A useful action is to cycle through all the available editor windows using Activate Next and Activate Previous commands from the Window menu (the keyboard shortcuts are A. and A, respectively); these commands bring the relevant window to the front and select it, ready for use. The windows can be organised in a number of ways and you can select this using Window Layout on the Window menu. the Window Layout sub-menu First of all, choose which layout you would like; Stacked re-sizes the windows to the same width and arranges them so that you can see the title bar of each window (depending on which window is at the front). Horizontal organises the windows one above the other and re-sizes them so that you can see the whole width of every window - this is most useful for a small number of windows. Vertical is like Horizontal except that the windows are arranged side by side. Full Size means that each window is made the size of whole screen and placed one behind the other. Having chosen the desired arrangement (this will not actually change any windows) you can then Arrange All windows that are open or only Arrange Project - this means only arrange the windows associated with the current project. Try this out for yourself to get the idea of how the different arrangements work. The sub-menu works best if you left-click over a layout style then release the right mouse button over one of the Arrange items. Entering text and moving the cursor To enter text, simply type on the keyboard and at the end of each line press the Return key (or the Enter key on the numeric pad) to start the next line. You can correct your mistakes by pressing the Backspace key, which deletes the character to the left of the cursor, or the Delete key, which removes the character under the cursor. Undo Line The HiSOFT Basic 2 editor keeps a copy of the line that you are working on so that as long as you have not moved off the current line, you can undo the changes you have made and recover the line as it was before you started editing it. To restore the original line select Undo Line from the Edit menu or press AZ. Remember, this will always work as long as the cursor is still within the line that you wish to recover. Cursor keys and the mouse You use the cursor keys, together with various keyboard modifiers, to move quickly around the file without needing to touch the mouse. The modifiers used are Shift, Ctrl and Alt and their use conforms to the guidelines given in the Amiga User Interface Style Guide which are as follows: Using the cursor keys by themselves will move the text cursor around the file by a character (¬ ® ) or a line (­ ¯) at a time, scrolling the display where necessary. Holding the Shift key down while using the cursor keys will move to the edge of the window (i.e., the top/bottom/left/right) or show a new windowful of text if the cursor is already at the extreme of the window. Shift¬ or Shift® have the effect of moving to the beginning or end of the current line. Shift also modifies the Backspace and Del keys in a similar way. Using the Ctrl key with the cursor keys moves to the appropriate extreme of the project i.e. the beginning or end of line (Ctrl¬ or Ctrl®) and the top or bottom of the file (Ctrl­ and Ctrl¯). Finally the Alt modifier works on words so that Alt¬ or Alt® move the cursor a word left and a word right respectively whilst Alt­ and Alt¯ move on a paragraph basis. A paragraph is defined as a line that is preceded by a line with no characters other than white space. When used with Backspace or Del, Alt has the effect of deleting a word at a time. The function of the Shift and Alt modifiers can be swapped (see Settings); this maintains some compatibility with previous HiSOFT editors. It is also possible to set up the numeric keypad to act like an IBM PC keypad so that you can perform many cursor operations using its keys - see the Settings section for details. You can use the mouse to move the cursor to a specific position on the screen by pointing and clicking. As usual, you can use the slider gadget to scroll through the file, in which case the cursor will move with the text. You can scroll the window up and down on a line basis by clicking on the vertical scroll gadgets. If you position the cursor past the right-hand end of the line and type some text at that point the editor will automatically add the text to the real end of the line. If you type in long lines the window display will scroll sideways if required. All the above commands along with the other keyboard shortcuts are summarised at the end of this chapter. Goto Change This command on the Search menu will move the cursor to the last line you changed; it is useful if you have moved the cursor a long way (may be to look at another piece of code) and want to return to the part that you are writing. The keyboard shortcut for Goto Change is AJ. Match Bracket If the cursor is on a ) character the Match Bracket (A[)command moves the cursor backwards to the corresponding ( character that matches it. If it is on a ( character it will move the cursor forward to the corresponding ) character. This is great for checking that your brackets are correct in complex expressions. The pairs [], {} and <> also match, so that you can use this command with other programming languages (or even ordinary text). Tab key The Tab key inserts a special character (ASCII code 9) into the text, which on the screen looks like a number of spaces, but is rather different. Pressing Tab aligns the cursor onto the next Ômultiple of 8' column (by default), so if you press it at the start of a line (column 1) the cursor moves to the next multiple of 8, +1, which is column 9. Tabs are very useful indeed for making items line up vertically and their main use in HiSOFT Basic is for such things as indenting structured program lines. When you delete a tab the line closes up as if a number of spaces had been removed. The advantage of tabs is that they take up only 1 byte of memory, but can show on screen as many more. You can also use the Indent and Outdent commands from the Utility sub-menu to add and remove tabs from the start of a number of lines. You can change the tab size for each individual file - see Settings for details. Return key In addition to entering a line of text, the return key can be used to insert a blank line into the text by pressing Ctrl-Return. When Return is pressed in the centre of a line, the line will be split into two. Ctrl-- (hyphen) can also be used to split a line at the cursor position whilst Ctrl-= will join the next line to the end of the current one. Bookmarks A further way to navigate your text is through the use of bookmarks. A bookmark is set by selecting the appropriate item on the Set Bookmark sub-menu from the Search menu or by using Shift and one of the function keys on the top row of the keyboard (e.g. Shift-F4 sets bookmark 4). Having set a bookmark in you are then able to select the corresponding item on the Goto Bookmark sub-menu to return the cursor to the line on which you set the bookmark; or use the appropriate function key by itself. The Bookmark submenus A possible total of 10 bookmarks are allowed per project which are saved along with the project only if Create Icons? is selected. Bookmarks can't be stored in the main project file because they are pure ASCII files. Bookmarks are lost if the line they are on is deleted. You can sort the Bookmarks within a file so that bookmark 1 is first, bookmark 2 second etc. by using the Sort Bookmarks command. Deleting text Backspace key The Backspace key (to the left of the Del key) removes text to the left of the cursor. When pressed on its own it will delete a single character but when used in conjunction with the Alt or Shift modifier keys, it will delete the previous word or to the start of the line. If you find that you often delete whole lines by mistake because your finger is still on the Shift key you can disable this via the Shift-Backspace item in the Settings requester. If you backspace off the very beginning of a line this will normally remove the Ôinvisible' return character and join the line to the end of the previous line (although you can change this behaviour using the End of Line item in the Settings requester). Backspacing when the cursor is past the end of the line will move the cursor to the end of the line without deleting a character. Del key The Del key removes text to the right of the cursor. In a similar manner to Backspace, just pressing Del will delete the character under the cursor whilst using the modifiers Alt and Shift with Del will delete by word or to the end of the line respectively. Del will join lines together if used at the end of a line, unless you have changed this behaviour using Set Settings.... Using Del when the cursor is past the end of the line will simply move the cursor to the end of the line. Delete line The current line can be deleted from the text by pressing ABackspace, Ctrl-Backspace or Ctrl-Y. The deleted line is remembered and may be later inserted back into the text. Undelete Line When a line is deleted using the above command it is preserved in an internal buffer, and can be re-inserted into the text by selecting Undelete Line from the Edit menu or pressing Ctrl-U. This can be done as many times as required which is particularly useful for repeating similar lines or swapping individual lines over. Delete block A marked block may be deleted from the text by pressing ADel or Ctrl-Del. These are equivalent to Erase on the Edit menu. The following table summarises the behaviour of Backspace and Del when used with various modifier keys: Alt Shift Ctrl or Amiga Backspace delete previous word delete to start of line delete line (also Ctrl-Y) Del delete next word delete to end of line delete block Remember that the current line is buffered, so you can undo all changes made to the line by using AZ Undo Line. Block Commands A block is a marked section of text which may be copied to another section, deleted, printed or saved onto disk. The editor will report Block required if a marked block is needed. Blocks may be marked using the mouse or with the keyboard. Marking a block The simplest way to mark a block is to left-click on the first character in the block and drag the mouse to the end of the block. The block is highlighted by showing the text in reverse as you drag the mouse. When you move the mouse past the edge of the window, the window will automatically scroll to allow blocks larger than the window size to be marked. You may mark a block by clicking at the end and dragging back if you wish. Double-clicking will cause the word under the mouse to be marked as the block. If you double-click and then drag, text will be highlighted a word at a time. Triple-clicking marks the line under the mouse. Triple-clicking and then dragging will highlight the block and then mark it a line at a time. A second way of marking a block is to place the cursor at one end of the block, either with the movement keys or by pointing and clicking. Then, holding down the Shift key, click at the other end of the block. This technique is often useful for marking a very large block as it can be used to extend an existing block. The start of a block may also be marked by moving the cursor to the either end of the block and pressing AB; then as you move the cursor with the keyboard the block will be highlighted. You can start marking the block either at the beginning or the end. You can also use the Mark Block item from the Edit menu to start marking the block. Shift-AB will mark the whole of the current line - subsequent cursor movements will highlight a line at a time. To unmark any selected block, press Esc. The Clipboard: Cut, Copy & Paste HiSOFT Basic 2 supports the Amiga¨ clipboard, allowing you to not only cut and paste text within HiSOFT Basic 2, but to share data between many different applications. The clipboard holds the most recently cut or copied block of text ready for subsequent pasting to another location. Once you have marked a block you may copy it into the clipboard using Copy from the Edit menu. The text will remain in the file and the copy of the text held in the clipboard may then be inserted at another position by moving the cursor there and selecting Paste. cut, copy and paste The current block may be removed and place in the clipboard using Cut from the Edit menu; selecting Paste will then insert the block that was cut as before. To move a block of text involves marking the text, selecting Cut, moving to a new position and then Paste. Cut block A marked block may be deleted from the text by selecting Cut on the Edit menu. A deleted block is remembered in the clipboard for later use. Copy block The current marked block may be copied to the clipboard using Copy on the Edit menu or by pressing AC. The block is automatically unmarked to show that it has been copied into the clipboard successfully. This command can be very useful for moving blocks of text between different files by loading the first, marking a block, copying it to the clipboard then switching to another window or loading the other file and pasting the clipboard into it. Paste block The contents of the clipboard may be pasted at the cursor position by selecting Paste from the Edit menu or by pressing AV. If the clipboard is empty or contains information other than text, the message No text in clipboard will be reported. If the editor is unable to access the clipboard, a Clipboard error is given. Delete block If you wish to delete a block without placing it in the clipboard, choose Erase on the Edit menu or press ADel or Ctrl-Del. There is no way of retrieving text which is deleted in this way. Save block Once a block has been marked, it can be saved to disk by selecting Save Block... from the Edit menu. Assuming a valid block has been marked, a file requester will appear, allowing you to select a suitable drive, drawer and filename in which to save the block. You will be warned if you specify a filename which already exists in which case a backup will be made if requested in Settings. The keyboard shortcut for this command is Shift-AA. To insert any previously saved file at the cursor position you may select Insert File on the Edit menu. Printing a block A marked block may be sent to the printer or a file by selecting Print As... on the Project menu. A requester will appear and you should choose Selected Block, the number of copies and the output name. See the Printing section for more detail on the use of this requester. Searching The Search menu The commands on the Search menu may be used for finding and perhaps replacing existing text. This is done by first selecting Find... (AF) or Find & Replace... (AR) to specify the search and replace text and then using either the requester or the Find Next, Find Previous and Replace commands. The Find requester is a subset of the Find and Replace requester described below with facilities for searching only. the Find & Replace requester In the example above myscr has been entered as the find text and myscreen as the text to replace it with. If you click on Cancel, the requester will disappear, taking no action and restoring the previous find and replace text. If you click Find Next (or press Return) the search will start forwards, while clicking on Previous will start the search backwards. If you click on OK the requester will appear keeping the strings you have chosen. If the search is successful, the window will be re-drawn with the cursor positioned at the start of the string. If the string could not be found, the message Not found will appear in the window title bar and the cursor will remain unmoved. You may continue the search with Find Next and Find Previous or by activating an editor window and selecting Find Next or Find Previous from the Search menu. The keyboard shortcuts for these commands are Ctrl-N and Ctrl-P. Note that you do not have to close the requester in order to continue editing although this can be done via the close gadget or by pressing Esc. Whether test is treated as the same as TEST or Test etc. depends on whether the Case Sensitive check box is selected. Normally, searching is case insensitive, meaning that upper and lower case letters are treated the same. However, with Case Sensitive, an exact match for the find text must be found before searching will stop. Optionally, you may search for Whole Words by selecting the second check box. This will prevent a search for the word in, for example, matching the word finish. It will still find the word in first-in-first-out however because the hyphen has been used to separate the words. If you have a block of text selected when you invoke the Find or Find & Replace commands the block of text will be used as the find string. This means you can double-click on a word, type AF and then Return and the editor will find the next occurrence of this word. Note however that if the word is followed by one or more spaces these will be included when you double click on a word so you may need to press backspace before pressing Return. Replacing text Having found an occurrence of the find text, it can be changed to the replace text by clicking on the Replace button. This is identical to selecting Replace from the Find sub-menu or pressing CtrlR whilst editing. Having replaced it, the editor will then search for further occurrences. You may of course replace several occurrences of the text by selecting Replace several times in succession however, if you wish to replace every occurrence of the find string with the replace string starting from the cursor position, click on the Replace All gadget. This may take some time if there are a large number of occurrences. You may search and replace Tab characters, line feed characters or any other control characters in a similar way by simply entering them in the appropriate text gadget. This facility can be used to search for something at the beginning or end of a line by including a line feed character (CtrlJ) at the start or end of the find text. Note that Workbench 2 users of Workbench 2 and above will have to hold down the left Amiga key while typing these or other control characters. Go to line To move the cursor to a specific line in the text, select Go to Line... from the Search menu, or press AG. A small requester will appear, allowing you to enter the line number and press Return. The cursor will move to the specified line, centring the window over it. If the line does not exist, you will be positioned over the start or end of file. Pressing Return with no line number or clicking the close gadget will abort the operation. Another fast way of moving around the file is by dragging the window scroll bar, which works in the usual fashion. The Last Change and Match Brackets commands are described in the Entering text and moving the cursor section above. Bookmarks The Go to Bookmark sub-menu may be used to move to one of the project's 10 bookmarks previously set up via the Set Bookmark commands. Further details can be found in the Bookmarks section. Disk Operations The Project menu contains many operations that involve disk files; you can save and load your source file, save any modified files, revert to the last saved version of your program, print your text and more. New Select New to open an untitled project and window ready for entering text. The number of projects is limited by available memory only. Opening files To load in a text file, select Open... from the Project menu, or press AO. A file requester will appear, allowing you to specify the volume, drawer and filename. Assuming you do not Cancel, the editor will attempt to load the file and open a new window if the current one is in use. The Load... command will load a file into an existing window; if you have changed the previous file you will be prompted with a requester like this: so you can save the modified project or discard the changes as you wish. If an error occurs, a requester appears showing the error and filename, giving you a chance to Retry or Cancel as with all file operations. Some less common errors are reported as AmigaDOS error numbers as documented in your system manual. A number of files may be opened automatically when HiSOFT Basic 2 is started by selecting project icons from the Workbench and Shift-double-clicking the editor icon, or by specifying a number of filenames on the command line. Under Workbench 2, you can also load files by dragging their icon to an open HiSOFT BASIC 2 window; this will replace the existing file. Save To save the text you are editing, select Save from the Project menu or press AS. If the file was loaded from disk, it will be backed up (if requested in Settings) and the new version is written to disk. Untitled projects will produce a file requester, allowing you to select a name for the project like Save As.... If Create Icons? on the Settings menu is selected, the editor will attempt to generate a suitable Workbench icon for the file. HiSOFT Basic 2 also saves the current tab size and positions of any bookmarks for the project in its icon. This information can only be saved to disk (and subsequently re-loaded) when Create Icons? is enabled. Save As... Save As... on the Project menu or AA allows you to save a project in a different place or under a new name. It will be selected automatically if you save an untitled project. The file requester will appear, giving the name and drawer where the file is currently located (if any). You may select the drawer and filename in the normal way. Clicking Save or pressing Return will then save the file onto disk. If you click on Cancel the text will not be saved. If the filename you select already exists, a requester will appear asking you if you wish to overwrite this file, select a new name or cancel the operation. To save the file under the same name, use the Save command. Backups and icons are also created if selected as described under Settings. Save Changes If you are editing a number of files and wish to save all of them to disk, Save Changes is equivalent to selecting Save for each modified file. You may use this before quitting the editor or for safety before running a program which you are testing. The keyboard short-cut for Save Changes is Shift-AS. Last Saved Last Saved (Shift-AL)-will warn you that you are about to lose the text in the selected window and, assuming that you choose to continue, will re-load the last saved version of the file you are editing. Last Saved will do nothing if you try to use it on an unmodified file or a project that has not been saved previously. Inserting a file To read a file from disk and insert it into a project, select Insert File (AI)from the Edit menu. The File Requester will appear allowing you to select a filename or to cancel. The file will be read from disk and inserted, memory permitting, at the current cursor position. Quitting HiSOFT Basic 2 To leave HiSOFT Basic 2, select Quit HBasic from the Project menu or press AQ. Closing the last open window will also quit the editor. If any changes have been made to the text and not saved to disk, a modified project requester will appear for each changed file giving you a chance to save or abandon the file. Selecting Cancel will abort the quit and resume editing. If you have a large number of modified projects, all of which you wish to save to disk, it can be quicker to select Save Changes before quitting. Macros Macros provide a simple way of teaching the HiSOFT Basic 2 editor to perform a sequence of actions. This facility can be used for simple operations, such as commenting out a number of lines, or more complex ones such as adding a comment to the end of all lines containing a call to the sub-program CheckInput. The Macro menu gives access to the four commands used to record and replay macros. the macro menu To begin a macro you should select Start Learning from the Macro menu or press Ctrl-[. The editor will subsequently remember each action you perform including all of the menu items, cursor movement commands and typed text. Mouse or requester operations are not remembered, only editor commands will be recorded. One you have completed your chosen sequence of actions, select Stop Learning or press Ctrl-]. The macro can now be played back to repeat the recorded sequence. Two playback commands are available. Selecting Play Macro or AM will replay the macro once whilst Repeat Macro... or Shift-AM will play the macro several times in succession. If you choose to repeat a macro, a number requester similar to the Go to Line requester will appear allowing you to enter the number of iterations and press Return. Clicking the close gadget or pressing Return without entering a number will cancel the operation. The following sequence of actions would be required in order to record a macro which inserted REM in front of a number of lines : * select Start Learning (Ctrl-[). * use Ctrl-¬ to move to the beginning of the line, type REM and then cursor down a line. Be sure to type space after the REM. * select Stop Learning (Ctrl-]) to complete the macro which will consists of these three actions. * choose Repeat Macro and enter the number 10 to proceed to comment out the next ten lines in exactly the same way. Settings Selecting Settings... from the Settings menu will produce a requester like this: The editor settings This allows you to configure the editor as you like to use it; you can then save your customisation to disk so that the editor will always behave the same way. Selecting Use will accept any changes you have made without saving them to disk. Changes will be lost at the end of the current session unless subsequently saved. Here are the different settings that you can change. Tab Size By default, the tab setting is 8, but this may be changed to any value from 1 to 20. This value will be used for the current project and as the default for any new projects. Tab sizes are saved for each individual project if Create Icons? is selected. End of Line There are three possible choices of the action that is taken when the editor reaches the end of a line. The default behaviour allows the most freedom although you can also choose for the cursor to wrap to the next line if you step past the end of a line or to treat the start and end line as terminators. This latter behaviour allows you to hold down the Del key to delete to the end of the line without it proceeding to delete the rest of your text. The best way to find out which you prefer is to try using each setting. Word Qualifier key By default, the Alt modifier is taken to mean Ôby word' and Shift is Ôby line' as is standard for the Amiga¨. However, users whose fingers are accustomed to other systems can swap this behaviour via the Word Qualifier setting. Save Before Run This option controls whether any changes in your source code will be saved to disk if when you run your BASIC program. It has three settings: Yes will save the changes without asking you, Ask will ask you whether you wish to save the changes and No will run the program immediately without saving the program. If there is any chance that running your program might crash the machine, perhaps because your calls to the operating system aren't quite right, we recommend use the Save setting. Stack New Projects Selecting this option will cause new files to be opened with a window that is slightly smaller than the current window so that you can see the title of the previous window. If Stack New Projects is not checked then new windows will take up the whole screen. Auto-Indent lines Selecting this option gives automatic line indenting. When active, an indent is added to the start of each new line created when you press Return or split a line. The contents of the indent of the new line is taken from the white space (i.e. tabs and/or spaces) at the start of the previous line. This allows you to lay out your program neatly by simply pressing Return. Make Backups Selecting this option causes the editor to make a backup (by adding the extension .bak) when saving text files. Note that backup files are saved without icons regardless of the Create Icons setting. IBM Keypad This option enables the use of the numeric keypad in an IBM PC-like way by default allowing single key presses for cursor functions. The keypad works as shown in the diagram below: When this option is not selected, the keyboard reverts to returning the digits etc. although these functions may still be accessed by using the Ctrl modifier in conjunction with the numeric pad keys. Note that unlike the Shift cursor key combinations, the PgUp and PgDn keys do not move to the top/bottom of the screen. This means that pressing PgUp and PgDn will return the cursor to its original position - this is not the case with Shift and the cursor keys. At all times, the Shift modifier and the numeric pad cursor keys will scroll the window in the appropriate direction whilst keeping the cursor in the same position over the text. Show Keywords This option causes any BASIC keywords that you type to be capitalised when you finish editing a line. Not only does this mean that you can type your whole program in lower case and have the BASIC keywords stand out, it also means that if you inadvertently use a keyword as a variable name you will know immediately and you can change the name. Note that the names of operating system library routines are not reserved words as such and so will not be modified. Public Screen Under Workbench 2 and above, the HiSOFT Basic 2 editor may be run either from the Workbench screen, its own screen or another public screen if required. When this cycle gadget is set to New a new screen will always be created and used. When set to Use a screen with the given name (HBASIC.1, by default) will be used if it already exists, otherwise the editor will use the Workbench screen. Create will also use the given screen if it already exists but will create the screen if no such screen exists. If you want HiSOFT BASIC to use the Workbench screen set this to Use; if you want each invocation of the editor to use a different screen use New; if you want multiple invocations of the editor to use the same screen use Create. You are free to use any screen the editor creates for other programs or for opening Shells via the SCREEN keyword of the CON: handler. Under Workbench 1.3, there is a single Create Screen check gadget; when this is selected, the editor will open a new screen, when it is not checked the editor will use the Workbench screen. Note that if you change this option, you will need to save the settings and re-start the editor. Tool Configuration This command lets you control when the editor will load the compiler and debugger. Loading of tools The last three options in this requester relate to the various elements of the HiSOFT Basic 2 package. You can choose to load the compiler and the debugger either when you run the editor (At Startup) or when the particular tool is used for the first time (On First Use). If you are low on memory, the As Required option provides minimal memory usage, only loading the file when necessary and then unloading it from memory when you finish using it. Each Select... gadget produces a file requester allowing you to locate the directory and relevant file. You shouldn't normally need to use this as the appropriate paths will have been set up by the installation process. The file requester is also displayed if the editor comes to load a tool and cannot find it. One final way of controlling tools is to load them externally by use of the AmigaDOS RESIDENT command. This way, the program will stay resident even when you quit HiSOFT Basic 2 which will save on loading time if you have sufficient memory. To pre-load non-program files (such as include and pre-tokenised files) we recommend copying them onto the RAM disk. The Load All gadget will cause both the compiler and debugger to be loaded immediately whilst the Free gadget will free the memory used by both the compiler and debugger. Compile to Disk When using the HiSOFT Basic 2 compiler from within the integrated environment, you may choose to generate programs in memory for speed or on disk using the Compile to Disk? option. This is described in more detail in the chapter on The Compiler. Create Icons With Create Icons? on the Settings menu selected, the editor will attempt to generate a suitable Workbench project icon for any saved file. The icon image is taken from the ENV:HBASIC or ENV:Sys directory and will match the file extension where possible. For example, the icon def_bas would be used for the file amiga.bas. If these could not be found then the icon def_project would be used instead. You may create these icons with the Workbench icon editor and include a suitable default tool (this can be used to automatically run the editor when you double-click the icon) and other tooltypes as desired. Some common icon names are def_bas and def_bh for source files with def_project for other files, def_prefs for settings files and def_tool for compiled programs. Display settings This menu item is only part of the Workbench 2 version of the editor. Its sub-menu items let you change the screen mode and fonts that the editor uses. Text Font The Text Font item lets you select the text font that the editor will use for displaying the contents of files. With the ASL library 2.1 and above, the editor will use the font requester like this: Text font requester Screen Mode The Screen Mode item lets you select the screen mode that the editor will use when opening its own screens. With the ASL library 2.1 and above, the editor will use the screen mode requester like this: Screen mode requester Screen Font The command sets the screen font that the editor will use on its own screens with the Font Requester, if available: Screen font requester The Screen Font is used for the menu and window title text. Select font This item on the Settings menu is only present in the Workbench 1.3 version of the editor and brings up the file requester to let you select the font that will be used to display the contents of files. By default, all windows use the currently selected system font. For Workbench 1.3 this is normally topaz 8 or 9 as specified in Preferences. Saving settings To save the settings file you can choose Save Settings or Save Settings As... from the Settings menu. This latter command saves all editor preferences to the current settings file or creates a default file if no preferences have been loaded. Selecting the Save gadget on the Settings requester has the same effect. An icon of type def_prefs will also be created if you have selected Create Icons? In addition to saving the editor configuration, the current fonts, screen mode, tool configuration, window layout style, find and print settings etc. are also saved. The current window position and size are saved as defaults for new projects and the relative position of all requesters are remembered. The settings file itself is formatted in a similar way to Workbench icon tooltypes as a list of keywords in upper case followed by an equals sign and their associated setting. Advanced users may wish to modify the files textually within the editor in order to override only certain defaults or to specify an exact window position etc. Note: although all of the settings described in this section are saved in the editor settings file, the information contained in the compiler options requesters (described elsewhere) is not saved. To save and load configuration files you must use the menu on the compiler option requesters themselves. Multiple settings files The usual name for settings files is HBasic.prefs. If you want to call your settings file a different name, you can use Save Settings As... which will allow selection of a name and drawer for the file via the File Requester. When the editor is loaded, it looks for the HBasic.prefs configuration file firstly in the current directory (which is the project icon drawer when started from Workbench by double-clicking), then in the editor directory (used by Save Settings when no file is available) and finally in ENV:HBASIC (for the convenience of network users). This can be overridden by the use of the SETTINGS= tooltype which can be added to editor or project icons via the Workbench Info or Information option. You can take advantage of this if you intend working on several projects, each requiring different settings, by saving settings files into each project drawer and a default settings file in the editor or ENV:HBasic directory. Under Workbench 2 and above you will probably want to also save this to ENVARC:HBasic so that it will get copied to ENV:HBasic when you next reboot the machine. Loading settings You may use Load Settings... from the Settings menu to select and load editor settings files from the File Requester. Workbench 2 users may wish to keep a number of settings files in the SYS:Prefs/Presets drawer. Utility Command The Utility sub-menu contains commands for making it easier to edit your text and keep your programs looking neat. Indent This command will insert a Tab character at the front of each line in the currently selected block; if there is no selected block then Indent will work on the current line. The keyboard shortcut for this is ATab. It is the command to use if you are inserting an IF...END IF pair around some existing code. Outdent will remove a Tab character from the start of every line in the currently selected block or the current line if there is no selected block. The shortcut for Outdent is Shift-ATab. Upper Case This command converts to upper case (capitals) all the characters in the current block. If no block is selected, the single character under the cursor is converted to upper case. Ctrl-\ will do this from the keyboard. Lower Case This command lower cases all the characters in the current block or the single character under the cursor if no block is selected. Ctrl-/ will do this from the keyboard. Correct Case Correct Case will convert any BASIC keywords in the selected block to upper case. If no block is selected then this command works on the entire file. This command understands about BASIC strings and comments so keywords that are embedded in them will not be converted. Using the Show Keywords item from the Settings requester will automatically do this as you enter your code. Miscellaneous Commands The About box It you select About... from the Project menu (also available via the Help key), a requester will appear giving various details about HiSOFT Basic 2, including its version number. You will also be told the name of the current project and its size both in lines and bytes. Pressing C or clicking on Continue will resume editing. Printing A range of printing options are available from HiSOFT Basic 2. To simply print a project using the current settings you may press AP or select Print from the Project menu. A requester will appear if the printer cannot be found or an error occurs. If you have selected a block only the current block will printed, not the whole file. You may change the printer settings from the requester below which is accessed by selecting Print As... or pressing Shift-AP. the printer settings Optional line numbers may be added and the number of copies specified. Multiple copies will be separated by a form feed and tabs are expanded to the appropriate number of spaces. The Print To gadget may be used to specify where the listing is sent. For most uses this should be set to PRT: which is the default printer although other AmigaDOS devices may be used. In order to select the type of printer or the serial or parallel port, do this via system preferences in the normal way (see your Amiga¨ documentation for further details). It is possible to specify a file or pathname in order to re-direct printing to disk. This can be used as a method of converting tabs to spaces or adding line numbers to a file. The Select button can be used to choose such a file with the file requester. One novel use of the Print As requester is to redirect printing of the selected block to the SPEAK: device. Marking a block and selecting Print will then proceed to Ôread' the selected text using the Amiga's text-to-speech facilities! The SPEAK: device is not supplied with newer Amigas. Read-Only projects This feature allows a project to be temporarily locked, preventing any accidental modifications. Blocks may still be marked or copied into the clipboard and the file can be saved but any command which would change the text will simply cause a Project is Read-Only error. Use Ctrl-W to turn this on or off for the current project. Centre Window Scrolls the current window so that the cursor is positioned as centrally as possible. Many commands such as Go to Bookmark or Find Next do this automatically although it is often a useful way of finding the cursor position when you get confused. The keyboard shortcut is A/ or Ctrl-5 or Shift-5 on the numeric keypad. Keyboard command summary Project commands AN New AO Open AL Load Shift-AL Last Saved AS Save Shift-AS Save Changes AA Save As AP Print Shift-AP Print As Help About AQ Quit HiSOFT Basic 2 Window commands AW New Window AK Close Window A. Activate Next A, Activate Previous Shift-A> Bring to Front Shift-A< Send to Back A/ Centre window Movement commands ¬ ® Character Left/Right ­ ¯ Line Up/Down Shift-¬/® Shift Left/Right Shift-­/¯ Shift Up/Down Alt-¬/® Word Left/Right Alt-­/¯ Shift Up/Down Ctrl-¬/® Start/End of Line Ctrl-­/¯ Top/Bottom of File Shift-Numeric ¬/® Scroll Left/Right Shift-Numeric ­/¯ Scroll Up/Down A/, Shift-Numeric 5 Centre Window Edit commands Tab Insert Tab Return Enter Line Ctrl-Return Insert Line Ctrl-- Join Lines Ctrl-= Split Line Backspace/Del Delete Character Left/Right Shift-Backspace/Del Delete to Start/End of Line Ctrl-K Delete to End of Line Alt-Backspace/Del Delete Previous/Next Word ABackspace, Ctrl-Backspace, Ctrl-Y Delete Line Ctrl-U Undelete Line AZ Undo Line Ctrl-W Read-Only mode Block commands AX Cut AC Copy AV Paste ADel Ctrl-Del Erase AB Mark Block Shift-AB Mark Line Esc Unmark Block Shift-AA Save Block AI Insert file Search commands AF Find AR Find & Replace Ctrl-N Find Next Ctrl-P Find Previous Ctrl-R Replace AG Go to Line F1-F10 Go to Bookmark Shift-F1-F10 Set Bookmark Macro commands Ctrl-[ Start Learning Ctrl-] Stop Learning AM Play Macro Shift-AM Repeat Macro Program commands Ctrl-X Run Ctrl-A Arguments Ctrl-C Compile Ctrl-D Debug Ctrl-M Make Ctrl-V Check Ctrl-T Tokenise Ctrl-E Next Error Shift-Ctrl-E Next Error AE Execute Settings A1 Compiler Options A2 Advanced Options A3 File Options AT Editor Settings Ctrl-S Editor Settings Shift-AT Tool configuration Utility commands Ctrl-\ Upper case Ctrl-/ Lower case Ctrl-W Change readonly status