home *** CD-ROM | disk | FTP | other *** search
/ ftp.uni-stuttgart.de/pub/systems/acorn/ / Acorn.tar / Acorn / acornet / dev / basic / blib2.spk / Docs / Windows < prev   
Text File  |  1993-03-02  |  6KB  |  141 lines
  1.  
  2. Technical description of the 'window' data type
  3. -----------------------------------------------
  4.  
  5. To make life easier a standard window structure has been defined to allow
  6. library routines to work with a range of different windows, whilst being
  7. able to locate data local to that window.
  8.  
  9. As a consequence wimp window handles are not generally used as parameters in
  10. the procedures/functions, rather pointers to these defined structures. This
  11. file sets out the format of these structures so that you can create your own
  12. specific window types.
  13.  
  14. The window library allows for upto 65536 different window 'types'. By
  15. default all created windows are given a null window type (number 0) which
  16. does nothing to describe the window. Simple Text Windows (STW library) are
  17. given a window type 1, thus you can easily work out that upon a redraw
  18. event, say, for any window of type 1 you need to call FNstw_redraw.
  19.  
  20. Useful routines to keep in mind with windows are :
  21.  
  22.   PROCwin_settype - Sets a window's type
  23.  
  24.   FNwin_findtype  - Gets a window's type (or -1 for a bad window structure)
  25.  
  26.   FNwin_findwin   - Returns a 'window' given the window handle
  27.                     (useful for when the WIMP simply gives you a handle)
  28.  
  29.  
  30. If you want to create your own window type you should initially give it a
  31. number between &F000 and &FFFF. This will allow future officially released
  32. libraries to fit in with your own libraries without a clash as only
  33. officially released window types should be numbered from &1 to &EFFF. This
  34. does leave you to define upto 4096 types of your own and so should not be
  35. too much of a limitation.
  36.  
  37.  
  38. A 'window' is a pointer to a data block which is as follows :
  39.  
  40. Address           Contents            Extra description
  41.  
  42.                  ________________
  43.                 |                | 
  44. window - 16     | Identifier     |    &076Cxxxx where xxxx is the type
  45.                 |________________|
  46.                 |                |
  47. window - 12     | Local pointer  |    to data associated with window
  48.                 |________________|
  49.                 |                |
  50. window -  8     | Wimp Handle    |
  51.                 |________________|
  52.                 |                |
  53. window -  4     | Indirect Data  |    pointer to indirected icons' data
  54.                 |________________|
  55.                 |                |
  56. window          | Definition Ptr |    Pointer to window definition
  57.                 |________________|
  58.  
  59.  
  60. Thus a 'window' is basically a pointer to the last word in a 20 word block.
  61. However with windows created by copying templates (using the templates
  62. library) the window definition follows directly on from this block (ie.
  63. !window = window + 4).
  64.  
  65. The &076C part of the 'window' identifier is used by the window library for
  66. checking that a given 'window' is valid, and thus all window structures must
  67. contain this value.
  68.  
  69. The local pointer ( !(window-12) ) is free for the use of a particular
  70. window type, and is not used by the window library at all. For example the
  71. STW library uses this pointer to point to the text contained within the
  72. window. 
  73.  
  74. When a window is destroyed (using PROCtemp_delcopy) the complete structure
  75. is deallocted, and it's contents become undefined. Thus before destroying a
  76. window you should make sure that any data pointed to by the local pointer is
  77. deallocted.
  78.  
  79. I know the window 'block' may seem a bit odd, particularly as the pointer
  80. points to the final word, but this is for historical reasons which are best
  81. not entered into. It also allows for future extension without affecting any
  82. current libraries (except the window library itself). Thus when writing your
  83. own window routines you can assume the structure given above, but nothing
  84. more as future extensions to this structure will be added to the top of the
  85. data structure (eg. at window!-20, etc.).
  86.  
  87.  
  88. Fake Windows
  89. ------------
  90.  
  91. Often you do not wish to have multiple copies of a template floating around,
  92. in many cases just one is enough (eg. the program information window for the
  93. main menu). For this reason it is possible to create a window directly from
  94. the template stored in memory, rather than first creating a copy of the
  95. template. Windows created in this way are termed 'Fake Windows'. This term
  96. refers to the fact that the window structure is very slightly different to
  97. that of a window created from a copy of the template.
  98.  
  99. A fake window block has a NULL pointer at window!-4 (indirected icons' data
  100. area). This does not mean that there is no area set aside for indirected icons
  101. but it means you can't get at it directly from the window structure.
  102.  
  103. It is possible, however, to use a fake window in almost exactly the same way
  104. as a normal window, even as far as passing it to PROCtemp_delcopy. If this
  105. is done, however, it is only the fake window that is deleted, NOT the template
  106. (or it's indirected icons' data area). Thus after a PROCtemp_delcopy you could
  107. create another fake window (or normal one) from that template.
  108.  
  109. Thus the only real difference, as far as the user is concerned, between a
  110. fake window and the normal (copy) window is that you can only have 1 fake
  111. window from each template, but as many copies as you like (memory permitting).
  112. Further more, it does not matter if you create a fake window from a template,
  113. and then create a normal window as a copy of that template.
  114.  
  115.  
  116. New Window Types
  117. ----------------
  118.  
  119. When defining a new window type there are a few things that are important :
  120.  
  121. 1) You should always use the access routines FNwin_findtype and PROCwin_settype
  122. for accessing/setting the window type.
  123.  
  124. 2) Your access routines should check that the window passed to it is of the
  125. valid type.
  126.  
  127. 3) You should have a procedure/function to perform the initialisation from
  128. a plain window to a window of your new type.
  129.  
  130. 4) If your window type makes use of the 'local pointer' (window!-12) and
  131. memory is allocated for this purpose, then you should supply a procedure/
  132. function to deallocate this memory and leave window!-12 clear so that the
  133. window can be destroyed without leaving any dangling memory blocks.
  134.  
  135. 5) If your window type needs a redraw routine, this should ideally take the
  136. form of a function taking a single parameter (the wimp_poll_block). This
  137. function should accept any window as it's input, and simply return FALSE
  138. if it is of the wrong type, and return TRUE if it is of the correct type.
  139.  
  140.  
  141.