- Updated WINGs/NEWS with info about hw the API changed how how things

[wmaker-crm.git] / WINGs / NEWS

*** Mon Oct 14 19:42:42 EEST 2002 - Dan

Double buffering
----------------

To avoid flickering caused by redrawing the widgets on Expose events, a
double buffering tehnique was implemented for most of the widgets.
This flickering effect has gotten more vizible with the introduction
of antialiased text. If with normal text one can redraw the text over the
old one over and over again without any degradation of the text (new pixels
simply overwrite old pixels), with antialiased text the situation is
different.
The pixels that constitute the antialias around the text are partially
transparent pixels, which let part of the background be visible through them.
If antialiased text is drawn over and over again, whithout first erasing the
old one, the partially transparent pixels of the antialias will no longer
see the background through them, but some of them will see the old pixels of
the antialias around the old text that was there before. This for example
will make a black antialiased text over a white background get thicker as
the pixels of the antialias around it, combine with semitransparent black
pixels of the old antialias instead of combining with the white background.
The result is that the antialias will get darker (in this case) and the text
will be altered.

Because of this the area where text is drawn needs to be cleared before
antialiased text can be drawn again. But between the moment whent he area is
cleared and the moment when the text is drawn again there is a small time
gap that results in flickering. This doesn't happen with normal text where
one doesn't need to clear the area before drawing the text, but instead can
simply draw over and over again.

To avoid this situation, a double buffering tehnique was used. Instead of
drawing directly in the wisget's window (which is mapped and will flicker as
described above), we draw in a pixmap (unmapped) and after all is done we
XCopyArea() from that pixmap to the real window.
Since all this takes place off-screen, no flickering will be observed in
this case.

This is a change that that will be automatically available for your
applications and will require no change from you.
However there is an exception from this in case of WMList if you delegate
the drawing of items to userspace (read below for the compelte details).


*** Mon Oct 14 22:07:42 EEST 2002 - Dan

WMList change
-------------

In case of WMList there is the posibility to delegate the drawing of the
list items to the application that is linked with WINGs, and this code will
not be inside the WINGs library, but in userland. Since we use the double
buffering tehnique in this case too (to allow all widgets based on WMList
and the ones that draw their list items by themselves to benefit from the
double buffering advantage automatically), we no longer pass the window to
the user code doing item drawing, but instead pass this pixmap in which we
draw before copying to the real window.

Since one cannot use XClearWindow() or XClearArea() on pixmaps, but only on
windows, if your list item drawing code used to contain these to clear the
item area before drawing it needs to change, else the application will die
when it tires to XClearArea() on a pixmap.

This means that in your application if you ever used WMSetListUserDrawProc()
so set a userspace routine which draws WMList items in a particular fashion,
you need to make sure your function will not call XClearArea() or
XClearWindow() on the drawable that was passed to draw in.

Instead you should use XFillRectangle().

This change also means that you no longer need to do double buffering in
your code, if you ever used to do. It is not done by WINGs and you benefit
from it automatically.


*** Mon Oct 14 19:28:35 EEST 2002 - Dan

API change
----------

WMDrawString() and WMDrawImageString() no longer take a GC as argument.
Instead WMDrawString() takes a WMColor* as the color for the string to be
drawn, while WMDrawImageString() takes 2 WMColor* arguments in place of the
old GC: first for text color and second for background color.

This change is required to support extending WMFont to allow it to handle
antialiased fonts through the XFree86 Xft extension.

This also has the advantage of hiding low level X11 details and use WINGs
internat objects instead.

To fix your old code to work with the new WINGs API you need to replace the
GC passed to WMDraw***String() in your code with a WMColor*.
Most of the old code used to be like this:

WMDrawString(screen, window, WMColorGC(color), font, x, y, txt, len);

for the new API it should be replaced by:

WMDrawString(screen, window, color, font, x, y, txt, len);

However if you used a particular GC created by yourself to suit your special
needs, you need to pass a color which is the same as the foreground color of
that gc.

For WMDrawImageString(), from:

WMDrawImageString(screen, window, gc, font, x, y, txt, len);

becomes

WMDrawImageString(screen, window, textColor, backColor, font, x, y, txt, len);

where textColor and backColor are declared like:

WMColor *textColor, *backColor;

and have the color of the foreground respective the background of the old gc.



*** Wed Oct  9 07:10:04 EEST 2002 - Dan

Xft support in WINGs
--------------------

If Xft is detected when configure it is run, support for drawing antialiased
fonts with transparency will be compiled into WINGs.
You need at least Xfree86 version 4.0.x for this but at least 4.1.x is
recommended.

