fltk/documentation/forms.dox

/**

 \page	forms	E - Forms Compatibility

This appendix describes the Forms compatibility included with FLTK.

\section forms_importing Importing Forms Layout Files

<A href=fluid.html#FLUID>FLUID</A> 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, <tt>
<FL/forms.H></tt>. 

\section forms_using 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 <tt>
forms.h</tt> file supplied with FLTK is included.  Take a look at <tt>
forms.h</tt> 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 <tt>forms.H</tt> a lot. 

\section forms_problems Problems You Will Encounter

Many parts of XForms use X-specific structures like <tt>XEvent</tt>
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. 

<A href=Fl_Free.html#Fl_Free><tt>Fl_Free</tt></A> widgets emulate
the <I>old</I> Forms "free" widget.  It may be useful for porting
programs that change the <tt>handle()</tt> function on widgets, but you
will still need to rewrite things. 

<A href=Fl_Timer.html#Fl_Timer><tt>Fl_Timer</tt></A> widgets are
provided to emulate the XForms timer.  These work, but are quite
inefficient and inaccurate compared to using <A href="Fl.html#Fl.add_timeout">
<tt>Fl::add_timeout()</tt></A>. 

<I>All instance variables are hidden.</I> 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()". 

<tt>const char *</tt> arguments to most FLTK methods are simply
stored, while Forms would <tt>strdup()</tt> 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 <tt>
label()</tt>.  If you are using labels to display program output you
may want to try the <A href=Fl_Output.html#Fl_Output><tt>Fl_Output</tt></A>
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 <tt>user_data()</tt>
 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 <tt>fl_add_timeout()</tt>
and <tt>fl_set_idle_callback()</tt> callback are different. 

<B>All the following XForms calls are missing:</B>

\li <tt>FL_REVISION</tt>, <tt>fl_library_version()</tt>
\li <tt>FL_RETURN_DBLCLICK</tt> (use <tt>Fl::event_clicks()</tt>) 
\li <tt>fl_add_signal_callback()</tt>
\li <tt>fl_set_form_atactivate()</tt> <tt>fl_set_form_atdeactivate()</tt>
\li <tt>fl_set_form_property()</tt>
\li <tt>fl_set_app_mainform()</tt>, <tt>fl_get_app_mainform()</tt>
\li <tt>fl_set_form_minsize()</tt>, <tt>fl_set_form_maxsize()</tt>
\li <tt>fl_set_form_event_cmask()</tt>, <tt>fl_get_form_event_cmask()</tt>
\li <tt>fl_set_form_dblbuffer()</tt>, <tt>fl_set_object_dblbuffer()</tt>
    (use an <tt>Fl_Double_Window</tt> instead) 
\li <tt>fl_adjust_form_size()</tt>
\li <tt>fl_register_raw_callback()</tt>
\li <tt>fl_set_object_bw()</tt>, <tt>fl_set_border_width()</tt>
\li <tt>fl_set_object_resize()</tt>, <tt>fl_set_object_gravity()</tt>
\li <tt>fl_set_object_shortcutkey()</tt>
\li <tt>fl_set_object_automatic()</tt>
\li <tt>fl_get_object_bbox()</tt> (maybe FLTK should do this) 
\li <tt>fl_set_object_prehandler()</tt>, <tt>fl_set_object_posthandler()</tt>
\li <tt>fl_enumerate_fonts()</tt>
\li Most drawing functions 
\li <tt>fl_set_coordunit()</tt> (FLTK uses pixels all the time) 
\li <tt>fl_ringbell()</tt>
\li <tt>fl_gettime()</tt>
\li <tt>fl_win*()</tt> (all these functions) 
\li <tt>fl_initialize(argc,argv,x,y,z)</tt> ignores last 3 arguments 
\li <tt>fl_read_bitmapfile()</tt>, <tt>fl_read_pixmapfile()</tt>
\li <tt>fl_addto_browser_chars()</tt>
\li <tt>FL_MENU_BUTTON</tt> just draws normally 
\li <tt>fl_set_bitmapbutton_file()</tt>, <tt>fl_set_pixmapbutton_file()</tt>
\li <tt>FL_CANVAS</tt> objects 
\li <tt>FL_DIGITAL_CLOCK</tt> (comes out analog) 
\li <tt>fl_create_bitmap_cursor()</tt>, <tt>fl_set_cursor_color()</tt>
\li <tt>fl_set_dial_angles()</tt>
\li <tt>fl_show_oneliner()</tt>
\li <tt>fl_set_choice_shortcut(a,b,c) </tt>
\li command log 
\li Only some of file selector is emulated 
\li <tt>FL_DATE_INPUT</tt>
\li <tt>fl_pup*()</tt> (all these functions) 
\li textbox object (should be easy but I had no sample programs) 
\li xyplot object 

\section forms_notes 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:

\par 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.

\par 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 <A href=Fl_Gl_Window.html#Fl_Gl_Window>
<tt>Fl_Gl_Window</tt></A> and write a <tt>draw()</tt> method and <tt>
handle()</tt> 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 <tt>
draw_overlay()</tt> method and call <tt>redraw_overlay()</tt> on the
OpenGL window. 

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

\par You Must Use OpenGL to Draw Everything

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

\par You Cannot Make Forms Subclasses

Programs that call <tt>fl_make_object</tt> or directly setting the
handle routine will not compile.  You have to rewrite them to use a
subclass of <tt>Fl_Widget</tt>.  It is important to note that the <tt>
handle()</tt> method is not exactly the same as the <tt>handle()</tt>
function of Forms.  Where a Forms <tt>handle()</tt> returned non-zero,
your <tt>handle()</tt> must call <tt>do_callback()</tt>. And your <tt>
handle()</tt> 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. 

\par 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:

<CENTER>
<TABLE border=1 WIDTH=90% summary="Mapping of Forms valuators to FLTK.">
<TR><TH align=center>Forms</TH><TH align=center>FLTK</TH></TR>
<TR><TD>MOUSE_X</TD><TD>Fl::event_x_root()</TD></TR>
<TR><TD>MOUSE_Y</TD><TD>Fl::event_y_root()</TD></TR>
<TR><TD>LEFTSHIFTKEY,RIGHTSHIFTKEY</TD><TD>Fl::event_shift()</TD></TR>
<TR><TD>CAPSLOCKKEY</TD><TD>Fl::event_capslock()</TD></TR>
<TR><TD>LEFTCTRLKEY,RIGHTCTRLKEY</TD><TD>Fl::event_ctrl()</TD></TR>
<TR><TD>LEFTALTKEY,RIGHTALTKEY</TD><TD>Fl::event_alt()</TD></TR>
<TR><TD>MOUSE1,RIGHTMOUSE</TD><TD>Fl::event_state()</TD></TR>
<TR><TD>MOUSE2,MIDDLEMOUSE</TD><TD>Fl::event_state()</TD></TR>
<TR><TD>MOUSE3,LEFTMOUSE</TD><TD>Fl::event_state()</TD></TR>
</TABLE>
</CENTER>

Anything else in <tt>getvaluator</tt> and you are on your own...

\par 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:

\code
fl_font_name(3,"*courier-medium-r-no*");
fl_font_name(4,"*courier-bold-r-no*");
fl_font_name(5,"*courier-medium-o-no*");
fl_font_name(6,"*times-medium-r-no*");
fl_font_name(7,"*times-bold-r-no*");
fl_font_name(8,"*times-medium-i-no*");
fl_font_name(9,"*bookman-light-r-no*");
fl_font_name(10,"*bookman-demi-r-no*");
fl_font_name(11,"*bookman-light-i-no*");
\endcode

<hr>
<a class="el" href="index.html">[Index]</a> &nbsp;&nbsp;
<a class="el" href="glut.html">[Previous]</a>&nbsp;
     \ref glut &nbsp;&nbsp;
<a class="el" href="osissues.html">[Next]</a>&nbsp;
     \ref osissues

*/