6 - Programming with FLUID

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.C" and "more test.H" and you can see the code it made. Also try "more test.fl" to see how fluid saves it's 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

Type

	fluid <name>.fl &

to edit the .fl file <name>.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 setup 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:

	 -display host:n.n
	 -geometry WxH+X+Y
	 -title windowtitle
	 -name classname
	 -iconic
	 -fg color
	 -bg color
	 -bg2 color

Changing the colors may be useful to see what your interface will look at if the user calls it with the same switches.

Fluid can also be called as a command-line "compiler" to create the .C and .H file from a .fl file. To do this type

	fluid -c <name>.fl

This will read the .fl file and write <name>.C and <name>.H (the directory will be stripped, they are written to the current directory always), and then exit. If there are any errors reading or writing the files it will print the error and exit with a non-zero code. This is useful in a makefile. A line like this will work:

my_panels.H my_panels.C : my_panels.fl
	fluid -c my_panels.fl

Some versions of Make will accept rules like this to allow all .fl files found to be compiled:

.SUFFIXES : .fl .C .H
.fl.H :
	fluid -c $<
.fl.C :
	fluid -c $<

Some versions of Make (gnumake) may prefer this syntax:

%.H: %.fl
        fluid -c $<

%.C: %.fl
        fluid -c $<

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 it's 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 .C file. Calling the function will create all of it's 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.

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 it's 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.

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

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.

File/Write code (Alt+Shift+C)

"Compiles" the data into a .C 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 ".C" 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.

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.

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.

Edit/Copy (Alt+c)

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.

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.

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.

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.

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.

Edit/Later (F3)

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.

Edit/Ungroup (F8)

If all the children of a group are selected, delete that group and make them all be children of it's 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.

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 it's 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 .C 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.

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.

Help/About fluid

Pops up a panel showing the version of fluid.

Help/Manual

Not yet implemented. Use netscape to read these pages instead.

The Widget 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.

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.

Type (upper-right pulldown 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).

Color

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.

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.

Label style (pull down menu)

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.

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 .C file, so if you wish to distribute the C code, you only need to copy the .C 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 it's 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.

XPM (X pixmap files)