 | Documentation Latest release ZapRedraw Contact Download |
 |  |
 | |
Previous | Contents | Index | Next
Here we look at one of Zap's most powerful features; the different editing and displaying modes. While you might be perfectly comfortable using the basic mode (Text) for editing emails, program source, and so on, you will probably find that many of these modes have features which can help you do the job faster and more effectively. In addition, Zap has some modes which offer features that Text mode can't supply - such as the binary editing modes, and Code, which allows you to edit ARM binaries (executable programs) directly.
To change mode, either use scFn (where Fn is a function key from F1 to F10), or select the mode's name from the Mode menu. Modes are dynamically loaded, meaning that they aren't loaded until they are needed. If a mode hasn't been loaded yet, its name won't be on the Mode menu - instead it will be on the Mode->Load mode submenu. (In addition, cloned modes that haven't been loaded will be on the Mode->Load clone submenu - see section 12.2.2 for information about cloned modes.)
So far in this manual, we have in general only discussed the features of Text mode. Many of the modes described here inherit some or all of those features - if they aren't available, the relevant key press will beep or do nothing, and the menu option will be greyed out or will do nothing.
Each mode can have a number of the options discussed previously set independently of the settings of any other mode. These are known as per-mode options; all the options introduced in chapter 6, and most of those in chapter 7 can be set up differently for each mode. For more information about this, see section 12.2.1.
In addition, each mode can have its own, unique options. For instance, many modes have a number of colours which aren't available in any other mode (the HTML colouring mode has a colour for HTML 'tags', which would be of no use in other modes). Except for specialised colours, which are at the bottom of the Display->Colours menu, all options unique to a mode will be presented in the mode's own menu. This is a submenu from the Modes menu itself - for instance, the options for Byte mode are in the submenu Mode->Byte.
Of course, quite often you might want to edit certain files in a particular mode with one set of options, and others in the same mode with different options. While you could change the options each time you look at a file, it is easier to clone a mode, essentially giving you two copies of the mode you want to use, and which you can then configure independently. For more information about this, see section 12.2.2.
All modes come with documentation; this will be in the application directory of the extension when you install it. Extensions modes are stored in !Zap.Modules.
One set of modes which Zap has which are radically different to Text mode are the binary editing modes. These allow you to directly edit files using an 'atomic size' of byte, halfword (sixteen bit quantity), word or doubleword (sixty-four bit quantity). The four modes are called Byte, HalfWord, Word and DoubleWord, and they share several common features.
Firstly, they typically employ an entry system called 'hex entry'. With it turned on, you type the byte or word's value in hexadecimal, a nibble (a single hexadecimal digit) at a time. For instance, in byte mode with hex entry turned on, typing 8 will set the byte at the cursor to 08, but keep the cursor where it is. Completing the byte (since a byte has two hex digits) by typing B will change the byte to 8B (the first nibble is rotated to make way for the second), and move the cursor on to the next byte. In Word mode, you have to type eight nibbles to complete a word. (Byte mode will also do normal entry - with hex entry turned off you can simply type as if you were in Text mode. The others will not do normal entry - with hex entry turned off, typing has no effect.)
(Note that while the option is called 'hex entry', it doesn't always employ hexadecimal - see below.)
The other editing option that the two modes share is that if you press Return the byte, halfword or word at the cursor is dropped into the minibuffer for you to edit; pressing Return in the minibuffer will set the edited value. This is actually done through an interface to the BASIC assembler - a word of value &8000 will be placed in the minibuffer as DCD &00008000. In addition, the address of the byte or word will be displayed at the far left of the minibuffer. As a variation, in Word mode pressing cReturn will disassemble the word at the cursor - for instance the word of value 0 will be disassembled to ANDEQ R0,R0,R0. Again, the address will be displayed at the far left of the minibuffer.
For DoubleWord mode, you can only edit using 'hex entry' - pressing Return in DoubleWord mode has no effect.
If you have already played with the binary modes, you will have noticed that the display falls into three sections. On the left is the address (this is done using Zap's line numbering system, and so can be turned off or altered if you require - see section 7.1.2). In the middle is a line of byte or word values, and at the right is those values displayed as the corresponding ASCII characters. You can click on either of the right hand two sections to set the cursor.
Zap 'display width' (see section 7.1.1) here sets the number of bytes, halfwords, words or doublewords to display per line. A useful option here is window wrap (see section 6.3.1), since this allows you to change the number per line quickly with the mouse.
There are a number of options that control how the display is formatted.
Firstly, you can make all 'control characters' (characters with values less than 32) be mapped to any other character. This is the Suppress ctrls option; the submenu from it sets the character to replace them with.
Secondly, you can choose to 'group' the bytes, words or whatever, and the ASCII dump at the far right. The group size must be the same in both cases (the Group size submenu from the mode's options menu gives the value used for both); a space is displayed between each group. In the default setup, DoubleWord groups to every second doubleword, Word mode groups to every fourth word, HalfWord groups to every four halfwords, and Byte mode groups to every eight bytes.
Thirdly, you can change the display in the middle of the window to work in binary instead. If you do this, the 'hex entry' system, and editing through the minibuffer by pressing Return will work in binary also. (The system is still called 'hex entry' for historical reasons :-)
Finally, all four modes have one mode-specific colour, ASCII chars, which is used for non-control characters in the ASCII dump at the right hand edge of the screen.
The binary modes also come in handy with Zap's ability to create files directly from memory or disc. This works from the iconbar Create submenu; the options are:
Get module - Reads a module from memory and dumps it into Code mode (see section 10.3 below).Get workspace - Reads a module's workspace and dumps it into Code mode (see section 10.3 below).Read memory... - Allows you to read the memory of a Wimp application.Read disc... - Allows you to read data directly from a disc.Get dynamic area - Grabs the contents of a dynamic area and displays it in Text mode (RISC OS 3.5 and later only).Selecting Create->Read memory ... from Zap's iconbar menu opens a small dialogue box allowing you to specify which range of memory and from which task you want to create a file. Dragging the Acorn icon at the top (Archimedes icon for RISC OS 2) to a window or icon will set the task name to the task that owns it. For instance, to grab memory from Alarm, drag the icon to Alarm's iconbar icon. At the bottom you can specify the range of memory to grab - when you set the task, Zap will update these fields to show to maximum range possible; the Grab button at the bottom grabs the memory and makes a file out of it.
Selecting Create->Read disc ... from Zap's iconbar menu opens a large dialogue box allowing you to specify which bit of which disc you want to read. At the top you specify the filing system (eg: SCSIFS, ADFS, RAMFS); to the right of this Zap will report the number of hard drives and floppy drives for the filing system you have chosen. In the middle on the left will be information about the disc you have selected - name, size, number of tracks, number of heads, bytes per sector and sectors per track.
At the right you can specify which drive, and which part of the disc to read, either by sector, head and cylinder or by sector address. Then you can click on Read Disc, Read Track or Read Sector to grab the relevant part of the disc into a file.
When a window on the file is opened, the Navigate disc dialogue will also pop up. This allows you to move the view around the disc. If you close this dialogue, you can bring it back up from the Misc->Move submenu (which also has entries which double the function of the buttons in the navigate dialogue).
You can only have one active disc reading operation in progress at a time.
ASCII mode allows you to edit text as an ASCII dump - the line length is fixed to the display width (so line endings are ignored), but otherwise editing is as you'd expect for Text mode.
This mode displays data in disassembled format with one instruction per line. The format of a line is address on the left (again using Zap's line numbering system, so this is configurable), an ASCII dump of the word, followed by a binary or hex display of the opcode (binary or hex display is controlled by the Binary OP codes option), followed by the disassembly itself. Some instructions will have comments or warnings displayed off to the right, unless you suppress them with the Comment free option.
Many of the normal keys don't perform as you'd expect in Code mode; instead they perform functions which are more useful in the context of editing ARM code.
Firstly, typing any normal letter, as well as typing Return, will place the disassembly of the instruction at the cursor in the minibuffer for you to edit. Pressing Return in the minibuffer will reassemble the command; this uses the BASIC assembler (optionally augmented by ExtBASICAsm - see section 13.2.2), and so you can use BASIC functions sure as ASC, EQUD, ADR etc.
Secondly, the arrow keys Left and Right work differently. Right will follow a referenced address in an instruction (for instance, pressing Right with the cursor on an instruction BL &12345 will jump to address &12345); it also places a mark when it does so, so the LASTMARK and NEXTMARK commands (see section 9.1) can be used to help you keep track of function calls. To make life easier, pressing Left moves you back to the last mark.
Thirdly, pressing cI will cause you to jump to the address given by the contents of the word at the cursor position - for instance in a module, the first word in the file gives the start offset of the module; pressing cI will jump to the start code. This also places a mark when it does so, and is known as indirecting (the command INDIRECT does the same thing).
Code mode supplies a very rich set of options to configure how it colours the disassembly. First there are some 'utility' colours, not associated with the disassembly itself:
ASCII chars - Used for non-control characters in the ASCII dump of the word.Hex chars - Used for the hex (or binary) number dump.Comment - Comments, warnings and offset information.The other colours affect how the disassembly itself is coloured. There are also three options in the Mode->Code submenu which affect this:
Unconditional - Colour condition codes the same colour as the rest of the instruction.Minimal - Colour instruction operands the same colour as the rest of the instruction.Condition back - The Conditions colour affects the background rather than the foreground (see the entry on this colour below for more information).The colours are as follows:
SWIs - SWI instructions.Branches - BL and B instructions.Push R14s - STM instructions that push R14 (these tend to indicate the start of a subroutine).Pull PCs - LDM instructions that pull PC (these tend to indicate an exit from a subroutine).[ and ] - The square bracket characters in STR and LDR instructions.{ and } - The curly brace characters in STM and LDM instructions.#, !, ^ & - - The character # prefixing an immediate constant; the character ! used for writeback in STM/LDM/STR/LDR; the character ^ used for SPSR to CPSR with PC in LDM instructions, and force user bank transfer for all other STM and LDM instructions; commas; and the character - used in a register list in LDM and STM instructions.Registers - All registers.Numbers - All numbers that aren't immediate constants (typically addresses in ADR and branch instructions).Immediate - Immediate constants.Shifts - Shift operators (ASR, LSL, LSR, ROR, RRX).LDM or STM - LDM and STM instructions (unless trapped above for push/pull R14/PC).LDR or STR - LDR and STR instructions.SWI names - SWI names (if a SWI number can't be resolved to a name, it is displayed as the number, using the Number colour).Conditions - Condition codes. If Unconditional is turned on, this won't do anything; if Condition back is turned on then it will affect the background instead of the foreground. Its style information will be used either way. If you want to change the style only, set Condition back and change the colour to the same as the Background 2 colour..'Undefined' - Undefined instructions. Note that this won't be used if the DCD option is turned on - see section 10.3.2.FP regs - Floating point registers.CP regs - Coprocessor registers.FP instrs - Floating point instructions.CP instrs - Coprocessor instructions.If you have set Disassembler (Darren Salt's Debugger Plus) to be autoloaded (see section 13.2.2 and section 12.2.6), then the Code->Disassembler submenu will enable you to alter how the disassembly is done. In general, if you don't understand these options, you probably want to leave them at their default settings; however here is a brief description of what each does. The Global option at the top sets whether the alterations you make to the settings will only affect disassembly within Zap, or everything using Debugger Plus. For more information, see the documentation which comes with Debugger Plus, in !Zap.Code.Extensions.ExtAsm.
FD if R13 - Use FD with R13, eg: STMDB R13 is disassembled as STMFD R13.APCS support - Use APCS-R register set, and recognise C function entry.LFM Stack - Use stack notation with LFM and SFM where possible.LFS & SFS - Use LFS and SFS in preference to LFM and SFM.Quote SWIs - Put quotes (") around SWI names.DCD - Use DCD instead of Undefined instruction, and BRK where DCD &x6000010 would be used.VDU - Use VDU x instead of SWI OS_WriteI+x.More DCDs - Use DCD instead of ANDEQ Rn,Rn,Rn, MOV Rn,Rn (same register), etc.ADRL - Use ADRL / ADRX instead of ADR followed by ADD / SUB on same register.ADRW - Use ADRW instead of ADD/SUB Rn,R12,#m and LDRW, STRW, LDRBW, STRBW instead of xxxx Rn,[R12,#m].Long MULs - Append L to UMUL, UMLA, SMUL, SMLA (thus using the official forms).LDRL - Use LDRL instead of ADD/SUB Rn,Rm,#o + LDR Rn,[Rn,#p] and ADD/SUB Rm,Ra,#o + LDR Rn,[Ra,#p]!; and STRL instead of equivalent STRs (the LDRWL form is enabled by this option and ADRW together).NOP - Use NOP instead of MOV R0,R0.Old PSR - Use the old PSR suffixes _ctl, _flg, _all.Wide - Disassemble for a wide display.HS and LO - Use HS and LO instead of CS and CC.Shift - Use x<<y comments where possible for numbers >= 8192. This affects arithmetic and logic instructions; y is restricted to multiples of 4 if possible, unless x=1.Lower - Force all register names to lower case.If a file is filetyped as Module (&FFA), Code mode will attempt to display useful comments instead of disassembling garbage for the module header.
AIF disassembly comes in two parts; firstly there's the part which isn't specific to AIF files, and secondly there's the part that is. The part that isn't is that when a disassembled offset (eg from an ADR) points to a string or some other pointer information, a useful comment is printed alongside. For instance, if you have ADR R0,<address> where <address> contains a string, the comment will be string: <string>. This system also puts comments for embedded debugging information (function names). The possibilities are:
func: <name> - C-style function name embedded prior to the function.-> code: <func> - C-style function reference; SharedCLibrary routines are identified in AIF files, where possible.-> code: at <address> - Unidentified code reference (no embedded function name).error: <string> - Reference to a standard error block (only when the ADR that finds the error is followed by an instruction which returns that error; only the string is shown).string: <string> - Reference to a string, where the destination contains no control characters but 10, 13 and 9.-> string: <string> - Reference to a string pointer.-> <header definition> - Reference to the header of the file; this should work in both AIF and Modules.-> ->... recursion: at <address> - A reference refers to itself (this isn't recursive, so it won't spot loops).-> ->... too deep: at <address> - References which would imply more than four arrows.The second part is that AIF files (recognised by SWI OS_Exit as the fifth instruction) have their headers given descriptive comments instead of disassembly garbage, much as for Modules. In addition, the bits of the header that are valid ARM code are also given useful comments.
The mode BASIC edits BASIC files directly in tokenised form. The mode BASTXT allows you to edit in detokenised form; however you need to load a BASIC file directly into it to detokenise it. Note that both these modes actually fiddle with the contents of the file to a greater or lesser extent to make editing easier - so you must save BASIC files from the same mode as you loaded them into. If you don't, you'll probably get garbage.
In its default setup, line numbers are displayed at the left hand side of the window, automatic renumbering occurs when needed, and all GOTO and GOSUB line number references are updated automatically. In addition, the mode will auto-expand keywords - for instance, typing P and then . will expand the P to PRINT. Unix tab mode also just advances to the next tab stop (spaces are inserted, and only then when you are at the end of a line; tab characters - ASCII 9 - cause problems in BASIC files).
The documentation that comes with ZapBASIC contains far more details about these modes that this section does (in particular, it describes the colours, of which there are an awful lot).
Once upon a time there was a BASIC editor called the ARM Basic Editor (ARMBE). This was single tasking, but at least it edited BASIC in tokenised form. If you want, Zap can emulate ARMBE fairly successfully (although you still have access to all the extended features).
First, turn on line editing (Edit->Misc->Line edit) and non standard editing (Edit->Misc->Non standard). The former will prevent you from editing across lines - you need to use SPLITLINE and JOINLINE (sF1 and cF1) to break up and reconstruct lines. The second strips spaces from the ends of lines as you type them.
These options are provided for those who are familiar with ARMBE, and don't want to take the time to learn a new system; the default options have both these turned off, because it tends to be much easier to edit BASIC (even tokenised BASIC) as close to the way you edit normal text as is possible.
To find out how to set these options permanently, see section 12.2.1.
ZapMJE provides a set of modes; in addition to a simple Pascal editing mode (not documented here), and an ARM Assembly editing mode (see section 10.6), there are three program source modes for languages with similar syntax. These are C, C++ and Java. The modes share a number of features, including bracket matching (the cursor momentarily flicks back to a bracket if you type its pair), syntax colouring, and smart auto indentation which tries to follow a sensible indentation style. If you don't like these, you can turn them off.
For information about all of these modes, see the documentation that comes with ZapMJE.
Assembler mode is another part of ZapMJE; it provides basic syntax colouring. This is done simply by highlighting the first column as labels, and the rest as instructions, picking out comments, strings, operators, names, numbers and brackets in different colours. It also uses the non standard option (see section 6.8) to alter the way the Tab key works; with it turned on, it creates three 'tab stops', one for instructions, one for their arguments, and one for comments. Thereafter it does the normal job of Tab.
For more information about Assembler mode, see the documentation that comes with ZapMJE.
This mode handles the files generated by Zap's search to buffer, C throwback and Find info output (as well as any other program which uses the throwback system). Double clicking on an item will jump to that item in the source file. Shift double clicking will jump to the item and then kill the throwback buffer. Clicking Adjust on a line will remove the line from the file. Triple clicking will move to the match and then bring the window to the front of the window stack.
Clicking on the title of a file, or on the blank lines surrounding it, will simply load the file. Adjust clicking on a file title will remove all throwback entries for that file.
Also note that Return acts in the same way as double click and Delete in the same way as Adjust for the throwback entry at the cursor.
Throwback mode provides simple colouring, colouring different types of messages and information differently. It has no support for, for instance, colouring the matched words in a throwback search.
This mode handles task windows. To create a new taskwindow, press cF12, or pick the appropriate option either from the Task manager iconbar menu, or from the Create submenu of Zap's iconbar menu.
Basically, a task window acts like the command line, only running in the desktop. It is vaguely similar to the Command Prompt under Windows. You can type in commands, and they are executed - if you have Olly Betts' Line editor loaded (see section 13.2.1), then you will have a command history available by pressing the arrow keys.
If you change mode, you will temporarily suspend the task - changing back to Taskwindow mode will resume it.
There are options on the mode's menu to suspend, resume, unlink, relink, and terminate and resurrect the task. When unlinked, the task will continue to run independently of the output window, changing mode will no longer suspend it, and closing the window or quitting Zap will no longer terminate it. This can be of use in low memory conditions. If a task window becomes permanently separated from Zap in this manner, it may need to be killed from the Task Manager.
The Die silently option allows you to kill the task without prompting simply by closing the window, for instance by pressing cF2.
The Bracket Matching option will cause the cursor to flick back briefly to a bracket if you type its pair.
More complete documentation is supplied with ZapBASIC, which contains the Taskwindow mode.
Email mode provides a powerful way to read and edit single emails (if you need to read or edit an entire BSD-style mbox, check out Newmail mode). It includes fancy things such as style-based emphasis recognition (like *this* etc.), header colouring, and a few automatic facilities. It also provides a button bar with access to many of the more common facilities.
Email mode will work happily with Messenger, TTFN, Marcel, GMail, Pluto and ArcWeb to supply email editing facilities.
You almost certainly won't be able to use Email mode straight off; you'll need to set it up so it knows which email system you use. See the documentation that comes with the mode for more information.
HoTMeaL is a syntax colouring mode for HTML. It currently supports HTML 3.2, and has a variety of useful commands, and a button bar, to assist in HTML editing. You can also drop files into HoTMeaL to create links - and with images, it will work out the relevant WIDTH and HEIGHT attributes.
For full documentation of HoTMeaL's features, see the supplied documentation.
The next section in the manual is chapter 11, which explains in more detail Zap's command language, including a look a functions, variables, and conditional and looping constructs.
Alternatively, you could move on to chapter 12, which looks at how to customise Zap to suit your specific needs.
Previous | Contents | Index | Next