Amiblitz/PED

Using the Amiblitz Text Editor (or PED)

To enter and compile your programs you need an editor. Blitz2 comes with a text editor that acts both as an interface to the Blitz2 compiler as well as a standalone ascii editor (ascii is the computer standard for normal text). The horizontal and vertical bars are called 'scroll bars'. When the file you are editing is longer or wider than the screen you can position your view of the file by dragging these bars inside their boxes with the left mouse button. At the bottom of the screen is information about the cursor position relative to the start of the file you are editing as well as a memory monitor that lets you know the largest block of memory available in your Amiga system. Using the left mouse button you can drag the Blitz2 screen up and down just like any other Amiga screen as well as place it to the back with the front to back gadgets at the top right of the screen.

Note on Current Directories

If you change the pathname in the file-requester to locate a program to load you will usually need to click on the CD gadget before selecting OK on the file requester. This changes the current directory to that which you loaded the program.

By changing the current directory any files the program attempts to use will be loaded from the same directory as that from which the source code was loaded.

This means that when the program is executed (run) and attempts to load any data or graphics from disk, the default path (directory it looks for files) will be set to, the same directory as where the program itself was loaded. If a program comes up with a runtime error "Couldn't Load Shape" or the like it will be because the current directory has not been to set. Hit Escape to exit the debugger and return to the editor. If a program crashes the machine, it its because the same error occurred but error checking was disabled on the compiler options menu.

Entering Text

The editor can be treated just like a standard typewriter, just go ahead and type, using the return key to start a new line.

The small box that moves across the screen as you type is called the cursor. Where the cursor is positioned on the screen is where the letters will appear when you type. By using the arrow keys you can move the cursor around your document, herein to be known as the file.

If you place the cursor in the middle of text you have already typed you can insert letters just by typing, the editor will move all the characters under and to the right of the cursor along one and insert the key you pressed into the space created.

The DEL key will remove the character directly under the cursor and move the remaining text on the line left one character to cover up the gap. The key to the left of the DEL key will also remove a character but unlike the DEL key it removes the character to the left of the cursor moving the cursor and the rest of the line to the left. The TAB key works similar to a typewriter moving the cursor and any text to the right of the cursor right by so many columns.

The RETURN key as mentioned allows you to start a new line. If you are in the middle of a line of text and want to move all text to the right of the cursor down to a new line use shift RETURN, this is known as inserting a carriage return. To join two lines of text use the Amiga keyboard combination.

Using the shift keys in combination with the arrow keys you can move the cursor to the very start or end of a line and up and down a whole page of the document. By pointing with the mouse to a position on the screen you can move the cursor there by clicking the left mouse button. See keyboard shortcuts at the end of this chapter for other important keys used with the Blitz2 editor.

Highlighting blocks of text

When editing text, especially programs you often need to operate on a block of text. Position the mouse at the start or end of the block, hold down the left mouse button and drag the mouse to highlight the area you wish to copy, delete, save or indent. While holding down the button you can scroll the display by moving the pointer to the very top or bottom of the display.

You can also select a block with the keyboard, position the cursor at the start of the block of text, hit the F1 key then position the cursor at the end of the text and hit F2.

A special feature for structured programmers is the Amiga-A key combination, this automatically highlights the current line and any above or below that are indented the same number of spaces.

The Editor Menus

Using the right mouse button you can access the menu system of the Blitz2 editor. The following is a list of the features accessible from these menus in order from left to right.

The PROJECT Menu

NEW Kills the file you are editing from the Amiga's memory. If the file has been changed since it was last saved to disk a requester will ask you if you really wish to NEW the file.

LOAD Reads a file from disk. A file requester appears when you select LOAD which enables you to easily select the file you wish to edit. See later in this chapter for a full description of using the file requester.

SAVE Writes your file to disk. A file requester appears when you select SAVE which enables you to easily select the file name you wish to save your file as. See later in this chapter for a full description of using the file requester.

DEFAULTS Changes the look of the Blitz2 editor. You can edit the palette, select the size of font and tell the system if you wish icons to be created when your files are saved. The scroll mARG1ns dictate how far from the edge of the screen your cursor needs to be before Blitz scrolls the text.

