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/fluid.html | 1320 +++++++++++++++++++--------------------------- 1 file changed, 536 insertions(+), 784 deletions(-) (limited to 'documentation/fluid.html') diff --git a/documentation/fluid.html b/documentation/fluid.html index c54a8c3e0..fc6519cbd 100644 --- a/documentation/fluid.html +++ b/documentation/fluid.html @@ -1,151 +1,104 @@ - - - -

8 - Programming with FLUID

- -This chapter shows how to use the Fast Light User-Interface Designer ("FLUID") to create -your GUIs. - + +

8 - Programming with FLUID

+ This chapter shows how to use the Fast Light User-Interface Designer +("FLUID") to create your GUIs.

What is FLUID?

- -The Fast Light User Interface Designer, or "FLUID", is a graphical -editor that is used to produce FLTK source code. - -

FLUID edits and saves its state in ".fl" files. These files are -text, and you can (with care) edit them in a text editor, perhaps to -get some special effects. - -

FLUID can "compile" the .fl file into a .cxx and a .h file. The .cxx -file defines all the objects from the .fl file and the .h file -declares all the global ones. - -

A simple program can be made by putting all your code (including a -main() function) into the .fl file and thus making the .cxx -file a single source file to compile. Most programs are more complex -than this, so you write other .cxx files that call the FLUID -functions. These .cxx files must #include the .h file or -they can #include the .cxx file so it still appears to be a single -source file. - -

- -

Normally the FLUID file defines one or more "functions", which -output C++ functions. Each function defines a one or more FLTK -windows, and all the widgets that go inside those windows. - -

Widgets created by FLUID are either "named", "complex named" or -"unnamed". A named widget has a legal C++ variable identifier as its -name (i.e. only alphanumeric and underscore). In this case FLUID -defines a global variable or class member that will point at the widget -after the function defining it is called. A "complex named" object has -punctuation such as '.' or '->' or any other symbols in its name. In -this case FLUID assigns a pointer to the widget to the name, but does -not attempt to declare it. This can be used to get the widgets into -structures. An "unnamed" widget has a blank name and no pointer to -them is stored. - -

Widgets may either call a named callback function that you write in -another source file, or you can supply a small piece of C++ source and -FLUID will write a private callback function into the .cxx file. - -

A Short Tutorial

- -
    - -
  1. Type "FLUID&" - -
  2. Pick "New/code/function" off the menu. - -
  3. Hit Tab, Delete to delete the function name and hit OK. This is - how you get FLUID to output a "main()" function. The text "main()" - with a triangle next to it should appear highlighted in the main - window. - -
  4. Pick "New/group/Window" off the menu. - -
  5. Move the new window and resize it to the size you want. - -
  6. Pick "New/buttons/Button" off the menu. - -
  7. Hit the "OK" button to dismiss the panel that appears. - -
  8. In the window you created, try moving the button by dragging it - around. Notice that it "snaps" to fixed locations. If you want to - drag it smoothly, hold down Alt. You can also change the size of the - steps with Edit/Preferences. - -
  9. Try resizing the widget by dragging the edges and corners. - -
  10. Type Alt+c to copy the widget. - -
  11. Type Alt+v to paste a copy into the window. - -
  12. Type Alt+v several times. - -
  13. Drag the widgets and resize them so they don't overlap. Notice - that you have to click a widget to pick it first, then drag it. - -
  14. Try selecting several widgets by dragging a box around them. Check - what happens when you move them, or when you drag an edge to resize - them. - -
  15. You can also use Shift+click to toggle widgets on and off. - -
  16. You can also select widgets by clicking on them in the list in the - main window, try that. - -
  17. Double-click one of the widgets. You will get a control panel. - -
  18. Try changing the "label". Try changing other items near the top of - the panel. To see any changes to the box type clearer, type "Alt+o" - to make the red overlay disappear. - -
  19. Type "#include <stdlib.h>" into the first line of "extra code:". - -
  20. Type "exit(0);" into the "callback:". - -
  21. Hit OK. - -
  22. Pick "File/Save As" off the menu. - -
  23. Type "test.fl" into the file chooser and hit return. - -
  24. Pick "File/Write Code" off the menu, hit OK on the confirmation panel. - -
  25. Go back to your terminal window. Type "more test.cxx" and "more - test.h" and you can see the code it made. Also try "more test.fl" to - see how FLUID saves its data. - -
  26. Type "make test" (you may have to add libaries to your Makefile). - -
  27. Type "./test" to run your program. - -
  28. Try the buttons. The one you put the code into will exit the - program. - -
  29. Type "Alt+Q" to exit FLUID. - -
  30. Ok, now try to make a real program. - -
- -

Running FLUID Under UNIX

- -To run FLUID under UNIX, type: - - - -to edit the .fl file filename.fl. If the file does not exist -you will get an error pop-up, but if you dismiss it you will be editing -a blank file of that name. You can run FLUID without any name, in -which case you will be editing an unnamed blank setup (but you can use -save-as to write it to a file). - -

You can provide any of the standard FLTK switches before the name: - -

+

The Widget Browser

+ + +
The main window shows a menu bar and a scrolling browser of all +the defined widgets. The name of the .fl file being edited is shown in +the window title. +

