RISC DISC 1

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

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

Wrap

Text File | 1994-02-20 | 14.0 KB | 310 lines

************************************************************************* * >E-Command Documents how to add commands to Zap * ************************************************************************* As mentioned in the ReadMe file, commands are added to Zap by registering a table of commands when the module providing the extra commands initialises. You should use the call Zap_AddCommands to register the table. The table has the format below. All offsets are from your module start unless otherwise indicated. #0 Offset of table from start of module (so Zap can convert the offsets below into addresses). #4 Offset from module start of 'Zap service call code' or 0 if none. Zap calls this entry point to tell you about various things - see the section below. #8 List of commands, terminated by a zero word. Each element of the list has the format: <command name>+<0 byte terminator>+ <ZERO bytes padding until word aligned>+ <word giving command offset from module start> The command name must be in UPPER CASE in this table. In general, command names are not case sensitive, but they are converted to upper case in order to search for them in the command tables. The characters padding to the next word alignment MUST be ZEROs as the table is searched through in words not in bytes. When a command is found in the table, its address is calculated, and henceforth the command is referred to by its address. This unfortunately means that I cannot pass the command your module workspace when the command is called as I do not know which module the command lies in. This is not usually a problem however as you may claim workspace from Zap's heap. If this is not sufficient, then you will just have to store the address of your workspace in the module itself and read it when you are called (until I work out a better method). The address of the command is of course the address called when the command is executed. However, at offset -4, the word before the first instruction of the command, some flags are stored. These flags determine what type of parameter the command takes and how the command interacts with the minibuffer. This word must be filled in. It's meaning is as follows: b0 Set if the command doesn't need R10 on entry (eg called from b1 Set if the command doesn't need R8 on entry a menu). b2 Set if the command doesn't need R9 on entry b3-b5 Argument type for the command: 0 = Command takes no parameters 1 = Command takes a list of bytes as parameter 2 = Command takes a list of words as parameter 3 = Command takes a string as parameter 4 = Command takes a block of data as parameter 5-7 reserved b6 Set if you wished to be called before minibuffer opened b7 Set if you wish to be called after every minibuffer update b8 Set if you wish to be called before a key is inserted into the minibuffer (and possibly alter it). b9 Set if you want TAB to complete file names in the minibuffer b10 Set if you may want to kill the minibuffer when it starts up. b11 Set if you may want minibuffer to remain open when command has finished. b12 Set if you wish universal argument to multiply R1 by n on calling the instruction instead of calling it n times. If the command takes byte or word list data then the data is duplicated the given number of times. b13 Reserved for Paul Moore's system. b14 Set if the command should not be executed when loading a file to prevent Trojans. b15-b31 Reserved - set to 0 Bits 0-2 are used by commands which may be called from a menu, and thus may not be typed. You should leave them as 0. The entry/exit conditions of your command depend on your flags word as I will detail below. You are ALWAYS called with the following registers set up on entry: R3 = info flags: b0 Set => The last command call was to this command as well. (eg to spot cumulative ctrl K's/Yanks). b1-b27 => Reserved b28-b31=> Top bits of R2 when command called via Zap_ProcessCommand. R8 = window of the input caret (see E-Windows) (unless flags b1 set) R9 = file block associated with R8 (see E-File) (flags b2=0) R10 = cursor block pointer of input cursor (see E-Cursors) (b3=0) (This is car_cursor if the cursors are combined and car_input if they are split - see E-Vars). R13 = small FD stack And in general registers R0-R2 have the meaning: R0 = data pointer (your input) R1 = number of times key was pressed (all key presses are buffered) R2 = action code (if you have a string argument) On exit from a command you may corrupt the registers R0-R11 and the flags. You should return V flag set and R0=error block on error. Some of the minibuffer calls with R2<>0 require you to return a result in R0. To detail the actual meaning of R0-R2 I have partitioned into cases below. Registers not mentioned are undefined. If you want to call a command yourself, then please use the call Zap_ProcessCommand or Zap_CommandString. All calls from Zap are made by this method. See the file 'Commands' for the syntax used when typing a command into the keys file, or sending it to Zap_CommandString. Data type = None (0) -------------------- Then R1=Number of times key pressed, and R0,R2 are not used. If the same command is bound to more than one key then all the buffered keypresses may not be due to the same key! Eg, the command UP. In the keys file it should appear with no parameters. Data type = Byte list (1) ------------------------- Then R0=Pointer to a list of bytes, and R1=Number of bytes in the list. Eg, the command CHAR. In the keys file, the command should appear with a byte as parameter, eg CHAR 143 (or CHAR n where n is substituted for the key number it lies on). Thus if the user types A,B,C which have the commands CHAR 65, CHAR 66, CHAR 67 assigned to them, then the command will be called once with the list 65,66,67 if the keypresses were buffered. Data type = Word list (2) ------------------------- Then R0=Pointer to a list of words, and R1=Number of words in the list. This works as for the byte list data type except that the command takes a word (4 bytes) as parameter. Data type = String (3) ---------------------- All strings in this section are zero terminated. When you are passed R0 as the contents of the minibuffer, this excludes the prompt (see Zap_MiniWrite). In the following calls, R2 gives the action code distinguishing them. CASE 1 - A string is specified after the command in the keys file (eg INSERT "Hello"). In this case you are called with R0=pointer to the string R1=number of times the key was pressed. R2=0. CASE 2 - No string specified in the keys file (eg INSERT). In this case, a minibuffer is opened for the user to type in the string for the command to use. Most of the flags in the flags word control the way the minibuffer works. If the flags in bits 6+ are all clear then everything is handled automatically for you and you are called with R2=1 and R0=minibuffer contents when the user types RETURN. The detailed workings of the minibuffer are described below. Please supply a prompt (use b6) where possible. The following happens before the minibuffer is opened on screen: First of all, the minibuffer is cleared. If you wish to be called at this point (eg to add a prompt) then set b6 of your flags word and you will be called with R2=6 (R0,R1 undefined, R8-R10 setup as usual). You should then insert your prompt using Zap_MiniPrompt. Please look at Zap_MiniWrite for other ways of changing the minibuffer contents. It is possible that you may wish to kill the minibuffer at this point, before it is opened, as an null argument may sometimes be acceptable. For example, the command SAVEFILE (Emacs CTRL-X CTRL-S) only wants to open a minibuffer if the file is untitled (does not have a full path name). To do this, set b10 of your flags word (in addition to b6) and return R0=0 to open the minibuffer as usual, or R0=pointer to the string argument you want the command to be executed with. Your command will then be called again with R2=0 and R0=the parameter you have passed. This method ensures that the command is learnt correctly, as only command calls with R2=0 or R2=1 are learnt. Minibuffer setup calls with R2>1 are NOT learnt when you are in 'learn a key sequence mode'. Now the minibuffer is opened on screen. The following happens when a key is typed by the user: If you have b7 and b8 cleared then the key is inserted into the minibuffer automatically. ESCAPE and CTRL-G cause the minibuffer to close (without calling you) and RETURN causes your command to be called as described below. If you want to intercept keys BEFORE they are acted on then set b8 of your flags word. You will then be called with R2=&8000+Zaps internal key number, and R0=the minibuffer contents string when the key is typed. After you have dealt with the key, you return a value in R0 to tell the minibuffer what to do with the key. There are 3 possible cases: R0=-1 In this case no change is made to the minibuffer. Command processing continues as normal (you will be called if b7 of your flags word set etc). R0=key number Then the given key is acted on as if it were the one typed. Hence you will usually exit by SUB R0,R2,#&8000. R0=&8000 In this case, the minibuffer is quitted as if Return had +key number been pressed (ie you are called with R2=1 as described below). Then, AFTER the minibuffer has been closed, the indicated key will be acted on as if typed in the editing window. This enables keyboard-search to be quitted by, for example, up arrow or ctrl X. (If you just want to quit the minibuffer then return R0=&1B=ESCAPE). One common use of this call is to trap the TAB key for completing an entry (eg command name or filename). If you set b9 of your flags word, then Zap assumes the buffer contains a file name and automatically completes the file name when TAB is pressed, saving you all the work! If you want to examine the minibuffer contents AFTER the character has been entered into the minibuffer by Zap, you should set b7 of your flags word. You will then be called with R0=the minibuffer contents string, and R2=7. This call (as with the previous one) is made before the minibuffer contents is updated on screen and thus you don't need to call Zap_MiniUpdate if you alter the minibuffer contents. For example, search as you type (CTRL-S) uses this call to jump to the next match after every key press. Zap enters keys into the minibuffer until the user presses ESCAPE, CTRL-G or RETURN. The first two quit the minibuffer. When the user presses RETURN, you are called with R0=pointer to string typed into the minibuffer, and R2=1. As usual, the string pointed to by R0 does not include the prompt. You should then perform the command action, with this string as input. Usually, the minibuffer will be closed after your command has finished. If you wish it to remain open (eg the COMMAND command) then set b11 of your command word, and return R0=0 to close the minibuffer and R0=1 to leave it open when you exit from being called with R2=1. The codes R2=1 and R2=0 should cause the same action to take place. This is to ensure the LEARN function works correctly. When a learnt function is executed, the minibuffer will not be opened again, but the command will be called with R2=0 and the previously typed string as input in R0. For example, if you learn the sequence: ctrl-S , "wibble" , RETURN typed in the minibuffer, then when this is played back the command SEARCHFORWARD will be called with R2=0 and R0="wibble" as opposed to opening the minibuffer. Only command calls with R2=0 or 1 are learnt. Data type = Block (4) --------------------- Then R0 = pointer to a data block (of command dependant format), and R1=number of times key pressed. This argument type is used by the command MULTICOMMAND which is used internally within Zap to execute a list of other commands. For example, when you type a sequence of commands separated by a ":" in the keys file, then this is converted to the one command MULTICOMMAND with data block as a list of the functions to call. You cannot put such a command in the keys file as there is no way of specifying a data block as parameter. EXAMPLE ------- The code below implements a simple command which asks you to enter a number into the minibuffer and then switches to that display mode. FNcall is a macro which calls the named Zap entry point (see E-Zapcalls for its definition). EQUD (3<<3)+(1<<6) \ string argument + ask for prompt .command_start STMFD R13!,{R14} TEQ R2,#6 \ is the minibuffer about to open BEQ add_prompt FNcall(Zap_MiniEval) \ find the number typed LDMVSFD R13!,{PC} \ error LDMCSFD R13!,{PC} \ wasn't a valid number FNcall(Zap_NewMode) \ change mode LDMFD R13!,{PC} \ finished .add_prompt ADR R0,prompt_string FNcall(Zap_MiniPrompt) \ insert the prompt string LDMFD R13!,{PC} .prompt_string EQUS "New mode: " EQUB 0 ALIGN It is the offset of command_start that you must place in your command table, not the offset of the EQUD flags word before it. Note that the command performs the same action regardless of whether R2=0 or R2=1. Zap service calls ----------------- If the second word in your command table is non zero then it gives the module offset of a 'Zap service call handler'. This code is called at various points to tell you about things. In general the entry/exit conditions are: \E R1=reason code and other registers may hold data. R11=undefined R12=Zaps workspace pointer as usual. \X You should preserve R1-R13 unless otherwise stated. R0 and flags may be corrupted. The (current) service calls are listed below. You should ignore unrecognised values in R1 so I can add more if necessary. R1=0 Zap is quitting and about to kill your module. Return R0=-1 to stop it. Your module will NOT be automatically killed if have no service call handler (for backwards compatibility). R1=1 Zap has just started but has not set up its heap yet. R1=2 Zap has started and set up its heap. You should use this call to claim any workspace via Zap_Claim. R1=3 Zap is deleting a file. R9=file block of file being deleted. (See E-File) R1=4 Zap is deleting a window. R8=window block of window being deleted. (See E-Windows)