
			  Zap's dialogue boxes
			  ====================

This document is intended as a guide to the dialogue boxes Zap uses. Note
that it does not cover Zap's button bars, or dialogues provided by extension
modules, such as ZapSpell.

There are some notes provided to offer assistance people who want to adjust
the templates to suit their way of working.

Up to 11 different outline font and font size combinations may be used.

Justin Fletcher has now provided useful information about the icon numbers
which should be used. This information is not guaranteed to be 100% correct,
but it will be maintained if there are any changes to the templates.

The icons are NOT listed in numerical order because seldom is this the
logical grouping of the icons.


Alphabetic index by template name
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 1. CloneBox   - clone mode management;
 2. CloneCrBox - clone mode creation;
 3. ColourBox  - selecting colours;
 4. DyingBox   - when a main window's close icon is activated;
 5. DzapBox    - reading information from discs;
 6. GotoBox    - jumping directly to a line or viewing the cursor's location;
 7. InfoBox    - info box available from the icon bar menu;
 8. LoadBox    - this file has already been loaded and has been modified;
 9. MacroBox   - list of macros available in the search box;
10. Main       - main editing windows;
11. MiniBuf    - the minibuffer;
12. Mode_(n)   - determines the position of the specified mode.
13. MoveBox    - to allow navigation of discs;
14. MzapBox    - reading information from memory;
15. NextBox    - the options available when replacing information in a file;
16. PrintBox   - the 'fancy' printing options;
17. QuickBox   - the main quick printing options;
18. QuitBox    - there are modified documents and Zap has been asked to quit;
19. ReplaceBox - search and replace;
20. SaveBox    - save the file;
21. SaveCBox   - no path supplied for this file - save to CSD?
22. SaveOBox   - this file seems to be older than the one on disc;
23. SaveSCBox  - no path supplied for this selection - save to CSD?
24. SaveSelBox - save the current selection;
25. SearchBox  - searching;
26. UndoBox    - undo buffer being turned off;
27. WCBox      - box used to transmit simple numerical values to the user.


1. CloneBox
~~~~~~~~~~~
Used as a simple way to list, delete and hide clones, with a link to
CloneCrBox for clone creation.

Icon	Meaning and special attributes
2	The clone mode name (indirected 16, never)
3	The clone's base mode name (indirected 16, never)
4	Menu icon, associated with icon 2 (click)
5	New clone mode - opens CloneCrBox (click or release)
6	Delete clone mode - no confirmation required (click or release)
7	Hide clone mode - no confirmation required (click or release)
8	Close dbox (click or release)


2. CloneCrBox
~~~~~~~~~~~~~
Used to create new clone modes.

Icon	Meaning and special attributes
2	The clone mode name (indirected 16, writable)
3	The clone's base mode name (indirected 16, never)
4	Menu icon, associated with icon 3 (click)
5	Cancel - closes window (click or release)
6	Create - creates the clone mode (click) (shortcut = Return)


3. ColourBox
~~~~~~~~~~~~
Used to change the physical colour used for each of Zap's logical colours.

The 'ColourBox' is usually accessed through the main->Display->Colours menu.

It is produced by the COLOURLIST command.

The colour may be set in a number of ways, including selecting a colour from
the WIMP palette, typing in RGB values, and dragging sliders. If a colour is
not being selected from the available palette, then note that the colours in
the document are not updated dynamically, but only when the user clicks on
the 'Set' icon to confirm their choices.

Also available from this box, are the font 'sub-styles'. These allow
different logical colours to have different fonts associated with them in the
same document.

When designing templates there are a number of factors to bear in mind here:
When sub-styles are not appropriate, Zap minimises the window vertically, and
when they are present it maximises it. This is to allow the font style icons
to be placed along the bottom edge of the window. This means that you need
to set the minimum width and height parameters on the window correctly to
mask out the sub-style buttons. Zap will also grey out these buttons.

[ ESGs of the font selection icons should be 1, 2, 3, 4 and 5, with the
'plain' font having an ESG of 1. - why? ]