The widgets are stored in a hierarchy. You can open and close a +level by clicking the "triangle" at the left of a widget. This widget +is the parent, and all the widgets listed below it are its +children. There can be zero children.

+

The top level of the hierarchy is functions. Each of these +will produce a single C++ public function in the output .cxx file. +Calling the function will create all of its child windows.

+

The second level of the hierarchy is windows. Each of these +produces an instance of class Fl_Window.

+

Below that are either widgets (subclasses of Fl_Widget) or +groups of widgets (including other groups). Plain groups are for +layout, navigation, and resize purposes. Tab groups provide the +well-known file-card tab interface.

+

Widgets are shown in the browser as either their name (such +as "main_panel" in the example), or if unnamed as their type + and label (such as "Button "the green"").

+
+ You select widgets by clicking on their names, which highlights +them (you can also select widgets from any displayed window). You can +select many widgets by dragging the mouse across them, or by using +shift+click to toggle them on and off. To select no widgets, click in +the blank area under the last widget. Notice that hidden children may +be selected and there is no visual indication of this. +

You open widgets by double clicking them, or (to open several +widgets you have picked) by typing the F1 key. This will bring up a +control panel or window from which you can change the widget.

+

Menu Items

+

The menu bar at the top is duplicated as a pop-up menu on any +displayed window. The shortcuts for all the menu items work in any +window. The menu items are:

+

File/Open... (Alt+Shift+O)

+ Discard the current editing session and read in a different .fl file. +You are asked for confirmation if you have changed the current data. +

FLUID can also read .fd files produced by the Forms and XForms +"fdesign" programs. It is best to read them with Merge. FLUID does +not understand everything in a .fd file, and will print a warning +message on the controlling terminal for all data it does not +understand. You will probably need to edit the resulting setup to fix +these errors. Be careful not to save the file without changing the +name, as FLUID will write over the .fd file with its own format, which +fdesign cannot read!

File/Save (Alt+s)

- -Write the current data to the .fl file. If the file is unnamed -(because FLUID was started with no name) then ask for a file name. - + Write the current data to the .fl file. If the file is unnamed +(because FLUID was started with no name) then ask for a file name.

File/Save As...(Alt+Shift+S)

- -Ask for a new name to save the file as, and save it. - + Ask for a new name to save the file as, and save it.

File/Merge... (Alt+i)

- -Insert the contents of another .fl file, without changing the name of -the current .fl file. All the functions (even if they have the same -names as the current ones) are added, you will have to use cut/paste -to put the widgets where you want. - + Insert the contents of another .fl file, without changing the name of +the current .fl file. All the functions (even if they have the same +names as the current ones) are added, you will have to use cut/paste to +put the widgets where you want.

File/Write code (Alt+Shift+C)

- -"Compiles" the data into a .cxx and .h file. These are exactly the same -as the files you get when you run FLUID with the -c switch. - -

The output file names are the same as the .fl file, with the -leading directory and trailing ".fl" stripped, and ".h" or ".cxx" -appended. Currently there is no way to override this. - + "Compiles" the data into a .cxx and .h file. These are exactly the +same as the files you get when you run FLUID with the -c switch. +

The output file names are the same as the .fl file, with the leading +directory and trailing ".fl" stripped, and ".h" or ".cxx" appended. + Currently there is no way to override this.

File/Quit (Alt+q)

- -Exit FLUID. You are asked for confirmation if you have changed the -current data. - + Exit FLUID. You are asked for confirmation if you have changed the +current data.

Edit/Undo (Alt+z)

- -Don't you wish... This isn't implemented yet. You should do save -often so that any mistakes you make don't irretrivably destroy your -data. - + Don't you wish... This isn't implemented yet. You should do save +often so that any mistakes you make don't irretrivably destroy your +data.

Edit/Cut (Alt+x)

- -Delete the selected widgets and all their children. These are saved -to a "clipboard" file (/usr/tmp/cut_buffer.fl) and can be pasted back -into this FLUID or any other one. - + Delete the selected widgets and all their children. These are saved +to a "clipboard" file (/usr/tmp/cut_buffer.fl) and can be pasted back +into this FLUID or any other one.

Edit/Copy (Alt+c)

- -Copy the selected widgets and all their children to the "clipboard" file. - + Copy the selected widgets and all their children to the "clipboard" +file.

Edit/Paste (Alt+c)

- -Paste in the widgets in the clipboard file. - -

If the widget is a window, it is added to whatever function is -selected, or contains the current selection. - -

If the widget is a normal widget, it is added to whatever window or -group is selected. If none is, it is added to the window or group -that is the parent of the current selection. - -

To avoid confusion, it is best to select exactly one widget before -doing a paste. - -

Cut/paste is the only way to change the parent of a widget. - + Paste in the widgets in the clipboard file. +

If the widget is a window, it is added to whatever function is +selected, or contains the current selection.

+

If the widget is a normal widget, it is added to whatever window or +group is selected. If none is, it is added to the window or group that +is the parent of the current selection.

+

To avoid confusion, it is best to select exactly one widget before +doing a paste.

+

Cut/paste is the only way to change the parent of a widget.

Edit/Select All (Alt+a)

