************************************************************************* * >E-ZapCalls Documentation of Zap entry points (how to call Zap) * ************************************************************************* Zap does NOT have a SWI interface as it uses registers R8-R10 to point to data blocks, and these cannot be passed to swi's. To call Zap you will need to know the address of the Zap module workspace (ie it's private word). If you are an extension mode then this will be passed to you in R12 whenever you are called by one of your entry points. However, for the first call you make to Zap, when you add your module to it's list via Zap_Addmode, you will not know it. Then you should use OS_Module 18 to find it. Eg, SYS "XOS_Module",18,"Zap" TO R0,R1,R2,R3,workspace% Now, the first word in Zap's workspace contains the address of a table of Zap's entry points. Thus to call the entry point (documented below) at offset a% if you are using the BASIC assembler then the use of the following macro is recommended: REM Call Zap at entry offset a% REM Entry: R0-R11=args R12=zap workspace REM Exit : R0-R11=returned values R12 preserved R14 corrupted DEF FNcall(a%) [OPTpass LDR R14,[R12] \ get start of zap table ADD R14,R14,#a% \ address of the sub STMFD R13!,{R14} \ save address on stack MOV R14,PC \ return address (with flags) LDMFD R13!,{PC} \ call the sub ]:="" The names of the routines are listed below in the order in which they appear in the table. Thus the first, Zap_AddMode, is at offset 0. The second, Zap_Claim is at offset 4, etc. These values are defined for you in the program E-Library. In general these routines have the following entry/exit conditions: \E R0-R11=arguments R12=Zap's workspace R13=user stack R14=return address \X R1-R13 preserved. R0 and Flags ALTERED. V set if error and R0=error block Thus if I write: \E R8 \X R1=3 Then I mean that on entry R8 was the window block pointer, R12 zap's workspace etc. And on exit that R1=3, R2-R13 saved, R0 corrupted etc. If I omit the \E or \X then I mean the standard entry/exit conditions hold. Errors should be passed back to Zap by the entry point through which the module was called (with V flag set and R0=error block pointer). Please note that for most calls, Zap must be paged in as the current task! This will be so if you are an extension mode. For a table/summary of the zap call names for including in your source, see the file E-Library. Zap_AddMode Adds a new Zap extension mode. This should be called after the module Zap is loaded, but before it starts up as a new task. Zap need not be paged in for this call. \E R0=address of table of entry points (see file E-Entry) Zap_Claim Claims a block of workspace in Zap's heap. \E R0=number of bytes required \X R0=pointer to the heap block Zap_Ensure Ensures a zap heap block is of a given size. \E R0=pointer to the heap block R1=number of bytes required. \X R0=new heap block pointer of (possibly moved) extended block. (An error is returned if the block couldn't be enlarged). Zap_Free Free a zap heap block after use. \E R0=pointer to heap block to free Zap_MoveBytes Moves a block of memory. The movement may be up or down by any amount. The data is ALWAYS preserved no matter where the destination is. This routine is highly optimised and should be used for moving any large block of data. Zap need not be paged in. \E R1=source byte address R2=destination byte address R3=number of bytes to move \X R1-R3 corrupted Zap_SplitBuffer This splits a file held in Zap at the indicated file offset ready for insertion/deletion of data. It also ensures that file buffer has a given amount of room free. See E-File. \E R0=file offset to split at (new value for f_splito) R1=minimum number of bytes to have free in the split R9=file to be split Zap_NewTxtStatus This updates the screen after changes are made to a file. This is very low level and you should use Zap_Command when possible. Zap_SaveTxtStatus should be called first. \E R0/R1 as for SaveTxtStatus and R2=new input caret offset. Zap_SaveTxtStatus This is a low level call used by Zap_DoCommand when changing a file. You should use Zap_Command/Zap_DoCommand in preference. Any file changes done using this call are NOT saved in the undo buffer. Ie, don't use it. To use it you specify the area of the file to be changed (R0 to R2) and the amount of the change (in R1). After making the change you use Zap_NewTxtStatus to update the screen. Set f_docom to 0 if in doubt. \E R0=file offset of first byte in file to be changed. R1=proposed signed change in size of file. R2=file offset of first character which is unchanged. f_docom,f_dolen,f_dodata must be set up - see e_prevline. Zap_Command This should be used for inserting/deleting/replacing data in a file. Its action is to call the mode entry point named e_command. See E-Entry. The mode's default action is then to call Zap_DoCommand. The commands are automatically placed in the undo buffer. If you are doing a sequence of insertions/deletions then please use Zap_Start/StopOp. Note that the cursor is automatically updated to the end of the inserted/deleted region. To prevent this, set b14 of f_flags, but you MUST restore it after the command returns. \E R0=command number: 1=insert 2=delete 3=replace (forward) 4=replace (backward). 5=delete 6=insert (the last two leave the cursor at the start). Add &10 if command is to be buffered in one block (and thus undone in one key press). Add &20 if you do not wish the input caret to be updated Add &40 if the region is/was/should be selected R1=file offset for command to take place at. R2=number of bytes being inserted/deleted/replaced. R3=data to insert/replace with for commands 1,3,4. R8=window on file to be altered/0 if none. R9=file to be altered. NB If you don't specify the window then it won't know which mode to call, so this command will just call Zap_DoCommand. Zap_NewWinStatus This recreates a window after some display parameters have changed. Use Zap_SaveWinStatus before changing any parameters. \E R8/R9 Zap_SaveWinStatus This is used before changing any of the 'w_*' window parameters which would effect the display. See E-Window. The current cursor position, scroll offsets etc are saved. After changing the window parameters call Zap_NewWinStatus. Zap will do it's best to recreate the window with the new attributes, preserving the position of the cursor on screen. \E R8/R9 Zap_ReplaceArea This command replaces one area of text with another (not necessarily of the same length) by performing the minimum number of insertions/deletions/simple replaces using Zap_Command. In BASIC mode it also retokenises the line as necessary. This is used during a search and replace. See mode entry point e_replace. \E R1=file offset of original data R2=length of original data R3=address of replacement data R4=length of replacement data R8/R9 Zap_PlotCaret This command plots a caret in its new position automatically removing it from its old position. Ie, it just calls Zap_ClearCaret then Zap_SetCaret. \E R10=caret block Zap_ReflectCaret This acts as Zap_PlotCaret but only uses c_off, updating the c_loff and c_col offsets from this (c_charoff is set to 0). Ie, it just calls Zap_UpdateCaret and then Zap_PlotCaret. \E R10=caret block Zap_SetCaret This updates the area of the window containing the the caret given on entry. Hence its effect is usually to draw the caret at its (new) position. It calculates a value for c_charoff. See E-Cursors. \E R10=caret block Zap_ClearCaret As for Zap_SetCaret, but it updates the area of the window where the caret last was (stored in the c_o* variables). Hence the caret is in effect removed from its old position. See E-Cursors. \E R10=caret block Zap_DoCommand This acts as Zap_Command but actually performs the action rather than calling the extension mode. \E As for Zap_Command. Zap_ShowCursor This call makes sure that a given cursor can be seen in its window (by changing the scroll offsets if necessary). It does not redraw the cursor in general (though changing the scroll offsets may cause it to be redrawn). \E R10=cursor block of cursor to show Zap_ReadVar Reads one of Zaps internal variables. See the file E-Vars for the numbers. \E R1=variable number. \X R0=variable value. Zap_WriteVar Writes one of zaps internal variables. See the file E-Vars for the numbers. \E R1=variable number R0=new value Zap_SaveFile This saves a file to disc (using f_name as the file name). The file may not actually be saved if a dialogue box is opened. (Eg: 'file is older than version on disc box'). Please note the value of R0 on exit! \E R8/R9 = window to save \X R0=0 => File has been saved to disc - you can now delete it. R0=-1 => File has not yet been saved - warning window opened / data transfer initiated. Zap_FillWords Fast word filling code. The block must be word aligned. Zap need not be paged in. \E R1=word to fill with. R2=address of memory to fill (word aligned). R3=number of bytes to fill (a multiple of 4). \X R0-R3 corrupted. Zap_UpdateLns This updates the line numbers column of a given window. This is usually done automatically by Zap_Command. This is used by the BASIC mode on a renumber. \E R0=first physical line to start from R8/R9 Zap_EachWindow This sub calls a given sub for each window on a given file. Each time it calls the sub pointed to in R10, it sets up R8 for that window. \E R0-R7=args to pass to the sub. R9=file (whose windows you are to call). R10=address of sub to call for each window on this file. The sub called has: \E R0-R7 as set up by you R8/R9 points to the given window \X Must preserve R1-R11 and VS on error etc. Zap_UpdateCaret This sub is called to update a caret position from a given file offset. Save the new offset of the caret in c_off. Call this. Then c_col, c_line, c_loff, c_charoff and c_width will be set up. See E-Cursors. \E R10=caret block Zap_GetWindState Updates the window block R8 (first few entries) by calling Wimp_GetWindowState. \E R8 Zap_StartOp Starts a sequence of operations. This should be used when performing a sequence of calls to Zap_Command. It causes all the file changes to be made with only ONE screen refresh, thus giving a much smoother update. After this has been called, all subsequent calls to Zap_Command before a Zap_StopOp call have their actions concatenated. When you call Zap_StopOp the screen is then updated. You MUST call Zap_StopOp before returning to Wimp_Poll. StartOp/ StopOp's can be nested to any depth (so only the last StopOp actually causes the screen to be updated). \E R9=file which will be operated on. Zap_StopOp Ends a StartOp/StopOp structure. \E R9=file which has been operated on. \X If VC on entry then R0 corrupted and R1-R11 preserved as usual. If VS on entry then error pointer in R0 and V flag status are also preserved. Zap_CallMode Calls a mode entry point. See E-Entry for a list of entry points. The mode called is the mode of the window given in R8. \E R0-R10=parameters R8 R11=mode entry point offset \X As for the given mode entry point. Zap_CallGivenMode Calls a mode entry point of a specified mode. \E R0-R9=parameters R10=mode number R11=entry point offset \X As for the given mode entry point. Zap_ReadMode Read the address of the mode entry point tables. Two pointers are returned. The first (R0) is a pointer to the mode table as stored in the extension module and documented in E-Entry. The second (R1) points to a table of actual addresses to be called, with entry points which were null in the original table converted to addresses and all offsets converted to addresses. In this table, each entry consists of 8 bytes. The first 4 bytes gives the address of the entry point, and the next 4 the value to pass in R11 when the entry point is called. This will obviously vary if some mode entry points are based on other modes. Thus the linked table has the form: e_module #0 module address, module workspace address e_title #8 title address, mode variable table address e_author #16 author address, undefined e_basemode #24 basemode, clone basemode e_mode #32 mode number, mode e.p. suppliers list e_init #40 init code addr, value to pass in R11 e_menu #48 wimp menu data, undefined e_len #56 undefined, undefined e_postload #64 postload addr, value to pass in R11 and the rest as for e_postload. I reserved the right to use the undefined words in future. You can change the table entries pointer to in R1, but I don't advise it :-) The mode entry points suppliers list contains a mode number (byte) per entry point. \E R0=mode number. \X R0=pointer to unlinked table in modes module / <=0 if invalid R1=pointer to linked table in zaps workspace / <=0 if invalid Zap_FindFile Given the name of a file, this call produces a window on that file (loading it if necessary). Path is canonicalised before comparing with currently loaded files. \E R0=file name. \X R8/R9=window on that file. Zap_FindWindow Given a file block pointer of a file already loaded, this call produces a window block pointer of a window on that file (opening it if necessary). \E R9 \X R8 Zap_ConvWindOff Converts a window offset to a window block pointer. See E-Windows. \E R0=offset of a window in the window list /-ve \X R8/R9=window and file /0 Zap_ConvFileOff Converts a file offset to a file block pointer. See E-File. \E R0=offset of a file in the file list/-ve \X R9=pointers to the file block/0 Zap_GetWindOff Converts a window block pointer to a window offset. See E-Windows. \E R8=window block pointer/0 \X R0=offset in the window list/-ve Zap_GetFileOff Converts a file block pointer to a file offset. See E-File. \E R9=file block pointer/0 \X R0=offset in the file list/-ve Zap_GotoOffset This call causes the given cursor to jump to a given file offset, leaving a mark behind at the previous position. \E R0=offset to go to R8-R9=file R10=cursor Zap_JumptoOffset As for GotoOffset but no mark left on jumping. \E R0=offset to go to R8-R9=file R10=cursor Zap_FindOffset Given the (x,y) position in work area characters, finds the file offset of the 'nearest' point in the file. See E-Windows. \E R2=x column (inc margin) R3=y row (from top) \X R0=file offset R1=file offset of physical line start R2/R3 clipped Zap_NewFileTitle Update the titlebars of all windows on a given file. \E R9=file Zap_InsertString Inserts a string at the end of a buffer using Zap_Command. \E R0=zero terminated string R8/R9 Zap_CreateFile Creates an empty file, possibly changing the opt_flags/format via BIC 'mask' EOR 'eor' when creating it. See E-Flags, E-Windows. It calls Zap_CreateWindBlock and Zap_CreateFileBlock etc. \E R0=file type R1=flags mask R2=flags eor R3=format mask R4=format eor \X R8/R9=newly created file (with open window). Zap_NewLinkEntry Adds a new link entry to the f_links list. See E-File for description of the links list format. This is a low-level call. Use Zap_Throwback in preference. This is used by throwback. A new block is created if the file name does not match that of the previous link block, or the flags differ. The point of the links is that they are updated when changes are made to the indicated file. \E R0=data word (Ie file offset of link / line number of link depending on flags in R5). R1=filename (Of the file that R0 is an offset in). R4=file offset/-1 (Ie, offset in file list of the file named in R1 if the file is loaded, or -1 if you don't know if the file is loaded or not - usually safest to put as -1). R5=flags (as documented under f_links in E-File). R9=file to which the link should be added - ie this is the throwback buffer file as opposed to R1 which is the file giving the C program / file which was searched through. \X R0=0 if link added to last list entry/1 if new entry created. Zap_DefaultClick Calls the default mouse click handling code. See the entry point e_click. \E R1=depth (0=drag 1=click 2=double click etc) R2=x R3=y R4=buttons R8/R9 as for e_click. Zap_PutCaret Sets standard cursor editing mode and puts the cursor caret at a given file offset in a given file. \E R0=file offset R8/R9=file Zap_DiscardFile Kill a file and all windows on that file without prompting user. \E R9=file Zap_DeleteFile As for Zap_DiscardFile but prompts user if file altered etc. \E R9=file Zap_DiscardWindow Kill a window, and the file if auto-delete is on and this is the last window on that file. Don't prompt user. \E R8/R9 Zap_DeleteWindow As for Zap_DiscardWindow but prompts user if file altered etc. \E R8/R9 Zap_BuildMenu This is Zap's 'variable length menu' building sub. See E-Menu for details on Zap's menu format. If you want to be able to specify help text, use Zap_BuildMenuWithHelp instead. \E R0=menu name (max 12 chars) R1=address of sub to generate the menu entries b0 set if the menu name is a MessageTrans token (no parameters, no GS translation) R2=address of menu updating sub/0 if none (see E-Menu) R3=address of menu interpret sub for all entries/0 (see E-Menu) R4=menu width in chars R8-R11=values to call the sub in R1 with on the first call. \X R0=pointer to wimp menu structure The sub passed in R1 has the following conditions: \E R0=buffer for you to put the next menu entry in (48 bytes) R5=address of menu structure start } R6=address of current menu entry } you don't need these R7=address of current buf entry } R8-R11=as returned from last call \X R0=index for this entry/-1 if no more entries (see E-Menu) R1-R7 saved R8-R11=updated (ie for your own use). Zap_ClearSel Clears currently selected area. Zap_CreateFileBlock Creates a new file block with currently configured options. f_ptr etc are set up for you. See E-File. Use Zap_Install file to load a file. \E R0=size to make buffer R1=filename of buffer R2/R3=load/exec \X R9=new file block (with file filled with rubbish). Zap_CreateWindBlk Creates a new window block with currently configured options. Window is opened on the screen etc. \E R9=file window is to be on. \X R8=New window on this file. R0=Block of info on the mode used (see Zap_WhichMode). Zap_GetSel Find out what area is selected. \X If CS then no valid selection. If CC then R1=file offset R2=selection length R8/R9=file. Zap_InsertMark Insert a marker. \E R0=file offset of mark R8/R9 Zap_InstallFile Load a file into zap. \E R0=filename \X R0=window offset of created window / -1 if not loaded. Zap_NewMode Change the display mode of a window. \E R0=new mode number R8/R9 (R8=0 to change options mode) Zap_NewTitle Update the titlebar on a given window. See also Zap_NewFileTitle. \E R8/R9 Zap_CallBaseMode DO NOT USE THIS. This call is now obsolete. Use the call Zap_BaseMode instead. If you use this call it will appear to work perfectly until someone tries to use your mode as a base mode. When this happens an infinite loop occurs which I can't fix. The docs are kept for backwards compatibility. -------------------------------------------------------------------------- As for Zap_CallMode except it calls the base mode instead. The window in R8 identifies the current mode. The entry point called is that of the base mode associated to this current mode. Hence, it would be used by a mode to call a base mode entry point which the current mode has redefined. \E R0-R10=parameters R8 R11=mode entry point offset (see E-Entry) \X As for the given mode entry point. Zap_NewView As for Zap_CreateWindBlk but 'clones' a given window image. The cursor is not put in the window. \E R8/R9=window to clone from (R8=0 then don't clone) Zap_ReadSel Reads the currently selected region into a heap block. You must free the heap block when you have finished with the selection. \X R3=heap block with data and R2=length / R3=0 if no selection Zap_Replace Calls the Zap file search and replace code using the current search string and current replace string. \E R1=0 for selective/1 for global R3=start offset in file R4=direction (+1/-1) R5=search flags (as for Zap_Search) R8/R9=current window Zap_Search Calls the Zap wildcard search code. \E R0=pointer to search string R1=output 0=to cursor 1=to buffer 2=no output 3=count OR &100+offset of throwback window to add search matches to. R3=start offset of the search (in the file) (NB The first offset actually tested is R3+R4 so use R3=-1 to search from the start of the file). R4=search direction +1/0/-1; if 0 the given offset only is examined. R5=search flags b31=set for a raw search (don't search by lines) b30=set if case sensitive b29=set if macros shouldn't be expanded b28=set if \commands should be ignored (and `s etc) b27=set to search all windows (move to next one after) b26=don't update hourglass in search_text b25=don't beep if no match found b24=return end of match offset in R1 (if one found) b23=rsvd (search_init sets if wild_conv_chars found \s) b22=don't display hourglass percentage if set b21=ignore supplied R3/R4; try to match at cursor/point R8/R9=current window of search \X If R1=0 or 1 then output displayed If R1=0 or 2 then R0=match offset on exit / -ve if none If R1=1 then R0=offset of throwback window / -ve if none If R1=3 then R0=number of matches R1=offset of end of match (if b24 of R5) Zap_Select Selects a given region, and puts carets back to default mode. \E R2=start offset R3=end offset R8/R9 Zap_AlterSel As for Zap_Select but doesn't restore caret modes. \E R2=start offset R3=end offset R8/R9 Zap_OffLineCol Converts a file offset to an x,y coordinate pair in the window work area. See also Zap_FindOffset. See E-Windows. \E R0=file offset R8/R9 \X R0=start of line offset R2=column (inc margin) R3=row Zap_AddCommands Adds a table of commands to zap's list. Zap can currently cope with up to 32 tables of commands. This should be called when a module initialises as for Zap_AddMode. Zap need not be mapped into memory for this call. See E-Commands for the table format. \E R0=address of command table (R12=Zaps workspace). Zap_MiniWrite This call sends a stream of characters to the minibuffer. The minibuffer contents is changed but not updated on screen. However, if this call is used within a command, then the minibuffer will updated on screen automatically by Zap. Use Zap_MiniUpdate to force an update, but you shouldn't have to use this. The minibuffer takes the form: . The user cannot move the cursor before the 'invisible' mark. The string passed to Zap_MiniWrite may contain the following control codes: 0=string terminator 1=move cursor to mark (ctrl a) 2=8=move cursor back one character (ctrl b) 4=delete character after cursor (ctrl d) 5=move to end of string (ctrl e) 6=9=move cursor forward one character (ctrl f) 11=clear buffer from cursor (ctrl k) 12=clear whole buffer (ctrl l) 21=clear buffer from mark (ctrl u) 28=set mark to current cursor offset 127=delete character before cursor When a command with string parameter is called, R0 points to the user editable part of the string. (See also Zap_MiniWriteToken.) \E R0=pointer to zero terminated string Zap_MiniPrompt This replaces the prompt string in the minibuffer with the given string. It's main use is for reason code R2=6 when a command with string parameter is called (see E-Commands). The buffer is not updated on screen (see Zap_MiniWrite). Unlike Zap_MiniWrite, the minibuffer cursor is not affected by this call (It remains the same number of characters after the mark). ": " is automatically appended (taking note of whether the string already ends with ": "). \E R0=new prompt string b31 set to suppress automatic appending of ": " Zap_MiniUpdate This call updates the minibuffer on screen (if open). This will usually be done automatically by Zap. Zap_AddYankRegion This call adds a region to the cut/paste kill ring. The region you pass it is not copied so must be stable (eg in a heap block). \E R0=address of region + flags: b31 MUST BE SET (If clear then denotes an undo buffer ref). b30 If set, then after yanking this block, it will move onto the block before (ie, yanks many blocks at once). R1=block length (provided b31 of R0 is set). Zap_FindCommand This call converts a command name into a command address by looking it up in Zap's command tables. If the command is in an extension module then that module is loaded as well. \E R0=command name terminated by <=32 or :,&," \X R0=command address / 0 if not found Zap_ProcessCommand (see also Zap_CommandString). This makes a call to a Zap command. It should be used for all calls to commands. You can find the address of a command via Zap_FindCommand. You may also call commands which may not have a name - it just considers the command address. The data the command takes is pointed to in R0. The data format depends on the command. It should point to a list of bytes/word or a string depending on whether the command takes a byte/word or string parameter. It is undefined if the command takes no parameter. See E-Commands for more details. Put R0=0 instead of the pointer to a string to open the minibuffer instead. The number of times the key has 'auto-repeated' is passed in R1. This will be the length of the byte/word list if the command takes byte or word parameters. Usually put R1=1. R2 holds the action code of the command. Action code 0 executes the command. The other action codes are used to read information about the command and are mainly used internally by Zap. See E-Commands for the details. NB The mode e_aligncaret entry point will be called before all command calls using R2=0,1 on entry. \E R0=pointer to command data (0 if there is no data) R1=length of the command data if byte or word list (in bytes or words). Number of times key has auto-repeated otherwise. R2=Command action code: b0-b23 = Action code to be passed to the command. 0 to execute it - see E-Command. b24-b31= Flags to tell Zap_ProcessCommand things. These are filtered out before R2 is passed to the command. b31=Set if command should not be learnt even if in learn mode. b30=Internal use; must be 0 b28-29 reserved b24-27=parameter type (use R6 returned by Zap_ReadValidateCommand) command table, but must conform to the specs in the file E-Command. Eg, [R7,#-4] must be the flags word). R8=window block pointer or 0 if none applicable (options menu) R9=file block pointer or 0 if none applicable (options menu) R10=input cursor (or cursor you wish command to act on) or 0 if not applicable. \X R1-R13 preserved. If action code=0 on entry then R0=0 or -1 if minibuffer opened. If action code>0 on entry then R0=value in R0 when command returned. Zap_FindKeyEntry This finds the entry corresponding to a given key and keymap. You might use it for redefining the key for instance. The block pointed to on exit has the format: #0 Command address (or 0 if none - key is passed on to wimp) (The module containing the command is loaded if necessary). #4 Command parameter, this depends on the command flags b3-7. If these bits are: 0 => #4 undefined (should be 0) 1/2 => #4 is the byte or word to be added to the list to be passed to the command when the key is pressed. 3 => #4=address of string parameter /0 if minibuffer should be used. 4 => #4=address of the data block. #8 Command parameter type As for b3-5 of command flags word, with 8=int expr 9=str expr \E R0=keymap number R1=zaps key number (0-&1FF) \X R0=entry for this key / 0 if keymap does not exist or key is out of range. Zap_FindLeafName This works out which part of a filename is the leafname. \E R0=filename pointer \X R0=pointer to the leafname part (within the filename). Zap_NewFileName Change the name of a given file. You may have to call Zap_NewFileTitle to update the titlebars (this will usually be done by Zap_SaveFile). \E R0=new file name R9 Zap_CheckFileName Decides whether a filename is a full path name (eg "ADFS::$.Wibble") or just the leaf name of a file (eg "Text1"). Should be used in conjunction with Zap_SaveFile as this will not save files without full path names. \E R0=filename \X R0=0 if it is a full path name / 1 otherwise Zap_GetCurrDir Returns current directory (of the temporary filing system) which should be used as default string in minibuffer file operations. On RISC OS 2, there is no way of reading the current directory so this call returns the root directory on the current disc (via OS_Args 0, OS_FSControl 33, OS_GBPB 5). On RISC OS 3, the current directory is read via OS_Args 0, OS_FSControl 33, and OS_FSControl 54. NB The block it is returned in is not stable over calls to Zap. You may call Zap_MiniWrite passing this block but should copy the string for other calls. \X R0=pointer to 256 byte buffer containing the directory name Zap_MiniWriteC Writes a single character to the minibuffer. See Zap_MiniWrite for the character codes. \E R0=character to insert in minibuffer. Zap_MiniClear Clears minibuffer contents without updating on screen. Resets marks etc. You should use this before using Zap_MiniStart. Zap_MiniStart This starts up the minibuffer. Do not use this call when writing a Zap command. Read the file E-Command to see how the minibuffer works in this case. You never need this call, Zap_ProcessCommand can open a minibuffer at any time if you feed it a string type command and R0=R2=0. \E R7=address of command to be called when return pressed in minibuffer. [R7,#-4] must contain the command flags word as documented in E-Command. R8/R9=window minibuffer should appear at. Zap_MiniEval This turns a string into a number via OS_EvaluateExpression. It is usually called near the start of a command which expects to find a number in the minibuffer. \E R0=string pointer (usually minibuffer pointer passed to you) \X R0=number stored in string/CS if not a valid number. Zap_CommandString (see also Zap_ProcessCommand) This call takes a command (or colon separated list of commands) in string form and executes them as typed. For example if R0="MODE 0" on entry then first of all a call to Zap_FindCommand will be made to find the address of the command "MODE" and then the command will be called via Zap_ProcessCommand with R2=0. \E R0=command string (zero terminated) Set b31 if you don't want the commands to be learnt if in learn mode. \X R0=0 or -1 if the minibuffer has been opened. Zap_ProcessKeys This entry point accesses Zap's main key handling sub so you can simulate keypresses. If you just wish to simulate one key press, then it is easier to use the next call. This call is for multiple keypresses and buffers the data as much as possible before it has to call a command. You must keep calling this command until it returns R0<0 (as it will do if you put R5=-1 on entry - it uses the R5=-1 call to execute the buffered data). \E R0=zap key number of next key to execute (if R5>=0) R5=-1 => there are no more keys to buffer (R0 not defined). 0-&1FF => wimp key number of key to send to Wimp_ProcessKey if no command is attached to the key. &200 => if Wimp_ProcessKey should never be called. R6=length of current buffering (set to 0 on first call) R7=command currently being buffered (if R6>0) R8-R10=input cursor \X R0>=0 if you should call this sub again with the next key (or R5=-1 if there are no more). R0<0 if the command has finished processing all buffered data so you needn't call it again. R6/R7 are updated for the next call. Zap_ProcessAKey This command simulates a key press by calling the above command twice, once with the key and then once with R5=-1. \E R0=zap key number R5=wimp key number (see Zap_ProcessKeys) R8-R10=input caret Zap_OpenWindow The current position of a Zap window can be read easily using the code: MOV R1,R8 : SWI "XWimp_GetWindowState". However, you should not call Wimp_OpenWindow to open a window as Zap has to keep track of the title length and position of the minibuffer etc. You should use this call instead. Use call 0 where possible as it prevents titlebar flicker. \E R0=type of open: 0 => Just changing scroll offsets or height in window stack. Size/position of window NOT changing. 1 => Window may move/change size. Minibuffer, title bar and cursors dealt with accordingly. 2 => Window is a new window. Toggle size data etc reset. 3 => Bring window to front of stack (ignore R1) 4 => Put window to back of stack (ignore R1) 5 => As for 0, but cursor kept within the window if the 'constrict cursor' option is on. (NB type 2 calls type 1 calls type 5 calls type 0) R1=open block (as for Wimp_OpenWindow) R8=window block (NB Usually alter this block and let R1=R8) Zap_RestoreModeWord This call should be used by your e_start entry point. If R8<>0 on entry then it reads the reads the options for the given mode from w_datablock using the call Zap_ModeData, and sets them as the current options. If R8=0 then it does the same thing but sets the default options. \E R0=mode number R8=window to restore options on / 0 for the default options. Zap_SaveModeWord This call should be used by your e_end entry point. If R8<>0 on entry then it reads the words w_flags and w_format and stores the current options in the w_modedata block by use of the call Zap_ModeData. If R8=0 on entry then it reads opt_flags and opt_format and stores them as the default option etc. \E R0=mode number R8=window to save options on / 0 for the default options. Zap_GetModeWord This call reads the contents of your mode word. If R8=0 then it reads opt_moden, otherwise it reads [R8,#w_moden]. This is useful for menu options. \E R1=mode number R8=window to get mode word / 0 for default options mode word \X R0=mode word contents. Zap_PutModeWord As above, but write the value. \E R0=new value for the word R1=mode number R8=window to put mode word / 0 for default options mode word Zap_BaseMode This call replaces Zap_CallBaseMode. It differs in that you must specify which mode is calling. This information is not necessarily available from the block in R8 if another mode is based on yours. The basemode of the mode named in R9 is called via the entry point offset given in R11. Before the entry point is actually called, R9 is converted to the file block pointer of the window specified in R8. Hence any entry point requiring R8 and R9 set up on entry can be called ok. \E R0-R7=parameters for the call R8=window block to be used by the call. R9=mode number making this call (your mode number). R10=parameter for the call (usually cursor block pointer). R11=mode entry point offset (see E-Entry) to call. \X As for the given mode entry point. Zap_ReadWord This call can be used for reading 4 byte from a file buffer. Note that although the offset of the word in the file may be word aligned, it's offset in the buffer may not be due to the split. This call reverses the word if the Big Endian flag is set. \E R0=File offset of the word to be read R8=window (for big endian flag to be read) R9=file \X R0=the word read (padded with zeros if it went off the file end). Zap_ReplaceWord This call replaces a word at the given file offset (inserting if the file offset+4>file length) via Zap_Command. The word is reversed if the big endian flag is set. \E R0=word to replace R1=file offset R8/R9 (R8 used for the big endian flag). Zap_ModeColour This call reads or writes the colour definition table. It will not usually have immediate effect unless you recreate the window (eg Zap_NewWinStatus). You shouldn't usually access this data as Zap handles it all for you, except to write sensible default values (using R8=0) if your mode starts up and finds its mode word is zero. \E R0=colour to write: -1 => Don't write anything (just read the value) b0-b7 <16 => Write this wimp colour (converting it to RGB) b0-b7 >15 => Write 24 bit colour of the form &BBGGRRZZ where ZZ is the Zap style: Bit 4=1 Bits 5, 6 and 7 : sub-style: bit 5 : Bold bit 6 : Italic bit 7 : Underlined R1=mode number R2=Zap colour number of the colour to write/read: 0/1=Background 2=Foreground 3=Selection background 4=selection foreground 5=cursor back 6=cursor for 7=line numbers 8=control chars 9+ mode dependent extension colours. R8=Window block to read from / 0 for default (!Config) settings. \X R0=colour value read / old value if writing it. This is of the form &BBGGRRZZ as above. Zap_FindInput This call works out the current position of the 'input focus' in a window. If the input caret is in this window then it returns it's offset. Otherwise it returns the 'point' position (usually marked by an empty square). \E R8/R9 \X R0=most suitable offset to insert data. Zap_ClipCache This call moves the cache reference point (w_cline/coff/clogl etc) to a given point (using e_clnoff). \E R0=Offset in line to move the cache reference point to. R8/R9 Zap_ModeData This call reads or write the mode dependent options that Zap handles automatically for you. See also Zap_ModeColour. Currently there is only one word per mode storing the width and things like whether auto-indent is on or not. You should use this call with R8=0 to write sensible default values if your mode starts up and finds its mode word is zero. If you don't then the default Text mode values will be used. \E R0=value to write / -1 to read R1=mode number R2=variable number to read write R8=window concerned / 0 for the default (!Config) settings. \X R0=variable value if read / old value if written Variables num: 0 b0-b15 stores the "width" for this mode b16 auto indent bit (w_format b16) b17 auto width bit (w_flags b6) b18 strip spaces bit (w_format b18) b19-b21 tab mode bits (w_flags b9-11) b19-b20 0=Unix 1=Edit 2=Coltab b21=insert tabs as spaces b22 hex entry mode bit (w_flags b5) b23 overwrite bit (w_flags b1) b24-b31 display bits (w_format b8-15) b24=line numbers shown b25=line numbers as lines (not addr) b26=line numbers in hex b27=logical line nums (not physical) b28-29 0=no tabs 1=spaces 2=> 3=-> b30=line edit paradigm b31=non standard editing 1 b0-b2 Line number width b3 Line number colons b4 Internal use : font sub-styles off b5 Infinite window wrap b6 Use line selection paradigm b7 Spell-as-you-type b8 Big endian (w_format b17) b9 Strong soft wrap b10 Block edit b11 Reserved b12 Set if linewrap mode on (w_flags b26) b13 Set if wordwrap mode on (w_flags b13) b14 Reserved b15 Reserved b21 Free mouse clicks (w_format b21) b22 Auto soft wrap (w_format b22) b23 Confined cursor U/D (w_format b23) b24 Confined cursor -> (w_format b24) b25 Smart shift-cursor (w_format b25) b26 Window-wrap (w_format b26) b27 Soft-wrap (w_format b27) ...other bits reserved... 2 b0-7 Reserved (was base keymap number) b8-15 Display colour block number b16-23 Printer colour block number b24-31 Number of colours per block 3 b0-7 Number of extra system colours ...other bits reserved... 4+ reserved. Zap_WhichMode This call decides which mode a given file should be displayed in. \E R0=load address of file (containing the filetype) R1=filename pointer / 0 if not known b31=flag to determine the meaning of R10 on exit \X R0=address of a data block of info about this file mode. R10=If b31 of R1 was clear on entry then this is the mode number of the default mode the file is loaded into (the mode is loaded if necessary). If is was set then this is a pointer to the mode name (mode not necessarily loaded). Zap_ModeNumber This calls turns a mode name (given by a string) into a mode number. The mode is loaded if not already resident in memory. \E R0=mode name string terminated by <= space (&20) \X R0=mode number or -1 if not found. Zap_SendDataSave This call initiates the save protocol, saving data to another window or application via RAM transfer or WimpScrap. It sends the data_save message and all replies are handled automatically. \E R2=proposed file/leaf name of the data (or 0 to use the file's) R3=destination window handle or task handle R4=destination icon handle (if R3=-2) R5/R6=destination mouse coords (if applicable) R7=routine to call after save finished (or 0 if none). R8/R9=R8<>0 => Save whole file R8=window block R9=file block R8=0 => Save currently selected region. (or set b1 of R10 to save an arbitrary region). R10=b0-b15 flags: b0 set => External edit flag. In this case R3=ext edit job handle and R4=ext edit task handle and external edit message sent instead. b1 set => R8=start address of data to save R9=size of the data to save b16-b31 of R10=filetype of data to save. b16-b31 = extra data (see b1) R11=data to pass to routine in R7 (if used). \X Data transfer protocol initiated. Sub pointed to by R7 is called with R11 as passed above and should preserve R1+ as usual. Zap_Warning Warns the user without generating an error. This opens a window with the given message and pauses for the message to be seen before returning. Wimp Poll is not called. \E R0=warning message R1=time to leave message open in cs (0 for default delay) + flags: b31 => Don't beep when opening the window b30 => no "Warning: " prefix. b29 => call Zap_LookupTokenR0 first R4-R7=parameters for %0..%3 (if R1 b29 set) R8/R9=window in which to show the warning. Zap_AllWindow Calls a given subroutine once for each valid Zap window. See also Zap_EachWindow. \E R0-R7=arguments to pass to the sub R10=address of the sub to call (which must preserve all registers except R0, and is called once for each window with R8/R9 set up to be that window). Zap_ReadMenu Converts a text file of the same format of Zap's 'Menu' file into a Zap menu structure. \E R0=start of a zero terminated menu text file (stored in memory) \X R0=pointer to heap block containing the following information #0 Number of valid menu handles for this file (first number appearing in the file) #4 Pointer to the menu structure (in Zap-Wimp format) for handle 0 (or 0 if handle 0 not used) #8 Pointer to structure for handle 1 #12 Pointer to structure for handle 2 etc. Zap_LoadMenu Converts a text menu file to a Zap menu structure. \E R0=pointer to filename of the menu file \X R0=list of menu handles as for Zap_ReadMenu Zap_OpenMenu Opens a menu on the screen. The menu structure is handled automatically once it has been opened. \E R1=pointer to Zap-Wimp menu structure R2=mouse x to open at R3=mouse y to open at R8/R9=window the menu is being opened on or 0's for none (eg the iconbar menu). Zap_CallBack Schedules a subroutine to be called again at a certain time but using wimp null events. \E R1=(earliest) monotonic time to call back at (>0) or -(smallest delay before calling back) =< 0. R2=address of routine to call. R3=data to pass to the routine in R11. The routine pointed to by R2 has conditions: \E R1=current time R11=value passed in R3 \X (must save R1+ as usual) Zap_DragBox Starts a wimp drag box making sure you get called when it's finished. \E R0=b0 set if you wish to be called repeatedly during the drag b1+ reserved (set to 0) R1=drag box block to be passed to Wimp_DragBox R2=address of routine to call. R3=data to pass to the routine in R11. The routine pointed to by R2 has conditions: \E R0=reason code 1=drag in progress 2=drag has just finished R1=drag box posn as returned by wimp if R0=2 R11=value passed in R3 \X (must save R1+ as usual) Zap_SendMessage Sends a wimp message and logs the message number (my_ref) so that any reply can be forwarded to you. The message reference is held for at least a minute and only deleted on a null event. E R0=b0-b27 message action number (to go in R1,#16) b28 set if you are interested in the reply. b29 set if you want to be called when message deleted b30-31 00 => Just send the message (with code 17) 01 => Just acknowledge the message (with code 19) 10 => Send the message recorded (with code 18) and call the reply code if the message replied to. 11 => Send the message recorded (with code 18) and call the reply code if the message replied to or bounces. R1=message block R2=dest task handle/window handle R3=b31 clear => This is the message length (is rounded up to next word) b31 set => This is the offset of a string ending the message. R4=icon handle if R2=-2 (iconbar) [not used otherwise] R5=address of routine to call when message replied to [if b28 of R0] (zero as a value means that you want any replies to be dealt with as if they were normal messages and not a reply) R6=private word to pass to routine on a reply [if b28 of R0] X The message is sent as an original message. Hence the my_ref, length and message action fields are filled in for you. R0=task handle of the dest task (R2 on exit from Wimp_SendMessage) Routine in R5 called with: ;E R0=message type 0 => message being removed from log list (see b29) 17 => message replied to as normal 19 => message bounced R1=message block R2=message number (R1!16) R11=private word R12=Zap's etc ;X You can corrupt R0-R11 if R0=17,19 You should save R1-R11 if R0=0 Zap_Reply Replies to a message. It copies my_ref to your_ref for you can reads the task handle of the task to reply to from the message block. The length word is assumed to be unchanged. E R0=message action number (as for SendMessage) R1=message block (with ref etc) R5/R6=routine to handle the reply if b28 of R0 (as for SendMessage) Zap_Extend Changes the size of a heap block, making it smaller or bigger as for OS_Heap with the extend action code. \E R0=pointer to the heap block R1=signed change in the size \X R0=new heap block pointer (it may have moved) Zap_ModeColourNum Reads/writes the size of the colour palette used by a given mode. Maximum size of a palette is currently 256 colours. Use R8=0 to read the default values. NB If you enlarge the palette then please write some sensible values for the new entries! \E R0=new size of palette (in number of colours) / -1 to read R1=mode number R8/R9=window or R8=0 for the default options. \X R0=old size / read size. Zap_CreateThrowback Creates a throwback buffer ready for lines being inserted by Zap_Throwback. \E R0=suggested width of window / 0 to use default width b31,30 = 01 R1 = task handle = 10 R1 = filename = 11 R1 = name token b29 set R2 = list of those tokens which the mode supplies to Zap_Throwback for use at various line starts. Note that codes < 32 are *not* ignored. Format: each entry consists of +0 0 +4 Throwback colour number + special value in top 4 bits +8 Token name (NUL term, padded to align) The list is terminated by 0,0,. The special value must be either 0 or 6; set it to 6 if the colour must be reset after a colon. \X R0=window offset of window R8/R9=newly created throwback window Zap_Throwback Inserts a line in a throwback file for you. \E R0=file offset or line number of line with info on it set b31 to suppress this being printed automatically. R1=filename (of the file that R0 is an offset in) R2=information string to print after the line number (eg "Bad syntax") b31 set if this is a MessageTrans token R3=string to precede filename (eg "Errors in file:") b31 set if this is a MessageTrans token R4=file offset of linked file / -1 if may not be loaded R5=flags to use for the new entry (see f_links,#12) R6=string to precede new info block (eg "Line num Error") b31 set if this is a MessageTrans token R7=string to go after filename (eg 10,"Search string: fred") b31 set if this is a MessageTrans token R8/R9=throwback window to add entry to (MessageTrans tokens: no GS translation, no parameters.) \X Throwback entry added and new title block given if file (or flags) have changed KB # The line number field is 10 characters wide if not suppressed. Zap_TestModeName This calls determines whether or not a given mode is loaded. It returns the mode number of the given mode or -1 if the mode is not loaded. \E R0=mode name string terminated by <= space (&20) \X R0=mode number or -1 if not loaded. Zap_UpdateArea *** DEPRECATED Forces an immediate redraw of a window area. The area in given in x,y character col, row coordinates. \E R1=redraw block (as for Wimp but in character coords - ie window handle, min x col, min y row, max x col, max y row) R8/R9 = window \X Coordinates in R1 changed to OS coords and window updated Zap_UpdateWindow *** DEPRECATED Forces an immediate redraw of a window area. Entry and exit as for Zap_UpdateArea except that coordinates are given in Window work area OS coords. (Internally UpdateArea calls UpdateWindow after coordinate conversion). Zap_UpdateWholeWindow Force immediate update of the text cache and redraw of the window. \E R8/R9 = window Zap_AllFiles Calls a given subroutine once for each valid Zap file. See also Zap_AllWindows and Zap_EachWindow. \E R0-R7=arguments to pass to the sub R10=address of the sub to call (which must preserve all registers except R0, and is called once for each file with R9 set up and R8 = 0. Zap_ReadValidateCommand Translates a string into an executable block of command information. E R10=pointer to string terminated by <&20 X R0=-1 => args invalid (only tested if command loaded) 0 => all ok 1 => args valid for keymaps only (uses n form) R1=parameter R6=parameter type 0=none 1=num 2=usekeynum 3=stringblock 4=data 8=int expr 9=str expr R7=command address R10 updated to next non-white space which is not a ':' CS if an external module has been loaded as a consequence CC otherwise. Error is generated if the command cannot be found. (String of commands concatenated to a single Multicommand) (: skipped so can have multiple lines) Zap_ProcessKeyCommand Calls a command using the same routine as used when a command is bound to a key. For use mainly with Zap_ReadValidateCommand. \E R0=data => The byte/word if mode 1/2 and ptr to data if mode 3+ R2=Command action code: b0-b23 = Action code to be passed to the command. 0 to execute it - see E-Command. b24-b27= parameter type (use R6 returned by Zap_ReadValidateCommand) b28-b31= 0 (Bits 24-31 are filtered out before calling the command.) R7=command address R8-R10=window/file/cursor or 0 \X Command called once with R1=1 Zap_ReturnWord Calls the text mode e_returnword entry with given delimiters. This is mostly of use to commands such as SelectUntil. \E R0=flags b0 => list are non-delimiters not delimiters b1 => control characters form an implicit list b2 => control characters are non-delimiters not delimiters R1=list (can include ranges, eg: "A-Za-z_" or "A-Z-") R8-R9 R2=offset to pass to e_returnword as R0 \X R0=file offset R1=length Zap_DoReplaceArea Acts like Zap_ReplaceArea, only does not involve the mode, i.e. it uses Zap_DoCommand, rather than Zap_Command. \E R1=file offset of original data R2=length of original data R3=address of replacement data R4=length of replacement data R9 Calls Zap_ReplaceArea with R8=0 Zap_LogicalLine Replaces e_clnlog in a manner which allows processing of the returned parameters. Entry and exit conditions are exactly as for e_clnlog: \E R0=logical line number R8/R9 \X R0=file offset of line start R1=physical line number Zap_PhysicalLine Replaces e_clnphy in a manner which allows processing of the returned parameters. Entry and exit conditions are exactly as for e_clnphy: \E R0=physical line number R8/R9 \X R0=file offset of line start R1=logical line number Zap_OffsetLine Replaces e_clnoff in a manner which allows processing of the returned parameters. Entry and exit conditions are exactly as for e_clnoff: \E R0=file offset R8/R9 \X R0=physical line number R1=file offset of physical line start R2=logical line number Zap_NextLine Replaces e_nextline in a manner which allows processing of the returned parameters. Entry and exit conditions are exactly as for e_nextline: \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 in the above four calls, the mode called is the mode specified by the window block in R8. Calling the entry points of arbitrary modes is currently only possible with this mechanism by manually poking the required mode number in temporarily. Generally, these calls should be used in place of their low level equivalents in extension modules. Zap_EvaluateExpression Evaluates the supplied string via OS_EvaluateExpression, after parsing and evaluation of any Zap functions that it may contain; for example, the string "@MODEN LEFT 3" will return the leftmost three characters of the mode name as a string. \E R0=zero terminated string (the expression) R1=maximum length of result, if string (0 if you want int only) \X R0=0 / address of string (in Zap's heap) / error R1=integer / length of string / undefined VS on error Zap_ClaimMessage Claims and forwards the next receipt of a given message. The claim is held until it has been successfully forwarded (or an error occurs when a potential claimant is called). \E R1=message number R2=address of routine to call when message received R3=private word to pass to routine You should store sufficient data here in order that the routine can check whether it's actually interested in this message and return quickly if it isn't. \X Claim is logged; R1 corrupt. Routine in R2 called with: \E R1=address of message block R2=message number R11=private word R12=Zap's workspace \X R0=0 if uninterested; claim remains logged R0<>0 if interested; claim removed from log The routine must do any necessary processing of the message before returning. VS on error; claim removed from log If the return type is string, then it is up to the calling code to free the heap block at R0. Zap_TestChanged Tests to see if a file is modified, allowing for the possibility of "possibly modified"; if the file is in this state (ie. >=16K, has its original length, and is marked as modified) it will calculate the checksum to determine whether the file is actually modified. \E R9=file \X R0 corrupt Z set if file is unchanged Zap_MarkChanged Marks the file as changed or unchanged, recalculating the checksum automatically. \E R0=0 (unchanged), <>0 (changed) R9 Zap_CalculateChecksum Calculates the checksum for the file. \E R9 \X R0 = checksum for the file. Zap_LookupToken Looks up a token, placing the result in the supplied buffer; parameter substitution is performed, and the string will be NUL-terminated. If no buffer is supplied, then no substitution can be done and the string will be LF (or possibly CR) terminated. (Uses MessageTrans_Lookup.) \E R1=token R2=buffer (or 0 to use none) R3=maximum length (ignored if R2==0) R4-R7=parameters for %0..%3 \X R1=token terminator R2=result string R3=length (exc. terminator) Zap_LookupTokenGS Looks up a token, placing the result in the supplied buffer; parameter substitution and GS translation (eg. '|J' -> LF) is performed, and the string will be NUL-terminated. If no buffer is supplied, then no substitution can be done and the string will be LF (or possibly CR) terminated. (Uses MessageTrans_GSLookup.) \E R1=token R2=buffer (or 0 to use none) R3=maximum length (ignored if R2==0) R4-R7=parameters for %0..%3 \X R1=token terminator R2=result string R3=length (exc. terminator) Zap_LookupError Looks up a token, placing the result in the supplied buffer or in a default buffer. (Uses MessageTrans_ErrorLookup.) \E R0=error block containing the token R2=buffer (or 0 to use default) R3=maximum length (if R2<>0) R4-R7 -> parameters for %0..%3 \X R0=pointer to error buffer V set Zap_LookupTokenR0 Look up token, performing no GS translation or parameter substitution. (This is equivalent to Zap_LookupToken with R2=0.) \E R0=token \X R0=string (LF terminated), or token if not found Zap_ExpandMenu This builds a Zap relocatable menu, which can be linked in for Zap to use automatically for your mode by calling Zap_ReadMode then writing the menu address to [R1,#2*e_menu]. The width is calculated automatically; if writable items are present, they are ignored (not expanded) and are assumed to be of the supplied width. \E R0=pointer to tokenised menu R1=submenu handler subroutine (0 = use Zap_ExpandMenu) R2=module base address \X R0=expanded menu The subroutine pointed to by R1 is called whenever a submenu is found and the warning flag is not set for it. It has the following conditions: \E R0=pointer to submenu R1,R2 unchanged \X R0=expanded menu, or 0 The tokenised menu closely resembles the relocatable menu format (see E-Menu), the differences being that all strings are MessageTrans tokens except when *started* with a NUL (in which case a string literal follows, unaligned), and the menu title is of variable length (to accomodate long token names). No GS translation and no parameter substitution is performed. Zap_MiniWriteToken A MessageTrans token-using version of Zap_MiniWrite. GS translation is performed (see Zap_LookupTokenGS). \E R0=token R4-R7=parameters for %0..%3 Zap_MiniPromptToken A MessageTrans token-using version of Zap_MiniPrompt. GS translation is performed (see Zap_LookupTokenGS). \E R0=token (b31 set to suppress automatic appending of ": ") R4-R7=parameters for %0..%3 Zap_TestIfCloneBase Tests to see if the given mode is the clone base of the current mode. This is primarily of use by cloneable modes' configuration commands, which should do nothing if this returns Z clear or if being used to update a menu (ie. R2=15..20, but see E-Commands) and R0<>R14; this is to prevent you accidentally configuring the wrong mode. \E R0=mode R8 \X Z set if it's the clone base of the current mode or if it's the current mode R0=current mode R14=menu mode Zap_ReadVariable Reads a user-controlled configuration variable. These are set per mode, and in the future will be overridden per file. (See ZapResources:Docs.Technical.TMFs for further discussion.) The variable name will be copied and stored in the variable table (don't worry about this, you still control the buffer); the result is a pointer directly into the variable table, so if you need to use it, COPY IT - particularly if you expose it through a function, since the command system will try to free the memory used for it when you do so. Note that V does *not* indicate an error condition. Use Z or R0=0 to indicate whether a variable returned or not. \E R0=variable name, r8/r9 optional \X R0=variable / 0 and Z set Zap_BuildMenuWithHelp This is Zap's 'variable length menu with help text' building sub. See E-Menu for details on Zap's menu format. The interface is as for Zap_BuildMenu, with the following additions: \E R5=pointer to help text / 0 The sub passed in R1 has the following extra condition: \X R1=pointer to help text / 0 If the first byte of the help text is ESC, then it is assumed to be a token. Note that the help text must be permanently stored; if tokenised, no % substitution will be performed. Zap_CharDelDispatch If the cursor is in the selection, then this will call the supplied routine once for each (logical) line in the selection for which the cursor, at its current column number, would still be in the selection. Otherwise, it will just call the routine normally. In your routine, you will most likely be using Zap_Command; you are advised to set b5 of R0 (delink the cursor) and to move it yourself, if necessary, on return from Zap_CharDelDispatch. \E R3 = routine (b31 =0 if it inserts/overwrites, =1 if it deletes) R4-R7 as for e_char or e_delete R8/R9/R10 \X R0-R2,R11 corrupt The routine passed in R3 has: \E R0=1 R4-R10 as above \X must preserve R1-R11; R0 = undefined or error (VS) Zap_SelectHistoryBuffer Selects (or creates) a history buffer for use in the minibuffer. It should be used when your command is caled with R2=6. \E R0 = history buffer ID \X Buffer assigned, possibly also created There are some preallocated buffer IDs: 0 Default 1 Search strings 2 Replace strings 3 Line numbers 4 Filenames 5 Numbers 6 Strings (general) 7 Expressions 8 CLI 9 Zap commands 10 Help - command and function names 11 Keymap names 12 Mode names 13 Date & time format strings 14 Assembly code (See h.ZapConsts for the label names.) If you require a private buffer, it is recommended that you use the address of your command or some other suitable resource within your module.