*************************************************************************
* >E-Windows	Documents a Zap window block format.			*
*************************************************************************

By convention, window blocks are pointed to by R8. However, as with files,
the pointer address may change whenever a window is created. Thus, as for
files, block pointers should be changed to window offsets for storing. Use
the calls Zap_GetWindOff, Zap_ConvWindOff. The first two paragraphs of E-File
hold if you replace 'file block' by 'window block' and R9 by R8. Please read
the E-File file first.

Window block offsets have names beginning 'w_'. See E-Library for a complete
list. Each window determines uniquely a file via the offset w_file.

As far as Zap and the extension modes are concerned, a Zap text window
consists of a rectangle of characters. Coordinates are usually given in terms
of row and column in R2,R3. Ie, by convention,

	R2=column offset from left hand edge, in characters.
	R3=offset in lines from the top of the display, in lines.
	
R2 includes the margin which may contain the line numbers. The line numbers
are handled automatically by zap. Thus a window looks like:

			0	w_margin	w_width
		      0 -------------------------
			|	|		|
			|	|		|
			|	|		|
			|	|		|
			|	|		|
	       w_height	-------------------------

The quantity w_width-w_margin is usually stored in the mode dependent byte
w_bpl (bytes per line). However for byte/word modes this is not true, and the
number of bytes in the file that the line represents is stored in w_bpl. It
is up to the mode concerned to fill in w_bpl.