- -Select all widgets in the same group as the current selection. - -

If they are all selected already then this selects all widgets in -that group's parent. Repeatedly typing Alt+a will select larger and -larger groups of widgets until everything is selected. - + Select all widgets in the same group as the current selection. +

If they are all selected already then this selects all widgets in +that group's parent. Repeatedly typing Alt+a will select larger and +larger groups of widgets until everything is selected.

Edit/Open... (F1 or double click)

- -If the current widget is a window and it is not displayed, display it. -Otherwise open a control panel for the most recent (and possibly all) -selected widgets. - + If the current widget is a window and it is not displayed, display it. +Otherwise open a control panel for the most recent (and possibly all) +selected widgets.

Edit/Sort

- -All the selected widgets are sorted into left to right, top to bottom -order. You need to do this to make navigation keys in FLTK work -correctly. You may then fine-tune the sorting with "Earlier" and -"Later". This does not affect the positions of windows or functions. - + All the selected widgets are sorted into left to right, top to bottom +order. You need to do this to make navigation keys in FLTK work +correctly. You may then fine-tune the sorting with "Earlier" and +"Later". This does not affect the positions of windows or functions.

Edit/Earlier (F2)

- -All the selected widgets are moved one earlier in order amoung the -children of their parent (if possible). This will affect navigation -order, and if the widgets overlap it will affect how they draw, as the -later widget is drawn on top of the earlier one. You can also use -this to reorder functions and windows within functions. - + All the selected widgets are moved one earlier in order amoung the +children of their parent (if possible). This will affect navigation +order, and if the widgets overlap it will affect how they draw, as the +later widget is drawn on top of the earlier one. You can also use this +to reorder functions and windows within functions.

Edit/Later (F3)

- -All the selected widgets are moved one later in order amoung the -children of their parent (if possible). - + All the selected widgets are moved one later in order amoung the +children of their parent (if possible).

Edit/Group (F7)

- -Create a new Fl_Group and make all the currently selected widgets be -children of it. - + Create a new Fl_Group and make all the currently selected widgets be +children of it.

Edit/Ungroup (F8)

- -If all the children of a group are selected, delete that group and -make them all be children of its parent. - + If all the children of a group are selected, delete that group and +make them all be children of its parent.

Edit/Overlays on/off (Alt+o)

- -Toggle the display of the red overlays off, without changing the -selection. This makes it easier to see box borders and how the layout -looks. The overlays will be forced back on if you change the selection. - + Toggle the display of the red overlays off, without changing the +selection. This makes it easier to see box borders and how the layout +looks. The overlays will be forced back on if you change the +selection.

Edit/Preferences (Alt+p)

- -Currently the only preferences are for the "alignment grid" that all -widgets snap to when you move them and resize them, and for the "snap" -which is how far a widget has to be dragged from its original -position to actually change. - + Currently the only preferences are for the "alignment grid" that all +widgets snap to when you move them and resize them, and for the "snap" +which is how far a widget has to be dragged from its original position +to actually change.

New/code/Function

- -Create a new C function. You will be asked for a name for the -function. This name should be a legal C++ function template, without -the return type. You can pass arguments, they can be referred to by -code you type into the individual widgets. - -

If the function contains any unnamed windows, it will be declared -as returning an Fl_Window*. The unnamed window will be returned from -it (more than one unnamed window is useless). If the function -contains only named windows it will be declared as returning void. - -

It is possible to make the .cxx output be a self-contained program -that can be compiled and executed. This is done by deleting the -function name, in which case "main(argc,argv)" is used. The function -will call show() on all the windows it creates and then call -Fl::run(). This can be used to test resize behavior or other parts of -the user interface. I'm not sure if it is possible to create really -useful programs using just FLUID. - -

You can change the function name by double clicking the function. - + Create a new C function. You will be asked for a name for the +function. This name should be a legal C++ function template, without +the return type. You can pass arguments, they can be referred to by +code you type into the individual widgets. +

If the function contains any unnamed windows, it will be declared as +returning an Fl_Window*. The unnamed window will be returned from it +(more than one unnamed window is useless). If the function contains +only named windows it will be declared as returning void.

+

It is possible to make the .cxx output be a self-contained program +that can be compiled and executed. This is done by deleting the +function name, in which case "main(argc,argv)" is used. The function +will call show() on all the windows it creates and then call Fl::run(). + This can be used to test resize behavior or other parts of the user +interface. I'm not sure if it is possible to create really useful +programs using just FLUID.

+

You can change the function name by double clicking the function.

New/Window

- -Create a new Fl_Window. It is added to the currently selected -function, or to the function containing the currently selected item. -The window will appear, sized to 100x100. You will want to resize it -to whatever size you require. - -

You also get the window's control panel, which is almost exactly -the same as any other Fl_Widget, and is described in the next chapter. - + Create a new Fl_Window. It is added to the currently selected +function, or to the function containing the currently selected item. +The window will appear, sized to 100x100. You will want to resize it +to whatever size you require. +

You also get the window's control panel, which is almost exactly the +same as any other Fl_Widget, and is described in the next chapter.

New/...

