What is Fluid?

Fluid (the FL User Interface Designer) is a graphical editor that is used to produce FL source code.

Fluid edits and saves it's state in ".fl" files. These files are text, and you could (with care) edit them in a text editor, perhaps to get some special effects.

When asked to "compile", fluid outputs a .C source file and a .H header file: The .C file contains one or more public functions, each of which will create one or more FL windows and all the objects in those windows. The .H file declares (as externs) all the functions and named objects created by the .C file, and includes all the necessary FL header files for those objects.

The C file must be compiled and linked with a "main" source file(s) that you write. This source code must include the .H output, and should call the functions in the .C file to create windows. The main code must do show() on the windows and run the Fl::wait() loop.

It is also possible to "#include" the C file directly into your main program, this is convienent if your program has only one source file because a default Make rule will work for it. It is also possible to make fluid output a main() function so the C file may be compiled by itself, this is mostly useful for testing.

                               _________
                              /        /
    __________            +->/.C file /--------+
   /         /           /  /________/         |
  /.fl file /<==>[fluid]<     #include         |
 /_________/             \     ___v_____       |
                          \   /        /       |
                           +>/.H file /        |
                            /________/         |
                                  ^            |
                              #include         |
                               ___|_____       |          __________
                              /        /       V         /         /
                             / main.C /--->[c++,link]-->/ program /
                            /________/                 /_________/

Objects created by fluid are either "named" or "unnamed". If they are named, the .C file will declare a global variable with that name of type "<type>*". This pointer has a value of zero until the fluid function is called, the fluid function will set it to the instance of the . Unnamed objects are only accessible through pointers from other objects.

Windows may be named or unnamed. Named windows are only created once even if you call the function several times (fluid outputs "if (!name) {...}" around the code that creates the window). Unnamed windows lets you create many instances of the same window structure, a pointer to the unnamed window is returned from the fluid function (you can only put one unnamed window in a function).

Objects 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 .C file.

Worlds shortest tutorial

  1. Type "fluid&"
  2. Pick "New/Function" off the menu.
  3. Delete the function name in the popup window 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/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 object by dragging the edges and corners.
  10. Type Alt+c to copy the object.
  11. Type Alt+v to paste a copy into the window.
  12. Type Alt+v several times.
  13. Drag the objects and resize them so they don't overlap. Notice that you have to click an object to pick it first, then drag it.
  14. Try selecting several objects 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 objects on and off.
  16. You can also select objects by clicking on them in the list in the main window, try that.
  17. Double-click one of the buttons. 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.
  25. Go back to your terminal window. Type "more test.C" and "more test.H" and you can see the code it made.
  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 FL 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.

In the current version, if you don't go into the background (with '&') then you will be able to abort fluid by typing ^C on the terminal. It will exit immediately, losing any changes.

Compiling .fl files

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:

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

The Object Browser

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

The objects are stored in a hierarchy. You can open and close a level by clicking the "triangle" at the left of an object. This object is the parent, and all the objects 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 objects (subclasses of Fl_Object) or groups of objects (including other groups). Plain groups are for layout, navigation, and resize purposes. Tab groups provide the well-known file-card tab interface.

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

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

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)

File/Save (Alt+s)

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

File/Merge... (Alt+i)

File/Write code (Alt+Shift+C)

File/Quit (Alt+q)

Edit/Undo (Alt+z)

Edit/Cut (Alt+x)

Edit/Copy (Alt+c)

Edit/Paste (Alt+c)

Edit/Select All (Alt+a)

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

Edit/Sort

Edit/Earlier (F2)

Edit/Later (F3)

Edit/Group (F7)

Edit/Ungroup (F8)

Edit/Overlays on/off (Alt+o)

Edit/Preferences (Alt+p)

New/Function

New/Window

New/...

Help/About fluid

Help/Manual

The Object Panel

When you double-click an object or a set of objects you will get the "object attribute panel":

When you change "visible" attributes (such as the box or label) 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 objects more accurately. Unfortunatly in the current version of fluid "revert" and "cancel" do not work for these visible attributes.

Attributes that don't have a visible effect (such as the callback) do not change until you hit the OK button. "Revert" or "cancel" will work to get the old values back.

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

It is possible to change the set of selected objects while the panel is up. This is extrememly convienent for comparing objects. Be warned, however, that doing so will in effect do a "revert" to the old set of objects. You will lose any editing you have made to the callbacks or code! You should always hit "OK" after editing any invisible attributes!

Object Attributes

Name (text field)

Type (upper-right pulldown menu)

Box (pulldown menu)

Color

Color2

Label

Label style (pull down menu)

Label alignement (buttons)

Label font

Label size

Label color

Text font, size, color

Visible

Active

Resizable

Hotspot

subclass

Extra code

Callback

user_data

User data type

When

Selecting & Moving Objects

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

To select an object, click it. To select several objects drag a rectangle around them. Holding down shift will toggle the selection of the objects instead.

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

The selected objects are shown with a red "overlay" line around them. You can move the objects 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 objects in the hierarchy. Hit the right arrow enough and you will select every object in the window. Up/down objects move to the previous/next objects that overlap horizontally. If the navigation does not seem to work you probably need to "Sort" the objects. This is important if you have input fields, as FL uses the same rules when using arrow keys to move between input fields.

To "open" an object, double click it. To open several objects 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 object borders.

You can resize the window by using the window manager border controls. FL will attempt to round the window size to the nearest multiple of the grid size and makes it big enough to contain all the objects (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 objects 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_Object. There are three extra items:

Border

Modal

xclass

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

XBM (X bitmap files)

XPM (X pixmap files)

GIF files

(back to contents)