RISC DISC 1

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

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

Wrap

Text File | 1994-03-23 | 36.5 KB | 903 lines

************************************************************************* * >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% I suggest you use the basic macro given below. 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). Add &10 if command is to be buffered in one block (and thus undone in one key press). 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. Ie, it just calls Zap_UpdateCaret then Zap_PlotCaret. \E R10=caret block Zap_SetCaret This updates the area of the window containing the the caret given on entry. Hence it's effect is usually to draw the caret at it's (new) position. 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_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, undefined e_author #16 author address, undefined e_basemode #24 basemode, undefined e_mode #32 mode number, undefined 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 :-) \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 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 zaps 'variable length menu' building sub. See E-Menu for details on Zap's menu format. \E R0=menu name (max 12 chars) R1=address of sub to generate the menu entries 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. 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. \E R1=0 for selective/1 for global/2 for continue selective R3=start offset in file R4=direction (+1/-1) R8/R9 Zap_Search Calls the zap wildcard search code. \E R0=search string (as typed by user) R1=output type (0=cursor 1=tobuffer 2=none) R3=start offset in file R4=search direction (+1/-1) R5=object type (0=string 2=word 4=assembler instruction) R8/R9 \X If R1=0 or 2 on entry then R0=match offset/-ve if none. 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 and x,y coordinate 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 16 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: <prompt string><mark><user editable field>. 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. \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). \E R0=new prompt string 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 Zaps command tables. \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! For the entry/exit conditions of commands see the file E-Commands. If the value of R2 is undefined for a command call in the documentation in E-Command then you should set it to ZERO. Thus R2=0 always for argument types except strings. The command will be learnt if the learn flag is set and executed a number of times if the universal argument flag is set. The mode entry point e_aligncaret will be called before all commands with R2=0 on entry. A minibuffer will be opened if the command type is STRING but R0=0 (and R2=0). \E R0-R1=command inputs - dependent on command (see E-Command). Usually R0=pointer to command data R1=length of the data R2=Command action code with flags in top bits. b0-b27 =Action code to be passed on to the command. This is always 0 in standard command calls. b28-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-b28 reserved. R7=command address (need not point to a command registered in a command table, but must conform to the specs in the file E-Command. Eg, [R7,#-4] must be the flags word). R8-R10=input cursor (or cursor you wish command to act on). \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) #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. \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 (0-15=wimp colour) / -1 to read (In future versions I may allow &BBGGRR10 24 bit settings as well). 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-15 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. NB This is currently a wimp colour (0-15) but may return 24 bit &BBGGRR10 settings in future versions. 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 dependant 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 (b16 of w_format) b17-b21 are reserved b22 hex entry mode bit (b5 of w_flags) b23 overwrite bit (b1 of w_flags) b24-b31 display bits (b8-b15 of w_format) 1+ 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 \X R0=flags b0 => Auto load flag is set, no shift test. R10=mode file should be loaded into. Zap_ModeNumber This calls turns a mode name (given by a string) into a mode number. \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=path name to use for the data / 0 to use the files R3=destination window handle (or task handle) R4=destination icon handle R5/R6=destination mouse coords (if applicable) R7=0 (non zero values used internally) R8/R9=window to save or R8=0 to save the currently selected area R10=flags b0 => External edit flag (do not use) 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 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).