- -All other items on the New menu are subclasses of Fl_Widget. Creating -them will add them to the currently selected group or window, or the -group or window containing the currently selected widget. The initial -dimensions and position are chosen by copying the current widget, if -possible. - -

When you create the widget you will get the widget's control panel, -described in the next chapter. - + All other items on the New menu are subclasses of Fl_Widget. Creating +them will add them to the currently selected group or window, or the +group or window containing the currently selected widget. The initial +dimensions and position are chosen by copying the current widget, if +possible. +

When you create the widget you will get the widget's control panel, +described in the next chapter.

Help/About FLUID

- -Pops up a panel showing the version of FLUID. - + Pops up a panel showing the version of FLUID.

Help/Manual

- -Not yet implemented. Use a HTML or PDF file viewer to read these pages -instead. - -

The Widget Panel

- - - - - - -
- -When you double-click a widget or a set of widgets you will get the -"widget attribute panel". - -

When you change attributes using this panel, the changes are -reflected immediately in the window. It is useful to hit the "no -overlay" button (or type Alt+o) to hide the red overlay so you can see -the widgets more accurately, especially when setting the box type. - -

If you have several widgets selected, they may have different -values for the fields. In this case the value for one of the -widgets is shown. But if you change this value, all the -selected widgets are changed to the new value. - -

Hitting "OK" makes the changes permanent. Selecting a different -widget also makes the changes permanent. FLUID checks for simple -syntax errors in any code (such as mismatched parenthesis) before -saving any text. - -

- -"Revert" or "Cancel" put everything back to when you last brought -up the panel or hit OK. However in the current version of FLUID, -changes to "visible" attributes (such as the color, label, box) are -not undone by revert or cancel. Changes to code like the callbacks -is undone, however. - - -

Widget Attributes

- + Not yet implemented. Use a HTML or PDF file viewer to read these +pages instead. +

The Widget Panel

+ + +
When you double-click a widget or a set of widgets you will get +the "widget attribute panel". +

When you change attributes using this panel, the changes are +reflected immediately in the window. It is useful to hit the "no +overlay" button (or type Alt+o) to hide the red overlay so you can see +the widgets more accurately, especially when setting the box type.

+

If you have several widgets selected, they may have different values +for the fields. In this case the value for one of the widgets +is shown. But if you change this value, all the selected +widgets are changed to the new value.

+

Hitting "OK" makes the changes permanent. Selecting a different +widget also makes the changes permanent. FLUID checks for simple +syntax errors in any code (such as mismatched parenthesis) before +saving any text.

+
+ "Revert" or "Cancel" put everything back to when you last brought up +the panel or hit OK. However in the current version of FLUID, changes +to "visible" attributes (such as the color, label, box) are not undone +by revert or cancel. Changes to code like the callbacks is undone, +however. +

Widget Attributes

Name (text field)

- -Name of a global C variable to declare, and to store a pointer to this -widget into. This variable will be of type "<class>*". If the name -is blank then no variable is created. - -

You can name several widgets with "name[0]", "name[1]", "name[2]", -etc. This will cause FLUID to declare an array of pointers. The -array is big enough that the highest number found can be stored. All -widgets that in the array must be the same type. - + Name of a global C variable to declare, and to store a pointer to this +widget into. This variable will be of type "<class>*". If the name is +blank then no variable is created. +

You can name several widgets with "name[0]", "name[1]", "name[2]", +etc. This will cause FLUID to declare an array of pointers. The array +is big enough that the highest number found can be stored. All widgets +that in the array must be the same type.

Type (upper-right pulldown menu)

- -Some classes have subtypes that modify their appearance or behavior. -You pick the subtype off of this menu. - + Some classes have subtypes that modify their appearance or behavior. +You pick the subtype off of this menu.

Box (pulldown menu)

- -The boxtype to draw as a background for the widget. - -

Many widgets will work, and draw faster, with a "frame" instead of -a "box". A frame does not draw the colored interior, leaving whatever -was already there visible. Be careful, as FLUID may draw this ok but -the real program leave unwanted stuff inside the widget. - -

If a window is filled with child widgets, you can speed up -redrawing by changing the window's box type to "NO_BOX". FLUID will -display a checkerboard for any areas that are not colored in by boxes -(notice that this checkerboard is not drawn by the resulting program, -instead random garbage is left there). - + The boxtype to draw as a background for the widget. +

Many widgets will work, and draw faster, with a "frame" instead of a +"box". A frame does not draw the colored interior, leaving whatever +was already there visible. Be careful, as FLUID may draw this ok but +the real program leave unwanted stuff inside the widget.

+

If a window is filled with child widgets, you can speed up redrawing +by changing the window's box type to "NO_BOX". FLUID will display a +checkerboard for any areas that are not colored in by boxes (notice +that this checkerboard is not drawn by the resulting program, instead +random garbage is left there).

Color

- -

The color to draw the box with. - +

The color to draw the box with.

Color2

- -

Some widgets will use this color for certain parts. FLUID does not -always show the result of this: this is the color buttons draw in when -pushed down, and the color of input fields when they have the focus. - +

Some widgets will use this color for certain parts. FLUID does not +always show the result of this: this is the color buttons draw in when +pushed down, and the color of input fields when they have the focus.

Label

- -String to print next to or inside the button. - -

