From 497afccb07164373e0de6639e754d7d691f1926f Mon Sep 17 00:00:00 2001 From: Fabien Costantini Date: Tue, 14 Oct 2008 22:12:25 +0000 Subject: Doxygen pdf man: First version added in documentation/fltk.pdf, old doc removed, images, dox files moved to a new src directory. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6431 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/forms.html | 203 ----------------------------------------------- 1 file changed, 203 deletions(-) delete mode 100644 documentation/forms.html (limited to 'documentation/forms.html') diff --git a/documentation/forms.html b/documentation/forms.html deleted file mode 100644 index 269fa299a..000000000 --- a/documentation/forms.html +++ /dev/null @@ -1,203 +0,0 @@ - - - E - Forms Compatibility - - -

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:

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

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

Forms	FLTK
MOUSE_X	Fl::event_x_root()
MOUSE_Y	Fl::event_y_root()
LEFTSHIFTKEY,RIGHTSHIFTKEY	Fl::event_shift()
CAPSLOCKKEY	Fl::event_capslock()
LEFTCTRLKEY,RIGHTCTRLKEY	Fl::event_ctrl()
LEFTALTKEY,RIGHTALTKEY	Fl::event_alt()
MOUSE1,RIGHTMOUSE	Fl::event_state()
MOUSE2,MIDDLEMOUSE	Fl::event_state()
MOUSE3,LEFTMOUSE	Fl::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: -

-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*");
-

- -- cgit v1.2.3