ABOUT Displays version number and credits concerning Blitz2.

PRINT Sends your file to an output device usually PRT: the printer device.

CLI Launches a command line interface from the editor, use the ENDCLI command to close this CLI and return to the Blitz2 editor.

CLOSEWB Closes WorkBench if it is currently open. This option should only be used if you are running very short on memory as closing WorkBench can free about 40K of valuable ChipMem.

QUIT Close the Blitz2 editor and returns you to workbench or CLI.

The EDIT Menu

COPY Copies a block of text that is highlighted with the mouse or f1-f2 key combination to the current cursor position. The F4 key is another keyboard shortcut for COPY.

KILL Deletes a highlighted block of text (same as shift F3 key).

BLOCK TO DISK Saves a highlighted block of text to disk in ascii format.

INSERT FROM DISK Loads a file from disk and inserts it into the file you are editing at the current cursor position.

FORGET De-selects a block of text that is selected (highlighted).

INSERTLINE Breaks the line into two lines at the current cursor position.

DELETE LINE Deletes the line of text the cursor is currently located on.

DELETE RIGHT Deletes all text on the line to the right of the cursor.

JOIN Places the text on the line below the cursor at the end of the current line.

BLOCK TAB Shifts all highlighted text to the right by one tab mARG1n.

BLOCK UNTAB Shifts all highlighted text to the left by one tab mARG1n.

The SOURCE Menu

TOP Moves the cursor to the top of the file

BOTTOM Moves the cursor to the last line of the file.

GOTO LINE Moves the cursor to the line number of your choice.

The SEARCH Menu

FIND Will search the file for a string of characters.

NEXT Positions the cursor at the next occurrence of the Find-String entered using the FIND menu option (as below).

PREVIOUS Will position the cursor at the last occurrence of the Find: String entered using the FIND menu option (as below).

REPLACE Will carry out the same function as discussed in the FIND requester below.

After selecting FIND in the SEARCH menu the following requester will appear: Type the string that you wish to search for into the top string gadget and click on NEXT. This will position the cursor at the next occurrence of the string, if there is no such string the screen will flash.

Use the PREVIOUS icon to search backwards from the current cursor position.

The CASE SENSITIVE option will only find strings that have the same letters capitalized, default is that the search will ignore whether letters are caps or not.

To replace the find string with an alternate string click on the box next to REPLACE: and type the alternate string. REPLACE will search for the next occurrence of the Find: string, delete it, and insert the Replace: string in its place.

REPLACE ALL will carry on through the file doing replaces on all occurrences of the Find: string.

The Blitz File Requester

When you select load or save, Blitz2 places a file requester on the screen. With the file requester you can quickly and easily find the file on a disk.

Clicking on the top left of the window or on the CANCEL gadget at the bottom right will cancel the file requester returning you to the editor.

The slider at the right enables you to scroll up and down through the files in the currently selected directory (drawer).

Double clicking on a file name (pointing to the name and pressing the left mouse button twice) will select that file name.

Clicking on a <DIR> will change to that directory and list the files contained in it.

Clicking on PARENT will return you to the parent directory.

Clicking on drives adds a list of all drives, volumes and assigned devices to the top of the file list so you can move into their directories.

You can also enter path and file names with the keyboard by clicking on the boxes next to PATH: and FILE: and entering the suitable text. Then Click on the OK gadget.

CD is a special command used when programming in Blitz2 to change the editors current directory to that specified in the path name. This means that when you select CLI or launch a task from the editor its root directory will be that selected by the CD gadget.

The last feature of the Blitz2 FileRequester is the ability to size its window, by dragging the bottom right of the window with the left mouse button you can see more files at one time.

The Compiler Menu

The following is a discussion of the extra options and commands available with Ted when used in Blitz2 programming mode. The Compiler menu includes all the commands needed to control the Blitz2 compiler.

COMPILE/RUN Compiles your Blitz2 program to memory and if there are no errors run the program.

RUN Runs the program if it has already been successfully compiled to memory.

CREATE FILE Compile your Blitz2 program to disk as an executable program.

