RISC DISC 1

home *** CD-ROM | disk | FTP | other *** search

/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / utilities / zap / !Zap / Docs / E-Entry < prev next >

Wrap

Text File | 1994-03-18 | 28.2 KB | 602 lines

************************************************************************* * >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 \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. It should be at most 7 chars long. (eg 'BASIC') e_author Offset of the author name string (eg 'Dominic Symes'). e_basemode Gives the mode on which to base null entry points. Current modes are: 0=Text 1=byte 2=word 3=ascii 4=hex 5=basic 6=bastxt 7=cmode 11=throwback 12=taskwindow. Needless to say, if you wish to clone the BASIC mode, you'd better be sure that the Zap_Basic module initialised before yours! e_mode Gives the mode number you would like to be in bits b0-b7. Bits 8-31 contain flags 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. 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 has just started but not set up its heap yet. R0=the mode number assigned to your mode. You should note the mode number that has actually been assigned to you and store it in your module somewhere. This is not guaranteed to be the one you asked for. R1=2 => Zap has started and set up its heap. On this call you should check your mode word opt_moden to see if it's zero. If so then you should initialise it to a sensible default value. (See E-Vars) You should also use this call to claim any buffers you need. 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). 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 pointer to a double zero terminated list of zero terminated entries giving the names of the colours starting from 9. Eg "REMs",0,"Strings",0,0. (Or leave R1 as 6 if this call is not supported). 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. 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 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. \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. Do NOT start counting from the start of the file, as the window being updated may be near the end. Instead, use the start of the w_txt cache as a reference. Ie, use the variables w_cline, w_coff, w_clogl as your start reference. \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. \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. \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. 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) 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 16 colours numbered 0-15 available. These 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-15 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 and the background colour at R6+2*n. These are initially cleared to bytes '2' and '0' respectively - you should overwrite these bytes to change the colour. 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. 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. You should use Zap_Command to delete the text. Try and support the line edit mode. \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. Use Zap_Command to perform the function. \E R1=number of times pressed R8-R10=input caret \X You may corrupt R0-R11 e_return Called when RETURN executed (\E \X as for e_tab) e_renumber Called when RENUMBER executed (\E \X as for e_tab) e_saveandrun Called when SAVEANDRUN executed (\E \X as for e_tab) 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 lines first character. e_lineend Called to find the lines last character. e_linenext Called to find the lines actual end (eg after &0A) e_lineprev Called to find the lines 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. \E As for Zap_Command e_compile This is called when Compile pressed (\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 pressed (\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 pressed (\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 pressed (\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 pressed (\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. R1 gives the reason code. It gives you a chance to 'doctor' the string. Eg, BASIC may tokenise it. It is also called to check a match is at a valid offset. Eg, BASIC checks it isn't in a line number. \E R1=0 => Starting a search R0=search string after macros replaced (in a heap block). \X R0=possibly new search string. OR \E R1=1 => Found a match R10=match offset R9=file. \X Return R0<0 if the offset invalid. 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!! \E R0=your mode number R1=message block (as sent by wimp) R2=message number (ie R1!16) R3=message type (17 or 19) as returned in R0 by wimp. 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 effects 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 follwing data is available: f_docom=the command currently being executed: 0,>5=none => text not changing (just return with R0 preserved). 1=insertion => 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=deletion => 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.