[XForms] New pre-release: xforms-1.0.92.pre4

[Jens Thoms Toerring]

To subscribers of the xforms list

Hi everybody,

   here we go again with another pre-release:

http://download.savannah.gnu.org/releases/xforms/xforms-1.0.92pre4.tar.gz

(as usual it may take some time until it has made it to the
mirror severs...)

For a start I would like to apologize for the length of the
following text but since I introduced a number of changes that
may affect existing applictions please bear with me...

When trying to write the code for the new "spinner" widget I hit
a number of snags. After some time I realized that this was due
to some inconsistencies I hadn't been aware of before.

As far as I understand the way XForms is supposed to works it's
like this: when the "state" of an object changes the object gets
either returned back to the application from a function like
fl_do_forms() or, if a callback for the object is installed, that
callback function is invoked. And you can influence what is repor-
ted (i.e. report all changes, report on the end of the interaction
or on end of interaction only if the object's state did change as
a result of the interaction). And this is the way it actually did
work, at least for most objects (of course leaving out objects
that never change state like boxes, frames etc.).

But things get hairy for objects that are basically a combination
of other objects. The simplest example is a scrollbar, which is
nothing but a slider and two (touch) buttons. But already for this
rather simple widget the usual rules don't hold anymore: a scroll-
bar never gets returned to the application e.g. by fl_do_forms() -
you could get at changes only via installing a callbac.

IMHO, this is simply wrong. The user shouldn't have to know if
some object is "simple" or made up of child objects, all objects
should work the same way. So I changed a few things while trying
not to break too much existent code.

Things now work like this:

a) As before, but with greater flexibility, you can set for all
   objects (at least those for which it makes sense) under which
   conditions they're supposed to be reported back to your appli-
   cation - be it either via invoking a callback you installed for
   an object or be it via the object getting returned by e.g.
   fl_do_forms().

b) All objects (with a few exceptions I didn't got around to
   fixing yet like menus etc., which are a a PITA anyway) now
   follow the same simple scheme: when a state change of the
   type you requested happens they get returned to your appli-
   cation, either via a callback you installed or by returning
   the object from fl_do_forms() or similar.

c) Once an object gets returned to your application you can check
   which condition led to it being returned.

Here's an example. Take a browser as one of the more complex
objects. It constists of a text area (a widget not part of the
public interface) and (up to) two scrollbars (of which each in
turn constists of a slider and two touch buttons). Until now
for browsers only changes in the selection state of lines (for
browser types that support selections) got reported, and that
only via their callbacks. To get at changes of the scollbars
an ad-hoc mechanism was needed, that's why the functions
fl_set_browser_[vh]scroll_callback() exist at all.

With the new version you can use the function

fl_set_object return()

(which already existed but wasn't documented) to tell what kind of
events you want to get reported back to your application. These are
(for browsers, for other objects there might be less choices):

FL_RETURN_NONE         never report changes
FL_RETURN_CHANGED      scrolling has happened (via scrollbars or e.g.
                       keyboard)
FL_RETURN_END          end of scroll interaction (i.e. mouse had been
                       used to move the scrollbar and has been released)
FL_RETURN_SELECTION    one (or more) lines in the browser got selected
FL_RETURN_DESElECTION  one (or more) lines in the browser got deselected
FL_RETURN_ALWAYS       one of all of the abobe events

All events can be OR'ed, so you can request combinations of them to be
reported. And then there's another one that's a bit special:

FL_RETURN_END_CHANGED  end of scroll interaction and, after scrolling,
                       the text displayed in the browser has been changed
                       (which wouldn't be the case if you scroll down
                       and back to the original position with the scroll-
                       bars)

which is a combination of FL_RETURN_CHANGED ans FL_RETURN_END, i.e.
it only gets reported when the interaction ends and resulted in a
change.

Within the code for handling object events you can find out which
kind of event resulted in the object getting reprorted to your
application by using the new function

int fl_get_object_return_state(FL_OBJECT *obj);

It will return FL_RETURN_CHANGED, FL_RETURN_END, FL_RETURN_SELECTION
or FL_RETURN_DESELECTION or a combination by logical OR. (If you asked
for the object to be reported on FL_RETURN_END_CHANGED then both
FL_RETURN_CHANGED and FL_RETURN_END will be set) Please note that
calling fl_get_object_return_state() only makes sense directly after
the object has been returned to your application (or in the calback
you installed) since any further user interaction with the object
will result in the value getting changed. One possibility is also
that the function returns the value FL_RETURN_TRIGGERED in case the
object wasn't returned due to user interaction but because of a call
of fl_trigger_object().

The descriptions in the documentation now list for each type of
object which return settings make sense and what will get returned
under which conditions.

Unfortunately, there are a few cases where problems with existing
code are inevitable. Programs that don't install a callback for
scrollbars or browsers and don't catch when they get returned
from fl_do_forms() may break. For these programs it would be best
if after creating the browser or scrollbar fl_set_object_return()
would be called with FL_RETURN_NONE as the second argument. A an
alternative, you can compile the librarry for backward compatibi-
lity for these cases by adding

--enable-bw-bs-hack

to the list of flags passed to configure. This makes sure that
browsers and scrollbars keep their traditional behaviour, i.e.
they won't get returned by fl_do_forms() but callbacks work.

In the process of doing these changes I also rewrote parts of the
browser object (especially the internal textbox widget). Before it
wasn't really possible to have different font sizes in a browser
(you had to put extra empty lines around lines with fonts larger
than the default font) and, at least to me, it didn't look nice
that there often was a lot of empty space at the end of the
browser area if there wasn't room enough to show the last line
completely. Also the restriction on the maximum number of charac-
ters in a line didn't look too good to me. Now I hope browsers
look more like people are used to from other toolkits (and I
changed the default background color from gray to white). I
tried to make things as similar as possible to the previous
behaviour but, of course, a few things had to be changed -
please take a look if there's anything that breaks your appli-
cations and tell me about it.

There are also a few new functions for browsers:

double fl_get_browser_rel_xoffset(FL_OBJECT *obj);
int fl_get_browser_yoffset(FL_OBJECT *obj);
double fl_get_browser_rel_yoffset(FL_OBJECT *obj);
void fl_set_browser_rel_xoffset(FL_OBJECT *obj, double offset);
void fl_set_browser_yoffset(FL_OBJECT *obj, int pixels);
void fl_set_browser_rel_yoffset(FL_OBJECT *obj, double offset);
int fl_get_browser_line_yoffset(FL_OBJECT *obj, int line);

They allow to query or set the amount of horizontal and vertical
scrolling of the browser. This can obtained or set either in
absolute values (pixels) or relative units (a value between 0.0
and 1.0 with the functions containing '_rel_' in their names).
The last function allows to determine which y-offset must be
set that a line appears as the topmost line in the browser
(-1 gets returned if the line doesn't exists).

And, of course, with the new pre-release also comes a new version
of the dicumentation which you also can download from savannah.

                               Best regards, Jens
-- 
  \   Jens Thoms Toerring  ________      jt at toerring.de
   \_______________________________      http://toerring.de
_______________________________________________
To unsubscribe, send any message to
xforms-leave at bob.usuhs.mil or see: 
http://cweblog.usuhs.mil/mailman/listinfo/xforms
List Archive: http://bob.usuhs.mil/pipermail/xforms and
http://bob.usuhs.mil/mailserv/list-archives/
XForms Home: http://savannah.nongnu.org/projects/xforms