You can put newlines into the string to make multiple lines, the -easiest way is by typing ctrl+j. - + String to print next to or inside the button. +

You can put newlines into the string to make multiple lines, the +easiest way is by typing ctrl+j.

Label style (pull down menu)

- -How to draw the label. Normal, shadowned, engraved, and embossed -change the appearance of the text. "symbol" requires the label to -start with an '@' sign to draw a named symbol. - -

From this menu you can also pick "Image...". This lets you use the contents -of an image file (currently an xpm pixmap or xbm bitmap) to label the -widget. - + How to draw the label. Normal, shadowned, engraved, and embossed +change the appearance of the text. "symbol" requires the label to +start with an '@' sign to draw a named +symbol. +

From this menu you can also pick +"Image...". This lets you use the contents of an image file +(currently an xpm pixmap or xbm bitmap) to label the widget.

Label alignement (buttons)

- -Where to draw the label. The arrows put it on that side of the -widget, you can combine the to put it in the corner. The "box" button -puts the label inside the widget, rather than outside. - + Where to draw the label. The arrows put it on that side of the +widget, you can combine the to put it in the corner. The "box" button +puts the label inside the widget, rather than outside.

Label font

- -Font to draw the label in. Ignored by symbols, bitmaps, and pixmaps. -Your program can change the actual font used by these "slots", in case -you want some font other than the 16 provided. - + Font to draw the label in. Ignored by symbols, bitmaps, and pixmaps. +Your program can change the actual font used by these "slots", in case +you want some font other than the 16 provided.

Label size

- -Point size for the font to draw the label in. Ignored by symbols, -bitmaps, and pixmaps. To see the result without dismissing the panel, -type the new number and then Tab. - + Point size for the font to draw the label in. Ignored by symbols, +bitmaps, and pixmaps. To see the result without dismissing the panel, +type the new number and then Tab.

Label color

- -Color to draw the label. Ignored by pixmaps (bitmaps, however, do use -this color as the foreground color). - + Color to draw the label. Ignored by pixmaps (bitmaps, however, do use +this color as the foreground color).

Text font, size, color

- -Some widgets display text, such as input fields, pull-down menus, -browsers. You can change this here. - + Some widgets display text, such as input fields, pull-down menus, +browsers. You can change this here.

Visible

- -If you turn this off the widget is hidden initially. Don't change -this for windows or for the immediate children of a Tabs group. - + If you turn this off the widget is hidden initially. Don't change +this for windows or for the immediate children of a Tabs group.

Active

- -If you turn this off the widget is deactivated initially. Currently -no FLTK widgets display the fact that they are inactive (like by graying -out), but this may change in the future. - + If you turn this off the widget is deactivated initially. Currently +no FLTK widgets display the fact that they are inactive (like by +graying out), but this may change in the future.

Resizable

- -If a window is resizable or has an immediate child that is resizable, -then the user will be able to resize it. In addition all the size -changes of a window or group will go "into" the resizable child. If -you have a large data display surrounded by buttons, you probably want -that data area to be resizable. - -

Only one child can be resizable. Turning this on turns it off for -other children. - -

You can get more complex behavior by making invisible boxes the -resizable widget, or by using hierarchies of groups. Unfortunatley -the only way to test it is to compile the program. Resizing the FLUID -window is not the same as what will happen in the user program. - + If a window is resizable or has an immediate child that is resizable, +then the user will be able to resize it. In addition all the size +changes of a window or group will go "into" the resizable child. If +you have a large data display surrounded by buttons, you probably want +that data area to be resizable. +

Only one child can be resizable. Turning this on turns it off for +other children.

+

You can get more complex behavior by making invisible boxes the +resizable widget, or by using hierarchies of groups. Unfortunatley the +only way to test it is to compile the program. Resizing the FLUID +window is not the same as what will happen in the user program.

Hotspot

- -Each window may have exactly one hotspot (turning this on will turn -off any others). This will cause it to be positioned with that widget -centered on the mouse. This position is determined when the FLUID -function is called, so you should call it immediately before showing -the window. If you want the window to hide and then reappear at a -new position, you should have your program set the hotspot itself just -before show(). - + Each window may have exactly one hotspot (turning this on will turn +off any others). This will cause it to be positioned with that widget +centered on the mouse. This position is determined when the FLUID +function is called, so you should call it immediately before showing +the window. If you want the window to hide and then reappear at a +new position, you should have your program set the hotspot itself just +before show().

subclass

- -This is how you put your own subclasses of Fl_Widget in. Whatever -identifier you type in here will be the class that is instantiated. - -

In addition, no #include header file is put in the .h file. You -must provide a #include line as the first of the "extra code" which -declares your subclass. - -

The class had better be similar to the class you are spoofing. It -does not have to be a subclass. It is sometimes useful to change this -to another FLTK class: currently the only way to get a double-buffered -window is to change this field for the window to "Fl_Double_Window" -and to add "#include <FL/Fl_Double_Window.h>" to the extra code. - + This is how you put your own subclasses of Fl_Widget in. Whatever +identifier you type in here will be the class that is instantiated. +

In addition, no #include header file is put in the .h file. You +must provide a #include line as the first of the "extrawhich declares +your subclass.

