From 8416a4012ecb985d150fad566659cf59ee1dc3aa Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sat, 13 Sep 2008 15:55:32 +0000 Subject: Doxygen documentation - WP12 and WP13 - first step. Converted the descriptive chapters of the html docs to doxygen format and modified index.dox accordingly. This checkin includes only trivial reformatting, no major rewriting. Added a chapter "Migrating Code from FLTK 1.1 to 1.3". All links on the main page are working now. Todo: - Check doxygen error messages, rewrite pages (html tags, contents). - Fill the new "Migrating..." chapter. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6224 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/forms.dox | 201 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 documentation/forms.dox (limited to 'documentation/forms.dox') diff --git a/documentation/forms.dox b/documentation/forms.dox new file mode 100644 index 000000000..b2cb92ade --- /dev/null +++ b/documentation/forms.dox @@ -0,0 +1,201 @@ +/** + + \page forms E - Forms Compatibility + +

This appendix describes the Forms compatibility included with FLTK. +

Importing Forms Layout Files

+FLUID can read the .fd files put out by +all versions of Forms and XForms fdesign. However, it will mangle them +a bit, but it prints a warning message about anything it does not +understand. FLUID cannot write fdesign files, so you should save to a +new name so you don't write over the old one. +

You will need to edit your main code considerably to get it to link +with the output from FLUID. If you are not interested in this you may +have more immediate luck with the forms compatibility header, +<FL/forms.H>.

+

Using the Compatibility Header File

+ You should be able to compile existing Forms or XForms source code by +changing the include directory switch to your compiler so that the +forms.h file supplied with FLTK is included. Take a look at +forms.h to see how it works, but the basic trick is lots of inline +functions. Most of the XForms demo programs work without changes. +

You will also have to compile your Forms or XForms program using a +C++ compiler. The FLTK library does not provide C bindings or header +files.

+

Although FLTK was designed to be compatible with the GL Forms +library (version 0.3 or so), XForms has bloated severely and it's +interface is X-specific. Therefore, XForms compatibility is no longer +a goal of FLTK. Compatibility was limited to things that were free, or +that would add code that would not be linked in if the feature is +unused, or that was not X-specific.

+

To use any new features of FLTK, you should rewrite your code to not +use the inline functions and instead use "pure" FLTK. This will make +it a lot cleaner and make it easier to figure out how to call the FLTK +functions. Unfortunately this conversion is harder than expected and +even Digital Domain's inhouse code still uses forms.H a lot.

+

Problems You Will Encounter

+

Many parts of XForms use X-specific structures like XEvent + in their interface. I did not emulate these! Unfortunately these +features (such as the "canvas" widget) are needed by most large +programs. You will need to rewrite these to use FLTK subclasses.

+

Fl_Free widgets emulate +the old Forms "free" widget. It may be useful for porting +programs that change the handle() function on widgets, but you +will still need to rewrite things.

+

Fl_Timer widgets are +provided to emulate the XForms timer. These work, but are quite +inefficient and inaccurate compared to using +Fl::add_timeout().

+

All instance variables are hidden. If you directly refer to +the x, y, w, h, label, or other fields of your Forms widgets you will +have to add empty parenthesis after each reference. The easiest way to +do this is to globally replace "->x" with "->x()", etc. Replace +"boxtype" with "box()".

+

const char * arguments to most FLTK methods are simply +stored, while Forms would strdup() the passed string. This is +most noticable with the label of widgets. Your program must always +pass static data such as a string constant or malloc'd buffer to +label(). If you are using labels to display program output you +may want to try the Fl_Output + widget.

+

The default fonts and sizes are matched to the older GL version of +Forms, so all labels will draw somewhat larger than an XForms program +does.

+

fdesign outputs a setting of a "fdui" instance variable to the main +window. I did not emulate this because I wanted all instance variables +to be hidden. You can store the same information in the user_data() + field of a window. To do this, search through the fdesign output for +all occurances of "->fdui" and edit to use "->user_data()" instead. + This will require casts and is not trivial.

+

The prototype for the functions passed to fl_add_timeout() + and fl_set_idle_callback() callback are different.

+

All the following XForms calls are missing:

+ +

Additional Notes

+ These notes were written for porting programs written with the older +IRISGL version of Forms. Most of these problems are the same ones +encountered when going from old Forms to XForms: +

Does Not Run In Background

+ The IRISGL library always forked when you created the first window, +unless "foreground()" was called. FLTK acts like "foreground()" is +called all the time. If you really want the fork behavior do "if +(fork()) exit(0)" right at the start of your program. +

You Cannot Use IRISGL Windows or fl_queue

+ If a Forms (not XForms) program if you wanted your own window for +displaying things you would create a IRISGL window and draw in it, +periodically calling Forms to check if the user hit buttons on the +panels. If the user did things to the IRISGL window, you would find +this out by having the value FL_EVENT returned from the call to Forms. +

None of this works with FLTK. Nor will it compile, the necessary +calls are not in the interface.

+

You have to make a subclass of +Fl_Gl_Window and write a draw() method and +handle() method. This may require anywhere from a trivial to a +major rewrite.

+

If you draw into the overlay planes you will have to also write a +draw_overlay() method and call redraw_overlay() on the +OpenGL window.

+

One easy way to hack your program so it works is to make the +draw() and handle() methods on your window set some +static variables, storing what event happened. Then in the main loop +of your program, call Fl::wait() and then check these +variables, acting on them as though they are events read from +fl_queue.

+

You Must Use OpenGL to Draw Everything

+

The file <FL/gl.h> defines replacements for a lot of IRISGL +calls, translating them to OpenGL. There are much better translators +available that you might want to investigate.

+

You Cannot Make Forms Subclasses

+ Programs that call fl_make_object or directly setting the +handle routine will not compile. You have to rewrite them to use a +subclass of Fl_Widget. It is important to note that the +handle() method is not exactly the same as the handle() + function of Forms. Where a Forms handle() returned non-zero, +your handle() must call do_callback(). And your +handle() must return non-zero if it "understood" the event. +

An attempt has been made to emulate the "free" widget. This appears +to work quite well. It may be quicker to modify your subclass into a +"free" widget, since the "handle" functions match.

+

If your subclass draws into the overlay you are in trouble and will +have to rewrite things a lot.

+

You Cannot Use <device.h>

+ If you have written your own "free" widgets you will probably get a +lot of errors about "getvaluator". You should substitute: +
+ + + + + + + + + + +
FormsFLTK
MOUSE_XFl::event_x_root()
MOUSE_YFl::event_y_root()
LEFTSHIFTKEY,RIGHTSHIFTKEYFl::event_shift()
CAPSLOCKKEYFl::event_capslock()
LEFTCTRLKEY,RIGHTCTRLKEYFl::event_ctrl()
LEFTALTKEY,RIGHTALTKEYFl::event_alt()
MOUSE1,RIGHTMOUSEFl::event_state()
MOUSE2,MIDDLEMOUSEFl::event_state()
MOUSE3,LEFTMOUSEFl::event_state()
+ Anything else in getvaluator and you are on your own... +

Font Numbers Are Different

+ The "style" numbers have been changed because I wanted to insert +bold-italic versions of the normal fonts. If you use Times, Courier, +or Bookman to display any text you will get a different font out of +FLTK. If you are really desperate to fix this use the following code: +