*************************************************************************
* >E-Entry Documents the format of a mode entry point table *
*************************************************************************
The offsets in the entry point table are given names beginning 'e_'. The
E-Library program will define the offsets for you.
You must fill in the first 8 entries of this table. The rest of the entries
you may leave as 0 (or more simply, set the table length in the 8th word to
32 bytes). The idea of the mode table, is that you specify a BASE mode. For
all the entry points (from the 9th onwards) that are off the end of your
table, or that you have left as 0, the base mode will be called instead.
Hence, the simplest Zap extension mode would just set the base mode as 0 (ie,
TEXT) and leave the rest as 0. You will then get a clone of the text mode.
In general the following register conventions are used:
R2 Current column in characters (see E-Windows)
R3 Current line in characters (see E-Windows)
R8 Window block pointer / 0 to change the default config
R9 File block pointer / 0 to change the default config
R10 Cursor block pointer
R11 Your extension mode workspace (private word)
R12 Zaps workspace (private word)
In general the entry points have entry and exit conditions:
\E R0-R10=parameters R11=your workspace
R12=Zap's workspace R13=FD stack R14=return addr
[R13]=mode number supplying the entry point
\X You must save R1-R11 (unless otherwise mentioned).
You may corrupt R0 and flags.
Set V flag and put R0=error block pointer on an error.
See the E-ZapCalls file for more details on my entry/exit syntax.
All offsets given in the table below must be from the start of the module.
Hence the table is relocatable. Zap finds the start address of your module
via the first table entry (e_module). It uses this and an OS_Module call to
determine the address of your workspace (to pass in R11). All strings should
be 0 terminated.
Entry points for arbitrary modes may be called using Zap_CallMode,
Zap_CallGivenMode or Zap_BaseMode. If none of these will do, then use
Zap_ReadMode to find the table entry linked points and the address of the
mode's workspace and the entry point can be called directly.
Each mode has a word of workspace reserved in the window block (pointed to by
R8) for each file. A mode is responsible for storing the current options in
their mode word when the user changes mode (see e_start/e_end). There are Zap
calls provided to make this easier for you. If you need more than one word of
workspace then the mode word can store the pointer to a block of workspace if
you set a flag in e_mode. See E-Windows (w_mode0...) and E-Vars
(opt_mode0...).
The entry points
================
e_module
This gives the table offset from the module start so that the module start
may be calculated by Zap. Ie, module start = address of table start - this
offset.
e_title
Offset of the mode title string to be used in the 'Mode' menu. (Ie, the name
of the mode). It should be:
* at most 10 chars long. (eg 'BASIC')
* useable as a filename.
Mode names are case insensitive.
e_author
Offset of the author name string (eg 'Dominic Symes').
e_basemode
Gives the mode number on which to base null entry points. This is a bit out
of date since modes are now referred to by names and assigned numbers when
loaded. For all practical purposes this will always be 0 (text mode) though
you can use any mode permanently installed in Zap (ie 0=Text 1=byte 2=word
3=ascii 4=hex 11=throwback).
e_mode
Gives the mode number you would like to be in bits b0-b7. Bits 8-31 contain
flags. It is VERY important that you do not assume you get this mode number.
Now that Zap loads modes on the fly, modes are often loaded in a funny order
and you cannot guarantee this mode number will be free. I suggest that
(seeing as modes 0-12 already have a standard meaning) you set this to 13 and
then Zap will assign you the next free mode >=13. It tells you which mode you
have actually been assigned on e_init with R1=1.
Bits 8-31 as follows:
b8 Set to receive RAW keyboard input. All key presses are sent
to e_char. Zap key codes greater than &FF are sent as a
zero byte followed by the low byte.
b9 Set to get taskwindow style keyboard input passed to e_chars.
This differs from normal e_chars entry in that:
1) Delete is passed on as &7F instead of calling e_delete
2) Characters &20-&FF are passed on regardless of mapping
3) If not in COPY mode then the cursor keys are passed on as
a 0 byte followed by bottom 8 bits of the wimp's code.
Similarly TAB.
4) Return and Escape are passed on as &0D and &1B.
This is subject to changes - contact me.
b10 Set to indicate that you use a mode word in a window block
(eg w_moden) to point to a block of data. See E-Windows
for the format this block must take.
b11 Set to indicate that this is not a 'textual' mode. Eg it's
like byte/word mode. Setting this bit prevents, for example,
auto DOS text file detection.
b12 Set if the mode uses MessageTrans tokens. So far, this only
affects the colours menu.
b13 Set if this mode is cloneable.
b31 Set to overwrite any mode already using this mode number.
Others bits are reserved and should be set to 0.
If b31 is not set then you are allocated the next free mode if the
one you wanted is being used.
e_init
Called at various points when Zap is starting up/dying or wants to give your
mode a chance to intercept an operation. Note that Zap will automatically
kill your module on dying unless you tell it otherwise. You should use reason
code 2 to claim any buffers from Zap. I am at liberty to add extra reason
codes so please return with all registers unaltered if you receive an
unrecognised code.
\E R1=reason code (and other registers may hold values dependent on it)
\X Save R1-R11 as usual unless otherwise stated below.
The reason codes are:
R1=0 => Zap is quitting and about to kill your module.
Return R0=-1 to stop this (eg if you've more than one mode).
R1=1 => Zap is just about to start up your mode (but hasn't read the
options block for this mode or anything like that).
R0=the mode number assigned to your mode.
This is for information only; you may note the mode number that has
actually been assigned to you and store it in your module somewhere.
If your mode is cloneable, then you should only store the mode
number if you have not previously done so (ie. if your local copy is
set to some invalid value).
** This mode number is not guaranteed to be the one you asked for.
R1=2 => Zap has started up your mode (and all other modes in your module).
You should also use this call to claim any buffers you need.
On this call you should check your mode word opt_moden to see if
it's zero.
If so, then you don't have any options, and should create some as
appropriate. You'll need to:
* set up Zap-handled mode data variables (see Zap_ModeData)
* set up mode-handled data words (see E-Vars)
* set the number of extension colours you use using
Zap_ModeColourNum
* set sensible defaults for your extension colours
If not, then you already have configured options. You should do
the following to ensure that they are up to date:
* read the current number of extension colours for your mode
using Zap_ModeColourNum. If you now use more colours, you
should set this (again using Zap_ModeColourNum), and set up
sensible defaults for the new colours.
* if you use more than one mode-handled data word, then you
should check to see that the block loaded from the config
file is long enough. If it isn't, you should extend it and
fill in sensible defaults for the new options you supply.
(See E-Vars.)
R0=the mode number assigned to your mode.
R1=3 => Zap is deleting a file with your mode number in f_cmode. R9=file
block on entry. See E-File.
R1=4 => Zap is saving a file with your mode number in f_cmode. R8/R9=the
window being saved. Return R1=-1 if you wish to abort the save (and
handle it yourself). If you return R1=-1 then return R0=0 if the
save is safe (file can now be deleted) or -1 if unsafe (entered data
transfer protocol for example).
This is only called for saves to disc (F3). For inter-application
saves and post-saves see R1=8 below.
R1=5 => Zap wants to delete a file your mode number in f_cmode, but it
has the 'altered' flag set. Return R1=-1 to override and allow the
file to be killed anyway.
R1=6 => Zap is creating the colours submenu and wants to know what you
call colours >=9. Return in R1 a pointer to:
- (if e_mode b12 is clear)
A double zero terminated list of zero terminated entries giving
the names of the colours starting from 9, eg.
"REMs",0,"Strings",0,0.
- (if e_mode b12 is set)
The name of a token, present in the (generated) Messages file,
which expands to a string in which each entry is
, eg. "|REMs|Strings".
(Leave R1 as 6 if this call is not supported.)
R1=7 => Zap is creating its menus. At this point you can override your
e_menu value by returning R1 as the pointer to the replacement
(wimp-style) menu (values at #-4 and #-8 - see E-Menus).
R0=your mode number.
Leave R1=7 if you don't want to do this.
You should use Zap_ReadMenu or Zap_LoadMenu to create the menu.
R1=8 => Zap is about to save a file with your mode number in f_cmode
to another application (not to disc). See also R1=4.
\E R0=0 if the file is just about to be saved
1 if the file has been transferred
R8/R9=the file being saved
R1=9 => ZapSpell wants to know if a word is correctly spelled.
\E R0=offset of the first character of the possibly misspelled word
(you will only be called if ZapSpell thinks it is incorrect).
R1 = 9
R2 = pointer to the last character (in a buffer with the word in)
R3 = length of word to be checked
R4 = pointer to the start of a 32 character buffer
R5 (byte 0) = type: 0 = BUF | 1 = SELBUF | 2 = PREV | 3 = NEXT
R5 (rest) = unique ID, maintained over a single ZapSpell command.
R8/R9=the relevant file
\X R1 < 0 : this word is OK - don't prompt;
> 0 : prompt user as normal;
= 0 : the word was malformed - skip the first R0 characters
of the word and try again. This option is mainly used
for parsing escape sequences. ZapMsg uses this option;
= 1 : this word is OK skip to offset R0, though;
= 2 : prompt for this word, but then carry on from offset R0;
= 3 - 8 : reserved...
= 9 : prompt user as normal;
> 9 : reserved...
R1=10 => ZapSpell is about to perform a spelling operation. Modes may
make modifications to the operation if they so choose.
\E R0=type: 0 = BUF | 1 = SELBUF | 2 = PREV | 3 = NEXT | 4 = CURRENT
0/1 R2=start offset R3=end offset R8/R9
2/3/4 R2=current cursor offset R8/R9/R10
\X 0/1 R2 and R3 may be modified if needed
2/3/4 R2 may be changed - the cursor /may/ have to be moved :|
R1=11 => Version of Zap is 1.36 or greater. Called just after e_init R1=2.
\E R0=136 (or corresponding version number).
R1=12 => The user is asking for the definition of the function at offset R0.
\X R1 = 12 : you don't know what they're talking about.
R1 = 0 : R0 = offset of start of function definition (this file).
R1 = 1 : Can't find the definition of that function anywhere.
R1 = 2 : The function has been found if it was possible to do so.
No further action is needed.
R1 = (other values) : reserved.
R1=13 => Redraw data about to be created.
\E R2 = start line.
R3 = end line.
R8/R9
R1=14 => Redraw data creation completed.
\E R8
R1=15 => Request pathname
\E R0 = pointer to 256-byte buffer
R8,R9 may be set up (check)
\X R0 = pointer to the directory name (it need not be in the buffer)
(ctrl terminated, buffer not freed)
= 0 (default to the file's pathname, or if none, the CSD)
This call is used by Taskwindow mode (in ZapBASIC) in conjunction
with a patched version of DDEUtils 1.53, 1.54 or 1.55 in order to
return the prefix directory (if set). Later versions of DDEUtils
contain the necessary SWI.
R1=16 => Miscellaneous "variable changed" message.
\E R2 = 0, 8 or 9 (representing opt_*, R8 or R9)
R3 = offset (e.g. w_wrapwidth)
R8/R9
This is used to inform the mode that a change may have occurred,
requiring some action on the part of the mode such as a redraw of
the affected window.
This call is issued by:
WRAPWIDTH
e_menu
Offset of submenu in Zap's format / 0 for none. This menu comes off the
'Mode' menu. See the file E-Menu for details of the menu format. Greater
versatility can be obtained by setting this to 0 and using e_init with R1=7.
e_len
Total length of the table data (>=32). (So that only entry points within the
table are called and for forward compatibility). If Zap finds an entry point
is off the end of the table then it will call the corresponding base mode
entry point.
If any of the following offsets are 0 then the corresponding offset for the
basemode is called.
e_postload
Called after a file is loaded and has had a window opened for it in your
mode. It is also called after a file in your mode has been saved. It enables
the file contents to be slightly altered before editing. (eg BASIC encrypts
the line numbers and BASTXT detokenises the program). You may alter the data
directly (ie, you needn't use Zap_Command).
\E R1=0 => This is a new file which has just been loaded. The window
hasn't been opened on screen yet so you can alter the file
directly.
R1=1 => File has just been saved. You should undo the effect of
e_presave. (If the effect isn't undone then the redraw
will be messed up if you don't use Zap_Command etc).
R8/R9
e_presave
Called before the file is saved. It enables file contents to be slightly
altered, undoing the effect of e_postload. (eg BASTXT retokenises the program
prior to saving). As above, you may alter the data directly.
\E R8/R9
e_loading
This is called when a file is loaded off disc for dropping into a window. The
file data is in a heap block. This enables you to change it before insertion
takes place (eg BASTXT detokenises the file). You are only called if the file
type of the file is claimed by your mode (in the 'keys' file).
\E R2=data length R3=data address
\X You may change the data, making it larger if necessary provided
that you enlarge the heap block R3. Return updated R2 and R3.
e_start
Called when a window enters your mode (eg via Zap_NewMode). You should
restore the current w_flags and w_format options, and any other options you
may have saved in your private word w_moden or block pointed to by w_moden.
The call Zap_RestoreModeWord should be made as this restores the options kept
track of by Zap using Zap_ModeData.
\E R8/R9=window mode is being changed in OR 0 if the mode on the
options menu is being changed and you should restore the
default options, of for example opt_flags and opt_format.
e_end
Called when a window leaves your mode (eg via Zap_NewMode). This is similar
to e_start except that you should save the current mode dependent options
from w_format, w_flags. The call Zap_SaveModeWord should be made as this
saves the options kept track of by Zap using Zap_ModeData. Again, if R8=0
then this all applies to the options menu and opt_flags,opt_format.
\E R8/R9=window / 0 for iconbar menu
e_width
Called when a window is (re)created to find out the width of the work area in
characters (excluding margin). You should read this either from your mode
word or block, or using Zap_ModeData variable number 0 where Zap reserves
space for a width value for you. If you support auto width and the auto width
flag is set (see E-Flags) then you should work this width out from the file.
Once you have calculated the width, it is advisable to store it in w_bpl, a
variable reserved for this purpose.
\E R8/R9
\X R0=width of work area in characters (excluding margin)
e_linecol
Converts a column offset on screen to file offset. This is called by
Zap_FindOffset and other subs. The start offset of the physical line on which
the column lies has been calculated (usually by e_clnoff).
\E R0=file offset of physical line start
R1=column offset on screen (exc margin) R8/R9
\X R0=file offset of nearest character on the left
e_lineoff
Convert file offset to column on screen. This performs the inverse function
to e_linecol. It is usually called by Zap_OffLineCol. Again the offset of the
start of the physical line has been calculated (usually by e_clnphy). This
call should also return the caret width for this mode.
\E R0=file offset of physical line start
R1=file offset (to convert to a column) R8/R9
\X R0=column offset on screen (exc margin)
R1=caret width (in characters - usually 1).
The next 3 subs do the main body of work of converting between screen display
lines and file offsets. A physical line means the actual offset in lines from
the top of the file when displayed - that is the actual 'y' coordinate.
Counting starts at 0. Logical lines can be interpreted however the mode
wishes. In text mode, a logical line is ended by a return (as opposed to the
display wrapping). These are given as offsets from 0 as the first line. It is
important that these routines are OPTIMISED as much as possible.
e_clnlog
Converts a logical line number to a file offset/physical line. This is not as
important as the other two. It is mainly used by the 'GOTO' box (F5). Ie,
user asks to go to logical line (eg basic line) 500 and Zap wants to know the
file offset of this.
Note that calling this routine (outside calls from within another e_clnlog
entry point) is deprecated. Use Zap_LogicalLine instead.
\E R0=logical line number R8/R9
\X R0=file offset of line start
R1=physical line number
e_clnphy
This converts a physical line number to a file offset. This is the most
important of the 3 as it is called when updating a window. For example the
WIMP asks Zap to redraw a rectangle. The top of the rectangle is at physical
line 100 say. Zap needs to know the file offset of this line to call
e_redrawline. It uses this call.
Starting counting from the start of the file is NOT recommended, as the area
of the window being updated may be near the end. Instead, use the start of
the w_txt cache as a reference - i.e, use the variables w_cline, w_coff,
w_clogl as your start reference.
Note that calling this routine (outside calls from within another e_clnoff
entry point) is deprecated. Use Zap_PhysicalLine instead.
\E R0=physical line number R8/R9
\X R0=file offset of line start
R1=logical line number
e_clnoff
Converts a file offset to a line number and offset. This call is used by
Zap_OffLineCol and when a window is first opened. It should find out which
physical line a file offset lies on. If the file offset is equal to the file
length then it should return the line of an 'imaginary' last character. This
is called when a window is initially opened to work out the w_height value.
As with e_clnphy you should use the cache reference point as a starting
point.
Note that calling this routine (outside calls from within another e_clnoff
entry point) is deprecated. Use Zap_OffsetLine instead.
\E R0=file offset R8/R9
\X R0=physical line number
R1=file offset of physical line start
R2=logical line number
e_nextline
This is called during a Zap_DoCommand operation. It is designed to work out
the first line on screen which can be shifted down, following an insertion/
deletion, without being redrawn. On entry you are told the first character
which occurs after the altered region and the amount by which its offset will
change due to the alteration. You must return the file offset of the first
line which may be shifted on the screen without being redrawn. (Usually the
first logical line with start offset > R0). In the case where there is no
such line, return the end of file offset and the physical line containing
this 'imaginary' character offset (as for e_clnoff).
See also e_prevline. e_prevline is called first, and the file block is set up
as for e_prevline.
Note that calling this routine (outside calls from within another e_nextline
entry point) is deprecated. Use Zap_NextLine instead.
\E R0=file offset of first 'shiftable' character
R1=signed change in file offset of this character R8/R9
\X R0=file offset of first 'shiftable' line
R1=physical line number of this line #
You must preserve the split offset and split size of the file.
Note that calling this routine (outside calls from within another e_nextline
entry point) is deprecated. Use Zap_NextLine instead.
e_minus
This is called when the user presses the left arrow key to work out the next
cursor position. The buffering is done for you.
\E R0=physical line start file offset
R1=cursor file offset
R2=cursor column (exc margin) R8/R9
R10=cursor caret block
\X If R2>=0 then R1,R2 given new cursor position on the
same physical line.
If R2=-1 then R1=new file offset of cursor.
If R2=-2 then you have moved the cursor yourself.
If R2=-3 then R0,R1=new x,y for cursor.
e_plus Perform cursor right (\E & \X as for e_minus)
e_sminus Perform cursor back a word (\E & \X as for e_minus)
e_splus Perform cursor forward a word (\E & \X as for e_minus)
e_cminus Move cursor to line start (\E & \X as for e_minus)
e_cplus Move cursor to line end (\E & \X as for e_minus)
Note that the 'DELWORD' commands currently rely on the second two methods
(R2=-2,R2=-3) not being used (in e_sminus and e_splus) for their correct
operation.
These entry points need to be replaced at some point by Zap_ commands. They
should not currently be called directly from extension modules.
e_redrawline
This is called when your mode is required to redraw one (physical) line of
the display - it is also here that you can specify the colour of each
character. You are passed:
1) As input:
The physical line start (calculated via e_clnphy - or the previous call
to this sub). This is not passed as a file offset, but as an actual
ADDRESS in the file buffer (in R7). Recalling the split nature of the
buffer (see E-File) the text may not be continuous. R10 is set to the end
of this section of the split so the file is continuous up to R10.
R5=R7-the offset of the character - I call this the apparent buffer start
(where the start would be if the file were continuous).
2) For output:
The address of a buffer (in R6) in which to write the characters to
appear on the line (one byte per character). This buffer has been cleared
to spaces beforehand so you only need to write the non-space characters.
Line numbers have been dealt with. You told Zap the width the buffer
should be when your e_width entry point was called.
3) Colours:
As far as this call is concerned there are up to 256 colours (numbered
0-255) available. Numbers 0-8 have a standard meaning and 9+ can be
declared for use by the mode (see e_init with R1=6/Zap_ModeColourNum).
These colour numbers bear no resemblance to wimp colour numbers, but are
'internal' Zap colour numbers. Their actual physical appearance is chosen
by the user from the colours menu - and can be selected from a palette.
Colours 0-8 have a standard interpretation but colours 9+ can be used as
the mode sees fit. Eg, colour 9 may be used for IF statements in a
language editor for example. The standard colours are
0=Background colour 1 (default background colour + off end of text)
1=Background colour 2 (this should be used under text)
2=Standard foreground colour
3/4=selection bac/foreground 5/6=cursor bac/foreground
7=line numbers 8=control characters.
Let n be the value stored in [R8,#w_txtw]. Then the foreground colour of
the cached character stored at R6 is stored at R6+n, the background
colour at R6+2*n, and the style at R6+3*n. These are initialised to bytes
2, 0 and 0 respectively - you should overwrite these bytes to change the
colour and/or style. Text mode puts colour 1 (background colour 2) under
actual text and you should do the same. See e_init for how to change the
colours menu. Note that the style information you write WILL BE IGNORED
unless you responded to e_interrogate 11 with return code 1.
4) Other comments:
On exit you should update several registers to the start of the next
physical line. e_clnphy is only called for the first line in a group. For
a simple example of how to write this redraw code, see the code for mode
3 (ascii mode).
\E R4=w_format (read from R8,#w_format)
R5=apparent buffer start (R7-offset of char in file)
(so it is either f_ptr or f_ptr+f_splits)
R6=address of cache line to draw line in (already blanked)
R7=address of start of (source) line (R5+file offset of line).
R8/R9
R10=address of end of this section of the buffer.
(so when you reach R10 you increase R5 and R7 by f_splits if
at the end of the first half or stop if at the file end).
R11=logical line number (for you to update for cache reference
and printing in the left hand column).
\X R0-R4,R6,R10 may be corrupted
R5,R7,R11 must be updated to the start of the next physical line
R8-R9,R12 must be preserved
e_redrawlnum
This is called when the user wishes logical line numbers to be displayed on
the left. You must decide whether the given physical line file offset it at
the start of a logical line. This is called while redrawing the line numbers.
\E R7=file offset of start of physical line
R11=proposed logical line number (as calculated by e_clnphy)
R8/R9
\X CC if R7 is at the start of a logical line (so print it)
CS if the line number column should be left blank
You may corrupt R0-R4. You may also change R11 as BASIC does
but this is not advised as the w_clogl will get out of sync.
BASIC ignores the w_clogl as the line number is stored in the
file.
e_char
This is called when the user types a string of ASCII chars via the CHAR
command. The characters have been concatenated for you. You should perform
the relevant insertions/deletions via Zap_Command.
\E R4=w_flags
R5=number of bytes typed
R6=w_format
R7=address of typed data
R8-R10=input caret (ie this points to the block car_cursor or
car_input depending on the caret mode and where typed
text should go).
\X You may corrupt R0-R11
e_delete
This is called when the user executes the commands DELETE or DELETENEXT. A
sequence of deletes is concatenated for you. Zap_Command may be used to
delete the text. Supporting the line edit mode is recommended if possible.
\E R5=number of times pressed
R6=w_format
R7=0 for DELETE/1 for DELETENEXT
R8-R10=input caret
\X You may corrupt R0-R11
e_tab
This is called when the user executes the command TAB. As usual, repetitions
are concatenated. Using Zap_Command to perform the function is recommended.
\E R1=number of times pressed
R8-R10=input caret
\X You may corrupt R0-R11
e_return Called when RETURN or RETURNNOINDENT executed
You should insert an appropriate number of newlines - remember to take
account of the buffering in R1.
\E R0=0 if RETURN, 1 if RETURNNOINDENT
R1=number of times pressed
R8-R10=input caret
\X You may corrupt R0-R11
e_renumber Called when RENUMBER executed (\E \X as for e_tab)
You should renumber/restyle the program - language specific.
e_saveandrun Called when SAVEANDRUN executed (\E \X as for e_tab)
You should save the program and then run it so that the program quits when
finished. This will often duplicate e_compile.
The next 4 subs are used by the various delete line calls. They each have
\E R0=current file offset in a line R8/R9
\X R0=new file offset (see below)
This is how the subs are called:
DELLINE Deletes from lineprev to linenext offsets.
DELTOEND Deletes from current offset to lineend unless this is empty
when it calls JOINLINE (as in emacs ctrl K)
DELTOSTART Deletes from linestart to current offset unless empty.
e_linestart Called to find the line's first character.
e_lineend Called to find the line's last character.
e_linenext Called to find the line's actual end (eg after &0A)
e_lineprev Called to find the line's actual start (eg for BASIC lines)
e_copy
Called when user wishes to copy characters via the COPY key. Is is called for
finding the characters to copy and for inserting the copied characters.
Reason code is in R0. When reading characters you must update the cursor
yourself. Note the source window may be in a different mode to the
destination window!
\E R0=1 => Fetch characters
R1=number of times copy pressed (number of chars to get)
R8-R10=copy cursor (car_cursor)
\X R3=pointer to buffer containing characters to 'type'
R2=number of characters to 'type'
Copy cursor updated to new position
OR
\E R0=2 => Write copied characters
R2=number of chars to type
R3=pointer to the chars
R8-R10=input cursor (car_input)
\X R0=0 means you've done it all yourself
R0=1 means please enter it for me via Zap_Command
R0=2 means please enter it for me by calling my e_chars
e_joinline
This is called when Joinline pressed (\E \X as for e_tab)
e_splitline
This is called when Splitline pressed (\E \X as for e_tab)
e_aligncaret
This is called before any commands are executed on a window in your mode. It
serves two purposes. The first is to align the input caret offset to a
sensible position (eg word align in word mode, put after line numbers in
basic). The second is to reset any counters you may have. For example, the
hex mode entry uses a counter to tell how many nibbles have been inserted in
a word. This is cleared on e_aligncaret with the old value being saved. Then
if the command 'insert 9' is executed it can retrieve and restore the saved
value. If any other command is executed (eg LEFT) then the counter will
remain reset.
\E R8-R10=caret
\X Input caret offset [R10,#c_off] can be updated.
e_command
This entry point is called whenever anyone issues a Zap_Command call, or
equivalent, to try and alter a file in a window in your mode. The easiest way
to deal with this is to pass the call onto Zap_DoCommand which will perform
the alteration. However, if you support wordwrap, you may wish to 'fiddle'
the data, or even perform additional operations.
This entry point should not normally be called directly.
\E As for Zap_Command
e_compile
This is called when COMPILE is executed (\E \X as for e_tab)
The mode should save the file to disc and then try to compile/run it.
e_formattext
This is called when FORMATTEXT is executed (\E \X as for e_tab)
The mode should try and format the current paragraph for its particular
language.
e_run
This is called when RUN is executed (\E \X as for e_tab)
The mode should try and run the program without saving it. Revert to
e_compile code if there is no difference.
e_runandquit
This is called when RUNANDQUIT is executed (\E \X as for e_tab)
This should act as e_run but add a -quit option if possible.
e_basic
This is called when BASIC is executed (\E \X as for e_tab)
This should drop the file into the command line state of the current
language.
e_search
This handles string searches in your mode. When the 'Raw search' option is on
the file is searched directly and the mode has no control over it. When, as
usual, the option is off the the text is searched through in lines. Each mode
has a chance to turn a line of the file into meaningful text. For example,
BASIC mode will detokenise the line and Code mode will disassemble the
instruction. Unrecognised reason codes should be ignored (and registers
preserved). After the line has been searched you are called again to convert
a match to a file offset and/or specify the start/end of the next line to
search (depending on the search direction).
\E R1=reason code
0 = starting a search - now obsolete and no longer used.
1 = match found - now obsolete and no longer used.
2 = starting search in a line (non 'raw' search)
Then R3=file offset of current search position
R4=search direction (+1/-1)
R8/R9=the window being searched
\X Preserve R1+ to use the standard text search routine
or set R1=pointer to 'detokenised line' string.
R2=offset in the string of the search posn.
R3=file offset of the start of the line.
R10=length of the string pointed to by R1.
3 = has finished searching through this line. You are called
with:
R1=pointer to 'detokenised string'
R2=offset in the string of the match/-ve if not found
R3=offset in the file of the start of the line
R4=search direction (+1/-1)
R8/R9=the window being searched
R10=length of the line
\X Preserve registers for default action. Otherwise
if a match has been found (R2 +ve) then you should set
R1=0
R2=file offset of the match
R3=next file offset to look at (usually R2+R4)
if a match was not found you should set
R1=0
R2=-ve (ie preserve it)
R3=next file offset to look at (usually R3+R10 or R3-1)
the search will be aborted (or move onto the next file if
R3<0 or R3>=file length).
4 = has found a match and wants to know the file offset of the
end of the match. This is called before the call with R1=3
to find the start. You are called with registers as set up
for R1=3 except R2=offset in the string of match end. \X As
for R1=3 except R2=file offset of end of match and R3 is
not used (you may corrupt it).
[Usually you will call the same code for R1=3 or 4]
5+ = reserved
e_replace
This is called when the user wishes to perform a search and replace. The
replacement string has been calculated for you and it is your job to insert
it. Your default action should be to call Zap_ReplaceArea.
\E R1=file offset (of match)
R2=length (of match)
R3=replacement data
R4=replacement length. R8/R9
e_selection
This handles region selections/saving. You should check the validity of the
selected area, confining it to lines/paragraphs if you wish.
\E R0=reason code R8/R9=window
R0=0 => starting selection
R10=proposed start caret. You can use the variable car_mode
to find out if the selection is mouse or keyboard (E-Vars).
R0=1 => updating selection size
R10=new selection block (car_selection)
You may alter the contents of the selection block.
R0=2 => saving selection
R3=data address (a heap block)
R2=data len
R4=proposed filetype
You may change these provided R3 remains a heap block.
(eg BASIC will tokenise it).
e_click
This is called when the user clicks on your window. Default action should be
to call Zap_DefaultClick which will handle R1=0,1 and ignore the rest. Clicks
are registered to any depth so you should modulo the click number with the
number of useful actions you support so they cycle round. Drags are also
passed to you. If the user drags straight away (ie after 1 click) then you
will be sent R1=0. If the user drags after a double click then you will be
sent R1=2 and b3 of R4 will be set. After treble click R1=3 etc.
\E R1=click depth (0=simple drag 1=single click 2=double click etc)
R2=x column (including margin)
R3=y row of click in work area characters
R4=buttons b0=adjust pressed
b1=undefined (menus are dealt with by Zap)
b2=select pressed
b3=drag after two or more clicks (given in R1)
b4-b31=reserved
R8/R9=window clicked on
e_message
This entry point is called when an unrecognised wimp message is received by
Zap. The message is broadcast to all modes. Please IGNORE (ie return) unless
you understand the message number and the window handle!!
\E R0=your mode number
R1=message block (as sent by wimp)
R2=R1!16=message number if R3=17 or 19
R3=message type
(Null requests are scheduled - use Zap_CallBack)
1=redraw window request for unrecognised window
2=open window request for unrecognised window
3=close window request for unrecognised window
4=pointer leaving unrecognised window
5=pointer entering unrecognised window
6=mouse click on unrecognised window
(Drags dealt with by Zap - use Zap_DragBox)
8=key press for unrecognised window
(Menu clicks handled automatically - use Zap_OpenMenu)
10=scroll request for unrecognised window
11=lose caret for unrecognised window
12=gain caret for unrecognised window
13-16=passed straight on (not recognised by Zap)
17=unrecognised user message (or recognised message applying
to unrecognised window)
(type 18 gets passed on as 17 as well)
19=unrecognised bounced message
20+=passed straight on (not recognised by Zap)
e_setwidth
This entry point is used by the SETWIDTH command (Ctrl W) and the 'width'
menu option on the display menu. It is called to read the currently
configured width for this mode (of a window or the default according to R8),
or in order to set the currently configured width. You should access this
width by looking at your mode word w_moden if that's where you keep it, or
using Zap_ModeData if you keep it in the place provided by Zap (this is the
default action of the text mode entry point). Following this call, the editor
window in question will be recreated automatically and your e_width entry
point will be called to calculate the actual display width as usual.
\E R0=new width user wants or -1 to read the current width
R8-R9=window/0 if it is the default width being changed.
\X R0=current width if it was -1 on entry.
e_listfns
This is called when the command LISTFNS is pressed. \E \X as for e_tab. The
mode should open a throwback buffer with a list of function definitions in.
(eg Use Zap_Search).
e_prevline
This entry point is used in conjunction with e_nextline to find the area on
the screen which needs to be updated after an insertion/deletion. It tells
you in R0 the first file offset being changed and you must tell it the first
file offset (<=R0) to start updating the screen from. Usually you will just
leave R0 unchanged but in the case of a mode using colours - where changing a
character later on in the line may affect earlier colours - you may want to
set this to the start of the current logical line. The cache reference point
(w_cline/w_coff) is moved so that it is most R0, and is thus not corrupted by
the insertion/deletion. If you wish to move it further back (eg if a control
code later in a line affects the formatting of earlier bits) then now is the
time to do so - via Zap_ClipCache.
e_prevline is called before e_nextline. Complicated colouring modes (eg
colour C mode) need to know what data is being inserted/deleted to decide
what to return for e_prevline/e_nextline. To make this possible, the
following data is available:
f_docom=the command currently being executed:
0,>6=none => text not changing (just return with R0 preserved).
1/6=insert => R0=offset that text is being inserted at
f_dolen=number of characters being inserted
f_dodata=pointer to the text being inserted
File is split at the offset R0 with split size >= f_dolen.
2/5=delete => R0=offset of start of block to delete
f_dolen=number of characters being deleted
File is split at R0+f_dolen with split size >=0.
3/4=replace => R0=offset of start of block to replace
f_dolen=number of characters to replace
f_dodata=replacement block
File is split at R0+f_dolen with split size >= f_dolen.
\E R0=First changed offset in the file. R8/R9
\X R0=Offset to start updating the screen from.
You must preserve the split offset and split size of the file.
e_openwindow
This entry point is for the use of modes which want to provide panes on the
main Zap window. It tells you when the window is being resized (but not
scrolled - though scrolling by dragging the scroll bars is currently
reported). Panes may usefully modify Zap's window block pointed to by R8 in
order to inform Zap that the top of the window stack has changed to prevent
it from overwriting any panes.
\E R0=0 => Just before calling Wimp_OpenWindow
R0=1 => Just after calling Wimp_OpenWindow
R0>1 => Reserved.
R1 = Open block (as for Wimp_OpenWindow) (may have R1=R8)
R8 = Zap window block
\X Preserve R1+ as usual. VS on error etc.
e_interrogate
This entry point is used by Zap to ask modes about a number of options.
\E R0 : query number; other registers depend on R0.
\X Depends on R0.
\E R0 = 0 : What width is this window-wrapped window?
R1 = width of the window if displayed in text mode.
R8 = Zap window block.
\X R0 = 0 : don't know / other : width, in bytes per line (bpl).
\E R0 = 1 : Can you cope with window-wrapping?
\X R0 = 1 : yes / any other value : no.
\E R0 = 2 : Can you cope with soft-wrap?
\X R0 = 2 : yes / any other value : no.
\E R0 = 3 : What width should I set for this window?
R1 = the value of bpl for the window.
\X R0 = the width that needs to be sent to e_setwidth.
\E R0 = 4 : Which characters should soft-wrap consider to be
possible line-ends.
\X R0 = 4 : use default / other : pointer to a string, which
should normally include " " and "-" characters, but
should not include the tab character and must be
zero-terminated.
\E R0 = 5 : Can you cope with the "ConfineH" cursor option?
\X R0 = 5 : yes / other : no.
\E R0 = 6 : Can you cope with the "ConfineV" cursor option?
\X R0 = 6 : yes / other : no.
\E R0 = 7 : Can you cope with the "Free Click" cursor option?
\X R0 = 7 : yes / other : no.
\E R0 = 8 : Can you cope with the "Smart" cursor option?
\X R0 = 8 : yes / other : no.
\E R0 = 9 : The user has pressed menu over a text window.
\X R0 = 9 : perform the default actions.
R0 = (other values) : menu handle returned in R0.
\E R0 = 10 : How are you going to paste this selection in?
R1 = proposed offset where the data is to be inserted
R2 = size of the proposed insertion.
R3 = a pointer to the data to be pasted.
\X R0 = 10 : at the cursor position / R0 = 0 : on a separate line.
\E R0 = 11 : Would you like more elaborate font sub-style processing.
\X R0 = 11 : no / 0 : yes (bgnd) / 1 : yes (bgnd+mode) /
other values : reserved.
Notes: you are called immediately after your e_redrawline entry is
called - thus processing this reason code should be as rapid
as possible. The font sub-style processing uses the
background as a cue to the font style if it is greater than
8. Since the processing has a speed penalty, you should keep
notes while redrawing the line, and only request processing
here if it needs to be done. As some modes (e.g. ZapEmail)
already use background colours in more than one context, this
should also allow them to selectively use the foreground
colour as the governor of font-style if they so choose.
Return code 0 causes the background style to override the
foreground; return code 1 causes the foreground, background
and mode-supplied style information to be ORred together.
\E R0 = 12 : Do you support the the "Line Select" option?
\X R0 = 12 : yes / other : no.
\E R0 = 13 : Do you support the the "Spell-as-you-type" option?
\X R0 = 13 : yes / other : no.
\E R0 = 14 : What sort of mode are you?
\X R0 (low byte) = 14 an ordinaryish text based mode;
= 0 a binary (Byte/Word/ASCII) mode;
= 1 Code mode;
= 2 Tokenised mode;
= 3 TaskWindow;
= 4 Throwback.
= other values reserved.
(other bytes) reserved.
\E R0 = 15 : Zap wants to know how you use a particular colour.
R1 = colour number (you will /only/ be called for colours 9+)
should the existing value be presented in?
\X R0 = bit 0 set if this is a foreground colour
(used to control fancy printing)
bit 1 set if this colour can control font sub-styles
(to be used when opening the colour dialogue boxes)
\E R0 = 16 : Editing a byte or word has been requested: what base
should the existing value be presented in?
\X R0 = 16 : 16=Hexadecimal 2=Binary.
\E R0=17 : Delimiter characters requested for e_returnword
\X R0=17 : use default settings (from text mode)
R0 b0 : set => R1 lists non-delimiters
: clear => R1 lists delimiters
b1 : control characters form their own list
b2 : set => control characters are non-delimiters
: clear => control characters are delimiters
R1=> zero-terminated list of delimiters/non-delimiters
This can include ranges, eg: "A-Za-z_" or "A-Z-".
\E R0 = 18 : Do you use substyles, other than those set up via the
colours menu?
\X R0 = 18 : no / 0 : yes.
Notes: This overrides the 'no substyles' bit.
\E R0=19 : A word end marker has been found. Is it the end of a word?
R1 = offset being examined.
R3 = direction (+/-1) or 0 if not relevant R8/R9.
\X R0=19 : Yes it's the end of a word.
R0=0 : No - continue your search with the next character.
Notes: called, for example, when the user double-clicks on a word.
\E R0=20 : Zap wants to know about the word at an offset.
R1 = offset being examined.
R3 = direction (+/-1) or 0 if not relevant R8/R9.
\X R1= : offset to consider the word starting from.
Notes: called when the user double-clicks on a word.
\E R0=21 : How should drags be treated?
\X R0=21 : as normal.
R0=0 : drags never reposition the cursor (e.g. TaskWindows).
\E R0=22 : Should Zap confine the cursor?
\X R0=22 : As normal.
R0=0 : No, this is a taskwindow, or something.
\E R0=23 : Do you support the 'Block editing' option?
\X R0=23 : Yes.
R0=0 : No.
\E R0=24 : Does your mode allow 'Auto-indent'?
\X R0=24 : Yes.
R0=0 : No.
\E R0=25 : Would you like default SAVEANDRUN and COMPILE behaviour?
\X R0=25 : No.
R0=0 : Yes - please save and Wimp_StartTask this file for me.
If R0-R13 are not explicitly mentioned on exit then they should be preserved.
Entry values in R1-R12 not sepcified in the above list are reserved and
should currently be ignored. Returning errors from your e_interrogate entry
point is not recommended.
Normally unrecognised values (especially = 0,3 & 10) should be passed on to
the base mode.
e_returnword
Return the start and end positions of the 'word' at the given offset.
Tokenised modes should return the offsets of the token which is at the cursor
if necessary. Binary modes should return the offsets of the atomic entry at
the cursor (a byte in byte and ASCII modes, a word in Word and Code modes)
\E R0 offset R8/R9
\X R0=file offset
R1=length
e_help
Return a list of possibilities for context help at the supplied offset.
Language editing modes may wish to skip comments (although Guttorm Vik
advised that this may be confusing). More usefully, Code mode (for instance)
may provide the SWI name/number in preference to the "SWI" opcode, or the
function name in preference to "B" or "BL".
\E R0 offset R8/R9
\X R0=number of possibilities (R0=0 => R1 undefined)
R1=heap block containing (R0) pointers to heap blocks
All heap blocks to be freed by the caller.
e_stripspaces
Space-stripping control, allowing a mode to determine whether or not specific
spaces and/or tabs should be removed or otherwise replaced. It may also do it
all itself if it so wishes. This is used by the STRIPSPACES command as well
as the automatic space-stripping on saving.
\E R0 = action
0: Prepare for space stripping.
\E R1 = the STRIPSPACES parameter.
\X R0 = 0 if the mode wants the standard action (default)
<>0 if it has done it all itself
R1 = (possibly modified) parameter (if R0 = 0)
1: Space/tab stripping.
\E R1 = offset of area to be removed
R2 = length of area to be removed
\X R0 = 0 to suppress removal
1 to allow normal removal (default)
2 if it has performed the replacement itself
R1 = length of the replacement text (if R0 = 2)
2: reserved for tabification.
(unimplemented)
255: Finished.
\E -
\X -
R8/R9
\X as detailed above