+

The class had better be similar to the class you are spoofing. It +does not have to be a subclass. It is sometimes useful to change this +to another FLTK class: currently the only way to get a double-buffered +window is to change this field for the window to "Fl_Double_Window" and +to add "#include <FL/Fl_Double_Window.h>" to the extra code.

Extra code

- -These four fields let you type in literal lines of code to dump into -the .h or .cxx files. - -

If the text starts with a '#' or the word "extern" then FLUID -thinks this is an "include" line, and it is written to the .h file. -If the same include line occurs several times then only one copy is -written. - -

All other lines are "code" lines. The widget being constructed is -pointed to by the local variable 'o'. The window being constructed is -pointed to by the local variable 'w'. You can also access any -arguments passed to the function here, and any named widgets that are -before this one. - -

FLUID will check for matching parenthesis, braces, and quotes, but -does not do much other error checking. Be careful here, as it may be -hard to figure out what widget is producing an error in the compiler. -If you need more than 4 lines you probably should call a function in -your own .cxx code. - + These four fields let you type in literal lines of code to dump into +the .h or .cxx files. +

If the text starts with a '#' or the word "extern" then FLUID thinks +this is an "include" line, and it is written to the .h file. If the +same include line occurs several times then only one copy is written.

+

All other lines are "code" lines. The widget being constructed is +pointed to by the local variable 'o'. The window being constructed is +pointed to by the local variable 'w'. You can also access any +arguments passed to the function here, and any named widgets that are +before this one.

+

FLUID will check for matching parenthesis, braces, and quotes, but +does not do much other error checking. Be careful here, as it may be +hard to figure out what widget is producing an error in the compiler. +If you need more than 4 lines you probably should call a function in +your own .cxx code.

Callback

- -This can either be the name of a function, or a small snippet of -code. FLUID thinks that if there is any punctuation then it is code. - -

A name names a function in your own code. It must be declared as -"void <name>(<class>*,void*)". - -

A code snippet is inserted into a static function in the .cxx output -file. The function prototype is -"void f(<class>* o, void* v)", so you can refer to -the widget as 'o' and the user_data as 'v'. FLUID will check for -matching parenthesis, braces, and quotes, but does not do much other -error checking. Be careful here, as it may be hard to figure out what -widget is producing an error in the compiler. - -

If the callback is blank then no callback is set. - + This can either be the name of a function, or a small snippet of code. + FLUID thinks that if there is any punctuation then it is code. +

A name names a function in your own code. It must be declared as +"voidname>(<class>*,void*)".

+

A code snippet is inserted into a static function in the .cxx output +file. The function prototype is "voidclass>*so you can refer to the +widget as 'o' and the user_data as 'v'. FLUID will check for matching +parenthesis, braces, and quotes, but does not do much other error +checking. Be careful here, as it may be hard to figure out what widget +is producing an error in the compiler.

+

If the callback is blank then no callback is set.

user_data

- -

This is a value for the user_data() of the widget. If blank the -default value of zero is used. This can be any piece of C code that -can be put "(void*)(<here>)". - +

This is a value for the user_data() of the widget. If blank the +default value of zero is used. This can be any piece of C code that +can be put "(void*)(<here>)".

User data type

- -The "void*" in the callback function prototypes is replaced with -this. You may want to use "long" for old XForms code. Be warned that -anything other than "void*" is not guaranteed to work by the C++ spec! -However on most architectures other pointer types are ok, and long is -usually ok. - + The "void*" in the callback function prototypes is replaced with this. + You may want to use "long" for old XForms code. Be warned that +anything other than "void*" is not guaranteed to work by the C++ spec! +However on most architectures other pointer types are ok, and long is +usually ok.

When

- -When to do the callback. Can be "never", "changed", "release". The -value of "enter key" is only useful for text input fields. The "no -change" button means the callback is done on the matching event even -if the data is not changed. - -

There are rare but useful other values for the when() field that -are not in the menu. You should use the extra code fields to put -these values in. - - -

Selecting & Moving Widgets

- -

Double-clicking a window name in the browser will display it, if -not displayed yet. From this display you can select widgets, sets of -widgets, and move or resize them. To close a window either -double-click it or type Esc. - -

To select a widget, click it. To select several widgets drag a -rectangle around them. Holding down shift will toggle the selection -of the widgets instead. - -

You cannot pick hidden widgets. You also cannot choose some -widgets if they are completely overlapped by later widgets. Use the -browser to select these widgets. - -

The selected widgets are shown with a red "overlay" line around -them. You can move the widgets by dragging this box. Or you can -resize them by dragging the outer edges and corners. Hold down the -Alt key while dragging the mouse to defeat the snap-to-grid effect for -fine positioning. - -

If there is a tab box displayed you can change which child is -visible by clicking on the file tabs. The child you pick is -selected. - -

The arrow, tab, and shift+tab keys "navigate" the selection. Left, -right, tab, or shift+tab move to the next or previous widgets in the -hierarchy. Hit the right arrow enough and you will select every -widget in the window. Up/down widgets move to the previous/next -widgets that overlap horizontally. If the navigation does not seem to -work you probably need to "Sort" the widgets. This is important if -you have input fields, as FLTK uses the same rules when using arrow keys -to move between input fields. - -

