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 (or ) 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.