diff options
Diffstat (limited to 'documentation/src/forms.dox')
| -rw-r--r-- | documentation/src/forms.dox | 247 |
1 files changed, 247 insertions, 0 deletions
diff --git a/documentation/src/forms.dox b/documentation/src/forms.dox new file mode 100644 index 000000000..d48457e60 --- /dev/null +++ b/documentation/src/forms.dox @@ -0,0 +1,247 @@ +/** + + \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 + +\htmlonly +<hr> +<a class="el" href="index.html">[Index]</a> +<a class="el" href="glut.html">[Previous]</a> + \ref glut +<a class="el" href="osissues.html">[Next]</a> + \ref osissues + +\endhtmlonly +*/ |