Icon	Meaning and special attributes
27-34	Wimp colours 0-7 (click)
8-15	Wimp colours 8-15 (click)
19	Red percentage (indirected 6, writable)
20	Green percentage (indirected 6, writable)
21	Blue percentage (indirected 6, writable)
16	Red drag bar, width should be the maximum extent (click/drag)
17	Green drag bar, width should be the maximum extent (click/drag)
18	Blue drag bar, width should be the maximum extent (click/drag)
35,36	Red down, up button (auto-repeat)
37,38	Green down, up button (auto-repeat)
39,40	Blue down, up button (auto-repeat)
25	Set button (click)
26	Colour box (never)
46	Plain (radio/click)
47	Bold (click)
48	Italic (click)
49	Underline (click)
50	Strikethrough (click)
51	Inverse video (click)


4. DyingBox
~~~~~~~~~~~
This is presented when a main window's close icon is clicked on.

There are three main buttons: 'Save', 'Discard' and 'Cancel'.

'Save', saves the file using its usual path, 'Discard' abandons the file
without further notice and 'Cancel' abandons the dialogue box and closes it
without doing anything drastic. 'Ok' confirms saving to the path in the
entered field. Ok is the default operation.

There are also a number of other icons closely resembling those available in
the Save Box.

Different templates may offer different possibilities. Cautious users may
prefer a large Cancel icon with the Save and Discard icons off to one side.
It is also possible to provide an icon which leads directly to the standard
Zap save box.

The Date and Time label icons will be modified by Zap to say Load and Exec 
respectively for untyped files. In this case, the Date and Time display icons
will be made writable.

Icon	Meaning and special attributes
16	Save file (click)
12	Discard - close window without save (click)
7	Cancel closing window (click)
0	Filename (indirected 256, writable or never)
5	File sprite (indirected 256, sprite only, len = 12)
11	Ok - confirm filename for save (click)
3	Type name (indirected 24, writable or never)
6	Type number (indirected 8, writable or never)
10	Type menu (click)
13	File size decimal (indirected 16, never)
15	File size hex (indirected 16, never)
1	Time (indirected 16, never)
2	Date (indirected 16, never)
14	'Go to save box' (click)
8	Label for Time (indirected 8, never)
9	Label for Date (indirected 8, never)


5. DzapBox
~~~~~~~~~~
This is for reading information from discs.

The filing system name should be entered (CASE SENSITIVE) and then return
pressed. Zap will then calculate the default drive number on your behalf.

Information may be read from the disc in the sizes of sectors, cylinders or
whole discs. One of the Disc or Sector address label buttons will be flagged
as deleted by Zap as appropriate.

Icon	Meaning and special attributes
0	FS name (indirected 16, writable)
1	Drive number (indirected 4, writable)
2	Sector to edit (indirected 12, writable)
3	Head to edit (indirected 12, writable)
4	Track to edit (indirected 12, writable)
5	Address to edit (indirected 12, writable)
10	Number of hard discs (indirected 4, never)
9	Number of floppy discs (indirected 4, never)
27	Disc name (indirected 12, never)
21	Tracks (indirected 12, never)
16	Sectors (indirected 12, never)
18	Size of disc (indirected 18, never)
13	Sector size (indirected 12, never)
30	Read disc (click)
29	Read track (click)
28	Read sector (click)
31	Cancel (click)
25	Label for Disc address, beside 5 (never)
33	Label for Sector address, also beside 5 (never)


6. GotoBox
~~~~~~~~~~
Used to jump directly to a line or for viewing the cursor's location. The
logical line number, physical co-ordinates and address within the file are
displayed and updated as the cursor moves.

Icon	Meaning and special attributes
7	Logical line button (radio, ESG 2)
8	Co-ordinates button (radio, ESG 2)
9	Address button (radio, ESG 2)
3	Current line (indirected 16, never)
4	Current x (indirected 16, never)
5	Current y (indirected 16, never)
6	Current address (indirected 10, never)
11	Goto line (indirected 32, writable)
10	Goto history menu (click)
12	Goto button (click)


7. InfoBox
~~~~~~~~~~
The info box is available from the icon bar menu, or via the INFOBOX command.
It has a button which displays the authors of any currently loaded modes.

Icon	Meaning and special attributes
3	Open list of currently installed modes and authors (click)
4	Version info (indirected 28, never)


8. LoadBox  
~~~~~~~~~~
This is a warning box which is displayed if the user tries to load a file,
and another copy of it has already been loaded and modified.

The user may load the new file, cancel the operation, bring the existing file
to the front of the window stack, or overwrite the existing modified file
with the new copy.

Note: This window doesn't get the focus, so there is no default operation.

Icon	Meaning and special attributes
6	Bring window to front (click)
5	Cancel load (click)
4	Overwrite old file (click)
3	Edit this one as well (click)
1	Filename (indirected 256, never)