OPTIONS See next page for details about Blitz2 compiler options.

CREATE RESIDENT Will create a 'resident file' from the current file. A resident is a file including all constants and macro definitions as well as newtype definitions. By removing large chunks of these definitions from your code and creating a resident (pre-compiled) file a dramatic increase in compile speed can be attained.

VIEW TYPE Allows you to view all currently resident types. Click on the type name and its definition will be shown. Subtypes can be viewed from this expansion also.

CLI ARGUMENT Enables you to pass parameters to your program when executing it from the Blitz2 editor environment just as if you had run the program from the CLI.

CALCULATOR Allows you do to calculations in base 2, 10 and 16. Precede hex values with $ and binary with %. It also supports multi levels of parenthesis.

RELOAD ALL LIBS Will read all files from BLITZLIBS: back into the Blitz2 compiler environment. This is useful when writing your own Blitz2 libraries and wish to test them without having to re-run Blitz2.

AmiBlitz Extensions

SAVE AND COMPILE/RUN Save your code and then Compile & Run your program.

SAVE AND CREATE EXECUTABLE Save your source code and then create an executable program.

Compiler Options

The following is a discussion of the Options requester found in the Compiler menu.

Create Icons for Executable Files If on, the compiler creates an icon to accompany the file created with the CREATE FILE option. This means the program will be accessible from the WorkBench. Note: for the program to execute correctly when run from workbench the WBStartUp command should be included at the top of the source code.

Enable Runtime Errors When on will trap runtime errors and invoke the Blitz2 debugger. See Chapter 5 for a thorough discussion of runtime errors in Blitz2.

Make Smallest Code Selects two pass compile mode, which always calculates the minimum amount of memory required for the object code. Make Smallest is automatically selected when creating executable files. Unselected, programs will compile quicker.

Debug Info: Creates a symbols table during CREATE FILE so executable can be debugged more easily.

Buffer Sizes Allows different buffers to be altered when using Blitz2 as a one pass compiler. These buffers are automatically optimized when using MakeSmallest (two pass compile). The one exception is the string buffer setting, if using large strings (such as reading entire files into one string) the string workspace buffer should be increased in size to handle the largest string used.

Object Maximums Allows setting of maximum number of Blitz2 objects such as screens, shapes etc. See Chapter 6 for a thorough explanation of Blitz2 objects and their maximum settings.

Resident: Adds precompiled resident files to the Blitz2 environment. Click in the box and type in the resident file name.

Amiblitz extensions

Label list window This will appear as a window on the right side of the screen, exactly where the old label list used to appear, but is now a window with some useful gadgets. The title of the window shows the filename of the current "deflibs" file (see the tooltypes).

The list which fills most of the window is the label list. This will show labels which start with the "." character. AmiBlitz2 also displays functions and statements here, and can also show comments and case statements. The list is limited to displaying 1,000 items, for speed reasons. You can click with the left mouse button on an item in the list and the editor window will jump to the line with that item. You can hold down the left mouse button and drag the pointer over the list to scroll it, or use the prop-gadget on the right side of the window.

The string gadget at the top of the window allows you to shorten the display to specific items (only the items which start with the text in the string gadget will be displayed). The C gadget will clear the string gadget.

The Case gadget makes the list show only the Case statements.

The ; gadget displays all comments.

The All gadget displays all labels, functions/statements, comments and Case statements - the string gadget is usable when "All" is enabled.

Dialog parameter window If you press Ctrl+Help over an instruction a window will open which shows you all the parameters for the instruction and allows you to enter values for each one.

If the dialog parameter window is already open you can simply click on another instruction to have its parameters shown.

The "Add Code" button will add the command and parameters, or modify the existing command and parameters, to the current source position.

AmiBlitz tooltypes

There are also some tooltypes which you can add to the AmiBlitz2 icon.

OLDSEARCH - When the search window is used, the cursor does not jump to the start of the line. This tooltype should be enabled or disabled, and has no parameters.

BACKDROP - This tooltype when enabled will make the editor window into a backdrop window. This is useful if it overlaps other windows on the AmiBlitz screen and you have no "Window-to-back" hotkey (since there is no window depth gadget on the editor window). This tooltype is enabled by default, and has no parameters.