For Xft support there is a new function to create a font that will render
using antialiasing and transparency: WMCreateAAFont().
Passing such a font to WMDrawString() or WMDrawImageString() will result
in antialiased text displayed on screen. Modifying the alpha value for the
WMColor passed to WMDrawString() or WMDrawImageString() will result in text
being displayed with the appropriate transparency.

To control antialiased font behavior, there are 3 new options that go into
WMGLOBAL. Two of them are to set the system font used when an antialiased
font is required. They operate in a similar way as SystemFont and
BoldSystemFont, just they are used when antialiased fonts are requested.
They are named AASystemFont respectively AABoldSystemFont. They are kept
separate from SystemFont and BoldSystemFont because the same fonts don't
render well as both normal and antialiased if they are not TrueType fonts.
Even though you can specify any font in the XLFD format for these new
options, it is recomended to use TrueType fonts for the antialiased case
since other fonts (standard X fonts)  don't render well and give ugly
results.

The third option is an option that globally controls if WINGs uses or not
antialiased fonts. It is named AntialiasedText and it has a boolean Yes/No
value. If set to Yes, WINGs will try to use antialiased fonts (if support
was compiled in, and antialiased fonts can be found) then revert to normal
fonts if not possible. Note that this applies if WMCreateFont(),
WMSystemFont(), WMSystemFontOfSize(), WMBoldSystemFont() or
WMBoldSystemFontOFize() are used. If any of the direct creation functions
are used, such as WMCreateAAFont() or WMCreateNormalFont(), then that kind
of font is returned independently of the value of AntialiasedText.
(However note that an antialiased font cannot be created if Xft support was
no compiled into WINGs, even if you call WMCreateAAFont() directly. In this
case WMCreateAAFont() will always return NULL)



*** Mon Sep 09 06:58:30 EEST 2002 - Dan

New delegate for the WMConnection class
---------------------------------------

ConnectionDelegate structure has a new member: canResumeSending.
The purpose of this callback is to notify you that you can resume sending
data over a WMConnection.
It works in the following manner:

WMSendConnectionData() can return 3 values: -1, 0, 1

-1 - means that the connection has died. you should stop sending data and
     close the connection ASAP.
 1 - means that the data was succesfully sent
 0 - means that the data (or part of it) was not sent. however, it was saved
     in a queue and the library will try to send it later when possible.

if the return value is 1, you can continue to send the next message, and so
on, until the return value of such a send call will be 0.
In this case you can continue sending, however, the data will not be sent
over the connection because the operating system cannot accept any more data
for the moment. Instead it will be queued inside the library, making your
program's memory footprint increase. If the ammount of data you need to
send is limited and not too big, this shouldn't be a problem, because your
data will be queued and sent when the operating system will notify the
library that sending is possible again.
If this is the case you can just ignore the output of WMSendConnectionData()
and not set a callback for canResumeSending.

