895 lines
32 KiB
HTML
895 lines
32 KiB
HTML
|
<HTML>
|
||
|
|
<BODY>
|
||
|
|
|
||
|
|
<H1 ALIGN=RIGHT><A NAME="fluid">6 - Programming with FLUID</A></H1>
|
||
|
|
|
||
|
|
This chapter shows how to use the Fast Light User-Interface Designer ("FLUID") to create
|
||
|
|
your GUIs.
|
||
|
|
|
||
|
|
<H2>What is FLUID?</H2>
|
||
|
|
|
||
|
|
<H2>Creating A Simple Program</H2>
|
||
|
|
|
||
|
|
<H2>Functions</H2>
|
||
|
|
|
||
|
|
<H2>Windows</H2>
|
||
|
|
|
||
|
|
<H2>Groups</H2>
|
||
|
|
|
||
|
|
<H2>Tabs</H2>
|
||
|
|
|
||
|
|
<H2>Menus</H2>
|
||
|
|
|
||
|
|
<H2>Using Custom Widgets</H2>
|
||
|
|
|
||
|
|
<H2>Classes</H2>
|
||
|
|
|
||
|
|
</BODY>
|
||
|
|
</HTML>
|
||
|
|
<title>fluid Reference Manual</title>
|
||
|
|
|
||
|
|
<center><img src=fluid.gif></center>
|
||
|
|
|
||
|
|
<h2>What is Fluid?</h2>
|
||
|
|
|
||
|
|
<p>Fluid (the Fast Light User Interface Designer) is a graphical
|
||
|
|
editor that is used to produce fltk source code.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>Fluid can "compile" the .fl file into a .C and a .H file. The .C
|
||
|
|
file defines all the objects from the .fl file and the .H file
|
||
|
|
declares all the global ones.
|
||
|
|
|
||
|
|
<p>A simple program can be made by putting all your code (including a
|
||
|
|
main() function) into the .fl file and thus making the .C file a
|
||
|
|
single source file to compile. Normally though you write other .C
|
||
|
|
files that call the fluid functions. These .C files must #include the
|
||
|
|
.H file output (or they can #include the .C file so it still appears
|
||
|
|
to make to be a single source file).
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
_________
|
||
|
|
/ /
|
||
|
|
__________ +->/.C file /--------+
|
||
|
|
/ / / /________/ |
|
||
|
|
/.fl file /<==>[fluid]< #include |
|
||
|
|
/_________/ \ ___v_____ |
|
||
|
|
\ / / |
|
||
|
|
+>/.H file / |
|
||
|
|
/________/ |
|
||
|
|
^ |
|
||
|
|
#include |
|
||
|
|
___|_____ | __________
|
||
|
|
/ / V / /
|
||
|
|
/ main.C /--->[c++,link]-->/ program /
|
||
|
|
/________/ /_________/
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>Widgets created by fluid are either "named", "complex named" or
|
||
|
|
"unnamed". A named widget has a legal C++ variable identifier as it's
|
||
|
|
name (ie only alphanumeric and underscore). In this case fluid
|
||
|
|
defines a global variable 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 it's 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.
|
||
|
|
|
||
|
|
<p>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 .C file.
|
||
|
|
|
||
|
|
<a name=tutorial>
|
||
|
|
<h2>Worlds shortest tutorial</h2>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
|
||
|
|
<li>Type "fluid&"
|
||
|
|
|
||
|
|
<li>Pick "New/code/function" off the menu.
|
||
|
|
|
||
|
|
<li>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.
|
||
|
|
|
||
|
|
<li>Pick "New/group/Window" off the menu.
|
||
|
|
|
||
|
|
<li>Move the new window and resize it to the size you want.
|
||
|
|
|
||
|
|
<li>Pick "New/buttons/Button" off the menu.
|
||
|
|
|
||
|
|
<li>Hit the "OK" button to dismiss the panel that appears.
|
||
|
|
|
||
|
|
<li>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.
|
||
|
|
|
||
|
|
<li>Try resizing the widget by dragging the edges and corners.
|
||
|
|
|
||
|
|
<li>Type Alt+c to copy the widget.
|
||
|
|
|
||
|
|
<li>Type Alt+v to paste a copy into the window.
|
||
|
|
|
||
|
|
<li>Type Alt+v several times.
|
||
|
|
|
||
|
|
<li>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.
|
||
|
|
|
||
|
|
<li>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.
|
||
|
|
|
||
|
|
<li>You can also use Shift+click to toggle widgets on and off.
|
||
|
|
|
||
|
|
<li>You can also select widgets by clicking on them in the list in the
|
||
|
|
main window, try that.
|
||
|
|
|
||
|
|
<li>Double-click one of the widgets. You will get a control panel.
|
||
|
|
|
||
|
|
<li>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.
|
||
|
|
|
||
|
|
<li>Type "#include <stdlib.h>" into the first line of "extra code:".
|
||
|
|
|
||
|
|
<li>Type "exit(0);" into the "callback:".
|
||
|
|
|
||
|
|
<li>Hit OK.
|
||
|
|
|
||
|
|
<li>Pick "File/Save As" off the menu.
|
||
|
|
|
||
|
|
<li>Type "test.fl" into the file chooser and hit return.
|
||
|
|
|
||
|
|
<li>Pick "File/Write Code" off the menu, hit OK on the confirmation panel.
|
||
|
|
|
||
|
|
<li>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.
|
||
|
|
|
||
|
|
<li>Type "make test" (you may have to add libaries to your Makefile).
|
||
|
|
|
||
|
|
<li>Type "./test" to run your program.
|
||
|
|
|
||
|
|
<li>Try the buttons. The one you put the code into will exit the
|
||
|
|
program.
|
||
|
|
|
||
|
|
<li>Type "Alt+Q" to exit fluid.
|
||
|
|
|
||
|
|
<li>Ok, now try to make a real program.
|
||
|
|
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<a name=running>
|
||
|
|
<h2>Running fluid</h2>
|
||
|
|
|
||
|
|
<p>Type
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
fluid <name>.fl &
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>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).
|
||
|
|
|
||
|
|
<p>You can provide any of the standard fltk switches before the name:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
-display host:n.n
|
||
|
|
-geometry WxH+X+Y
|
||
|
|
-title windowtitle
|
||
|
|
-name classname
|
||
|
|
-iconic
|
||
|
|
-fg color
|
||
|
|
-bg color
|
||
|
|
-bg2 color
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>Changing the colors may be useful to see what your interface will
|
||
|
|
look at if the user calls it with the same switches.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<a name=compiling>
|
||
|
|
<h2>Compiling .fl files</h2>
|
||
|
|
|
||
|
|
<p>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
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
fluid -c <name>.fl
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>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:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
my_panels.H my_panels.C : my_panels.fl
|
||
|
|
fluid -c my_panels.fl
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>Some versions of Make will accept rules like this to allow all .fl
|
||
|
|
files found to be compiled:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
.SUFFIXES : .fl .C .H
|
||
|
|
.fl.H :
|
||
|
|
fluid -c $<
|
||
|
|
.fl.C :
|
||
|
|
fluid -c $<
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>Some versions of Make (gnumake) may prefer this syntax:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
%.H: %.fl
|
||
|
|
fluid -c $<
|
||
|
|
|
||
|
|
%.C: %.fl
|
||
|
|
fluid -c $<
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<a name=browser>
|
||
|
|
<h2>The Widget Browser</h2>
|
||
|
|
|
||
|
|
<p><img src=fluid_main.gif align = left>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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 <i>parent</i>, and all the widgets listed below it are it's
|
||
|
|
<i>children</i>. There can be zero children.
|
||
|
|
|
||
|
|
<p>The top level of the hierarchy is <i>functions</i>. 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.
|
||
|
|
|
||
|
|
<p>The second level of the hierarchy is <i>windows</i>. Each of these
|
||
|
|
produces an instance of class Fl_Window.
|
||
|
|
|
||
|
|
<p>Below that are either <i>widgets</i> (subclasses of Fl_Widget) or
|
||
|
|
<i>groups</i> of widgets (including other groups). Plain groups are
|
||
|
|
for layout, navigation, and resize purposes. <i>Tab groups</i>
|
||
|
|
provide the well-known file-card tab interface.
|
||
|
|
|
||
|
|
<p>Widgets are shown in the browser as either their <i>name</i> (such
|
||
|
|
as "main_panel" in the example), or if <i>unnamed</i> as their
|
||
|
|
<i>type</i> and <i>label</i> (such as "Button "the green"").
|
||
|
|
|
||
|
|
<p>You <i>select</i> 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.
|
||
|
|
|
||
|
|
<p>You <i>open</i> 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.
|
||
|
|
|
||
|
|
<a name=menu>
|
||
|
|
<h2>Menu Items</h2>
|
||
|
|
|
||
|
|
<p>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:
|
||
|
|
|
||
|
|
</ul><h4>File/Open... (Alt+Shift+O)</h4><ul>
|
||
|
|
|
||
|
|
Discard the current editing session and read in a different .fl file.
|
||
|
|
You are asked for confirmation if you have changed the current data.
|
||
|
|
|
||
|
|
<p>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!
|
||
|
|
|
||
|
|
</ul><h4>File/Save (Alt+s)</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>File/Save As...(Alt+Shift+S)</h4><ul>
|
||
|
|
|
||
|
|
Ask for a new name to save the file as, and save it.
|
||
|
|
|
||
|
|
</ul><h4>File/Merge... (Alt+i)</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>File/Write code (Alt+Shift+C)</h4><ul>
|
||
|
|
|
||
|
|
"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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
</ul><h4>File/Quit (Alt+q)</h4><ul>
|
||
|
|
|
||
|
|
Exit fluid. You are asked for confirmation if you have changed the
|
||
|
|
current data.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Undo (Alt+z)</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Cut (Alt+x)</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Copy (Alt+c)</h4><ul>
|
||
|
|
|
||
|
|
Copy the selected widgets and all their children to the "clipboard" file.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Paste (Alt+c)</h4><ul>
|
||
|
|
|
||
|
|
Paste in the widgets in the clipboard file.
|
||
|
|
|
||
|
|
<p>If the widget is a window, it is added to whatever function is
|
||
|
|
selected, or contains the current selection.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>To avoid confusion, it is best to select exactly one widget before
|
||
|
|
doing a paste.
|
||
|
|
|
||
|
|
<p>Cut/paste is the only way to change the parent of a widget.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Select All (Alt+a)</h4><ul>
|
||
|
|
|
||
|
|
Select all widgets in the same group as the current selection.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Open... (F1 or double click)</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Sort</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Earlier (F2)</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Later (F3)</h4><ul>
|
||
|
|
|
||
|
|
All the selected widgets are moved one later in order amoung the
|
||
|
|
children of their parent (if possible).
|
||
|
|
|
||
|
|
</ul><h4>Edit/Group (F7)</h4><ul>
|
||
|
|
|
||
|
|
Create a new Fl_Group and make all the currently selected widgets be
|
||
|
|
children of it.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Ungroup (F8)</h4><ul>
|
||
|
|
|
||
|
|
If all the children of a group are selected, delete that group and
|
||
|
|
make them all be children of it's parent.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Overlays on/off (Alt+o)</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>Edit/Preferences (Alt+p)</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>New/code/Function</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>You can change the function name by double clicking the function.
|
||
|
|
|
||
|
|
</ul><h4>New/Window</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
</ul><h4>New/...</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
<p>When you create the widget you will get the widget's control panel,
|
||
|
|
described in the next chapter.
|
||
|
|
|
||
|
|
</ul><h4>Help/About fluid</h4><ul>
|
||
|
|
|
||
|
|
Pops up a panel showing the version of fluid.
|
||
|
|
|
||
|
|
</ul><h4>Help/Manual</h4><ul>
|
||
|
|
|
||
|
|
Not yet implemented. Use netscape to read these pages instead.
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<a name=widget_panel>
|
||
|
|
<h2>The Widget Panel</h2>
|
||
|
|
|
||
|
|
When you double-click a widget or a set of widgets you will get the
|
||
|
|
"widget attribute panel":
|
||
|
|
|
||
|
|
<p><img align = left src = fluid_widget.gif>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>If you have several widgets selected, they may have different
|
||
|
|
values for the fields. In this case the value for <i>one</i> of the
|
||
|
|
widgets is shown. But if you change this value, <i>all</i> the
|
||
|
|
selected widgets are changed to the new value.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>"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.
|
||
|
|
|
||
|
|
<a name=widget_attributes>
|
||
|
|
<h2>Widget Attributes</h2>
|
||
|
|
|
||
|
|
</ul><h4>Name (text field)</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
</ul><h4>Type (upper-right pulldown menu)</h4><ul>
|
||
|
|
|
||
|
|
Some classes have subtypes that modify their appearance or behavior.
|
||
|
|
You pick the subtype off of this menu.
|
||
|
|
|
||
|
|
</ul><h4>Box (pulldown menu)</h4><ul>
|
||
|
|
|
||
|
|
The boxtype to draw as a background for the widget.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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).
|
||
|
|
|
||
|
|
</ul><h4>Color</h4><ul>
|
||
|
|
|
||
|
|
<p>The color to draw the box with.
|
||
|
|
|
||
|
|
</ul><h4>Color2</h4><ul>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
</ul><h4>Label</h4><ul>
|
||
|
|
|
||
|
|
String to print next to or inside the button.
|
||
|
|
|
||
|
|
<p>You can put newlines into the string to make multiple lines, the
|
||
|
|
easiest way is by typing ctrl+j.
|
||
|
|
|
||
|
|
</ul><h4>Label style (pull down menu)</h4><ul>
|
||
|
|
|
||
|
|
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 <a
|
||
|
|
href=Labeltypes.html#symbols>symbol</a>.
|
||
|
|
|
||
|
|
<p>From this menu you can also pick <a
|
||
|
|
href=#images>"Image..."</a>. This lets you use the contents
|
||
|
|
of an image file (currently an xpm pixmap or xbm bitmap) to label the
|
||
|
|
widget.
|
||
|
|
|
||
|
|
</ul><h4>Label alignement (buttons)</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>Label font</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>Label size</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>Label color</h4><ul>
|
||
|
|
|
||
|
|
Color to draw the label. Ignored by pixmaps (bitmaps, however, do use
|
||
|
|
this color as the foreground color).
|
||
|
|
|
||
|
|
</ul><h4>Text font, size, color</h4><ul>
|
||
|
|
|
||
|
|
Some widgets display text, such as input fields, pull-down menus,
|
||
|
|
browsers. You can change this here.
|
||
|
|
|
||
|
|
</ul><h4>Visible</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>Active</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>Resizable</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
<p>Only one child can be resizable. Turning this on turns it off for
|
||
|
|
other children.
|
||
|
|
|
||
|
|
<p>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 <i>not</i> the same as what will happen in the user program.
|
||
|
|
|
||
|
|
</ul><h4>Hotspot</h4><ul>
|
||
|
|
|
||
|
|
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 <i>when the fluid
|
||
|
|
function is called, so you should call it immediately before showing
|
||
|
|
the window</i>. 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().
|
||
|
|
|
||
|
|
</ul><h4>subclass</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
</ul><h4>Extra code</h4><ul>
|
||
|
|
|
||
|
|
These four fields let you type in literal lines of code to dump into
|
||
|
|
the .H or .C files.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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 .C code.
|
||
|
|
|
||
|
|
</ul><h4>Callback</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
<p>A name names a function in your own code. It must be declared as
|
||
|
|
"void <name>(<class>*,void*)".
|
||
|
|
|
||
|
|
<p>A code snippet is inserted into a static function in the .C 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.
|
||
|
|
|
||
|
|
<p>If the callback is blank then no callback is set.
|
||
|
|
|
||
|
|
</ul><h4>user_data</h4><ul>
|
||
|
|
|
||
|
|
<p>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>)".
|
||
|
|
|
||
|
|
</ul><h4>User data type</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>When</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<a name=windows>
|
||
|
|
<h2>Selecting & Moving Widgets</h2>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>Type Alt+o to temporarily toggle the overlay off without changing
|
||
|
|
the selection, so you can see the widget borders.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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:
|
||
|
|
|
||
|
|
</ul><h4>Border</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul><h4>xclass</h4><ul>
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<a name=images>
|
||
|
|
<h2>Image Labels</h2>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>The <i>contents</i> 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.
|
||
|
|
|
||
|
|
<p>However the <i>file name</i> 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.
|
||
|
|
|
||
|
|
</ul><h4>Notes for all image types</h4><ul>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
</ul><h4>XBM (X bitmap files)</h4><ul>
|
||
|
|
|
||
|
|
<p>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".
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>The program "bitmap" on the X distribution does an ok job of
|
||
|
|
editing bitmaps.
|
||
|
|
|
||
|
|
</ul><h4>XPM (X pixmap files)</h4><ul>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>I have not found any good editors for small iconic pictures. For
|
||
|
|
pixmaps I have used <a
|
||
|
|
href=http://www.danbbs.dk/~torsten/xpaint/index.html>XPaint</a>. 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.
|
||
|
|
|
||
|
|
</ul><h4>GIF files</h4><ul>
|
||
|
|
|
||
|
|
<p>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.
|
||
|
|
|
||
|
|
<p>Fluid converts these into <a href=xpm.html>(modified)</a> 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.
|
||
|
|
|
||
|
|
<p>Behavior and performance with large .gif files is not guaranteed!
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p><a href = index.html>(back to contents)</a>
|