DONTSORT - When enabled, this tooltype tells the label window to not sort the labels in the list into alphabetical order. This tooltype is a switch and so has no parameters.

LIBFILE - You can use this tooltype to tell AmiBlitz2 what file to use as a "deflibs" file. The format is LIBFILE=<filename>. The default, or if the tooltype is not specified, is "deflibs".

STANDARDEDITMODE - Makes the editor work like any normal text editor. Pressing return will split a line instead of starting a new one, backspace will join lines and pressing "Del" with a marked block will delete the block. This tooltype is a switch and has no parameters.

STARTDIR - Tells AmiBlitz what directory to use as the current directory after starting. This tooltype is a string and has the format STARTDIR=<directory path>

NO_AUTO_TOKENIZE - Forces AmiBlitz to not try to automatically decide whether to tokenise a file or not, and will always work in the regular AmiBlitz manner (files are always tokenised). This tooltype is a switch and has no parameters.

NEWCOLORMODE - Allows the editor to work in 8 or 16 colour screenmodes. Without this tooltype set, you can only use palette number 0 to 3 for the following tooltypes (anything higher and it will wrap back to 0). When this tooltype is set, it also makes the block highlight colour the last entry in the palette. This tooltype is a switch and has no parameters.

RemarkForg - The colour number to use for the foreground colour of comments. The format of this tooltype is RemarkForg=<Palette colour number>.

RemarkBackg - The colour number for the background colour of comments. The format of this tooltype is RemarkForg=<Palette colour number>.

FunctionColor - The colour number to use for function/statement names. The format of this tooltype is FunctionColor=<palette colour number>. This colour will be used in your code when you type a function/statement name followed by a bracket, e.g. "foo()" will have the "foo" shown in the specified colour.

MacroColor - The colour number to use for macro names. The format of this tooltype is MacroColor=<palette colour number>. This colour will be used in your code when you call a macro, e.g. "!iamamacro" will be shown in the specified colour.

ConstantColor - The colour number to use for constants. The format of this tooltype is ConstantColor=<palette colour number>. This colour will be used in your code when you type any constant, e.g. "#MYWINDOW" will be shown in the specified colour.