To "open" a widget, double click it. To open several widgets -select them and then type F1 or pick "Edit/Open" off the pop-up menu. - -

Type Alt+o to temporarily toggle the overlay off without changing -the selection, so you can see the widget borders. - -

You can resize the window by using the window manager border -controls. FLTK will attempt to round the window size to the nearest -multiple of the grid size and makes it big enough to contain all the -widgets (it does this using illegal X methods, so it is possible it -will barf with some window managers!). Notice that the actual window -in your program may not be resizable, and if it is, the effect on -child widgets may be different. - -

The panel for the window (which you get by double-clicking it) is -almost identical to the panel for any other Fl_Widget. There are -three extra items: - + When to do the callback. Can be "never", "changed", "release". The +value of "enter key" is only useful for text input fields. The "no +change" button means the callback is done on the matching event even if +the data is not changed. +

There are rare but useful other values for the when() field that are +not in the menu. You should use the extra code fields to put these +values in.

+

Selecting Moving Widgets

+

Double-clicking a window name in the browser will display it, if not +displayed yet. From this display you can select widgets, sets of +widgets, and move or resize them. To close a window either +double-click it or type Esc.

+

To select a widget, click it. To select several widgets drag a +rectangle around them. Holding down shift will toggle the selection of +the widgets instead.

+

You cannot pick hidden widgets. You also cannot choose some widgets +if they are completely overlapped by later widgets. Use the browser to +select these widgets.

+

The selected widgets are shown with a red "overlay" line around +them. You can move the widgets by dragging this box. Or you can +resize them by dragging the outer edges and corners. Hold down the Alt +key while dragging the mouse to defeat the snap-to-grid effect for fine +positioning.

+

If there is a tab box displayed you can change which child is +visible by clicking on the file tabs. The child you pick is selected.

+

The arrow, tab, and shift+tab keys "navigate" the selection. Left, +right, tab, or shift+tab move to the next or previous widgets in the +hierarchy. Hit the right arrow enough and you will select every widget +in the window. Up/down widgets move to the previous/next widgets that +overlap horizontally. If the navigation does not seem to work you +probably need to "Sort" the widgets. This is important if you have +input fields, as FLTK uses the same rules when using arrow keys to move +between input fields.

+

To "open" a widget, double click it. To open several widgets select +them and then type F1 or pick "Edit/Open" off the pop-up menu.

+

Type Alt+o to temporarily toggle the overlay off without changing +the selection, so you can see the widget borders.

+

You can resize the window by using the window manager border +controls. FLTK will attempt to round the window size to the nearest +multiple of the grid size and makes it big enough to contain all the +widgets (it does this using illegal X methods, so it is possible it +will barf with some window managers!). Notice that the actual window +in your program may not be resizable, and if it is, the effect on child +widgets may be different.

+

The panel for the window (which you get by double-clicking it) is +almost identical to the panel for any other Fl_Widget. There are three +extra items:

Border

- -This button turns the window manager border on or off. On most window -managers you will have to close the window and reopen it to see the -effect. - + This button turns the window manager border on or off. On most window +managers you will have to close the window and reopen it to see the +effect.

xclass

- -The string typed into here is passed to the X window manager as the -class. This can change the icon or window decorations. On most -(all?) window managers you will have to close the window and reopen it -to see the effect. - - -

Image Labels

- -

Selecting "Image..." off the label style pull-down menu will bring -up a file chooser from which you pick the image file. If an image has -already been chosen, you can change the image used by picking -"Image..." again. The name of the image will appear in the "label" -field, but you can't edit it. - -

The contents of the image file are written to the .cxx file, -so if you wish to distribute the C code, you only need to copy the .cxx -file, not the images. If many widgets share the same image then only -one copy is written. - -

However the file name is stored in the .fl file, so to read -the .fl file you need the image files as well. Filenames are relative -to the location the .fl file is (not necessarily the current -directory). I recommend you either put the images in the same -directory as the .fl file, or use absolute path names. - + The string typed into here is passed to the X window manager as the +class. This can change the icon or window decorations. On most (all?) +window managers you will have to close the window and reopen it to see +the effect. +

Image Labels

+

Selecting "Image..." off the label style pull-down menu will bring +up a file chooser from which you pick the image file. If an image has +already been chosen, you can change the image used by picking +"Image..." again. The name of the image will appear in the "label" +field, but you can't edit it.

+

The contents of the image file are written to the .cxx file, +so if you wish to distribute the C code, you only need to copy the .cxx +file, not the images. If many widgets share the same image then only +one copy is written.

+

However the file name is stored in the .fl file, so to read +the .fl file you need the image files as well. Filenames are relative +to the location the .fl file is (not necessarily the current +directory). I recommend you either put the images in the same +directory as the .fl file, or use absolute path names.

Notes for all image types

- -

FLUID runs using the default visual of your X server. This may be -8 bits, which will give you dithered images. You may get better -results in your actual program by adding the code "Fl::visual(FL_RGB)" -to your code right before the first window is displayed. - -

All widgets with the same image on them share the same code and -source X pixmap. Thus once you have put an image on a widget, it is -nearly free to put the same image on many other widgets. - -

