 | Documentation Latest release ZapRedraw Contact Download |
 |  |
 | |
Previous | Contents | Index | Next
Now we will look at configuring Zap; as has been mentioned several times before, you can customise many of the features of Zap. Here we'll show you how. Note that some areas of configuration are substantially less complex than others; some, introduced in the first few sections (up to and including section 12.2.1), are both fairly simple and incredibly useful - you'll almost certainly want to read these at least briefly now. Later ones get increasingly complex - the last few sections of this chapter describe how to completely reconfigure how Zap deals with different filetypes; how to reconfigure all the keystrokes; and how to define Zap's menus! You're unlikely to need these features straight away - so you might want to skip the second part of this chapter until you have a need for these facilities.
Zap uses two distinct types of configuration, known as textual configuration files and binary configuration files. You don't really need to know why, but you do need to know what it means. The first options we'll look at are all handled by the binary configuration system, and these are options you can set up from inside Zap. This means that you can change them while it's running, experiment with the settings until you have them right, and then save them so you'll have the same options next time. The second set of options (from section 12.3.1 onwards) are part of the textual configuration system. To edit these, you'll need to load the relevant configuration file into a text editor, edit them to make the alterations, save them - and then you need to get Zap to reload them.
All configuration options are stored within one place - ZapUser. As noted in section 2.2.1, in the installation notes, this means that you can carry your own options around with you, even while using Zap on a different computer.
If you don't like the default configuration, but don't want to get your hands dirty trying to set things up yourself - or want to save some time by starting with a configuration closer to what you want - then you might like to look at the alternative configuration sets available from the Zap ftp site. Due to time constraints, these may not be as 'pure' as is ideal - it would be nice to have an Emacs-like configuration, an Edit-like configuration, a StrongED-like configuration, and so on - what you will actually probably find is that the various developers have simply packaged up their own configuration sets, including whatever bizarre (and sometimes fairly specific) needs they have. Nonetheless, they should be useful to someone - in particular, they may well show some of the more sophisticated things that can be done with Zap.
Complete replacement configuration setups come in the form of a copy of ZapUser; you should follow the instructions in the installation guide to change configuration sets - see section 2.2.1 for more information.
For more information, see http://zap.tartarus.org/download.html, or go straight to the FTP site at ftp://zap.tartarus.org/pub/configs/.
Here we look at the binary configuration options. These can all be edited within Zap, so you can experiment with them until you're happy, then save them so they'll be the same next time.
Something we've been mentioning through the manual is that many of the options can be set on a per-mode basis; that is, that each mode can have these options configured independently of all the other modes. In addition to all the colours, the following options can be configured per-mode:
There are two main ways of configuring these options. Firstly, and probably most usefully, you can change the options for a particular window, and then copy those options across to become the defaults for that mode. You do this with the Misc->Set default options menu item. Note that this won't save those options - merely set them up as the defaults. To save the current default options, you either need to use Options->Save options from the iconbar menu, or Misc->Set default options->Save defaults from the window menu.
This system can be extended slightly - since each window 'remembers' the options it has for each mode, you can set up the options you like in all the modes using one window, and then set the default options for all modes from this one window in one go. Use Misc->Set default options->All modes to do this. (Note that this doesn't save the options.)
The only options that won't be copied across in this way are the read only attributes. This is because it would be rather irritating if every file were opened read only - doubly so if they were opened permanent read only, because then you couldn't make them writable again at all.
The second method is via the iconbar menu. The Options submenu has a number of submenus and options; the important ones here are Mode, Edit and Display - the mode selected in the Mode submenu is the mode for which you are configuring options (and the mode-specific options can be configured through this submenu), and the current settings in Edit and Display are its current defaults. You can therefore change the options for any mode by first switching Options->Mode to the relevant mode, then changing the options in Options->Edit and Options->Display.
Once finished, you should always change Options->Mode back to whatever it was before - this is known as the 'default mode', and is used when Zap doesn't know what mode to drop a file into - and also as the mode when you load a file whilst holding down Control. In general, you probably want this to be either Text or Byte. Note that the default mode is actually a textual configuration option - once Zap is loaded you can change it from the iconbar menu, but you can't change the default setting without editing one of the textual configuration files. See section 12.3.1 for how to do this.
Again, changing options in this way doesn't save them - use Options->Save options to make these new defaults permanent.
Several of Zap's modes are fairly non-specific; they can be used to edit a variety of different types of file. For instance Text, Byte HalfWord, Word and DoubleWord modes assume very little about the content of the file - unlike Code, Email or HoTMeaL (the HTML mode), for instance. Consequently you may want to use them in different situations with different default settings.
The way to do this is to create a clone of the mode. This is an exact copy of a mode, given a different name, and which you can configure differently. A cloned mode is used exactly as you would a normal mode.
Clones are managed via Options->Clone modes... from the iconbar menu. This opens a small dialogue box which lists the current clones you have (as Zap is supplied, there are no clone modes). The top half of the window allows you to select the different clones you have, to see which mode they are based on, and to Delete and Hide the one currently being shown. Deleting a clone will also delete its options; only do this if you won't need them again! Hiding a clone removes it from currently loaded modes; since Zap can only cope with thirty two modes loaded at one time, this allows you to work with many more clones.
To create a new clone, click on New in the dialogue box. This creates another small dialogue allowing you to enter the new clone's name, and to select which mode you would like the clone to act like. Currently, in addition to the core modes Text, Byte, HalfWord, Word, DoubleWord, ASCII and Code, only Email mode can be cloned - and clones themselves can be cloned. Clicking on Create will create the clone, set up initially with the options of the base mode you selected.
Cloned modes show up in blue instead of black in the mode menu. Non-core modes (such as Email) show up in grey.
Clone don't appear on Mode->Load mode in the main window, or Options->Mode->Load mode in the iconbar menu; instead, they have their own Load clone submenu.
As with all binary options, you must remember to save Zap's options (Options->Save options from the iconbar menu) once you have made alterations to your clones - otherwise you will lose them when you quit Zap.
You may remember that Zap has four different cursors - the usual editing cursor, two cursors used when you are in copy mode, and a 'mark' cursor to indicate where the cursor would be in a window that doesn't have the focus. (See section 3.3.1 for more information.) You can configure how these are drawn from Options->Cursor types; each can be set to any one of block, square, underscore, bar or none; they all should be fairly self-explanatory.
You can configure how the minibuffer works from Options->Mini buffer; you can set the foreground and background colour, whether the system font (the alternative being the desktop font) is used under RISC OS 3.5 or later (or the soft-loadable 'nested wimp'), and whether the minibuffer is permanently available, or just pops up when needed.
Zap has a variety of miscellaneous options which you can set on or off. They are configured through Options->Misc, and are as follows:
Auto-delete files - Auto-delete files when the last window is closed; if not, files will hang around until you remove them directly using Files->Remove or Files->Close on the iconbar menu.Auto-clear regions - Automatically clear the selection when you do anything which doesn't use the selection (this is like various word processing and DTP packages).Undo supported - Whether undo is supported for all newly-created or -loaded files.Flashing cursor - Whether Zap's editing cursors flash - you can also configure the flash rate (see section 12.3.1).Check datestamp - Warn if you try to save to a file where the copy on disc is newer than the file you're trying to save (this can cause problems if saving over a network where the clocks on the different computers aren't properly in sync).Auto-clr search - Clear the search window each time it is opened.Confine cursor - Confine the cursor so that when you scroll a window it remains in sight.Trap MSDOS files - Recognise files with MSDOS and Spool file line endings, and take appropriate action.Be tolerant - Be tolerant of other applications which use broken Wimp messages; some applications, including Fresco, may not function properly with Zap unless this is turned on.Silent operation - Don't beep.No anti-aliasing - Don't use anti-aliasing when using DSA outline font redraw; sometimes it can look messy, so turning it off makes things easier to read.Remove H scroll - Avoid having a horizontal scrollbar when it isn't needed - it will be turned off when window wrap mode is turned on, and also when the window is at its fullest extent. The latter will only happen under the 'nested wimp'.Force startup command - Forces the startup command to be executed even if files are being loaded on startup. See section 12.3.1 for more information.Minibuffer autowidth - Sets the width of the minibuffer to match the width of the window it's being used with. Otherwise it will use the width set for it in the Templates file (which isn't terribly useful).Zap has a number of 'internal' extensions, introduced in section 13.2, which it can load automatically when it thinks it needs them. None of these is essential, but they can make life easier in some cases. Whether they are automatically loaded or not is configured from Options->Misc->Autoload (Zap will use them if they weren't set to be autoloaded, but were loaded for some other reason - for instance by the user, or by another application).
Here we look at the different options that are part of the textual configuration system. This is all accessed through the bottom part of the Options submenu from the iconbar. Firstly, you can open any textual configuration file using the Options->Edit config submenu - and you can open the directory containing all of them by selecting Options->Edit config itself.
Secondly, you reload the settings using Options->Reload keys. This will work for everything except the filetypes configuration, where you have to rebuild all the options first (this is because, in addition to the user-specified filetype configuration, each mode can tell Zap which types of file it knows about) - do this through Options->Create keys, and then use Options->Reload keys to get the new options.
Except for the Menus file, all the textual configuration files use the same format. Any non-blank line defines a single key variable, and is of the following form.
<comment> &xxx <value>
The comment is any text without an ampersand (&) character in it. Any line without an ampersand in it is discarded completely. The &xxx is known as the key number, and dictates what the value is actually used for. For instance, it might be a particular setting, or it might be a key binding.
The Settings file is divided into two sections: firstly Zap's search macros. These have key numbers &200 to &20F; the value is of the form macro_string replacement_string, with the strings separated by whitespace. The macro string can be up to seven characters, and the replacement string up to 23 characters.
The second part of the Settings file is various miscellaneous options. They are as follows:
INSERTDATE (scD) command; see OS_ConvertDateAndTime for details of the format string.INSERTTIME (scT) command.GSTransed first.x,y).GSTransed first.GSTransed first.Force startup command option is enabled. This variable may be useful for NCOS users.There are two filetype configuration files: Types (low) and Types (high). Typically you should put user configuration things in Types (high). Types (low) is intended for default filetype recognition for the core of Zap (extension modes that handle filetypes have their own filetype configuration files).
These files contain two types of variable. Firstly, &1xxx variables (which also includes &2000), which affect which mode files of a particular type are loaded into, and secondly &5xx variables, which affect which mode files with certain filenames are loaded into. Both have a similar final part, which is the command. This is of the form [+]<mode name>[:<command(s)>].
The mode name indicates which mode a file will be loaded into if it matches this rule; the optional +, if present, will cause the file to be loaded even if Shift is not held down. The command(s) after the mode name, if present, will be executed after the file is loaded. For instance, the default configuration has the following command for all files of type &100: Byte : STARTADDR 55; files of this type are loaded into Byte mode, and then the command STARTADDR 55 is executed. There is no '+', so you have to either drag the file to Zap's iconbar, or double click it while holding down Shift (left Shift on RISC OS 2).
Now we'll look at the two different sorts of rules. The first is a very simple rule: is the file of a certain filetype? We use the &1xxx variables for this - they have the form <comment> &1xxx <command>, where command is as above, and comment is as usual. The xxx specifies which filetype this rule matches, in hexadecimal. Use the key variable &2000 to match untyped files.
The second possible rule is more complex. These are the &5xx variables, and they work by trying to match the complete filename against a Zap search string. The format is <comment> &5xx <filetype> <path> <command>. Comment and command are as above; path is a normal Zap search expression (see chapter 8 - note that macros won't work, but \-commands will). The xx here is completely irrelevant - typically you would have all your &5xx variables actually using &500 as the key number. The command is executed only if both filetype and path match; a filetype of -1 can be used to match all filetypes.
As an example, consider the following from the default configuration:
&500 &FFD \\ #\\*.o.\\o\\* +Code
This will load any file of type &FFD (Data), that is within a directory called o, into Code mode. (ie: it ensures that object files, as produced by C compilers and similar, will be loaded into Code mode). The + ensures that it will be loaded without needing to drag to Zap's iconbar, or to hold down Shift.
Remember that you must run Options->Recreate keys before reloading to get changes to the filetypes configuration to work properly.
The Keys file defines Zap's base keymaps: in addition, extensions can have their own Keys files in the extension directory so that keymaps that are useful only to individual extensions don't need to be supplied with the main Zap distribution.
Each keymap is introduced by an &800 key variable, with the exception of the first keymap in the Keys file, which is the default. (Note that this only applies to Zap's core Keys file - per-extension files cannot contain default keymaps, and must have all their keymaps introduced by an &800 variable.) The value of an &800 variable is actually four values; it looks as follows.
<comment> &800 <low> <high> <name> <base>
<low> and <high> define the range of the keymap, in keycodes - for keypresses outside that range, the keymap will do nothing. <name> is the name of the new keymap; this name is used on the Misc->Keymap menu, and by the KEYMAPN and BASEMAPN commands. <base> is the name of the base for this keymap - any keycodes that are not defined in the keymap, but which fall within the range of the keymap, are inherited from this base keymap.
The key variables &000-&1FF define the keymap itself; the value is the command or commands (:-separated, as usual) to be executed on that keycode - we'll go into this in more detail in a minute.
The keymap used as the base map for any mode which doesn't choose its own is given by key variable &400. Base maps for modes can be set using the configuration variable Basemap - see section 12.3.6 for more information about configuration variables.
Keycodes are based on those returned by Wimp_Poll; thus function keys return &180-&1FF, as documented in the PRMs. (Look at the Keys file if you don't have a copy of the PRMs - or get the WimpKeys manual for StrongHelp. Standard characters return their ASCII values &20-&FF as usual. &7F is unshifted Delete. Additionally, Zap augments these basic values to allow, for instance, to have scD and cD doing different things. These are documented in Docs.Technical.E-Keycodes.
To make life easier, you can define a range of keycodes in one line, simply by specifying the range instead of a single keycode. For instance, to map F1-F8 to insert Please don't press this key again, use something like:
F1-F8 &181-188 INSERT "Please don't press this key again"
There are a number of special substitutions which happen for keycode definitions, both in the base keymap and in subsequent ones. Firstly, if you use n instead of the numeric parameter to a command, it will be replaced by the keycode. For instance:
Ascii chars &020-7E CHAR n
in the default keymap makes sure that typing a character will insert that character.
Secondly, instead of a command you can use *<n>. Here, the command will be taken from the keycode n. If you omit the n (ie: just use *), then the keycode used will be the keycode you are currently defining, in the base keymap (for instance, in the Emacs keymap, we have:
&01E-14E *
which defines most of the Emacs keymap to be the same as the Default keymap that it inherits from. If you use this substitution in a keycode range, it will work in the most sensible way: for instance, in the base keymap the keypad numbers are mapped to do the same as the number keys using:
k0-k9 &1C0-1C9 *&30
If you want to stop a keystroke from being passed on, bind NULL to it. Try to avoid binding anything to F12, because it will stop you easily accessing the command prompt.
It is possible to configure the Alt+double click behaviour of Zap from the ClickSend file. This uses key variables &6xx (as with the &5xx variables, the xx doesn't matter and you should usually use &600 for all of them). The format is documented at the header of the file, and is fairly difficult to explain in any other way. In general you won't need to alter this, but if you do it's probably advisable to talk to Darren Salt, author of the Click Send system, if you start running into problems. See section 15.4 for details of how to get in touch with Darren.
Zap's Menus file defines all the menus that Zap uses. The format is fairly simple: any line starting with '|' is treated as a comment and is discarded; blank lines are also discarded. The file then starts with a single initial line which specifies the number of valid menu handles (so you need to set this to at least as many menus as you define, or some of them won't load). After this are a series of menu definitions.
Each menu definition contains a declaring line of the form:
<handle> <name>
The name must be given in quotes. In Zap's actual Menus file, handles are numbers that start at zero, with the first twenty (0-19) reserved for internal use (see below). However it is more convenient to work from a 'source' format, where the handles are names instead of numbers - symbolic handles start with a dot (.). Zap is supplied with a program called MakeMenus which generates the actual Menus file from the source file; it lives in ZapCode:Tools.MakeMenus, which also contains more detailed documentation. Source menus files live in ZapUser:Config.Menus.Source.
In addition to allowing handles to be names instead of numbers, MakeMenus provides a preprocessor vaguely similar to that used by C compilers. This allows a source file to provide various options which can be turned either on or off when generating the real file. Zap is supplied with a program that gives a simple text interface to configuring these options, called MenuConf (which also lives in ZapCode:Tools.MakeMenus.
In order to work, MenuConf requires a block somewhere in the file describing the options supported by that file. The block is of the form:
| Start options | [*]<option name> <description> ... | End options
A star (*) at the start of an option name indicates that the option is turned on in the default configuration. The delimiter lines (| Start options and | End options must be preserved exactly. See ZapUser:Config.Menus.Source.UK for an example with plenty of options.
The Options->Edit config->Menus submenu from the iconbar contains three options which use this: Menus source opens the source file for the current country, Run MenuConf allows you to select which of its options are enabled and disabled, and generates the real file, and Rebuild defaults rebuilds the default menus for the current country.
The following menu handles are reserved for internal use, and are listed here with the symbolic names that MakeMenus supports.
Zap.IconbarZap.WindowZap.FiletypesZap.FontsZap.SelectionMode.ThrowbackMode.ByteMode.WordMode.CodeMode.HalfwordMode.DoublewordAfter the declaration for a menu is a series of lines giving the items in it. Each of these must be indented by a single tab character (ASCII 9).
Text [<command>] [> (<command> | <menu handle>)]
The text must be quoted; the first command is executed if the menu item is selected by the user. Anything after a > character defines a submenu - either give a command which can supply a submenu (any command that takes a string parameter can be used as a submenu; in addition, some commands specifically create submenus), or give a valid menu handle to use as the submenu.
If you need to, you can specify Wimp help text for each menu and menu item. This is done using a line of the form:
* Text
The line should come immediately after the entry it describes. To supply default help for a menu, place the help line first in the menu definition (before any menu entries). The text must be quoted.
If you want to use a command which isn't part of the core, you can do so; it won't be loaded until it's actually needed. This allows you to have very flexible menus, without a huge memory overhead of loading all the extensions when Zap starts up.
To get a separator line in a menu, use a line containing a tab character (ASCII 9) followed by a hyphen -.
See the supplied Menus file, and the supplied source files, for examples on how this all fits together; it's actually a lot easier to use than to describe!
Note that it is impossible to get Zap to reload its menus. In order to get edited menus in Zap, you'll have to quit and restart it.
Configuration variables (or c-vars for short) are Zap's way of allowing the same command or feature to function in different ways depending on the mode you're in. Each mode within Zap can have a Textual Mode File, or TMFTMF for short, which defines the c-vars for that mode.
For a mode <name>, its TMF is looked for first as ZapUser:Config.TMFs.<name>, and then in the file given the system variable Zap$TMF_<name>. Core modes and clones will typically just have their TMFs in ZapUser:Config.TMFs; other modes will usually have their default TMFs within their application directory: you should copy them into ZapUser:Config.TMFs and edit there to override their options.
The format of a TMF is as a MessageTrans file (the same format as used for Zap's internationalised messages files - see section 12.4 for internationalisation issues). This means that lines starting with a # character are treated as comments (ignored), and that all other lines must be of the form:
<variable>:<value>
The value is subjected to interpolation to find the final value; this allows the values of other c-vars to be used within the definition of any given c-var (although care must be taken to ensure that you don't indirectly include the value you are trying to define, or Zap may enter an infinite loop while trying to figure out what to do!).
The syntax for interpolation is /<modename>:<variablename>/, where both <modename> and <variablename> are optional - although at least one must be present (otherwise you're trying to include yourself!). If either is missing, it will be filled in with the appropriate value for the variable being defined - so /:<variablename>/ will expand to the value of <variablename> in the current mode, and /<modename>:/ (or /<modename>/) will expand to the value of the current variable in mode <modename>.
In addition, <modename> can be either one of the special characters ^ (meaning the parent of the current mode) or @ (meaning the current mode).
This means that the / (slash) character can't be inserted directly into the value of a c-var. To get around this, the \ (backslash) character 'escapes' the following character - so ab\cd is equivalent to abcd, and ab\/d will come out as ab/d.
A few examples should explain things:
HelpSearchPath:MySearch,/C++/
Sets the value of the c-var HelpSearchPath to MySearch,<foo> where foo is the value of HelpSearchPath in C++ mode.
SetNameStart:\\<\/* >
Sets the value of the c-var SetNameStart to \</* >.
Any c-vars not listed for a given mode will be inherited from the mode's parent. For instance, if the variable TestVariable is defined in Text mode, but not in C mode, using it within C mode will actually use the value given for Text mode - because C mode is derived from Text mode. What this means is that if you want to set a c-var once for all modes, you should put it in the TMF for Text mode (since all modes are derived from Text mode).
Note that c-vars for cloned modes inherit from the clone's base, and not from the clone's base's parent. So if, in the example above, we clone C mode as D, and then give TestVariable a value for C mode that is different to its value for Text mode, when we use TestVariable in D mode, the value from C mode will be used (which is more or less what you'd expect). C mode will still inherit variables from its parent, in this case Text.
c-vars are case-sensitive. When developing your own features using c-vars, please remember that mixed-case c-vars (eg: HelpSearchPath, SetNameStart) are reserved for 'official' use - ie for features that have been finished. While developing new features, either prepend _ (underscore) to your c-var name, or use all upper or all lower-case.
In order to get help on a c-var, use the HELPVAR command, or type c\ v and type in the c-var name.
In the future, c-vars will be able to be set on a per-file basis. Currently this isn't possible.
As it is supplied, all Zap's communication with you will be in English. However there is support for complete and relatively painless translation to other languages. In order, Zap will use the system variable Zap$Country, the system variable Sys$Country or "UK" to determine which country it needs to run for.
To make life easier, Zap has a single file, ZapUser:Config.Country, where you can set the country to use. By default, the line to set this is commented out, so Zap will use your system setting - only change this if you want to force Zap to use a different country.
If a particular part of Zap isn't available in the country you choose, Zap will use the English (UK) version instead. Currently much of Zap's core distribution is supplied for France and Germany as well as the UK (see section 15.3).
Due to different features supplied by different versions of RISC OS itself, Zap has a few issues which alter depending on which operating system you are using. Note that as of v1.45, Zap no longer supports RISC OS 2.
Zap uses dynamic area storage for files and fonts from RISC OS 3.5; it uses the Wimp Slot in earlier versions of the operating system. (Note that there is a utility called Dummy Dynamic Areas, which supplies dynamic area support for earlier operating systems; Zap will use this if it is present.)
Note that there is a bug in the ROM fonts supplied with some versions of RISC OS 3.7 (notably for the A7000+), which means that the OldStyle template set doesn't work properly (it can spontaneously reset the desktop font to the system font). This problem does not affect the Default template set.
In theory, Zap should work on NCOS (Network Computer Operating System - as used in Acorn's NetStation, and other similar products). There are two issues: firstly, the iconbar under NCOS is hidden until someone puts an icon on it; Zap supports a -noicon option to prevent it from doing this, and a command INSTALLICON to place an icon on the iconbar if it hasn't already done so. However -noicon isn't used as standard under NCOS; you'll have to edit !Zap.!Run (!Zap.!Run,feb) to get this behaviour. Secondly, since NCOS has no Filer, loading files is more tricky - particularly so if you don't have an iconbar icon either. The settings variables &322, which allows you to specify a command to run at startup, can be set to NEWFILE (Text &FFF) to open a blank text file automatically in this case. You can then use FINDFILE (F2) to load files.
The authors are uncertain about the utility of Zap under NCOS in any case; however if you have any difficulties with Zap on NCOS (or any information about its being useful :-), please get in touch (see section 15.4).
The next section in the manual is chapter 13, which introduces a number of useful extensions to Zap. In particular, it looks at ZapSpell (an interface to the Computer Concepts' spell checker), and introduces Olly Betts' invaluable line editor.
Alternatively, you could move on to chapter 14, which you should read if you want to help with Zap development, whether in a technical or non-technical role.
Previous | Contents | Index | Next