StringColor - The colour number to use for strings, including quotation marks. The format of this tooltype is StringColor=<palette colour number>. This colour will be used in your code when you type, e.g. `"hello, world"' will be shown in the specified colour (including quote marks).

NewtypeColor - The colour number to use for fields inside newtypes. The format of this tooltype is NewtypeColor=<palette colour number>. This colour will be used in your code when you use a field from inside a newtype, e.g. "hi.there\dr_nick" will have the "\dr_nick" part shown in the specified colour.

ClassicColor - The colour number to use for instructions from libraries which use the classic Amiga chipset directly. The format of this tooltype is ClassicColor=<palette colour number>. A value of 99 will also disable the classic commands in the instruction helper.

The actual colours used by the new tooltypes can be changed in the Prefs item in the Project menu. Note the USA style of spelling "Color" in the tooltype names!

Other Amiblitz extensions to the editor

Joining lines of code A new feature is you can now join lines together, which is useful if you reach the limit of the line length (which is 250 since AB2.26, 128 characters before this and in the original Blitz2). To do this, simply put @@ in your code and AmiBlitz will continue from the next line as if they were the same line. This feature requires you use optimise with at least a value of 4.

Source position saved When you save your source in AmiBlitz2, the current position of the editor is also saved. When you re-load your source, the editor will start with the previous cursor position displayed.

Executable format AmiBlitz can now create different styles of executable. The first, most obvious change is that it can create PPC executables, when you use PPC assembly language in your programs. The executable format is a WarpOS fat binary, which will run under WarpOS and also MorphOS using the WarpOS emulation. Note that a lot of the current libraries are still 68k, and so is the code generated by AmiBlitz! If you want to create PPC executables, you need to write the PPC assembly language code yourself.

The second addition is that AmiBlitz can create chip or BSS sections in your executable (only one!). This can be useful if you need to put specific parts of your executable into e.g. chipmem for a picture which you can then display without decoding from fastram->chipmem.

AmiBlitz2 defaults to the CODE section. You can type either "chip" or "bss" in your code to change to another section, which will remain the current section until the other type of section is typed in your code (either "bss" or "chip") or the end of the code. Do NOT use the same section type twice (i.e. do not use "chip" twice)!

AB2 source file format If you save your sourcecode with the extension ".ab2" then the source code will be saved as an ASCII file, but the ".xtra" file will also be saved.

This is useful since you do not need to load your source into the AmiBlitz editor just to read it (as you would have to do with the ".bb2" source format) and you also have the use of the .xtra file (which you would not get if you saved your source as ASCII).

Keyboard Shortcuts

The right Amiga key is just to the right of the space bar.

Amiga A SELECTs all text that is indented the same amount as the current line (strictly for structured programming housekeeping)

Amiga B BOTTOM will position cursor on last line of file

Amiga D DELETE LINE removes the line of text on which the cursor is currently positioned

Amiga F FIND/REPLACE executes the FIND command in the SEARCH menu

Amiga G GOTO LINE moves cursor to specific line of file

Amiga I INSERT LINE moves all text at and below the cursor down one line

Amiga J JOIN LINE adjoins next line with current line

Amiga L LOAD reads a file from disk

Amiga N NEXT searches for the next occurrence of the 'find string'

Amiga P PREVIOUS searched for previous occurrence of the 'find string'

Amiga Q QUIT will exit the Blitz2 editor

Amiga R REPLACE will replace text at cursor (if same as find string) with the alternate string specified with the Find command.

Amiga S SAVE writes a file to disk

Amiga T TOP moves the cursor to the top of the file

Amiga W FORGET will unhighlight a selected block of text

Amiga Y DELETE TO RIGHT of cursor

Amiga Z CLI

Amiga ? DEFAULTS allows the user to change the look and feel of the Blitz2 editor

Amiga ] BLOCK TAB moves whole block right one tab

Amiga [ BLOCK UNTAB moves whole block left one tab

Amiblitz Extensions

CTRL U Undo current line

CTRL CursorUp Jump to top of source

CTRL CursorDown Jump to end of source

ALT Left Mouse (cursor right) Jump to function/label etc.

ALT Mid Mouse (cursor up) Back to old pos

ALT (cursor down) Back to previous pos

LAmiga A Jump to position in source code where text was last added

LAmiga Shift 1/2/3 Store a bookmark at this line

LAmiga 1/2/3 Jump to previously stored bookmark

F4/F5/F6 Fast switching between three different window configurations*

LAmiga F4/F5/F6 Store settings for window configuration*

F7/F8 Previous / Next entry in label listview

You must save the preferences to store the window configuration to a file and when AmiBlitz starts, it always defaults to the F4 configuration.

HELP

"Help" with nothing under the cursor (and nothing in the position to the left of the cursor) will bring up an instruction search window. You can type some text in the string gadget and all the instructions and 'library' macros which contain that text will be shown in the listview. This is known as the "instruction helper".

"Help" when there is a character under, or to the left of, the cursor will display the usual help string in the title-bar of the screen if the character is part of a recognised instruction. When it is not part of an instruction, AmiBlitz will show you how many times you have used this word in your source code. This is useful to check the correct spelling of a variable (Count>1) or to make sure you have not used that variable before (Count=1).

"Help" while over a slash character ("\") as used in types will show you all the fields of that NEWTYPE. This will work for variables, USEPATH code (e.g. "\name") and arrays. If you have local and global variables with the same name but different types then the local variable type will be shown.

Shift+Help over an instruction or object name will show you the full text of the online help for that instruction (if it is available). Pressing Alt+Help over an instruction will show you the commands in the library that the instruction is in. These are changeable in the PED menu editor (in the Custom menu).

RAmiga+Help will bring up the default help program, which is useful for internal AmiBlitz commands. This help can be in English or German, depending on which help.dat file you use (help_en.dat or help_de.dat). By default, the English help file is used.

Ctrl+Help gives you the dialog parameter window