home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilst / zap / !Zap / Docs / E-Command < prev    next >
Text File  |  1995-06-19  |  22KB  |  552 lines
  1. *************************************************************************
  2. * >E-Command    Documents how to add commands to Zap            *
  3. *************************************************************************
  4.  
  5. As mentioned in the ReadMe file, commands are added to Zap by registering a
  6. table of commands when the module providing the extra commands initialises.
  7. You should use the call Zap_AddCommands to register the table. The table has
  8. the format below. All offsets are from your module start unless otherwise
  9. indicated.
  10.  
  11.     #0    Offset of table from start of module (so Zap can convert the
  12.         offsets below into addresses).
  13.     #4    Offset from module start of 'Zap service call code' or 0
  14.         if none. Zap calls this entry point to tell you about
  15.         various things - see the section below.
  16.     #8    List of commands, terminated by a zero word. Each element
  17.         of the list has the format:
  18.         
  19.         <command name>+<0 byte terminator>+
  20.         <ZERO bytes padding until word aligned>+
  21.         <word giving command offset from module start>
  22.         
  23. The command name must be in UPPER CASE in this table. In general, command
  24. names are not case sensitive, but they are converted to upper case in order
  25. to search for them in the command tables. The characters padding to the next
  26. word alignment MUST be ZEROs as the table is searched through in words not
  27. in bytes.
  28.  
  29. When a command is found in the table, its address is calculated, and
  30. henceforth the command is referred to by its address. This unfortunately
  31. means that I cannot pass the command your module workspace when the command
  32. is called as I do not know which module the command lies in. This is not
  33. usually a problem however as you may claim workspace from Zap's heap. If this
  34. is not sufficient, then you will just have to store the address of your
  35. workspace in the module itself and read it when you are called (until I work
  36. out a better method).
  37.  
  38. The address of the command is of course the address called when the command
  39. is executed. However, at offset -4, the word before the first instruction of
  40. the command, some flags are stored. These flags determine what type of
  41. parameter the command takes and how the command interacts with the
  42. minibuffer and menus. This word must be filled in. It's meaning is summarised
  43. below. Greater detail is given further down the file.
  44.  
  45. b0    Set if the command doesn't need R10 on entry (eg called from
  46. b1    Set if the command doesn't need R8 on entry   a menu).
  47. b2    Set if the command doesn't need R9 on entry
  48. b3-b5    Argument type for the command:
  49.     0 = Command takes no parameters
  50.     1 = Command takes a list of bytes as parameter
  51.     2 = Command takes a list of words as parameter
  52.     3 = Command takes a string as parameter
  53.     4 = Command takes a block of data as parameter
  54.     5-7 reserved
  55. b6    Set if you wished to be called before minibuffer opened
  56. b7    Set if you wish to be called after every minibuffer update
  57. b8    Set if you wish to be called before a key is inserted into
  58.     the minibuffer (and possibly alter it).
  59. b9    Set if you want TAB to complete file names in the minibuffer
  60. b10    Set if you may want to kill the minibuffer when it starts up.
  61. b11    Set if you may want minibuffer to remain open when command finished.
  62. b12    Set if Universal arg should multiply R1 by the number of times to do.
  63. b13    Set if command should be called repeatedly with R1 smaller.
  64. b14    Set if the command should not be executed when loading a file.
  65. b15    Set if the command is 'tickable' when on a menu entry.
  66. b16    Set if the command can create a submenu or leaf window.
  67. b17    Set if the command can provide a default string for a menu entry.
  68. b18    Set if the command wishes to provide the menu entry text.
  69. b19    Set if the command wishes to specify the submenu.
  70. b20    Set if the command may wish to remove the menu entry.
  71. b21-b31    Reserved - set to 0
  72.  
  73. The entry/exit conditions of your command depend on your flags word as I will
  74. detail below. When the command is called the registers have the meaning:
  75.  
  76.  R0 = input data for the command (dependent on R2 & command type - see below)
  77.  R1 = length of input data       (dependent on R2 & command type - see below)
  78.  R2 = action code         (details below)
  79.  
  80.  R8 = window of the input caret (see E-Windows) (unless flags b1 set)
  81.  R9 = file block associated with R8 (see E-File) (unless flags b2 set)
  82.  R10 = cursor block pointer of input cursor (see E-Cursors)
  83.        (unless flags b3 set) (This is car_cursor if the cursors are combined 
  84.        and car_input if they are split - see E-Vars).
  85.  R11 = undefined
  86.  R12 = Zap's workspace
  87.  R13 = small FD stack
  88.  
  89. ALL calls to your command have these registers set up. The descriptions of R0
  90. and R1 given above are for action code R2=0 (execute the command). In general
  91. their meaning will be dependent on R2 and are undefined otherwise. Note that
  92. you are only called with the action codes you request via your flags word so
  93. do not need to test for all possible action codes.
  94.     
  95. On exit from a command you may corrupt the registers R0-R11 and the flags.
  96. You should return V flag set and R0=error block on error. Some of the calls
  97. with R2<>0 require you to return a result in R0. To detail the actual meaning
  98. of R0-R2 I have partitioned into cases below. Registers not mentioned are
  99. undefined.
  100.  
  101. If you want to call a command yourself, then please use the call
  102. Zap_ProcessCommand or Zap_CommandString. All calls from Zap are made by this
  103. method. See the file 'Commands' for the syntax used when typing a command
  104. into the keys file, or sending it to Zap_CommandString.
  105.  
  106. NB Only command calls with R2=0 or R2=1 are learnt. All other calls are
  107. regarded as 'setup' calls and are not learnt.
  108.  
  109. ************************
  110. * Details of flag bits *
  111. ************************
  112.  
  113. Bit 0
  114. -----
  115.  
  116. If this bit is set then R10 is undefined on entry. If it is clear then the
  117. current position of the input cursor will be read if R10 is not specified (ie
  118. is 0) when Zap_ProcessCommand is called. Note that reading the current
  119. input cursor position may change R8 and R9 as well.
  120.  
  121. This is useful when the command is called from a menu. The menu may not be on
  122. the window with the input focus. If this bit is set then the command can act
  123. on the menu the window is on, where as if it is clear then it will always act
  124. on the window with the input focus. Thus it should be set for any command
  125. which only affects the window state and doesn't need to know the cursor
  126. position.
  127.  
  128. Bit 1
  129. -----
  130.  
  131. If this bit is set then R8 either points to a window or is 0 on entry. If 0
  132. then the command is being called from the options menu to change the default
  133. state. If the bit is clear and Zap_ProcessCommand is called with R8=0 then an
  134. error is given.
  135.  
  136. Thus this bit should be set for commands which don't need to know where the
  137. cursor is and can change the default options as well as the current window
  138. state. If this bit is set then you should also set Bit 0.
  139.  
  140. Bit 2
  141. -----
  142.  
  143. As for Bit 1 except that the file pointer R9 is checked instead of R8. If the
  144. command is called from the options menu then both R8 and R9 will be 0.
  145.  
  146. Bits 3-5
  147. --------
  148.  
  149. These determine what type of data the command takes. When the command is
  150. executed it is called with R2=0. In general the meaning of R2>0 is documented
  151. under the Bit with value R2. Note that Bits 12 and 13 are used in deciding
  152. which value is passed in R1. When the command is called with R2=0 additional
  153. information is passed in R3:
  154.  
  155.  R3 =     b0 Set => This command was executed as the last command as well.
  156.           (eg to spot cumulative ctrl K's/Yanks).
  157.     b1-b27 => Reserved
  158.     b28-b31=> Top bits of R2 when command called via Zap_ProcessCommand.
  159.  
  160.  Data type None (0) is called with:
  161.  
  162.   R0=undefined
  163.   R1=number of times the key has been pressed (depends on flags bits):
  164.      Suppose the key has been buffered a total of m times. Suppose also that
  165.      Universal argument (^U) is active and that the user has requested a
  166.      repetition of n times. (n=1 if universal argument not active).
  167.      Ie, Zap_ProcessCommand has been called with R1=m. Then:
  168.     b12=0 & b13=0 => Command is called n times with R1=m
  169.     b12=1 & b13=0 => Command is called once with R1=m*n
  170.     b12=0 & b13=1 => Command is called m*n times with R1=1
  171.     b12=1 & b13=1 => Command is called m times with R1=n
  172.     ie b12=1 => R1 is multiplied by n (the universal argument)
  173.        b13