However, if the ammount of data you have to send is undetermined and you
also want to keep a small memory footprint for your program (so that it
won't grow until it uses all your available memory ;) ), you will have to
stop sending data over the connection as soon as WMSendConnectionData()
returns with 0. Then you should somehow mark this situation in your program
to avoid it trying to send anymore data until notified that it can resume.
(You should have also set a canResumeSending callback when you initialized
your WMConnection object because else you cannot be notified when to resume.)

Now, when you receive such a 0 from the send operation, your last sent data
is put in a queue inside the library. At a later time when the operating
system notifies the library that sending is possible again, the library will
resume to send the data that is saved in the queue. After it will be able to
send all the data in the queue, the canResumeSending callback will be
called, letting you know that not only you can resume sending because the
operating system is again able to send data, but also that the queue was
completely flushed.

From the canResumeSending callback, you should again update the status of
your program marking that it can send again, and then resume sending the
data from where you were left.


*** Thu Oct 04 06:00:09 EEST 2001 -Dan

Property lists handling code
----------------------------

Code to handle property lists was added to WINGs. It is more robust
than the libPropList code, mostly because some conflicting concepts 
borrowed from UserDefaults (which libPropList use) are no longer used in
the WINGs property lists code. These borrowed concepts conflicted with the
retain/release mechanism of property lists and could lead in certain cases
to segmentation faults when executing libPropList based code. But the worse
part was that these libPropList problems were practically unsolvable without
removing one of those conflicting concepts and without a complete redesign. 
The new WINGs property lists code is also better integrated with the other
data types from WINGs and is actively maintained.

Practically the things that were removed from the WINGs property list
implementation compared to the old libPropList implementation, are exactly
the UserDefaults borrowed concepts that conflict with the retain/release
mechanism:
- The container of a proplist object and the associated functions are gone.
- The filename associated with a proplist object and the corresponding
  functions are gone. Now the saving function needs the filename as a
  parameter.
- The synchronization functions are no longer supported. They are part of
  the UserDefaults and are implemented there.
- No functions related to domains/registering were implemented in the WINGs
  property lists code, because they are also not part of property lists.
  They are more in connection with UserDefaults and a central point of access
  for domains.

The above 2 concepts: container and filename were added to libPropList just
to let it support synchronization which was borrowed from UserDefaults.
Property lists as defined in the openstep specification are just complex
data structures composed of strings, data, arrays, dictionaries and a mix of
them and are not associated with any file in particular. UserDefaults on the
other hand are property lists read from a specific file and they associate
that property list with that file and allow them to be synchronized.

Old libPropList based code can still be used by linking against the WINGs
library containing the new proplist code with minimal changes which are
described in detail in the comments at the top of the WINGs/proplist-compat.h
header file (the same file carries the #defines for mapping old libPropList
functions to the new WINGs proplist functions).
Our recommendation is to move to the new functions WINGs provide because
they better integrate with other function naming conventions in WINGs.
The proplist-compat.h header file is just a way to have old code up and
running with minimal changes so that we can remove the old and unmaintained
libPropList from systems while keeping to use old libPropList based code
without rewriting it and it should not be used for other purposes.


*** Sat Apr 21 09:12:09 EEST 2001 -Dan

API change
----------

To allow a correct display of icon images with alpha blending in panels and
other places where a WINGs based application may use them the following
changes took place:

1. The following functions were renamed:
   - WMSetApplicationIconImage()  --> WMSetApplicationIconPixmap()
   - WMGetApplicationIconImage()  --> WMGetApplicationIconPixmap()
   - WMSetWindowMiniwindowImage() --> WMSetWindowMiniwindowPixmap()
2. The following functions were added:
   - WMSetApplicationIconImage(WMScreen *scr, RImage *image)
   - RImage* WMGetApplicationIconImage(WMScreen *scr)
   - WMPixmap* WMCreateApplicationIconBlendedPixmap(WMScreen *scr, RColor *col)

As you can see the old functions that operated on WMPixmap images (which are
basically X Pixmaps that lack alpha information) were renamed to ...Pixmap()
to make them more suggestive about what they do and to make room for the
new functions that operate on RImages (that hold alpha information).

Since the corresponding WMGet... functions only retrieve the stored
image/pixmap from the application, I'll outline how the WMSet...
functions operate:

All WM...IconPixmap() functions operate on WMPixmaps
All WM...IconImage() functions operate on RImages


- WMSetApplicationIconImage() will set the RImage to be used in panels
    and will also convert the RImage to a WMPixmap with a threshold of 128
    and will use that pixmap for the appicon image. If that doesn't satisfy
    you, you can make a call to WMSetApplicationIconPixmap() on your own to
    set whatever WMPixmap you see fit for the appicon. 

- WMSetApplicationIconPixmap() will set the WMPixmap to be used for the
    appicon and for the panels 


If you use only one of the above functions, the corresponding image/pixmap
will be used everywhere where needed (panels and appicon), but the pixmap
version will not be able to handle alpha blending correctly.

If you use both WMSetApplicationIconImage() and WMSetApplicationIconPixmap()
then the RImage will have priority in panels, and the WMPixmap will only be
used for the appicon. This allows you to better control what icon is
displayed in the appicon, in case the default conversion of the RImage to a
pixmap with a threshold of 128 is not good enough, or in case you want a
different icon to be shown in the appicon than in panels.


Also this new function was added:

- WMCreateApplicationIconBlendedPixmap() will use the RImage set with
    WMSetApplicationIconImage() if available and will blend it with the color
    you passed. This will make the image show well on a background of that
    color. If the RImage was not set it will return NULL. You need to call
    WMReleasePixmap() on it after you finish with it. Passing a NULL pointer
    instead of a color will make the RImage be blended with the default color
    of the WINGs widgets: '#aeaaae' making it suitable to be assigned to any
    WINGs widget.


To make your existing code work as before all you need to do is to rename
the following functions:

   - WMSetApplicationIconImage()  --> WMSetApplicationIconPixmap()
   - WMGetApplicationIconImage()  --> WMGetApplicationIconPixmap()
   - WMSetWindowMiniwindowImage() --> WMSetWindowMiniwindowPixmap()

But if you want to take advantage of the new abilities to show alpha
blended images you need to start using the new functions.