The documentation for XForms, see e.g.

http://download.savannah.gnu.org/releases/xforms/forms.ps.gz

has become a bit outdated. Unfortunately, the sources for the
documentation aren't available anymore, so it will have to be
rewritten from scratch sometime in the (hopefully not too far)
future. Since there have been a few additions they are documen-
ted here.


New functions:
--------------

The first one isn't really a new function, it already exists
for some time but wasn't documented. It's called

   int fl_set_directory( const char * path )

and allows to set a new path for the file selector. 


There are three new functions for determining properties of
an object:

a) void fl_get_object_bw( FL_OBJECT * obj,
                          int       * bw )

It returns the borderwidth set for object 'obj' via 'bw'.


b) void fl_get_object_gravity( FL_OBJECT    * obj,
                               unsigned int * nw,
                               unsigned int * se )

It returns the NWgravity of object 'obj' via 'nw' and the
SEgravity via 'se'.


c) void fl_get_object_resize( FL_OBJECT *    obj,
                              unsigned int * resize )

It returns the resize setting for object 'obj'.


The next two functions allow to set and query to which mouse
buttons a button will react. Per default a button reacts to
all mouse buttons, including "clicks" generated by mouse
wheel. Sometimes this is not desired and the behaviour of
each button can be controlled via the function

   void fl_set_button_mouse_buttons( FL_OBJECT * ob,
                                     int         mouse_buttons )

The 'mouse_button' argument is the inclusive or of the numbers
1 for the left mouse button, 2 for the middle and 4 for the
right mouse button, 8 for moving the scroll wheel up and 16
for scrolling down.

The corresponding function to find out to which mouse buttons
a button reacts is

   void fl_get_button_mouse_buttons( FL_OBJECT    * obj,
                                     unsigned int * mouse_buttons )

which returns the setting for the button in the same way as
it has to be passed to fl_set_button_mouse_buttons().

This property of a buttons can also be set via fdesign under
the "Spec" tabfolder in the window for setting object attributes.


There is now a third goodie function for creating a message
box

   void fl_show_msg( const char * fmt, ... )

It expects a printf()-like format string 'fmt' and as many
more arguments as there are format specifiers in the format
string. The resulting string can have arbitrary length and
embedded newline characters ('\n') produce line breaks. The
size of the message box gets set in a way that the whole text
fits into it.

Also the alert boxes got changed so that they automatically
get a size that all text will fit. And there's another new
function 

   void fl_show_alert2( int c, const char * fmt, ... )

The first argument is the same as the one for fl_show_alert(),
i.e. it tells if the alert box is to be centered on the scrren.
The second argument is a printf()-like format string 'fmt',
followed by as many more arguments as there are format specifiers
in the format string. The resulting string can have arbitrary
length and the first embedded form-feed character is used as the
separator between the title string and the message of the alert
box. Embedded newline characters ('\n') produce lines break.


The new function

   int fl_set_menu_notitle( FL_OBJECT * ob,
                            int         off )

allows to switch off the "title" which per default is
displayed at the top of a menu. The second argment is a
boolean value, if non-zero the menu title will not be
displayed, if 0 they again be displayed. The function
returns the previous setting.

For FL_PUSH_MENU objects with the title set to off this
has the additional the consequence that they only get
opened when the mouse button has been released and they
appear just below the menu button (just like in the case
of FL_PULLDOWN_MENU objects).


The function

   void fl_get_decoration_sizes( FL_FORM * form,
                                 int     * top,
                                 int     * right,
                                 int     * bottom,
                                 int     * left )

tries to determine the widths of the decorations the window
manager puts around the window 'form' is displazed in. The
function returns 0 if it was successful, 1 otherwise. 'form'
must be a form that is currently displayed and it can't be
a form embedded in another form (like e.g. forms that are
part of a tab-folder).


Finally

   int fl_form_is_isconified( FL_FORM *form )

allows to query if a form's (visible) window is in iconified state.


Handling of counter objects has been changed. Before counters
changed values with a constant (normally rather fast) repeat rate.
This lead to some problems when one wanted to only change a
counters value by a single step. Now the default is that the
first step takes a longer time and the times betwen following
steps get shorter and shorter until a minumum delay is reached.
The function fl_set_counter_repeat(), that previously allowed
to set the delay between steps now conrols the delay for the
first step. The final, short delay between step can be set and
queried by the functions

void fl_set_counter_min_repeat( FL_OBJECT * ob, int millisec );
int fl_get_counter_min_repeat( FL_OBJECT * ob );

In case the old behaviour is desired simply set the times set by
fl_set_counter_repeat() and fl_set_counter_min_repeat() to the
same value.

It's also possible to hav just the very first delay being different
from the others. To achieve this set the the first delay time via
fl_set_counter_repeat() and the time for all other delays by
fl_get_counter_min_repeat() and then call the function

void fl_set_counter_sppedjump( FL_OBJECT * ob, int yes_no );

with a true value for the argument 'yes_no'. The actual value
for this setting can be queried by using

int fl_get_counter_speedjump( FL_OBJECT * ob );


Changes in Menu handling
------------------------

In 1.0.90 and before it was neither possible to set menu item
IDs (the value returned when a menu item has been selected and
reported by fl_get_menu()) nor to associate an item with a call-
back function (except when menus were created with the function
fl_set_menu_entries). Also, when a menu item got deleted, the
values returned when selecting menu items could change. This
made the interface a bit awkward to use.

All changes only concern menus created via either fl_set_menu()
or fl_addto_menu(). For those created via fl_set_menu_entries()
nothing has changed (and they still do not allow e.g. removing
a menu item).

