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 HiSoft DevpacST Version 2 - Manual