diff options
Diffstat (limited to 'documentation/src/forms.dox')
| -rw-r--r-- | documentation/src/forms.dox | 247 |
1 files changed, 0 insertions, 247 deletions
diff --git a/documentation/src/forms.dox b/documentation/src/forms.dox deleted file mode 100644 index d48457e60..000000000 --- a/documentation/src/forms.dox +++ /dev/null @@ -1,247 +0,0 @@ -/** - - \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 -*/ |