From 87dd7f0d23eba5c09e71ec6efeb34c6844f5e95f Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Tue, 29 Dec 1998 14:21:17 +0000 Subject: Revised documentation files. git-svn-id: file:///fltk/svn/fltk/trunk@177 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/forms.html | 230 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 230 insertions(+) create mode 100644 documentation/forms.html (limited to 'documentation/forms.html') diff --git a/documentation/forms.html b/documentation/forms.html new file mode 100644 index 000000000..1d6614581 --- /dev/null +++ b/documentation/forms.html @@ -0,0 +1,230 @@ + + + +

E - Forms Compatibility

+ +Fluid (the Fast Light User Interface Designer) +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 compatability header, +<FL/forms.H>. + +

You should be able to compile existing Forms or XForms source code +by changing the -I 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. + +

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 compatability is no longer a goal of +FLTK. Compatability was limited to things that were free, or that +would add code that would not be linked in if the feature is unused. +I did not add anything that would make the FLTK widgets bigger, or that +used X types as arguments. + +

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 I +expeceted and even our 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_VERSION, 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 for porting old Forms programs

+ +

These notes were written for porting programs written with the +older GL version of Forms. Most of these problems are the same ones +encountered when going from old Forms to XForms: + +

Does not go into background

+ +The GL 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 GL windows or fl_queue

+ +

If a Forms (not XForms) program if you wanted your own window for +displaying things you would create a GL 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 GL 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. See the example program shape.C for +how this is structured. + +

If you draw into the overlay planes you will have to also write a +draw_overlay() routine and call redraw_overlay() on the gl 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 gl 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()&(1<<10) +
MOUSE2,MIDDLEMOUSE	Fl::event_state()&(1<<9) +
MOUSE3,LEFTMOUSE	Fl::event_state()&(1<<8) +

+ +

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