WINGs/NEWS

   1 *** Mon Sep 09 06:58:30 EEST 2002 - Dan
   2
   3 New delegate for the WMConnection class
   4 ---------------------------------------
   5
   6 ConnectionDelegate structure has a new member: canResumeSending.
   7 The purpose of this callback is to notify you that you can resume sending
   8 data over a WMConnection.
   9 It works in the following manner:
  10
  11 WMSendConnectionData() can return 3 values: -1, 0, 1
  12
  13 -1 - means that the connection has died. you should stop sending data and
  14      close the connection ASAP.
  15  1 - means that the data was succesfully sent
  16  0 - means that the data (or part of it) was not sent. however, it was saved
  17      in a queue and the library will try to send it later when possible.
  18
  19 if the return value is 1, you can continue to send the next message, and so
  20 on, until the return value of such a send call will be 0.
  21 In this case you can continue sending, however, the data will not be sent
  22 over the connection because the operating system cannot accept any more data
  23 for the moment. Instead it will be queued inside the library, making your
  24 program's memory footprint increase. If the ammount of data you need to
  25 send is limited and not too big, this shouldn't be a problem, because your
  26 data will be queued and sent when the operating system will notify the
  27 library that sending is possible again.
  28 If this is the case you can just ignore the output of WMSendConnectionData()
  29 and not set a callback for canResumeSending.
  30
  31 However, if the ammount of data you have to send is undetermined and you
  32 also want to keep a small memory footprint for your program (so that it
  33 won't grow until it uses all your available memory ;) ), you will have to
  34 stop sending data over the connection as soon as WMSendConnectionData()
  35 returns with 0. Then you should somehow mark this situation in your program
  36 to avoid it trying to send anymore data until notified that it can resume.
  37 (You should have also set a canResumeSending callback when you initialized
  38 your WMConnection object because else you cannot be notified when to resume.)
  39
  40 Now, when you receive such a 0 from the send operation, your last sent data
  41 is put in a queue inside the library. At a later time when the operating
  42 system notifies the library that sending is possible again, the library will
  43 resume to send the data that is saved in the queue. After it will be able to
  44 send all the data in the queue, the canResumeSending callback will be
  45 called, letting you know that not only you can resume sending because the
  46 operating system is again able to send data, but also that the queue was
  47 completely flushed.
  48
  49 From the canResumeSending callback, you should again update the status of
  50 your program marking that it can send again, and then resume sending the
  51 data from where you were left.
  52
  53
  54 *** Thu Oct 04 06:00:09 EEST 2001 -Dan
  55
  56 Property lists handling code
  57 ----------------------------
  58
  59 Code to handle property lists was added to WINGs. It is more robust
  60 than the libPropList code, mostly because some conflicting concepts
  61 borrowed from UserDefaults (which libPropList use) are no longer used in
  62 the WINGs property lists code. These borrowed concepts conflicted with the
  63 retain/release mechanism of property lists and could lead in certain cases
  64 to segmentation faults when executing libPropList based code. But the worse
  65 part was that these libPropList problems were practically unsolvable without
  66 removing one of those conflicting concepts and without a complete redesign.
  67 The new WINGs property lists code is also better integrated with the other
  68 data types from WINGs and is actively maintained.
  69
  70 Practically the things that were removed from the WINGs property list
  71 implementation compared to the old libPropList implementation, are exactly
  72 the UserDefaults borrowed concepts that conflict with the retain/release
  73 mechanism:
  74 - The container of a proplist object and the associated functions are gone.
  75 - The filename associated with a proplist object and the corresponding
  76   functions are gone. Now the saving function needs the filename as a
  77   parameter.
  78 - The synchronization functions are no longer supported. They are part of
  79   the UserDefaults and are implemented there.
  80 - No functions related to domains/registering were implemented in the WINGs
  81   property lists code, because they are also not part of property lists.
  82   They are more in connection with UserDefaults and a central point of access
  83   for domains.
  84
  85 The above 2 concepts: container and filename were added to libPropList just
  86 to let it support synchronization which was borrowed from UserDefaults.
  87 Property lists as defined in the openstep specification are just complex
  88 data structures composed of strings, data, arrays, dictionaries and a mix of
  89 them and are not associated with any file in particular. UserDefaults on the
  90 other hand are property lists read from a specific file and they associate
  91 that property list with that file and allow them to be synchronized.
  92
  93 Old libPropList based code can still be used by linking against the WINGs
  94 library containing the new proplist code with minimal changes which are
  95 described in detail in the comments at the top of the WINGs/proplist-compat.h
  96 header file (the same file carries the #defines for mapping old libPropList
  97 functions to the new WINGs proplist functions).
  98 Our recommendation is to move to the new functions WINGs provide because
  99 they better integrate with other function naming conventions in WINGs.
 100 The proplist-compat.h header file is just a way to have old code up and
 101 running with minimal changes so that we can remove the old and unmaintained
 102 libPropList from systems while keeping to use old libPropList based code
 103 without rewriting it and it should not be used for other purposes.
 104
 105
 106 *** Sat Apr 21 09:12:09 EEST 2001 -Dan
 107
 108 API change
 109 ----------
 110
 111 To allow a correct display of icon images with alpha blending in panels and
 112 other places where a WINGs based application may use them the following
 113 changes took place:
 114
 115 1. The following functions were renamed:
 116    - WMSetApplicationIconImage()  --> WMSetApplicationIconPixmap()
 117    - WMGetApplicationIconImage()  --> WMGetApplicationIconPixmap()
 118    - WMSetWindowMiniwindowImage() --> WMSetWindowMiniwindowPixmap()
 119 2. The following functions were added:
 120    - WMSetApplicationIconImage(WMScreen *scr, RImage *image)
 121    - RImage* WMGetApplicationIconImage(WMScreen *scr)
 122    - WMPixmap* WMCreateApplicationIconBlendedPixmap(WMScreen *scr, RColor *col)
 123
 124 As you can see the old functions that operated on WMPixmap images (which are
 125 basically X Pixmaps that lack alpha information) were renamed to ...Pixmap()
 126 to make them more suggestive about what they do and to make room for the
 127 new functions that operate on RImages (that hold alpha information).
 128
 129 Since the corresponding WMGet... functions only retrieve the stored
 130 image/pixmap from the application, I'll outline how the WMSet...
 131 functions operate:
 132
 133 All WM...IconPixmap() functions operate on WMPixmaps
 134 All WM...IconImage() functions operate on RImages
 135
 136
 137 - WMSetApplicationIconImage() will set the RImage to be used in panels
 138     and will also convert the RImage to a WMPixmap with a threshold of 128
 139     and will use that pixmap for the appicon image. If that doesn't satisfy
 140     you, you can make a call to WMSetApplicationIconPixmap() on your own to
 141     set whatever WMPixmap you see fit for the appicon.
 142
 143 - WMSetApplicationIconPixmap() will set the WMPixmap to be used for the
 144     appicon and for the panels
 145
 146
 147 If you use only one of the above functions, the corresponding image/pixmap
 148 will be used everywhere where needed (panels and appicon), but the pixmap
 149 version will not be able to handle alpha blending correctly.
 150
 151 If you use both WMSetApplicationIconImage() and WMSetApplicationIconPixmap()
 152 then the RImage will have priority in panels, and the WMPixmap will only be
 153 used for the appicon. This allows you to better control what icon is
 154 displayed in the appicon, in case the default conversion of the RImage to a
 155 pixmap with a threshold of 128 is not good enough, or in case you want a
 156 different icon to be shown in the appicon than in panels.
 157
 158
 159 Also this new function was added:
 160
 161 - WMCreateApplicationIconBlendedPixmap() will use the RImage set with
 162     WMSetApplicationIconImage() if available and will blend it with the color
 163     you passed. This will make the image show well on a background of that
 164     color. If the RImage was not set it will return NULL. You need to call
 165     WMReleasePixmap() on it after you finish with it. Passing a NULL pointer
 166     instead of a color will make the RImage be blended with the default color
 167     of the WINGs widgets: '#aeaaae' making it suitable to be assigned to any
 168     WINGs widget.
 169
 170
 171 To make your existing code work as before all you need to do is to rename
 172 the following functions:
 173
 174    - WMSetApplicationIconImage()  --> WMSetApplicationIconPixmap()
 175    - WMGetApplicationIconImage()  --> WMGetApplicationIconPixmap()
 176    - WMSetWindowMiniwindowImage() --> WMSetWindowMiniwindowPixmap()
 177
 178 But if you want to take advantage of the new abilities to show alpha
 179 blended images you need to start using the new functions.
 180
 181