WINGs/NEWS

   1
   2 *** Thu Oct 04 06:00:09 EEST 2001 -Dan
   3
   4 Property lists handling code
   5 ----------------------------
   6
   7 Code to handle property lists was added to WINGs. It is more robust
   8 than the libPropList code, mostly because some conflicting concepts
   9 borrowed from UserDefaults (which libPropList use) are no longer used in
  10 the WINGs property lists code. These borrowed concepts conflicted with the
  11 retain/release mechanism of property lists and could lead in certain cases
  12 to segmentation faults when executing libPropList based code. But the worse
  13 part was that these libPropList problems were practically unsolvable without
  14 removing one of those conflicting concepts and without a complete redesign.
  15 The new WINGs property lists code is also better integrated with the other
  16 data types from WINGs and is actively maintained.
  17
  18 Practically the things that were removed from the WINGs property list
  19 implementation compared to the old libPropList implementation, are exactly
  20 the UserDefaults borrowed concepts that conflict with the retain/release
  21 mechanism:
  22 - The container of a proplist object and the associated functions are gone.
  23 - The filename associated with a proplist object and the corresponding
  24   functions are gone. Now the saving function needs the filename as a
  25   parameter.
  26 - The synchronization functions are no longer supported. They are part of
  27   the UserDefaults and are implemented there.
  28 - No functions related to domains/registering were implemented in the WINGs
  29   property lists code, because they are also not part of property lists.
  30   They are more in connection with UserDefaults and a central point of access
  31   for domains.
  32
  33 The above 2 concepts: container and filename were added to libPropList just
  34 to let it support synchronization which was borrowed from UserDefaults.
  35 Property lists as defined in the openstep specification are just complex
  36 data structures composed of strings, data, arrays, dictionaries and a mix of
  37 them and are not associated with any file in particular. UserDefaults on the
  38 other hand are property lists read from a specific file and they associate
  39 that property list with that file and allow them to be synchronized.
  40
  41 Old libPropList based code can still be used by linking against the WINGs
  42 library containing the new proplist code with minimal changes which are
  43 described in detail in the comments at the top of the WINGs/proplist-compat.h
  44 header file (the same file carries the #defines for mapping old libPropList
  45 functions to the new WINGs proplist functions).
  46 Our recommendation is to move to the new functions WINGs provide because
  47 they better integrate with other function naming conventions in WINGs.
  48 The proplist-compat.h header file is just a way to have old code up and
  49 running with minimal changes so that we can remove the old and unmaintained
  50 libPropList from systems while keeping to use old libPropList based code
  51 without rewriting it and it should not be used for other purposes.
  52
  53
  54 *** Sat Apr 21 09:12:09 EEST 2001 -Dan
  55
  56 API change
  57 ----------
  58
  59 To allow a correct display of icon images with alpha blending in panels and
  60 other places where a WINGs based application may use them the following
  61 changes took place:
  62
  63 1. The following functions were renamed:
  64    - WMSetApplicationIconImage()  --> WMSetApplicationIconPixmap()
  65    - WMGetApplicationIconImage()  --> WMGetApplicationIconPixmap()
  66    - WMSetWindowMiniwindowImage() --> WMSetWindowMiniwindowPixmap()
  67 2. The following functions were added:
  68    - WMSetApplicationIconImage(WMScreen *scr, RImage *image)
  69    - RImage* WMGetApplicationIconImage(WMScreen *scr)
  70    - WMPixmap* WMCreateApplicationIconBlendedPixmap(WMScreen *scr, RColor *col)
  71
  72 As you can see the old functions that operated on WMPixmap images (which are
  73 basically X Pixmaps that lack alpha information) were renamed to ...Pixmap()
  74 to make them more suggestive about what they do and to make room for the
  75 new functions that operate on RImages (that hold alpha information).
  76
  77 Since the corresponding WMGet... functions only retrieve the stored
  78 image/pixmap from the application, I'll outline how the WMSet...
  79 functions operate:
  80
  81 All WM...IconPixmap() functions operate on WMPixmaps
  82 All WM...IconImage() functions operate on RImages
  83
  84
  85 - WMSetApplicationIconImage() will set the RImage to be used in panels
  86     and will also convert the RImage to a WMPixmap with a threshold of 128
  87     and will use that pixmap for the appicon image. If that doesn't satisfy
  88     you, you can make a call to WMSetApplicationIconPixmap() on your own to
  89     set whatever WMPixmap you see fit for the appicon.
  90
  91 - WMSetApplicationIconPixmap() will set the WMPixmap to be used for the
  92     appicon and for the panels
  93
  94
  95 If you use only one of the above functions, the corresponding image/pixmap
  96 will be used everywhere where needed (panels and appicon), but the pixmap
  97 version will not be able to handle alpha blending correctly.
  98
  99 If you use both WMSetApplicationIconImage() and WMSetApplicationIconPixmap()
 100 then the RImage will have priority in panels, and the WMPixmap will only be
 101 used for the appicon. This allows you to better control what icon is
 102 displayed in the appicon, in case the default conversion of the RImage to a
 103 pixmap with a threshold of 128 is not good enough, or in case you want a
 104 different icon to be shown in the appicon than in panels.
 105
 106
 107 Also this new function was added:
 108
 109 - WMCreateApplicationIconBlendedPixmap() will use the RImage set with
 110     WMSetApplicationIconImage() if available and will blend it with the color
 111     you passed. This will make the image show well on a background of that
 112     color. If the RImage was not set it will return NULL. You need to call
 113     WMReleasePixmap() on it after you finish with it. Passing a NULL pointer
 114     instead of a color will make the RImage be blended with the default color
 115     of the WINGs widgets: '#aeaaae' making it suitable to be assigned to any
 116     WINGs widget.
 117
 118
 119 To make your existing code work as before all you need to do is to rename
 120 the following functions:
 121
 122    - WMSetApplicationIconImage()  --> WMSetApplicationIconPixmap()
 123    - WMGetApplicationIconImage()  --> WMGetApplicationIconPixmap()
 124    - WMSetWindowMiniwindowImage() --> WMSetWindowMiniwindowPixmap()
 125
 126 But if you want to take advantage of the new abilities to show alpha
 127 blended images you need to start using the new functions.
 128
 129