home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / languages / panebasic / lib / blib2 / !BlibII / Docs / Windows < prev   
Encoding:
Text File  |  1993-01-25  |  3.9 KB  |  90 lines
  1.  
  2. Tachnical 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. When you create a 'window' using FNwin_fakewin (ie. it was not created 
  80. from a copy of a template, but instead from a template itself, etc.) you can
  81. still pass this window to PROCtemp_delcopy, but care must be taken with this.
  82. A call to PROCtemp_delcopy on such a window will cause the 'window' block
  83. to be deallocated, as well as the block pointed to by !(window-4) (ie. the
  84. indirect data block). Thus for this to work the pointer at window-4 must point
  85. either to NULL (zero) or to the start of a block allocated by malloc.
  86.  
  87. I know the window 'block' may seem a bit odd, particularly as the pointer
  88. points to the final word, but this is for historical reasons which are best
  89. not entered into.
  90.