home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilst / zap / !Zap / Docs / E-Entry < prev    next >
Text File  |  1995-06-19  |  35KB  |  708 lines
  1. *************************************************************************
  2. * >E-Entry    Documents the format of a mode entry point table    *
  3. *************************************************************************
  4.  
  5. The offsets in the entry point table are given names beginning 'e_'. The
  6. E-Library program will define the offsets for you.
  7.  
  8. You must fill in the first 8 entries of this table. The rest of the entries
  9. you may leave as 0 (or more simply, set the table length in the 8th word to
  10. 32 bytes). The idea of the mode table, is that you specify a BASE mode. For
  11. all the entry points (from the 9th onwards) that are off the end of your
  12. table, or that you have left as 0, the base mode will be called instead.
  13.  
  14. Hence, the simplest Zap extension mode would just set the base mode as 0 (ie,
  15. TEXT) and leave the rest as 0. You will then get a clone of the text mode.
  16.  
  17. In general the following register conventions are used:
  18.  
  19.     R2    Current column in characters (see E-Windows)
  20.     R3    Current line in characters (see E-Windows)
  21.     R8    Window block pointer / 0 to change the default config
  22.     R9    File block pointer / 0 to change the default config
  23.     R10    Cursor block pointer
  24.     R11    Your extension mode workspace (private word)
  25.     R12    Zaps workspace (private word)
  26.  
  27. In general the entry points have entry and exit conditions:
  28.  
  29.     \E R0-R10=parameters R11=your workspace
  30.        R12=Zap's workspace R13=FD stack R14=return addr
  31.     \X You must save R1-R11 (unless otherwise mentioned).
  32.        You may corrupt R0 and flags.
  33.        Set V flag and put R0=error block pointer on an error.
  34.  
  35. See the E-ZapCalls file for more details on my entry/exit syntax.
  36.  
  37. All offsets given in the table below must be from the start of the module.
  38. Hence the table is relocatable. Zap finds the start address of your module
  39. via the first table entry (e_module). It uses this and an OS_Module call to
  40. determine the address of your workspace (to pass in R11). All strings should
  41. be 0 terminated.
  42.  
  43. Entry points for arbitrary modes may be called using Zap_CallMode,
  44. Zap_CallGivenMode or Zap_BaseMode. If none of these will do, then use
  45. Zap_ReadMode to find the table entry linked points and the address of the
  46. mode's workspace and the entry point can be called directly.
  47.  
  48. Each mode has a word of workspace reserved in the window block (pointed to
  49. by R8) for each file. A mode is responsible for storing the current options
  50. in their mode word when the user changes mode (see e_start/e_end). There
  51. are Zap calls provided to make this easier for you. If you need more than
  52. one word of workspace then the mode word can store the pointer to a block of
  53. workspace if you set a flag in e_mode. See E-Windows (w_mode0...) and E-Vars
  54. (opt_mode0...).
  55.  
  56. The entry points
  57. ================
  58.  
  59. e_module
  60. This gives the table offset from the module start so that the module start
  61. may be calculated by Zap. Ie, module start = address of table start - this
  62. offset.
  63.  
  64. e_title
  65. Offset of the mode title string to be used in the 'Mode' menu. (Ie, the
  66. name of the mode). It should be at most 7 chars long. (eg 'BASIC')
  67.  
  68. e_author
  69. Offset of the author name string (eg 'Dominic Symes').
  70.  
  71. e_basemode
  72. Gives the mode number on which to base null entry points. This is a bit out
  73. of date since modes are now referred to by names and assigned numbers when
  74. loaded. For all practical purposes this will always be 0 (text mode) though
  75. you can use any mode permanently installed in Zap (ie 0=Text 1=byte 2=word
  76. 3=ascii 4=hex 11=throwback).
  77.  
  78. e_mode
  79. Gives the mode number you would like to be in bits b0-b7. Bits 8-31
  80. contain flags. It is VERY important that you do not assume you get this mode
  81. number. Now that Zap loads modes on the fly, modes are often loaded in a
  82. funny order and you cannot guarantee this mode number will be free. I suggest
  83. that (seeing as modes 0-12 already have a standard meaning) you set this to
  84. 13 and then Zap will assign you the next free mode >=13. It tells you which
  85. mode you have actually been assigned on e_init with R1=1.
  86.  Bits 8-31 as follows:
  87.     b8    Set to receive RAW keyboard input. All key presses are sent
  88.         to e_char. Zap key codes greater than &FF are sent as a
  89.         zero byte followed by the low byte.
  90.     b9    Set to get taskwindow style keyboard input passed to e_chars.
  91.         This differs from normal e_chars entry in that:
  92.         1) Delete is passed on as &7F instead of calling e_delete
  93.         2) Characters &20-&FF are passed on regardless of mapping
  94.         3) If not in COPY mode then the cursor keys are passed on
  95.            as a 0 byte followed by bottom 8 bits of the wimp's code.
  96.            Similarly TAB.
  97.         4) Return and Escape are passed on as &0D and &1B.
  98.         This is subject to changes - contact me.
  99.     b10    Set to indicate that you use a mode word in a window block
  100.         (eg w_moden) to point to a block of data. See E-Windows
  101.         for the format this block must take.
  102.     b11    Set to indicate that this is not a 'textual' mode. Eg it's
  103.         like byte/word mode. Setting this bit prevents, for example,
  104.         auto DOS text file detection.
  105.     b31    Set to overwrite any mode already using this mode number.
  106.     Others bits are reserved and should be set to 0.
  107.     If b31 is not set then you are allocated the next free mode if the
  108.     one you wanted is being used.
  109.  
  110. e_init
  111. Called at various points when Zap is starting up/dying or wants to give your
  112. mode a chance to intercept an operation. Note that Zap will automatically
  113. kill your module on dying unless you tell it otherwise. You should use reason
  114. code 2 to claim any buffers from Zap. I am at liberty to add extra reason
  115. codes so please return with all registers unaltered if you receive an
  116. unrecognised code.
  117.     \E R1=reason code (and other registers may hold values dependent on it)
  118.     \X Save R1-R11 as usual unless otherwise stated below.
  119.  The reason codes are:
  120.  R1=0 => Zap is quitting and about to kill your module.
  121.      Return R0=-1 to stop this (eg if you've more than one mode).
  122.  R1=1 => Zap is just about to start up your mode (but hasn't read the
  123.       options block for this mode or anything like that).
  124.       R0=the mode number assigned to your mode.
  125.       You should note the mode number that has actually been assigned to
  126.       you and store it in your module somewhere. This is not guaranteed
  127.       to be the one you asked for.
  128.  R1=2 => Zap has started up your mode (and all other modes in your module).
  129.       You should also use this call to claim any buffers you need.
  130.      On this call you should check your mode word opt_moden to see if
  131.      it's zero. If so then you should initialise it to a sensible
  132.      default value. (See E-Vars)
  133.  R1=3 => Zap is deleting a file with your mode number in f_cmode. R9=file
  134.      block on entry. See E-File.
  135.  R1=4 => Zap is saving a file with your mode number in f_cmode. R8/R9=the
  136.      window being saved. Return R1=-1 if you wish to abort the save
  137.      (and handle it yourself). If you return R1=-1 then return R0=0 if
  138.      the save is safe (file can now be deleted) or -1 if unsafe (entered
  139.      data transfer protocol for example).
  140.      This is only called for saves to disc (F3). For inter-application
  141.      saves and post-saves see R1=8 below.
  142.  R1=5 => Zap wants to delete a file your mode number in f_cmode, but it
  143.       has the 'altered' flag set. Return R1=-1 to override and allow the
  144.       file to be killed anyway.
  145.  R1=6 => Zap is creating the colours submenu and wants to know what you
  146.       call colours >=9. Return in R1 pointer to a double zero terminated
  147.       list of zero terminated entries giving the names of the colours
  148.       starting from 9. Eg "REMs",0,"Strings",0,0. (Or leave R1 as 6
  149.       if this call is not supported).
  150.  R1=7 => Zap is creating its menus. At this point you can override your
  151.      e_menu value by returning R1 as the pointer to the replacement
  152.      (wimp-style) menu (values at #-4 and #-8 - see E-Menus).
  153.      Leave R1=7 if you don't want to do this.
  154.      You should use Zap_ReadMenu or Zap_LoadMenu to create the menu.
  155.  R1=8 => Zap is about to save a file with your mode number in f_cmode
  156.       to another application (not to disc). See also R1=4.
  157.       ;E R0=0 if the file is just about to be saved
  158.             1 if the file has been transferred
  159.          R8/R9=the file being saved
  160.  
  161. e_menu
  162. Offset of submenu in Zap's format / 0 for none. This menu comes off the
  163. 'Mode' menu. See the file E-Menu for details of the menu format. Greater
  164. versatility can b