CHAPTER 2 - Screen Editor
Here begins Part 2 of the extensive Devpac Docs. Again, it was typed by the Animal House and edited by Sewer Rat.
CHAPTER 2 - SCREEN EDITOR
INTRODUCTION
To enter and assemble your programs you need an editor of some sort and an assembler. GenST combines both of these functions together in one integrated program, giving a GEM-driven full-screen editor and a fast, full specification assembler. It also allows you to run your assembled programs directly from memory without having to quit the program or do a disk access and to access a debugger at the press of a key. The fact that all these features are combined in one program means that the correcting errors and making changes is as fast as possible without the need for slow disk accesses and other programs.
This chapter details the use of the editor and how to assemble programs - it does not detail the assembler or the debugger themselves, they are covered in the following chapters.
To run GenST, double click on the GENST2.PRG icon from the Desktop. When it has loaded a menu bar will appear and an empty window will open, ready for you to enter and assemble your programs.
THE EDITOR
A text editor is a program which allows you to enter and alter lines of text, store them on disk, and load them back again. There are two types of text editors: line editors, which treat each line separately and can be very tricky to use, and screen editors, which display your text a screen at a time. The latter tend to be much easier to use.
The editor section of GenST is a screen editor which allows you to enter and edit text and save and load from disk, as you would expect. It also lets you print all or some of your text, search and replace text patterns and use any of the ST's desk-accessories. It is GEM-based, which means it uses all the user-friendly features of GEM programs that you have become familiar with on your computer such as windows, menus and mice. However, if you're a die-hard, used to the hostile world of computers before the advent of WIMP's, you'll be pleased to know that you can do practically everything you'll want to do from the keyboard without having to touch a mouse.
The editor is 'RAM-based', which means that 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 the ST range has so much memory, the size limitations often found in older computer editors don't exist with GenST; if you have enough memory you can edit files of over 300k (though make sure your disk is large enough to cope with saving it if you do!). As all editing operations, including things like searching, are RAM based they act blindingly quickly.
When you have typed in your program it is not much use if you are unable to save it 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 Alternate key (subsequently referred to as Alt) in conjunction with another such as Alt-F for Find:
- Using the control key (subsequently referred to as Ctrl) in conjunction with another, such as Ctrl-A for cursor word left:
- Clicking on the screen, such as a scroll bar.
The menu short cuts have been chosen to be easy and obvious to remember, while the Ctrl commands are based on those used in Wordstar, and many other compatible editors since.
If at any time you get stuck, pressing the HELP key will bring up a comprehensive display of the keys for functions not visible in menus.
A FEW WORDS ABOUT DIALOGUE BOXES
The editor makes extensive use of dialogue boxes, so it is worth recapping how to use them, particularly for entering text. The editor's dialogue box contains buttons, radio buttons, and editable text.
Buttons may be clicked on with the mouse and cause the dialogue box to go away. Usually there is a default button, shown by having a wider border than the others. Pressing RETURN on the keyboard is equivalent to clicking on the default button.
Radio buttons are groups of buttons of which only one may be selected at a time - clicking on on automatically de-selects all the others.
Editable text is shown with a dotted line, and a vertical bar marks the cursor position. Characters may be typed in and corrected using the Backspace, Delete and cursor keys. You can clear the whole edit field by pressing the ESC key. If there is more than one text field in a dialogue box, you can move between them using the up and down cursor keys or by clicking near them with the mouse.
Some dialogue boxes allow only a limited range of characters to be typed into them - for example the Goto Line dialogue box only allows numeric characters (digits) to be entered.
ENTERING TEXT AND MOVING THE CURSOR
Having loaded GenST, you will be presented with an empty window with a status line at the top and a flashing black block, which is the cursor, in the top left-hand corner.
The status line contains information about the cursor position in the form of Line Column offsets as well as the number of bytes of memory which are free to store your text. Initially this is displayed as 59980, as the default text size is 60000 bytes. You may change this default if you wish, together with various other options, by selecting Preferences, described later. The missing 20 bytes are used by the editor for internal information. The rest of the status line area is used for error messages, which will usually be accompanied with a 'ping' sound to alert you. Any message that gets printed will be removed subsequently when you press a key.
To enter text, you type on the keyboard. As you press a key it will be shown on the screen and the cursor will be advanced along the line. If you are a good typist you may be able to type faster than the editor can re-display the line; if so, don't worry, as the program will not lose the keystrokes and will catch up when you pause. At the end of each line you 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 the cursor is over.
The main advantage of a computer editor as opposed to a normal typewriter, is its ability to edit things you typed a long time ago. The editor's large range of options allow complete freedom to move around your text at will.
CURSOR KEYS
To move the cursor around the text to correct errors or enter new characters, you use the cursor keys, (the arrows). If you move the cursor past the right-hand end of the line this won't add anything to your text, but it you type some text at the 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 necessary.
If you cursor up at the top of the window the display will either scroll down if there is a previous line, or print the message Top of file in the status line. Similarly if you cursor down off the bottom of the window the display will either scroll up if there is a following line, or print the message End of file.
You can move the cursor on a character basis by clicking on the arrow boxes at the end of the horizontal and vertical scroll bars.
For those of you used to Wordstar, the keys Ctrl-S, Ctrl-D, Ctrl-E and Ctrl-X work in the same way as the cursor keys.
To move immediately to the start of the current line, press Ctrl (left arrow), to move to the end of the current line press Ctrl (right arrow).
To move the cursor a word to the left, press Shift (left arrow) and to the right press Shift (right arrow). You cannot move a cursor past the end of a line with this. A word is defined as anything surrounded by a space, a tab or a start or end of line. The keys Ctrl-A and Ctrl-F also move the cursor left and sight on a word basis.
To move the cursor a page up, you can click on the upper grey part of the vertical scroll bar, or press Ctrl-R or Shift (up arrow). To move the cursor a page down, you can click on the lower grey part of the scroll bar, or press Ctrl-C or Shift (down arrow).
If you want to move the cursor to a specific position on the screen you move the mouse pointer to the required place and click (There is no Wordstar equivalent for this feature!)
TAB KEY
The Tab key inserts a special character (ASCII code 9) into your 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, 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 its main use in GenST is for making instructions line up. 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 only take up 1 byte of memory, bat can show on screen as many more, allowing you to tabulate your program neatly. You can change the tab size before or after loading GenST using the Preferences command described shortly.
BACKSPACE KEY
The Backspace key removes the character to the left of the cursor. If you backspace at the very beginning of a line it will remove the 'invisible' carriage return and join the line to the end of the previous line. Backspacing when the cursor is past the end of the line will delete the last character on the line, unless the line is empty in which case it will re-position the cursor on the left of the screen.
DELETE KEY
The Delete key removes the character under the cursor and has no effect if the cursor is past the end of the current line.
GOTO A PARTICULAR LINE
To move the cursor to a particular line in the text, click on Goto line.. from the Options menu, or press Alt-G. A dialogue box will appear allowing you to enter the required line number. Press Return or click on OK button to go to the line or click on Cancel to abort the operation. After clicking on OK the cursor will move to the specific line, re-displaying if necessary, or give error End of file if the line doesn't exist.
Another fast way of moving around the file is by dragging the slider on the vertical scroll bar, which works in the usual GEM-like fashion.
GOTO TO TOP OF FILE
To move to the top of the text, click on Goto Top from the Options menu, or press Alt-T. The screen will be re-drawn if required starting from line 1.
GOTO END OF TEXT
To move the cursor to the start of the very last line of text, click on Goto Bottom, or press Alt-B
QUITTING GENST
To leave GenST, click on Quit from the File menu, or press Alt-Q. If changes have been made to the text which have not been saved to disk, an alert box will appear asking for confirmation. Clicking on Cancel will return you to the editor, while clicking on OK will discard the changes and return you to the Desktop.
DELETING TEXT
DELETE LINE.
The current line can be deleted from the text by pressing Ctrl-Y.
DELETE TO END OF LINE.
The text from the cursor position to the end of the current line can be deleted by pressing Ctrl-Q. (This is equivalent to the Wordstar sequence Ctrl-Q Y).
UNDELETE LINE
When a line is deleted using either of the above commands it is preserved in an internal buffer, and can be re-inserted into the text by pressing Ctrl-U, or the Undo key. This can be done as many times as required, particularly useful for repeating similar lines or swapping over individual lines.
DELETE ALL TEXT
To clear out the current text, click on Clear from the File menu, or press Alt-C. If you have made any changes to the text that have not been saved onto the disk, a confirmation is required and the requisite alert box will appear. Clicking on OK will delete the text, or Cancel will abort the operation.
DISK OPERATIONS
GEM FILE SELECTOR BOX
(This section has been left out as it is common knowledge to anyone who uses their ST, if you want to read it, it is the same details as contained in your Atari manual)
- In all pre-blitter versions of the ST ROM's there is a bug which means that if you press _ (underline) when the cursor is in the Directory string the machine will crash!!
SAVING TEXT
To save the text you are currently editing, click on Save As from the File Menu, or press Alt-S. The standard GEM File Selector will appear, allowing you to select a suitable disk and filename. Clicking OK or pressing Return will then save the file onto the disk. If an error occurs a dialogue box will appear showing a TOS error number, the exact meaning of which can be found in Appendix A.
If you click on Cancel the text will not be saved. Normally if a file exists with the same name it will be deleted and replaced with the new version, but if Backups are selected from the Preferences options then any existing file will be renamed with extension .BAK (deleting any existing .BAK file) before the new version is saved.
SAVE
To save the file you can click on the Save option on the File menu, or press Shift-Alt-S, and it will use the old name.
LOADING TEXT
To load a new file, click on Load from the File menu, or press Alt-L.
INSERTING TEXT
If you want to read a file from disk and insert it at the current position in your text click on Insert File from the File menu or press Alt-L
SEARCHING AND REPLACING TEXT
To find a particular section of text click on Find from the Search menu, or press Alt-F. A dialogue box will appear, allowing you to enter the Find and Replace strings. If you click on Cancel, no action will be taken; if you click Next (or press Return) the search will start forwards, while clicking on Previous will start the search backwards. If you do not wish to replace, leave the Replace string empty. If the search was successful, the screen will be re-drawn at that point with the cursor positioned at the start of the string. If the search string could not be found , the message Not Found will appear in the status area and the cursor will remain unmoved. By default the search is always case-independant, so for example if you enter the search string as test you could find the words TEST, Test or test. If you click on the Upper & Lower case Different button the search will be case dependant.
To find the next occurrence of the string click on Find Next from the Search menu, or press Alt-F. The search starts at the position just before the cursor.
To search for the previous occurrence of the string click on Find Previous from the Search menu, or press Alt-P.
Having found an occurrence of the required text, it can be replaced with the Replace string by clicking on Replace from the Search menu, or pressing Alt-R. Having replaced it, the editor will then search for the next occurrence.
If you wish to replace every occurrence of the find string with the replace string from the cursor position onwards, click on Replace All from the Search menu. During the global replace the ESC key can be used to abort and the status area will show how many replacements were made. There is deliberately no keyboard equivalent for this to prevent it being chosen accidentally.
BLOCK COMMANDS
A Block is a marked section of text which may be copied to another section, deleted, printed or saved onto disk. The function keys are used to control blocks.
MARKING A BLOCK
The start of a block is marked by moving the cursor to the required place and pressing key F1. The end of a block is marked by moving the cursor and pressing key F2. The start and end of the block do not have to be marked in a specific order - if it is more convenient you may mark the end of the block first.
A marked block is highlighted by showing the text in reverse. While you are editing a line that is within a block this highlighting will not be shown but will be re-displayed when you leave that line or choose a command.
SAVING A BLOCK
Once a block has been marked, it can be saved by pressing key F3. If no block is marked, the message What blocks! will appear. If the start of the block is textually after its end the message Invalid block! will appear. Both errors abort the command. Assuming a valid block has been marked, the standard GEM file selector will appear, allowing you to select a suitable disk and filename. If you save the block with a name that already exists the old version will be overwritten - no backups are made with this command.
COPYING A BLOCK
A marked block may be copied, memory permitting, to another part of the text by moving the cursor to where you want the block copied and pressing key F4. If you try to copy a block into a part of itself, the message Invalid block will appear and the copy will be aborted.
DELETING A BLOCK
A marked block may be deleted from the text by pressing Shift-F5. The shift key is deliberately required to prevent it being used accidentally. A deleted block is remembered, memory permitting, in the block buffer, for later use.
- This is on a different key to that used in GenST in versions before 2.0.
COPY BLOCK TO BLOCK BUFFER
The current marked block may be copied to the block buffer, memory permitting, by pressing Shift-F4. This can be very useful for moving blocks of text between different files by loading the first, marking the block, copying it to the block buffer then loading the other file and pasting the block buffer into it.
PASTING A BLOCK
A block in the block buffer may be pasted at the current cursor position by pressing F5.
- The block buffer will be lost if the edit buffer size is changed or an assembly occurs.
PRINTING A BLOCK
A marked block may be sent to the printer by printing on Print Block from the File menu, or by pressing Alt-W. An alert box will appear confirming the operation and clicking on OK will print the block. The printer port used will depend on the port chosen with the Install Printer desk accessory, or will default to the parallel port. Tab characters are sent to the printer as a suitable number of spaces, so the net result will normally look better than if you print the file from the Desktop.
If you try to print when there is no block marked, the whole file will be printed.
Block markers remain during all editing commands, moving where necessary, and are only reset by the commands New, Delete Block, and Load.
MISCELLANEOUS COMMANDS
ABOUT GENST2
If you click on About GenST2.. from the Desk menu, a dialogue box will appear giving various details about GenST. Pressing Return or clicking OK will return you to the editor.
HELP SCREEN
The key equivalents for the commands not found in menus can be seen by pressing the HELP key, or Alt-H. A dialogue box will appear showing the Wordstar and function keys, as well as the free memory left in the system.
PREFERENCES
Selecting Preferences.. from the Options menu will produce a dialogue box allowing you to change several editor settings.
TABS
By default, the tab setting is 8, but this may be changed to any value from 2 to 16.
TEXT BUFFER SIZE
By default the text buffer size is 60000 bytes, but this can be changed from 4000 to 999000 bytes. This determines the largest file size that can be loaded and edited, Care should be taken to leave sufficient room in memory for assembly or running MonST - pressing the HELP key displays free system memory, and for assembly or debugging this should always be about 100k bytes. Changing the editor work-space size will cause any text you are currently editing to be lost, so a confirmation is required if it has not been saved.
NUMERIC PAD
The Numeric Pad option allows the use of the numeric keypad in an IBM-PC-like way allowing single key presses for cursor functions, and defaults to Cursor pad mode. The keypad works as shown below,
7 START 8 (UP) 9 PAGE UP
OF LINE
4 (LEFT) 5 6 (RIGHT)
1 END OF 2 (DOWN) 3 PAGE DOWN
LINE
BACKUPS
By default the editor doesn't make backups of programs when you save them, but this can be turned on by clicking on the Yes radio button.
AUTO INDENTING
It can be particularly useful when editing programs to indent subsequent lines from the left, so the editor supports an auto-indent mode. When active, an indent is added to the start of each new line created when you press RETURN. 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.
CURSOR
By default the GenST cursor flashes but this can be disables if required.
LOAD MONST
By default a copy of MonST is loaded during the editor initialisation, allowing it to be accessed at the press of a key. Should this not be required it can be disabled with this option. This will save around 24k of memory. The new value of this option will only have an effect if you save the preferences and re-execute the editor.
SAVING PREFERENCES
If you click on the Cancel button any changes you make will
be ignores. If you click on the OK button the changes specific
will remain in force until you quit the editor. If you would like
the configuration made permanent then click on the Save button,
which will create the file GENST2.INF on your disk. Next time you
run GenST the configuration will be read from that file.
In addition to saving the editor configuration the current
setting from the Assembly Options dialogue box are also saved.
ASSEMBLING & RUNNING PROGRAMS
All assembly and run options can be found on the Program menu
ASSEMBLY
To assemble the program you are currently editing click on
Assemble from the Program menu, or press Alt-A. The meaning of the
various options, together with the assembly process itself is
detailed in the next chapter. The only option covered here is the
Output option.
GenST can assemble to disk, to memory, or nowhere -
assembling to nowhere is ideal for syntax checking while assembly
to memory is much faster than to disk and good for trying things
out quickly. When you assemble to memory you have to specify the
maximum program size in the Max: entry in the dialogue box -
normally this is 20k, enough for an average program with debug or
a large program with no debug. This number determines the program
buffer size, used by the assembler to store your assembled
program. If you get the program buffer full error when you
assemble something you should change the number to be larger.
There is of course a penalty for this - the bigger the program
buffer size the smaller the amount of memory left for the
assembler itself to use while assembling your program. If the
assembler itself aborts with Out of memory it means there is not
enough left for a complete assembly - you should reduce the buffer
size, or if this still fails you will have to assemble to disk.
When you assemble to disk the program buffer size number is
ignored, giving maximum room in memory for the assembler itself.
If you haven't saved your program source code yet the file will be
based on the name NONAME.
After you click on Assembly or press RETURN the assembly
process will start, describe more fully in the next chapter. At
the end of the assembly the program will wait for a key press,
allowing you to read any messages produced, before returning you
to the editor. If there were any errors the editor will go to the
first erroneous line and display the error message in the status
bar. Subsequent errors (and warnings) may be investigated by
pressing Alt-J.
RUNNING PROGRAMS
If you click on Run or press Alt-X (eXecute) you can then run
a program previously assembled into memory. When your program
finishes it will return you to the editor. If the assembly didn't
complete normally for any reason then it is not possible to run
the program.
If your program crashes badly you may never return to the
editor, so if in doubt save your source code before using this, or
the following command.
** If only non-fatal errors occurred during assembly (e.g.
undefined symbols) you will still be permitted to run your
program, at your own risk.
PLEASE NOTE
When running a Run command from the editor the machine may
seem to 'hang up' and not run the program. This occurs if the
mouse is in the menu bar area of the screen and can be corrected
by moving the mouse. Similarly when a program has finished
running, the machine may not return to the editor. Again, moving
the mouse will cure the problem. This is due to a feature of GEM
beyond our control.
DEBUG
If you wish to debug a program previously assembled to memory
click on Debug form the Program menu, or press Alt-D. his will
invoke MonST to debug your program, including any debugging
information specified. Pressing Ctrl-C from MonST will terminate
both your program and the debugger. The screen type is determined
by the Run with GEM option, described below.
** If the Load MonST option is disabled this option is not
available and the menu is disabled.
MONST
Clicking on MonST from the Program menu, or pressing Alt-M,
will invoke MonST in a similar way to if it was invoked by double-
clicking on the program icon from the Desktop, but instantly, as
it is already in memory. You will return to the editor on
termination of the debugger. The screen type is determined by the
Run with GEM option, described below.
** If the Load MonST option is disabled this option is not
available and the menu is disabled.
RUN WITH GEM
Normally when the commands Run, Debug or MonST are used the
screen is initialised to the normal GEM type, with a blank menu
bar and patterned desktop. However if running a TOS program this
can be changed to a blank screen with a flashing cursor, by
clicking on Run with GEM, or by pressing Alt-K. A check-mark next
to the menu item means GEM mode, no check mark means TOS mode. The
current setting of this option is remembered if you Save
Preferences.
** Running a TOS program in GEM mode will look messy but work,
but running a GEM program in TOS mode can crash the machine.
JUMP TO ERROR
During an assembly any warnings or errors that occur are
remembered, and can be recalled from the editor. Clicking on Jump
to Error from the Program menu, or pressing Alt-J will move the
cursor to the next line in your program which has an error, and
display the message in the status line of the window. You can
step to the next one by pressing Alt-J again, and so on, letting
you correct errors quickly and easily. If there are no further
errors when you select this option the message No more errors will
appear, or if there are no errors at all the message What errors!
will appear.
RUN OTHER...
This option lets you run other programs from within the
editor, then return to it when they finish. Its main use is to
allow you t run programs you have assembled to disk, or to run the
linker, without having to return to the desktop and double-
clicking them. You can run both TOS and GEM programs with this
option, subject to available memory. When you click on Run
Other... you will first be warned if you have not saved your
source code, then the GEM file selector will appear, from which
you should select the program you wish to run. If it is a .TOS or
.TTP program you will be prompted for a command line, then the
screen initialised suitably.
** Screen initialisation depends on the filename extension, not
the current Run with GEM option setting.
WINDOW USAGE & DESK ACCESSORIES
THE GEM EDITOR WINDOW
The window used by the editor works like all other GEM
windows, moving it and altering it with the mouse.
DESK ACCESSORIES
If your ST system has any accessories, you will find them in
the Desk menu. If they use their own window, as Control Panel
does, you will find that you can control which window is at the
front by clicking on the one you require. For example, If you have
selected the control panel it will appear in the middle of the
screen, on top of the editor window. You can then move it around
and if you wish it to lie 'behind' the editor window, you can do
it by clicking on the editor window, which brings it in front,
then re-sizing it so you can see part of the control panel's
window behind it. When you want to bring that to the front just
click on it and the editor window will go behind. The editors
cursor only flashes and the menus only work when the editors
window is at the front.
AUTOMATIC DOUBLE CLICKING
You may configure GenST to be loaded automatically whenever a
source file is double-clicked from the desktop, using the INSTALL
APPLICATION option.
To do this you first have to decide on the extension you are
going to use for your files, which we recommend to be .S for
source files. Having done this, go to the Desktop, and click once
on GENST2.PRG to highlight it. Next click on Install Application
from the Options menu and a dialogue box will appear. You should
set the Document Type to be S (or whatever you require), and leave
the GEM radio button selected. Finally click on the OK button (if
you press Return it will be taken as Cancel).
Having done this, you will return to the Desktop. To test the
installation, double-click on a file with the chosen extension
which must be on the same disk and in the same folder as GenST
and the desktop will load GenST, which will in turn load in the
file of your choice ready for editing or assembly.
** To make the configuration permanent, you have to use the Save
Desktop option.
SAVED! DESK ACCESSORY USERS
If you use the PATH feature of the Saved! by HiSoft desk
accessory then the restriction of having your data files in the
same folder and drive as your assembler described above is not
relevant. The editor looks for the GENST2.INF configuration file
firstly in the current directory which is the folder where you
double-clicked on the data file), then using the system path.
Saving the editor preferences will put the .INF file in the same
place it was loaded from, or if it was not found then it will be
put in the current directory.
You may invoke Saved! from within the editor at any time by
pressing Shift-Clr. his will only work if the desk accessory is
called SAVED!.ACC or SAVED.ACC on your boot disk.
Back to Devpac_Manual