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


1. 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.

ESGs of the font selection icons should be 1, 2, 3, 4 and 5, with the
'Regular font having an ESG of 1.

Icon   Meaning and special attributes
27-24  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     Regular (radio/option, ESG 1)
47     Bold (option, ESG 2)
48     Italic (option, ESG 3)
49     Underline (option, ESG 4)
50     Strikethrough (option, ESC 5)
50     Inverse video (option, ESC 6)


2. 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 using its usual path, 'Discard' abandons the file without
further notice and 'Cancel' abandons the dialogue box and closes it without
doing anything drastic.

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 orthodox
Zap save box.

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)


3. 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.

Icon	 Meaning and special attributes
0	 FS name (indirected 16, writable)
1	 Drive number (indirected 4, 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 12, never)
13	 Sector size (indirected 12, never)
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)
30	 Read disc (click)
29	 Read track (click)
28	 Read sector (click)


4. 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 10, never)
4	 Current x (indirected 12, never)
5	 Current y (indirected 12, never)
6	 Current address (indirected 10, never)
11	 Goto line (indirected 32, writable)
10	 Goto history menu (click)
12	 Goto button (click)


5. 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)


6. 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.

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 (never)


7. 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 4, writable)
	 Even numbers : Macro expansion (indirected 16, writable)


8. 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.


9. 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.  It may be configured to be 'pop up' or 'permanently
on display.  Pressing ESCAPE to leaves the minibuffer and closes it if
it is of the 'pop up' kind.


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


11. MoveBox
~~~~~~~~~~~
This box is used when the user wants to 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)


12. 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)


13. 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 over the current item to the next match.
2     Last     L	      Performs this replacement, and then stops.
3     Cancel   C, Q	      Cancels the operation and 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, or 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 have the type 'click'


14. PrintBox
~~~~~~~~~~~~
This box is used for 'fancy' printing operations using the printer drivers.
is the main method used for quick printing operations.  Printing uses the
outline font selected via the display menu.  Press 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 (option, ESG=0)
10	 Cancel window (click)
9	 Confirm print (click)


15. 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 (option, ESG 0)
1	 Start line (indirected 12, writable)
0	 End line (indirected 12, writable)
3	 Cancel window (click)
5	 Confirm print (click)


16. 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.

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


17. 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)


18. SaveBox
~~~~~~~~~~~
Saves the file.

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)


19. 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)


20. 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 128, never)
3	 Overwrite 'newer' version button (click)
5	 Cancel save (click)


21. 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)


22. 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)


23. 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)


24. 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)


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

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