Since now a value to be returned (in the following called "menu
item ID") or reported by fl_get_menu() when a certain menu item
is selected a few rules have to be clarified:

a) A menu item ID can be associated with a certain menu item
   using "%xn" in the string for the text of the menu item.
   Note that 'n' must be a number larger than 0. This concerns
   both the functions fl_set_menu() and fl_addto_menu().

b) If no menu item ID is assigned explicitely it gets its ID
   from a counter that is incremented for each menu item added
   (starting from 1). This number is never re-used, even when
   menu items get deleted. The only exception is that on a call
   of fl_clear_menu() also the counter gets reset to 1.

c) fl_get_menu() now returns the menu item ID and not an index
   (if no menu item IDs have been set and no menu items deleted
   this number is identical to the index).

d) To all functions expecting an item number the menu item ID
   must now be passed.

e) If two menu items receive the same menu item ID the results
   are unspecified, so the user must make sure that this never
   happens.

f) If a menu item gets delete via fl_delete_menu_item() all
   other items keep their menu item IDs, even if no menu item
   IDs have been set for them explicitely.

g) Menu items can now get associated with a callback function that
   is executed when the menu item is selected. The callback function
   is of type FL_PUP_CB, which receives the menu item ID of the
   selected menu. The return value of the callback function over-
   rides the menu item ID that normally would be returned.

All this was done this way to make menus behave as far as possible
like popups.


Three functions now have a slightly different prototype but which
should be compatible with previous versions. The functions now accept
in addition to their traditional arguments an unspecified number
of extra arguments:

 void fl_set_menu( FL_OBJECT *ob, const char * menustr, ... );
 int fl_addto_menu( FL_OBJECT *ob, const char * menustr, ... );
 fl_replace_menu_item( FL_OBJECT *ob, int numb, const char * menustr, ... );

These addition was necessary in order to allow that pointers to
callback functions for menu items can be added. If this is done
the 'menustr' variable must contain the characters "%f" for each
of the additional argument function pointers. This is exactly the
same way as callback functions can be set for popup items. A typical
invokation now is

fl_set_menu( obj, "Item1|Item2|Item3%f|Item4", item3_cb );

This creates a menu with 4 items and at the same time sets the
function 'item3_cb' as the callback function for menu item3.

As it was already possible for popups now also the menu item ID
can be set when a menu item gets created. The above invokation
may thus become

fl_set_menu( obj, "Item1|Item2|Item3%f%x10|Item4", item3_cb );

This results in item 3 returning 10 (the number directly following
"%x") instead of the default value of 3. This menu item ID is then
to be used in all calls of functions that expect menu item identifiers
(with one exception, see below).


Callback functions can also be set or changed via the new function

FL_PUP_CB fl_set_menu_item_callback( FL_OBJECT *  ob,
                                     int          numb,
                                     FL_PUP_CB    cb );

The arguments are the menu object, the menu item ID of the menu
item for which the callback is to be set and the address of the
callback function (NULL switches the callback mechansim off). The
function returns the address of the previously set callback func-
tion (or NULL if none was set),


The menu item ID associated with a menu item can also be set or
changed at any time by calling

int fl_set_menu_item_id( FL_OBJECT * ob,
                         int         index,
                         int         id );

Please note: the second argument is not the menu item ID but the
index of the menu item. This allows to correct situations were
erroneously two menu items got assigned the same menu item ID and
thus addressing a specific menu item isn't possible anymore.
The first argument is again the menu object and the last one the
new menu item ID. The function returns the previous value of the
menu item ID or -1 on error (it's an error if either the menu
was created with fl_set_menu_entries(), the new 'id' is smaller
than 1 or 'index' does not address an existing menu item).


The additions made above are also reflected in the handling of
menus in fdesign. Here under the 'Spec' attributes the callback
for a menu item can now be set and a stub for the callback
function gets created if requested. For menus to be created
via the fl_set_menu() or fl_addto_menu() also the menu item ID
can be set (this is the case when the button 'Use Struct', which
toggles between creation of menus with the fl_set_menu_entries()
and fl_addto_menu(), is off).


Miscellaneous changes
---------------------

The '-debug' option has been renamed to '-fldebug' to
avoid problems with programs that use the same option.

The new '-flhelp' option outputs a list of all options
that the library accepts.

The default borderwidth of object has been reduced to 1.

Input objects now lose the focus (and report changes back
to the program) on clicks of other objects that accept a
click with the mouse (buttons, sliders, etc.). This gets
around the problem that if one had an input field, edited
something in it (without hitting the ENTER or TAB key) and
then clicked on some button that's supposed to make use of
what just had been entered, the function fl_get_input() still
returned the unchanged value since the input field never lost
its focus and thus didn't accept the changes. 

When the mouse gets moved out of a window with an active input
object and moved into another window keyboard input now goes
to the new window instead of to the one that had been left.

Multi-line inpput object now also can be left by pressing the
<Tab> (or <Shift><Tab>) keys.

Date input fields handle verification of leap years correctly. 

ince the 0.89 version on calling fl_initialize() the locale for
the program was set to the default locale on the machine the pro-
gram was running on. Unfortunately, this was never documented
and led to trouble in several cases. This has now been removed.

When a file selector has a callback installed the field for
manually entering a file name isn't shown anymore - that field
could not be used anyway.

Message boxes created by fl_show_message() and fl_show_messages()
now can display an unlimited amount of text and they automatically
get a size so that the whole text fits in.

fdesign and the library can now deal with an arbitrary number of
forms, groups and objects.

No error messages are output anymore via popup windows.