9. MacroBox
~~~~~~~~~~~
This box displays the Macros which may be used in the 'search' and 'search
and replace' operations.

Icon	Meaning and special attributes
3-34	Odd numbers  : Macro sequence (indirected 8, writable)
	Even numbers : Macro expansion (indirected 24, writable)


10. Main
~~~~~~~~
This controls the type of main window used by Zap. It is not useful to edit
most aspects of the window, but the title-bar foreground colour may be
modified - this also has the effect of altering the left-hand side border of
the window - which can be useful.


11. MiniBuf
~~~~~~~~~~~
This is Zap's minibuffer. It may be dragged with SELECT to alter its position
on the screen, or - if it is dragged near its right hand edge - it will
resize itself. The resize extent is limited by that of the maximum x extent,
so you should probably set this to a large number (eg 10000). It may be
configured to be 'pop up' or 'permanently on display. Pressing ESCAPE leaves
the minibuffer and closes it if it's configured as 'popup'. 


12. Mode_(n)
~~~~~~~~~~~~
Used to determine where windows in mode (n) open. There may not be any of
these templates present by default.

(Only useful for the built-in modes.)


13. MoveBox
~~~~~~~~~~~
This box is used when the user wants to navigate data read directly from
disc, tracks and sectors.

Icon	Meaning and special attributes
3	Move to previous cylinder (click)
4	Move to next cylinder (click)
5	Move to previous track (click)
6	Move to next track (click)
7	Move to previous sector (click)
8	Move to next sector (click)
9	Bring window to front (click)
10	Cancel MoveBox (click)


14. MzapBox
~~~~~~~~~~~
This box is used when the user wants to read information from memory.

The memory to be read may be chosen by:
Dragging the 'switcher' icon to a window/icon belonging to the task you want;
Entering the memory addresses directly; or
Dragging the icon to a Zap taskwindow to read the taskwindow's memory.

Icon	Meaning and special attributes
8	Draggable icon for selecting tasks (click/drag)
0	Start address (indirected 12, writable)
1	End address (indirected 12, writable)
2	Task name (indirected 24, never)
7	Grab button (click)


15. NextBox
~~~~~~~~~~~
The options available when replacing information in a file;

Icon	Option	Shortcuts	Description:
0	Replace R, M, Return	Replaces the highlighted text.
1	Skip	S, N		Skips the current item.
2	Last	L		Performs this replacement, and then stops.
3	Cancel	C, Q		Cancels the operation & closes the dialogue.
4	Undo	U		Undo.
5	Redo	D		Redo.
6	All	T, A, E		Replaces from the current match to the end of
				file, start of file if searching backwards,
				or all files if searching all files
7	In sel	I		Replaces all matches which start inside the
				current selection (working in the direction
				of the search).
8	Front	F		Brings the window to the front.

All should be of type 'click'.


16. PrintBox
~~~~~~~~~~~~
This box is used for 'fancy' printing operations using the printer drivers.
Printing uses the outline font selected via the display menu, and optionally
the colours defined for the window from which you're printing. Click on
'Print' to start printing.

Icon	Meaning and special attributes
5	Number of columns per page (indirected 12, writable)
1	Start page (indirected 12, writable)
0	End page (indirected 12, writable)
11	Number of lines per column (indirected 12, never)
13	Number of pages (indirected 12, never)
14	Use colour (option, ESG 0)
15	Printer driver name (indirected 21, never)
7	Portrait (click, ESG 2)
8	Landscape (click, ESG 2)
6	Heading on each page (radio, ESG 0)
10	Cancel window (click)
9	Confirm print (click)


17. QuickBox
~~~~~~~~~~~~
This box is the main method used for quick printing operations. The RISC OS
Printer drivers are not required for this operation, as the text is sent to
the printer directly.

The start and end lines of the print may be controlled here, and the page
header which Zap adds may be suppressed.

Icon	Meaning and special attributes
4	Header with file info (radio, ESG 0)
1	Start line (indirected 12, writable)
0	End line (indirected 12, writable)
3	Cancel window (click)
5	Confirm print (click)


18. QuitBox
~~~~~~~~~~~
There are modified documents and Zap has been asked to quit. The user may
opt to abandon any documents, bring them to the front of the window stack,
or cancel the operation.

Note: Quit is the default option for this window (weird though it may be)

