From d7b88a3bcc7e76f38ee5799be7722fd5a10781ef Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Wed, 13 Jan 1999 19:28:54 +0000 Subject: Updated all links so they work between files. Revision 1. git-svn-id: file:///fltk/svn/fltk/trunk@219 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/forms.html | 467 ++++++++++++++++++++--------------------------- 1 file changed, 198 insertions(+), 269 deletions(-) (limited to 'documentation/forms.html') diff --git a/documentation/forms.html b/documentation/forms.html index c1c69cf0e..6fd5282d7 100644 --- a/documentation/forms.html +++ b/documentation/forms.html @@ -1,271 +1,200 @@ - - - -

E - Forms Compatibility

- -This appendix describes the Forms compatibility included with FLTK. - + +

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>. - +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 compatable 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()&FL_BUTTON3 MOUSE2,MIDDLEMOUSE Fl::event_state()&FL_BUTTON2 MOUSE3,LEFTMOUSE Fl::event_state()&FL_BUTTON1 - -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*"); - - - - + 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 compatable 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*"); + + + \ No newline at end of file -- cgit v1.2.3

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()&FL_BUTTON3
MOUSE2,MIDDLEMOUSE	Fl::event_state()&FL_BUTTON2
MOUSE3,LEFTMOUSE	Fl::event_state()&FL_BUTTON1