The are two ways of numbering lines in Zap. These are called PHYSICAL line
numbers and LOGICAL line numbers. The PHYSICAL line number of a file offset
is the line offset from the top of the file in the display. Ie, it is the 'y'
value of that character starting from 0 on the first line. All line counts
start from zero within zap, though the number w_stline is added before the
line number is printed on screen for the user. The LOGICAL line number of a
file offset is determined entirely by the extension mode and Zap doesn't care
what it is. For example, in text mode it is taken to be the number of
carriage returns before the offset (ie the physical line it would have been
on if the display hadn't been wrapped). In BASIC mode, it is taken to be the
actual number of the line as encoded in the program.

A further complication is that the window text display is cached. The start
of the cached area is used as a reference point for working out the file
offset of a given physical or logical line number. Thus it is not necessary
to start counting from the start of the file to find out where a line is. All
line references work locally from this value, which is the start of the
cached display, which is where the user is likely to be editing! The calls
Zap_FindOffset and Zap_OffLineCol use this fact. These calls use the mode
entry points 'e_cln*'. Thus these entry points should use this reference
point. Thus the mode will need a piece of code (usually called cln_backward)
for tracing lines backwards up the file. (See the docs on these entry
points).

The cache itself consists of a number of lines of width w_txtw. This width is
usually w_width rounded up to the next multiple of 8. An extension mode need
not usually concern itself with this cache unless it is drawing its own
display. See the mode entry point e_redrawline in which you are asked to fill
a line in the cache. I reserve the right to change the format of the cache,
so don't access it directly.

The window block offsets are described below. Use E-Library to set up the
definitions.

w_handle
Window handle for this window or -1 if the window has been deleted and this
block is now 'dead'. Dead blocks should be skipped if you are going through
the windows in sequence.

w_minx
w_miny
w_maxx
w_maxy
w_scrollx
w_scrolly
w_infront
w_windowflags
These are as for a wimp window block. See PRM if in doubt. You can use
the code MOV R1,R8:SYS "XOS_GetWindowState" to update these values.

w_file
Gives the file offset of the associated file. Use Zap_ConvFileOff to convert
this to a file pointer in R9. This is done automatically for you by
Zap_ConvWindOff.

w_format
Gives the display format flags and the mode the window is in. See E-Flags for
details.

w_width
Width of window in columns (including the margin).

w_height
Height of window in lines.

w_txt
Address of text cache.

w_txth
Number of lines claimed for txt cache. Each line consists of w_txtw number of
columns (which may be w_txtw or w_txtw*4 bytes depending on whether the
window is using wide redraw - see w_info and e_interrogate) followed by a
foreground mask (of length w_txtw bytes) and then a background mask (of
length w_txtw bytes), then a substyle mask (also of length w_txtw bytes).
Thus the size of a cache line is either w_txtw*4 or w_txtw*7, and this value
is stored in the variable w_txtlen. The size of the whole cache is w_txth *
w_txtlen. See e_redrawline for more details.

w_txtw
Width of a text cache line in columns. Must be a multiple of 8. This does
not include the colour or style data. See w_txtlen.

w_txtn
Number of lines cached in the txt cache.

w_coff
Reference point giving the file offset of the start of the first cached
physical line.

w_cline
Reference point giving the physical line number (first line 0) of the start
of the first cached physical line.

w_clogl
As for w_cline but gives the logical line number.

w_tab
Gives the coltab width.

w_tabc
Gives the character code tab mask (x4) eg &09090909. Set this to the same as
w_cr if you want the tabs to be invisible.

w_cr
Gives the line terminator mask (x4) eg &0A0A0A0A.

w_flags
Gives the flags status for this window. See E-Flags. When a window is created
the default value is taken from opt_flags.

w_title
Points to the window title string.

w_bpl
Mode dependent word. Usually stores the width of the display in characters.
Byte mode stores the number of bytes shown on each line etc.

w_margin
Width of the left hand margin in characters (including any line numbers - so
this may be non zero even if the user has not set a margin).

w_rl
Height in pixels of each character including the line spacing.

w_rw
Width in pixels of each character.

w_rh
Height in pixels of each character excluding line spacing.

w_addr
Address to show in margin for file offset 0.

w_stline
Line number to show in margin for line offset 0.

w_titlelen
w_titbuf
w_titlen
Used internally for title update.

w_mwidth
User required margin width before space for line numbers added.

w_tabchar
User required tab character code x4 (eg &09090909) before tab visibility
taken into account. w_tabc contains the one actually being used.

w_linesp
User required line spacing in 1/8ths char.

w_savedo
Used internally by Zap_DoCommand to store the offset of the first shiftable
line after a command, and by Zap_SaveWinStatus to store the file offset of
the character whose position should remain fixed when the window is
recreated.

w_savedl
Used internally by Zap_DoCommand to store the physical line number of the
first shiftable line after a command, and by Zap_SaveWinStatus to store the y
offset from the top of the window in pixels of the character whose position
should remain fixed when the window is recreated.

w_savedc
Used internally by Zap_DoCommand to store the number of physical lines text
after the first shiftable line should be shifted down after a command
(signed).

w_savedh
Used internally by Zap_DoCommand to save the window height before a sequence
of commands was performed.

w_savedlc
Used internally by Zap_DoCommand and Zap_SaveWinStatus

w_wrapwidth
Wordwrap width.

w_togminx
w_togminy
w_togmaxx
w_togmaxy
These save the 'small' window position for the toggle size key (scG).

w_txtlen
Actual length of a cache line including the colour and style data.

w_palette
Pointer to current redraw palette. Its format depends on the redraw mode and
the Zap mode and the number of colour it has. You should access colours via
the call Zap_ModeColour and should not look at this directly. For debugging
purposes it may help to know than in DSA mode it points to a list of bitmap
masks and in VDU mode a list of 24 bit colour values (&BBGGRRZZ).

w_pwind
w_pline
w_pcol
w_poff
w_ploff
w_pwidth
This is the 'cursor block' of the 'point' position. This is the file offset
of the current 'input' position in the file when the file does not contain
the cursor. It is updated when the cursor moves from one file to another.
This position is usually marked with an empty square cursor. See the file
E-Cursors for what the variables store - w_poff is the most useful giving the
file offset of the 'point'. w_pwind is set up as the window offset of this
current window. This in its self is not useful but enables you to call
cursor handling routines with R10=R8+w_pwind (provided the routine doesn't
use any of the 'old' offsets).

w_saveds
Used internally by Zap_DoCommand. Saves the first file offset to be updated
on screen after the command has finished.

w_modedata
This points to a block which stores the mode dependant data handled by Zap.
This includes the mode palettes. Use the calls Zap_ModeData and
Zap_ModeColour to read/write this block. It's format changes regularly!

w_basemap (byte)
The base keymap for this window.

w_currentmap (byte)
The current keymap for this window.

w_helpmap (byte)
The previously active keymap in this window. This is reserved for internal
use by HELPKEY.

w_res10_3 (byte)
Reserved.

w_font
This contains a ZapRedraw font handle for the current display, as set by
the variables w_vdufontname, w_vdufontsize, w_dsafontname and the redraw
flags in w_flags.

w_savedscy
 'scrolly' of window - used internally by Zap_DoCommand.

w_info
Various window status bits - more details are in the E-Flags file.

w_dsafontname
Contains a pointer to the name of the font to use in DSA mode, or 0 for
the default, which will be Settings variable &31A or &31B depending on
the screen mode.

w_vdufontname
Contains a pointer to the name of the font to use in VDU mode, or 0 for
the default, which will be Settings variable &302.

w_vdufontsize
The lower 16 bits contain the size of the font to use in VDU mode, in
points. The upper 16 bits contain the aspect ratio, as Y/X*100.

w_tabstops
Points to an array of 16 bits per displayed column, containing the number
of columns to the next tab stop. The order of each half word is reversed, so
to jump the the next column you can
    LDR off, [w_tabstops, column, LSL #1]
    ADD column, column, off, LSR #16
This table is will not be created if the mode replies to e_interrogate #26
with 1 (TabStops_None), and in this case will contain 0.

w_tabstring
Contains the tab definition string for this window, or 0 for default
(the default is set by Settings variable &324).

w_encoding
Contains a pointer to a heap block containing the name for the encoding to
use, or 0 for no encoding.

w_encodinghandle
Contains the ZapRedraw encoding handle for use in the window, or 0 if no
encoding is to be applied (as per ZapRedraw_PrepareDataLine).

w_encodingtable
Contains a pointer to a 256 word table contatining a UCS character for the
corresponding input byte in the window's current encoding, or 0 if no
translation table is available.

w_alphabet
Continas the RISC OS alphabet number corresponding to the window's current 
encoding, or -1 if no such alphabet exists.

w_mode0,w_mode1,.... (number depends on number of modes allowed)
Mode words. Each mode has one word in each in window in which to store the
options pertaining to that mode. If bit 10 of the flags in the modes e_mode
entry point is SET then instead of storing data, the mode word holds
a pointer to a block of data in Zap's heap (or 0 if the block has not been
created). In this case, the first word of the block MUST contain the length
of the block (including the first word). The block will be copied
automatically by Zap, for example, on a New View. The block will be freed
automatically when the window is closed. The block is created automatically
when a window is opened, and filled with the contents of the default block
stored in the !Config file and accessed via Zap_Read/Write Var - see E-Vars.

Note that the position of these mode words can chage between releases of Zap,
so extension modes MUST NOT access them directly.
