home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / utilities / zap / !Zap / Docs / E-Windows < prev    next >
Encoding:
Text File  |  1994-01-23  |  9.7 KB  |  270 lines
  1. *************************************************************************
  2. * >E-Windows    Documents a zap window block format.            *
  3. *************************************************************************
  4.  
  5. By convention, window blocks are pointed to by R8. However, as with files,
  6. the pointer address may change whenever a window is created. Thus, as for
  7. files, block pointers should be changed to window offsets for storing. Use
  8. the calls Zap_GetWindOff, Zap_ConvWindOff. The first two paragraphs of E-File
  9. hold if you replace 'file block' by 'window block' and R9 by R8. Please read
  10. the E-File file first.
  11.  
  12. Window block offsets have names beginning 'w_'. See E-Library for a complete
  13. list. Each window determines uniquely a file via the offset w_file.
  14.  
  15. As far as Zap and the extension modes are concerned, a Zap text window
  16. consists of a rectangle of characters. Coordinates are usually given in terms
  17. of row and column in R2,R3. Ie, by convention,
  18.  
  19.     R2=column offset from left hand edge, in characters.
  20.     R3=offset in lines from the top of the display, in lines.
  21.     
  22. R2 includes the margin which may contain the line numbers. The line numbers
  23. are handled automatically by zap. Thus a window looks like:
  24.  
  25.             0    w_margin    w_width
  26.               0 -------------------------
  27.             |    |        |
  28.             |    |        |
  29.             |    |        |
  30.             |    |        |
  31.             |    |        |
  32.            w_height    -------------------------
  33.  
  34. The quantity w_width-w_margin is usually stored in the mode dependent byte
  35. w_bpl (bytes per line). However for byte/word modes this is not true, and the
  36. number of bytes in the file that the line represents is stored in w_bpl. It
  37. is up to the mode concerned to fill in w_bpl.
  38.  
  39. The are two ways of numbering lines in Zap. These are called PHYSICAL line
  40. numbers and LOGICAL line numbers. The PHYSICAL line number of a file offset
  41. is the line offset from the top of the file in the display. Ie, it is the 'y'
  42. value of that character starting from 0 on the first line. All line counts
  43. start from zero within zap, though the number w_stline is added before the
  44. line number is printed on screen for the user. The LOGICAL line number of a
  45. file offset is determined entirely by the extension mode and Zap doesn't care
  46. what it is. For example, in text mode it is taken to be the number of
  47. carriage returns before the offset (ie the physical line it would have been
  48. on if the display hadn't been wrapped). In BASIC mode, it is taken to be the
  49. actual number of the line as encoded in the program.
  50.  
  51. A further complication is that the window text display is cached. The start
  52. of the cached area is used as a reference point for working out the file
  53. offset of a given physical or logical line number. Thus it is not necessary
  54. to start counting from the start of the file to find out where a line is. All
  55. line references work locally from this value, which is the start of the
  56. cached display, which is where the user is likely to be editing! The calls
  57. Zap_FindOffset and Zap_OffLineCol use this fact. These calls use the mode
  58. entry points 'e_cln*'. Thus these entry points should use this reference
  59. point. Thus the mode will need a piece of code (usually called cln_backward)
  60. for tracing lines backwards up the file. (See the docs on these entry
  61. points).
  62.  
  63. The cache itself consists of a number of lines of width w_txtw. This width is
  64. usually w_width rounded up to the next multiple of 8. An extension mode need
  65. not usually concern itself with this cache unless it is drawing its own
  66. display. See the mode entry point e_redrawline in which you are asked to fill
  67. a line in the cache. I reserve the right to change the format of the cache,
  68. so don't access it directly.
  69.  
  70. The window block offsets are described below. Use E-Library to set up the
  71. definitions.
  72.  
  73. w_handle
  74. Window handle for this window or -1 if the window has been deleted and this
  75. block is now 'dead'. Dead blocks should be skipped if you are going through
  76. the windows in sequence.
  77.  
  78. w_minx
  79. w_miny
  80. w_maxx
  81. w_maxy
  82. w_scrollx
  83. w_scrolly
  84. w_infront
  85. w_windowflags
  86. These are as for a wimp window block. See PRM if in doubt. You can use
  87. the code MOV R1,R8:SYS "XOS_GetWindowState" to update these values.
  88.  
  89. w_file
  90. Gives the file offset of the associated file. Use Zap_ConvFileOff to convert
  91. this to a file pointer in R9. This is done automatically for you by
  92. Zap_ConvWindOff.
  93.  
  94. w_format
  95. Gives the display format flags and the mode the window is in. See E-Flags for
  96. details.
  97.  
  98. w_width
  99. Width of window in columns (including the margin).
  100.  
  101. w_height
  102. Height of window in lines.
  103.  
  104. w_txt
  105. Address of text cache.
  106.  
  107. w_txth
  108. Number of lines claimed for txt cache. Each line consists of w_txtw number of
  109. characters followed by a foreground mask (of length w_txtw) and then a
  110. background mask (of length w_txtw). Thus the size of the cache is
  111. w_txth*w_txtw*3. w_txtw*3, the 'actual length' of a cached line is stored in
  112. the variable w_txtlen. See e_redraw line for more details.
  113.  
  114. w_txtw
  115. Width of a text cache line in characters. Must be a multiple of 8.
  116.  
  117. w_txtn
  118. Number of lines cached in the txt cache.
  119.  
  120. w_coff
  121. Reference point giving the file offset of the start of the first cached
  122. physical line.
  123.  
  124. w_cline
  125. Reference point giving the physical line number (first line 0) of the start
  126. of the first cached physical line.
  127.  
  128. w_clogl
  129. As for w_cline but gives the logical line number.
  130.  
  131. w_tab
  132. Gives the coltab width.
  133.  
  134. w_tabc
  135. Gives the character code tab mask (x4) eg &09090909. Set this to the same as
  136. w_cr if you want the tabs to be invisible.
  137.  
  138. w_cr
  139. Gives the line terminator mask (x4) eg &0A0A0A0A.
  140.  
  141. w_flags
  142. Gives the flags status for this window. See E-Flags. When a window is created
  143. the default value is taken from opt_flags.
  144.  
  145. w_title
  146. Points to the window title string.
  147.  
  148. w_bpl
  149. Mode dependent word. Usually stores the width of the display in characters.
  150. Byte mode stores the number of bytes shown on each line etc.
  151.  
  152. w_margin
  153. Width of the left hand margin in characters (including any line numbers - so
  154. this may be non zero even if the user has not set a margin).
  155.  
  156. w_rl
  157. Height in pixels of each character including the line spacing.
  158.  
  159. w_rw
  160. Width in pixels of each character.
  161.  
  162. w_rh
  163. Height in pixels of each character excluding line spacing.
  164.  
  165. w_addr
  166. Address to show in margin for file offset 0.
  167.  
  168. w_stline
  169. Line number to show in margin for line offset 0.
  170.  
  171. w_titlelen
  172. w_titbuf
  173. w_titlen
  174. Used internally for title update.
  175.  
  176. w_mwidth
  177. User required margin width before space for line numbers added.
  178.  
  179. w_tabchar
  180. User required tab character code x4 (eg &09090909) before tab visibility
  181. taken into account. w_tabc contains the one actually being used.
  182.  
  183. w_linesp
  184. User required line spacing in 1/8ths char.
  185.  
  186. w_savedo
  187. Used internally by Zap_DoCommand to store the offset of the first shiftable
  188. line after a command, and by Zap_SaveWinStatus to store the file offset of
  189. the character whose position should remain fixed when the window is
  190. recreated.
  191.  
  192. w_savedl
  193. Used internally by Zap_DoCommand to store the physical line number of the
  194. first shiftable line after a command, and by Zap_SaveWinStatus to store the y
  195. offset from the top of the window in pixels of the character whose position
  196. should remain fixed when the window is recreated.
  197.  
  198. w_savedc
  199. Used internally by Zap_DoCommand to store the number of physical lines text
  200. after the first shiftable line should be shifted down after a command
  201. (signed).
  202.  
  203. w_savedh
  204. Used internally by Zap_DoCommand to save the window height before a sequence
  205. of commands was performed.
  206.  
  207. w_savedlc
  208. Used internally by Zap_DoCommand and Zap_SaveWinStatus
  209.  
  210. w_wrapwidth
  211. Wordwrap width.
  212.  
  213. w_togminx
  214. w_togminy
  215. w_togmaxx
  216. w_togmaxy
  217. These save the 'small' window position for the toggle size key (scG).
  218.  
  219. w_txtlen
  220. Actual length of a cache line including the foreground and background masks.
  221.  
  222. w_palette
  223. Pointer to current redraw palette. This consists of 32 words. The first 16
  224. give the 24 bit colour translations (&BBGGRRxx) for Zap colours 0-15
  225. (0/1=background 2=foreground etc) and is used by VDU mode redraws. The 16
  226. words after that give the corresponding bitmap masks for poking into the
  227. screen during a fast redraw.
  228.  
  229. w_pwind
  230. w_pline
  231. w_pcol
  232. w_poff
  233. w_ploff
  234. w_pwidth
  235. This is the 'cursor block' of the 'point' position. This is the file offset
  236. of the current 'input' position in the file when the file does not contain
  237. the cursor. It is updated when the cursor moves from one file to another.
  238. This position is usually marked with an empty square cursor. See the file
  239. E-Cursors for what the variables store - w_poff is the most useful giving the
  240. file offset of the 'point'. w_pwind is set up as the window offset of this
  241. current window. This in its self is not useful but enables you to call
  242. cursor handling routines with R10=R8+w_pwind (provided the routine doesn't
  243. use any of the 'old' offsets).
  244.  
  245. w_saveds
  246. Used internally by Zap_DoCommand. Saves the first file offset to be updated
  247. on screen after the command has finished.
  248.  
  249. w_modedata
  250. This points to a block which stores the mode dependant data handled by Zap.
  251. The block consists of blocks of the same format as in the Zap dependant bit
  252. of the !Config file - see E-Vars, and is liable to change with different
  253. versions. Use Zap calls (eg Zap_ModeColour) to read/write the contents of
  254. this block.
  255.  
  256. w_res10-w_res16
  257. Reserved words
  258.  
  259. w_mode0-w_mode15
  260. Mode words. Each mode has one word in each in window in which to store the
  261. options pertaining to that mode. If bit 10 of the flags in the modes e_mode
  262. entry point is SET then instead of storing data, the mode word holds
  263. a pointer to a block of data in Zap's heap (or 0 if the block has not been
  264. created). In this case, the first word of the block MUST contain the length
  265. of the block (including the first word). The block will be copied
  266. automatically by Zap, for example, on a New View. The block will be freed
  267. automatically when the window is closed. The block is created automatically
  268. when a window is opened, and filled with the contents of the default block
  269. stored in the !Config file and accessed via Zap_Read/Write Var - see E-Vars.
  270.