If you are using a painting program to edit an image: the only way -to convince FLUID to read the image file again is to remove the image -from all widgets that are using it (including ones in closed windows), -which will cause it to free its internal copy, and then set the image -again. You may find it easier to exit FLUID and run it again. - -

Don't rely on how FLTK crops images that are outside the widget, as -this may change in future versions! The cropping of inside labels -will probably be unchanged. - -

To more accurately place images, make a new "box" widget and put -the image in that as the label. This is also how you can put both an -image and text label on the same widget. If your widget is a button, -and you want the image inside it, you must change the button's boxtype -to FL_UP_FRAME (or another frame), otherwise when it is pushed it will -erase the image. - +

FLUID runs using the default visual of your X server. This may be 8 +bits, which will give you dithered images. You may get better results +in your actual program by adding the code "Fl::visual(FL_RGB)" to your +code right before the first window is displayed.

+

All widgets with the same image on them share the same code and +source X pixmap. Thus once you have put an image on a widget, it is +nearly free to put the same image on many other widgets.

+

If you are using a painting program to edit an image: the only way +to convince FLUID to read the image file again is to remove the image +from all widgets that are using it (including ones in closed windows), +which will cause it to free its internal copy, and then set the image +again. You may find it easier to exit FLUID and run it again.

+

Don't rely on how FLTK crops images that are outside the widget, as +this may change in future versions! The cropping of inside labels will +probably be unchanged.

+

To more accurately place images, make a new "box" widget and put the +image in that as the label. This is also how you can put both an image +and text label on the same widget. If your widget is a button, and you +want the image inside it, you must change the button's boxtype to +FL_UP_FRAME (or another frame), otherwise when it is pushed it will +erase the image.

XBM (X bitmap files)

- -

FLUID will read X bitmap files. These files have C source code to -define a bitmap. Sometimes they are stored with the ".h" or ".bm" -extension rather than the standard ".xbm". - -

FLUID will output code to construct an Fl_Bitmap widget and use it -to label the widget. The '1' bits in the bitmap are drawn using the -label color of the widget. You can change the color in FLUID. The -'0' bits are transparent. - -

The program "bitmap" on the X distribution does an ok job of -editing bitmaps. - +

FLUID will read X bitmap files. These files have C source code to +define a bitmap. Sometimes they are stored with the ".h" or ".bm" +extension rather than the standard ".xbm".

+

FLUID will output code to construct an Fl_Bitmap widget and use it +to label the widget. The '1' bits in the bitmap are drawn using the +label color of the widget. You can change the color in FLUID. The '0' +bits are transparent.

+

The program "bitmap" on the X distribution does an ok job of editing +bitmaps.

XPM (X pixmap files)

- -

FLUID will read X pixmap files as used by the libxpm library. -These files have C source code to define a pixmap. The filenames -usually have a ".xpm" extension. - -

FLUID will output code to construct an Fl_Pixmap widget and use it -to label the widget. The label color of the widget is ignored, even -for 2-color images that could be a bitmap. - -

XPM files can mark a single color as being transparent. Currently -FLTK and FLUID simulate this transparency rather badly. It will use the -color() of the widget as the background, and all widgets using the -same pixmap are assummed to have the same color. This may be fixed in -the future or on non-X systems. - -

I have not found any good editors for small iconic pictures. For -pixmaps I have used XPaint. This -(and most other) painting programs are designed for large full color -images and are difficult to use to edit an image of small size and few -colors. - +

FLUID will read X pixmap files as used by the libxpm library. These +files have C source code to define a pixmap. The filenames usually +have a ".xpm" extension.

+

FLUID will output code to construct an Fl_Pixmap widget and use it +to label the widget. The label color of the widget is ignored, even +for 2-color images that could be a bitmap.

+

XPM files can mark a single color as being transparent. Currently +FLTK and FLUID simulate this transparency rather badly. It will use +the color() of the widget as the background, and all widgets using the +same pixmap are assummed to have the same color. This may be fixed in +the future or on non-X systems.

+

I have not found any good editors for small iconic pictures. For +pixmaps I have used +XPaint. This (and most other) painting programs are designed for +large full color images and are difficult to use to edit an image of +small size and few colors.

GIF files

- -

FLUID will also read GIF image files. These files are often used -on html documents to make icons. This lets you use nice icons that -you steal off the net in your user interface. - -

FLUID converts these into (modified) XPM format and uses an -Fl_Pixmap widget to label the widget. Transparency is handled the same -as for xpm files. Notice that the conversion removes the compression, -so the code may be much bigger than the .gif file. Only the first -image of an animated gif file is used. - -

Behavior and performance with large .gif files is not guaranteed! - - - +

FLUID will also read GIF image files. These files are often used on +html documents to make icons. This lets you use nice icons that you +steal off the net in your user interface.

+

FLUID converts these into (modified) XPM format and uses an +Fl_Pixmap widget to label the widget. Transparency is handled the same +as for xpm files. Notice that the conversion removes the compression, +so the code may be much bigger than the .gif file. Only the first +image of an animated gif file is used.

+

Behavior and performance with large .gif files is not guaranteed!

+ \ No newline at end of file -- cgit v1.2.3