Icon	Meaning and special attributes
4	Bring altered window to front (click)
3	Cancel quit (click)
2	Quit anyhow (click)


19. ReplaceBox
~~~~~~~~~~~~~~
Used to search for sequences of text and replace these with other sequences.

Icon	Meaning and special attributes
25	Raw search - spans linebreaks (option)
26	Case sensitive search (option)
27	Use macros (option)
28	Allow '\' commands (option)
8	Search from start (radio, ESG 3)
9	Search forwards from position (radio, ESG 3)
10	Search backwards from position (radio, ESG 3)
11	Search all files (option, ESG 3)
12	Don't bother asking the user (radio, ESG 0)
15	Search string (indirected 128, writable)
16	Replace string (indirected 128, writable)
18	Search history menu (click)
19	Replace history menu (click)
20	Copy button - copies search into replace (click)
1	Count button - counts matches (click)
3	Results of any count ESG determines if pop-up is used (never)
17	Do replace (click)
29	Cancel (click)
14	Open macro edit window (click)


20. SaveBox
~~~~~~~~~~~
Saves the file.

The Date and Time label icons will be modified by Zap to say Load and Exec 
respectively for untyped files. In this case, the Date and Time display icons
will be made writable.

Icon	Meaning and special attributes
0	Filename (indirected 256, writable or never)
5	File sprite (indirected 12, sprite only, len = 12)
11	Ok - confirm filename for save (click)
7	Cancel save (click)
3	Type name (indirected 24, writable or never)
6	Type number (indirected 8, writable or never)
10	Type menu (click)
13	File size decimal (indirected 16, never)
15	File size hex (indirected 16, never)
1	Time (indirected 16, never)
2	Date (indirected 16, never)
8	Label for Time (indirected 8, never)
9	Label for Date (indirected 8, never)


21. SaveCBox
~~~~~~~~~~~~
No path has been supplied for this file - the option to save it to the
currently selected directory (CSD) is presented, or the operation may be
cancelled.

Icon	Meaning and special attributes
0	Filename (indirected 128, never)
3	Save to CSD button (click)
5	Cancel save (click)


22. SaveOBox
~~~~~~~~~~~~
An attempt is being made to save a file which appears to have a timestamp
which is older than the timestamp of the file it is being saved over - this
may be a mistake, and Zap queries the operation.

Icon	Meaning and special attributes
0	Filename (indirected 256, never)
3	Overwrite 'newer' version button (click)
5	Cancel save (click)


23. SaveSCBox
~~~~~~~~~~~~~
No path has been supplied for this selection - the option to save it to the
currently selected directory (CSD) is presented, or the operation may be
cancelled.

Icon	Meaning and special attributes
0	Filename (indirected 128, never)
3	Save to CSD button (click)
5	Cancel save (click)


24. SaveSelBox
~~~~~~~~~~~~~~
Save the current selection.

Icon	Meaning and special attributes
0	Filename (indirected 256, writable or never)
5	File sprite (indirected 12, sprite only, len = 12)
11	Ok - confirm filename for save (click)
7	Cancel save (click)
3	Type name (indirected 24, writable or never)
6	Type number (indirected 8, writable or never)
10	Type menu (click)
13	File size decimal (indirected 16, never)
15	File size hex (indirected 16, never)
1	Time (indirected 16, never)
2	Date (indirected 16, never)


25. SearchBox
~~~~~~~~~~~~~
Used to search for particular sequences of text.

Icon	Meaning and special attributes
25	Raw search - spans linebreaks (option)
26	Case sensitive search (option)
27	Use macros (option)
28	Allow '\' commands (option)
8	Search from start (radio, ESG 3)
9	Search forwards from position (radio, ESG 3)
10	Search backwards from position (radio, ESG 3)
11	Search all files (radio, ESG 3)
12	Place results in a throwback window (option, ESG 0)
15	Search string (indirected 128, writable)
18	Search history menu (click)
1	Count button - counts matches (click)
3	Results of any count - ESG determines if pop-up is used (never)
16	Do search (click)
29	Cancel (click)
14	Open macro edit window (click)


26. UndoBox
~~~~~~~~~~~
Displayed when the undo buffer is being turned off.

Icon	Meaning and special attributes
3	Cancel turning undo off (click)
2	Confirm undo off (click)


27. WCBox
~~~~~~~~~
Box used to transmit simple numerical values to the user.

Icon	Meaning and special attributes
0	Number (indirected 13, writable)
