WINGs/NEWS

   1
   2 *** Sat Apr 21 09:12:09 EEST 2001 -Dan
   3
   4 API change
   5 ----------
   6
   7 To allow a correct display of icon images with alpha blending in panels and
   8 other places where a WINGs based application may use them the following
   9 changes took place:
  10
  11 1. The following functions were renamed:
  12    - WMSetApplicationIconImage()  --> WMSetApplicationIconPixmap()
  13    - WMGetApplicationIconImage()  --> WMGetApplicationIconPixmap()
  14    - WMSetWindowMiniwindowImage() --> WMSetWindowMiniwindowPixmap()
  15 2. The following functions were added:
  16    - WMSetApplicationIconImage(WMScreen *scr, RImage *image)
  17    - RImage* WMGetApplicationIconImage(WMScreen *scr)
  18    - WMPixmap* WMCreateApplicationIconBlendedPixmap(WMScreen *scr, RColor *col)
  19
  20 As you can see the old functions that operated on WMPixmap images (which are
  21 basically X Pixmaps that lack alpha information) were renamed to ...Pixmap()
  22 to make them more suggestive about what they do and to make room for the
  23 new functions that operate on RImages (that hold alpha information).
  24
  25 Since the corresponding WMGet... functions only retrieve the stored
  26 image/pixmap from the application, I'll outline how the WMSet...
  27 functions operate:
  28
  29 All WM...IconPixmap() functions operate on WMPixmaps
  30 All WM...IconImage() functions operate on RImages
  31
  32
  33 - WMSetApplicationIconImage() will set the RImage to be used in panels
  34     and will also convert the RImage to a WMPixmap with a threshold of 128
  35     and will use that pixmap for the appicon image. If that doesn't satisfy
  36     you, you can make a call to WMSetApplicationIconPixmap() on your own to
  37     set whatever WMPixmap you see fit for the appicon.
  38
  39 - WMSetApplicationIconPixmap() will set the WMPixmap to be used for the
  40     appicon and for the panels
  41
  42
  43 If you use only one of the above functions, the corresponding image/pixmap
  44 will be used everywhere where needed (panels and appicon), but the pixmap
  45 version will not be able to handle alpha blending correctly.
  46
  47 If you use both WMSetApplicationIconImage() and WMSetApplicationIconPixmap()
  48 then the RImage will have priority in panels, and the WMPixmap will only be
  49 used for the appicon. This allows you to better control what icon is
  50 displayed in the appicon, in case the default conversion of the RImage to a
  51 pixmap with a threshold of 128 is not good enough, or in case you want a
  52 different icon to be shown in the appicon than in panels.
  53
  54
  55 Also this new function was added:
  56
  57 - WMCreateApplicationIconBlendedPixmap() will use the RImage set with
  58     WMSetApplicationIconImage() if available and will blend it with the color
  59     you passed. This will make the image show well on a background of that
  60     color. If the RImage was not set it will return NULL. You need to call
  61     WMReleasePixmap() on it after you finish with it. Passing a NULL pointer
  62     instead of a color will make the RImage be blended with the default color
  63     of the WINGs widgets: '#aeaaae' making it suitable to be assigned to any
  64     WINGs widget.
  65
  66
  67 To make your existing code work as before all you need to do is to rename
  68 the following functions:
  69
  70    - WMSetApplicationIconImage()  --> WMSetApplicationIconPixmap()
  71    - WMGetApplicationIconImage()  --> WMGetApplicationIconPixmap()
  72    - WMSetWindowMiniwindowImage() --> WMSetWindowMiniwindowPixmap()
  73
  74 But if you want to take advantage of the new abilities to show alpha
  75 blended images you need to start using the new functions.
  76
  77