bc5a58036a
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.0@633 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
873 lines
42 KiB
HTML
873 lines
42 KiB
HTML
<HTML><BODY>
|
|
<H1 ALIGN=RIGHT><A NAME=FLUID>8 - 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>
|
|
The Fast Light User Interface Designer, or FLUID, is a graphical
|
|
editor that is used to produce FLTK source code.
|
|
<P>FLUID edits and saves its state in <TT>.fl</TT> files. These files are
|
|
text, and you can (with care) edit them in a text editor, perhaps to
|
|
get some special effects. </P>
|
|
<P>FLUID can "compile" the <TT>.fl</TT> file into a <TT>.cxx</TT> and a <TT>.h</TT> file. The
|
|
<TT>.cxx</TT> file defines all the objects from the <TT>.fl</TT> file and the <TT>.h</TT> file
|
|
declares all the global ones. </P>
|
|
<P>A simple program can be made by putting all your code (including a <TT>
|
|
main()</TT> function) into the <TT>.fl</TT> file and thus making the <TT>.cxx</TT> file a
|
|
single source file to compile. Most programs are more complex than
|
|
this, so you write other <TT>.cxx</TT> files that call the FLUID functions.
|
|
These <TT>.cxx</TT> files must <TT>#include</TT> the <TT>.h</TT> file or they can <TT>
|
|
#include</TT> the <TT>.cxx</TT> file so it still appears to be a single source
|
|
file.
|
|
<P ALIGN=CENTER><IMG src=fluid-org.gif>
|
|
<P>Normally the FLUID file defines one or more functions or classes which
|
|
output C++ code. Each function defines a one or more FLTK
|
|
windows, and all the widgets that go inside those windows. </P>
|
|
<P>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 is stored. </P>
|
|
<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 <TT>.cxx</TT> file. </P>
|
|
<H2>Running FLUID Under UNIX</H2>
|
|
To run FLUID under UNIX, type:
|
|
<UL>
|
|
<PRE>
|
|
fluid <I>filename.fl</I> &</PRE>
|
|
</UL>
|
|
to edit the <TT>.fl</TT> file <TT>filename.fl</TT>. 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).
|
|
<P>You can provide any of the standard FLTK switches before the filename: </P>
|
|
<UL>
|
|
<PRE>
|
|
-display host:n.n
|
|
-geometry WxH+X+Y
|
|
-title windowtitle
|
|
-name classname
|
|
-iconic
|
|
-fg color
|
|
-bg color
|
|
-bg2 color
|
|
</PRE>
|
|
</UL>
|
|
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. </P>
|
|
<H2>Running FLUID Under Microsoft Windows</H2>
|
|
To run FLUID under WIN32, double-click on the <I>FLUID.exe</I> file.
|
|
You can also run FLUID from the Command Prompt window (FLUID always
|
|
runs in the background under WIN32).
|
|
<H2>Compiling <TT>.fl</TT> files</H2>
|
|
FLUID can also be called as a command-line "compiler" to create the
|
|
<TT>.cxx</TT> and <TT>.h</TT> file from a <TT>.fl</TT> file. To do this type:
|
|
<UL><PRE>
|
|
fluid -c <I>filename.fl</I>
|
|
</PRE></UL>
|
|
This will read the <TT>filename.fl</TT> file and write <I>filename.cxx</I> and <I>
|
|
filename.h</I>. The directory will be stripped, so they are written to
|
|
the current directory always. If there are any errors reading or
|
|
writing the files it will print the error and exit with a non-zero
|
|
code. In a makefile you can use a line like this:
|
|
<UL>
|
|
<PRE>
|
|
my_panels.h my_panels.cxx: my_panels.fl
|
|
FLUID -c my_panels.fl
|
|
</PRE>
|
|
</UL>
|
|
Some versions of make will accept rules like this to allow all <TT>.fl</TT>
|
|
files found to be compiled:
|
|
<UL>
|
|
<PRE>
|
|
.SUFFIXES: .fl .cxx .h
|
|
.fl.h .fl.cxx:
|
|
FLUID -c $<
|
|
</PRE>
|
|
</UL>
|
|
<H2>A Short Tutorial</H2>
|
|
|
|
FLUID is an amazingly powerful little program. However, this power
|
|
comes at a price, as it is not always obvious how to accomplish seemingly
|
|
simple tasks with it. This tutorial will show you how to generate a
|
|
complete user interface class with FLUID that is used for the CubeView
|
|
program below.
|
|
|
|
<P ALIGN=CENTER><IMG SRC="cubeview.gif"></P>
|
|
|
|
<P>The window is of class CubeViewUI, and is completely generated by FLUID, including
|
|
class member functions. The central display of the cube is a separate
|
|
subclass of Fl_Gl_Window called CubeView. CubeViewUI manages CubeView
|
|
using callbacks from the various sliders and rollers to manipulate the
|
|
viewing angle and zoom of CubeView.
|
|
<p>At the completion of this tutorial you will (hopefully) understand
|
|
how to:
|
|
<ol>
|
|
<li>Use FLUID to create a complete user interface class, including
|
|
constructor and any member functions necessary.
|
|
<li>Use FLUID to set callbacks member functions of a custom widget
|
|
classes.
|
|
<li>Subclass an <a
|
|
href="Fl_Gl_Window.html#Fl_Gl_Window"><TT>Fl_Gl_Window</TT></A> to suit
|
|
your purposes.
|
|
</ol>
|
|
|
|
<h3>The CubeView Class</h3>
|
|
The CubeView class is a subclass of Fl_Gl_Window. It has methods for
|
|
setting the zoom, the <i>x</i> and <i>y</i> pan, and the rotation angle
|
|
about the <i>x</i> and <i>y</i>axes.
|
|
<p>You can safely skip this section as long as you realize the CubeView
|
|
is a sublass of <tt>Fl_Gl_Window</tt> and will respond to calls from
|
|
CubeViewUI, generated by FLUID.
|
|
<h4><a name="def">The CubeView Class Definition</a></h4>
|
|
Here is the CubeView class definition, as given by its header file
|
|
"test/CubeView.h":
|
|
<ul><pre>
|
|
class CubeView : public Fl_Gl_Window {
|
|
public:
|
|
CubeView(int x,int y,int w,int h,const char *l=0);
|
|
// this value determines the scaling factor used to draw the cube.
|
|
double size;
|
|
/* Set the rotation about the vertical (y ) axis.
|
|
*
|
|
* This function is called by the horizontal roller in CubeViewUI
|
|
* and the initialize button in CubeViewUI.
|
|
*/
|
|
void v_angle(float angle){vAng=angle;};
|
|
// Return the rotation about the vertical (y ) axis.
|
|
float v_angle(){return vAng;};
|
|
/* Set the rotation about the horizontal (x ) axis.
|
|
*
|
|
* This function is called by the vertical roller in CubeViewUI
|
|
and the
|
|
* initialize button in CubeViewUI.
|
|
*/
|
|
void h_angle(float angle){hAng=angle;};
|
|
// the rotation about the horizontal (x ) axis.
|
|
float h_angle(){return hAng;};
|
|
/* Sets the x shift of the cube view camera.
|
|
*
|
|
* This function is called by the slider in CubeViewUI and the
|
|
* initialize button in CubeViewUI.
|
|
*/
|
|
void panx(float x){xshift=x;};
|
|
/* Sets the y shift of the cube view camera.
|
|
*
|
|
* This function is called by the slider in CubeViewUI and the
|
|
* initialize button in CubeViewUI.
|
|
*/
|
|
void pany(float y){yshift=y;};
|
|
/* The widget class draw() override.
|
|
* The draw() function initialize Gl for another round of
|
|
* drawing then calls specialized functions for drawing each
|
|
* of the entities displayed in the cube view.
|
|
*/
|
|
void draw();
|
|
|
|
private:
|
|
/* Draw the cube boundaries
|
|
* Draw the faces of the cube using the boxv[] vertices, using
|
|
* GL_LINE_LOOP for the faces. The color is #defined by
|
|
* CUBECOLOR.
|
|
*/
|
|
void drawCube();
|
|
|
|
float vAng,hAng; float xshift,yshift;
|
|
|
|
float boxv0[3];float boxv1[3]; float boxv2[3];float boxv3[3];
|
|
float boxv4[3];float boxv5[3]; float boxv6[3];float boxv7[3];
|
|
};
|
|
</pre></ul>
|
|
<h4><a name="imp">The CubeView Class Implementation</a></h4>
|
|
Here is the CubeView implementation. It is very similar to the
|
|
"cube" demo included with FLTK.
|
|
<ul><pre>
|
|
#include "CubeView.h"
|
|
#include <math.h>
|
|
|
|
CubeView::CubeView(int x,int y,int w,int h,const char *l)
|
|
: Fl_Gl_Window(x,y,w,h,l)
|
|
{
|
|
vAng = 0.0; hAng=0.0; size=10.0;
|
|
/* The cube definition. These are the vertices of a unit cube
|
|
* centered on the origin.*/
|
|
boxv0[0] = -0.5; boxv0[1] = -0.5; boxv0[2] = -0.5; boxv1[0] = 0.5;
|
|
boxv1[1] = -0.5; boxv1[2] = -0.5; boxv2[0] = 0.5; boxv2[1] = 0.5;
|
|
boxv2[2] = -0.5; boxv3[0] = -0.5; boxv3[1] = 0.5; boxv3[2] = -0.5;
|
|
boxv4[0] = -0.5; boxv4[1] = -0.5; boxv4[2] = 0.5; boxv5[0] = 0.5;
|
|
boxv5[1] = -0.5; boxv5[2] = 0.5; boxv6[0] = 0.5; boxv6[1] = 0.5;
|
|
boxv6[2] = 0.5; boxv7[0] = -0.5; boxv7[1] = 0.5; boxv7[2] = 0.5;
|
|
};
|
|
|
|
// The color used for the edges of the bounding cube.
|
|
#define CUBECOLOR 255,255,255,255
|
|
|
|
void CubeView::drawCube() {
|
|
/* Draw a colored cube */
|
|
#define ALPHA 0.5
|
|
glShadeModel(GL_FLAT);
|
|
|
|
glBegin(GL_QUADS);
|
|
glColor4f(0.0, 0.0, 1.0, ALPHA);
|
|
glVertex3fv(boxv0);
|
|
glVertex3fv(boxv1);
|
|
glVertex3fv(boxv2);
|
|
glVertex3fv(boxv3);
|
|
|
|
glColor4f(1.0, 1.0, 0.0, ALPHA);
|
|
glVertex3fv(boxv0);
|
|
glVertex3fv(boxv4);
|
|
glVertex3fv(boxv5);
|
|
glVertex3fv(boxv1);
|
|
|
|
glColor4f(0.0, 1.0, 1.0, ALPHA);
|
|
glVertex3fv(boxv2);
|
|
glVertex3fv(boxv6);
|
|
glVertex3fv(boxv7);
|
|
glVertex3fv(boxv3);
|
|
|
|
glColor4f(1.0, 0.0, 0.0, ALPHA);
|
|
glVertex3fv(boxv4);
|
|
glVertex3fv(boxv5);
|
|
glVertex3fv(boxv6);
|
|
glVertex3fv(boxv7);
|
|
|
|
glColor4f(1.0, 0.0, 1.0, ALPHA);
|
|
glVertex3fv(boxv0);
|
|
glVertex3fv(boxv3);
|
|
glVertex3fv(boxv7);
|
|
glVertex3fv(boxv4);
|
|
|
|
glColor4f(0.0, 1.0, 0.0, ALPHA);
|
|
glVertex3fv(boxv1);
|
|
glVertex3fv(boxv5);
|
|
glVertex3fv(boxv6);
|
|
glVertex3fv(boxv2);
|
|
glEnd();
|
|
|
|
glColor3f(1.0, 1.0, 1.0);
|
|
glBegin(GL_LINES);
|
|
glVertex3fv(boxv0);
|
|
glVertex3fv(boxv1);
|
|
|
|
glVertex3fv(boxv1);
|
|
glVertex3fv(boxv2);
|
|
|
|
glVertex3fv(boxv2);
|
|
glVertex3fv(boxv3);
|
|
|
|
glVertex3fv(boxv3);
|
|
glVertex3fv(boxv0);
|
|
|
|
glVertex3fv(boxv4);
|
|
glVertex3fv(boxv5);
|
|
|
|
glVertex3fv(boxv5);
|
|
glVertex3fv(boxv6);
|
|
|
|
glVertex3fv(boxv6);
|
|
glVertex3fv(boxv7);
|
|
|
|
glVertex3fv(boxv7);
|
|
glVertex3fv(boxv4);
|
|
|
|
glVertex3fv(boxv0);
|
|
glVertex3fv(boxv4);
|
|
|
|
glVertex3fv(boxv1);
|
|
glVertex3fv(boxv5);
|
|
|
|
glVertex3fv(boxv2);
|
|
glVertex3fv(boxv6);
|
|
|
|
glVertex3fv(boxv3);
|
|
glVertex3fv(boxv7);
|
|
glEnd();
|
|
};//drawCube
|
|
|
|
void CubeView::draw() {
|
|
if (!valid()) {
|
|
glLoadIdentity(); glViewport(0,0,w(),h());
|
|
glOrtho(-10,10,-10,10,-20000,10000); glEnable(GL_BLEND);
|
|
glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
|
|
}
|
|
|
|
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
|
|
glPushMatrix(); glTranslatef(xshift, yshift, 0);
|
|
glRotatef(hAng,0,1,0); glRotatef(vAng,1,0,0);
|
|
glScalef(float(size),float(size),float(size)); drawCube();
|
|
glPopMatrix();
|
|
};
|
|
</pre></ul>
|
|
|
|
<h3>The CubeViewUI Class</h3>
|
|
We will completely construct a window to display and control the
|
|
CubeView defined in the previous section using FLUID.
|
|
<h4><a name="def">Defining the CubeViewUI Class</a></h4>
|
|
Once you have started FLUID, the first step in defining a class is to
|
|
create a new class within FLUID using the <b>New->Code->Class</b>
|
|
menu item. Name the class "CubeViewUI" and leave the
|
|
subclass blank. We do not need any inheritance for this
|
|
window. You should see the new class declaration in the FLUID
|
|
browser window.
|
|
<p align=center><img src="fluid1.gif"></p>
|
|
<h4><a name="addcon">Adding the Class Constructor</a></h4>
|
|
Click on the CubeViewUI class in the FLUID window and add a new method
|
|
by selecting <b>New->Code->Function/Method.</b> The name of the
|
|
function will also be CubeViewUI. FLUID will understands that this will
|
|
be the constructor for the class and will generate the appropriate
|
|
code. Make sure you declare the constructor public.
|
|
<p>Then add a window to the CubeViewUI class. Highlight the name of
|
|
the constructor in the FLUID browser window and click on
|
|
<b>New->Group->Window</b>. In a similar manner add the
|
|
following to the CubeViewUI constructor:
|
|
<ul>
|
|
<li>A horizontal roller named <tt>hrot</tt>
|
|
<li>A vertical roller named <tt>vrot</tt>
|
|
<li>A horizontal slider named <tt>xpan</tt>
|
|
<li>A vertical slider named <tt>ypan</tt>
|
|
<li>A horizontal value slider named <tt>zoom</tt>
|
|
</ul>
|
|
None of these additions need be public. And they shouldn't be
|
|
unless you plan to expose them as part of the interface for
|
|
CubeViewUI.
|
|
<p>When you are finished you should have something like this:
|
|
<p align=center><img src="fluid2.gif">
|
|
<p>We will talk about the <tt>show()</tt> method that is highlighted
|
|
shortly.
|
|
<h4><a name="addcube">Adding the CubeView Widget</a></h4>
|
|
|
|
What we have is nice, but does little to show our cube. We have already
|
|
defined the CubeView class and we would like to show it within the
|
|
CubeViewUI.
|
|
<p>The CubeView class inherits the <tt>Fl_Gl_Window</tt> class, which
|
|
is created in the same way as a <tt>Fl_Box</tt> widget. Use
|
|
<b>New->Other->Box</b> to add a square box to the main window.
|
|
This will be no ordinary box, however.
|
|
<p>The Box properties window will appear. The key to letting CubeViewUI
|
|
display CubeView is to enter CubeView in the "Class:" text
|
|
entry box. This tells FLUID that it is not an <tt>Fl_Box</tt>, but a
|
|
similar widget with the same constructor. In the "Extra
|
|
Code:" field enter <tt>#include "CubeView.h"</tt>
|
|
<p>This <tt>#include</tt> is important, as we have just included
|
|
CubeView as a member of CubeViewUI, so any public CubeView methods are
|
|
now available to CubeViewUI.
|
|
|
|
<p align=center><img src="fluid3.gif"></p>
|
|
|
|
<h4><a name="defcall">Defining the Callbacks</a></h4>
|
|
Each of the widgets we defined before adding CubeView can have
|
|
callbacks that call CubeView methods. You can call an external
|
|
function or put in a short amount of code in the "Callback"
|
|
field of the widget panel. For example, the callback for the
|
|
<tt>ypan</tt> slider is:
|
|
<ul><pre>
|
|
cube->pany(((Fl_Slider *)o)->value());
|
|
cube->redraw();
|
|
</pre></ul>
|
|
We call <tt>cube->redraw()</tt> after changing the value to update
|
|
the CubeView window. CubeView could easily be modified to do this, but
|
|
it is nice to keep this exposed in the case where you may want to do
|
|
more than one view change only redrawing once saves a lot of time.
|
|
<p>There is no reason no wait until after you have added CubeView to
|
|
enter these callbacks. FLUID assumes you are smart enough not to refer
|
|
to members or functions that don't exist.
|
|
<h4><a name="addmeth">Adding a Class Method</a></h4>
|
|
You can add class methods within FLUID that have nothing to do with the
|
|
GUI. An an example add a show function so that CubeViewUI can actually
|
|
appear on the screen.
|
|
<p>Make sure the top level CubeViewUI is selected and select
|
|
<b>New->Code->Function/Method</b>. Just use the name
|
|
<tt>show()</tt>. We don't need a return value here, and since we will
|
|
not be adding any widgets to this method FLUID will assign it a return
|
|
type of <tt>void</tt>.
|
|
<p align=center><img src="fluid4.gif"></p>
|
|
<p>Once the new method has been added, highlight its name and select
|
|
New->Code->Code. Enter the method's code in the code window.
|
|
|
|
<h3><a name="addconst">Adding Constructor Initialization Code</a></h3>
|
|
If you need to add code to initialize class, for example setting
|
|
initial values of the horizontal and vertical angles in the
|
|
CubeView, you can simply highlight the Constructor and select
|
|
<b>New->Code->Code</b>. Add any required code.
|
|
|
|
<h3><a name="gencode">Generating the Code</a></h3>
|
|
Now that we have completely defined the CubeViewUI, we have to generate
|
|
the code. There is one last trick to ensure this all works. Open the
|
|
preferences dialog from <b>Edit->Preferences</b>.
|
|
<p>At the bottom of the preferences dialog box is the key: "Include
|
|
Header from Code". Select that option and set your desired file
|
|
extensions and you are in business. You can include the CubeViewUI.h
|
|
(or whatever extension you prefer) as you would any other C++ class.
|
|
<HR BREAK>
|
|
<H2>FLUID Reference</H2>
|
|
|
|
<H3>The Widget Browser</H3>
|
|
The main window shows a menu bar and a scrolling browser of all
|
|
the defined widgets. The name of the <TT>.fl</TT> 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.
|
|
The leftmost widgets are the <I>parents</I>, and all the widgets
|
|
listed below them are their <I>children</I>. Parents don't have to have
|
|
any children.</P>
|
|
<P>The top level of the hierarchy is composed of <I>functions</I> and
|
|
<I>classes</I>. Each of these will produce a single C++ public
|
|
function or class in the output <TT>.cxx</TT> file. Calling the function or
|
|
instantiating the class will create all of the child widgets. </P>
|
|
<P>The second level of the hierarchy contains the <I>windows</I>. Each of these
|
|
produces an instance of class <tt>Fl_Window</tt>. </P>
|
|
<P>Below that are either <I>widgets</I> (subclasses of <tt>Fl_Widget</tt>) 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>
|
|
<P>Widgets are shown in the browser by either their <I>name</I> (such
|
|
as "main_panel" in the example), or by their <I>type</I>
|
|
and <I>label</I> (such as "Button "the green""). </P>
|
|
<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. Note that hidden children may
|
|
be selected even when there is no visual indication of this.
|
|
<P>You <I>open</I> widgets by double-clicking on them, or (to open several
|
|
widgets you have picked) by typing the F1 key. A control panel will appear
|
|
so you can change the widget(s).</P>
|
|
<H3>Menu Items</H3>
|
|
<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: </P>
|
|
<H4>File/Open... (Alt+o)</H4>
|
|
Discards the current editing session and reads in a different <TT>.fl</TT> file.
|
|
You are asked for confirmation if you have changed the current file.
|
|
<P>FLUID can also read <tt>.fd</tt> files produced by the Forms and
|
|
XForms "fdesign" programs. It is best to File/Merge them
|
|
instead of opening them. FLUID does not understand everything in a
|
|
<tt>.fd</tt> 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
|
|
<tt>.fd</tt> file with its own format, which fdesign cannot read! </P>
|
|
<H4>File/Save (Alt+s)</H4>
|
|
Writes the current data to the <TT>.fl</TT> file. If the file is unnamed
|
|
then FLUID will ask for a filename.
|
|
<H4>File/Save As...(Alt+Shift+S)</H4>
|
|
Asks for a new filename and saves the file.
|
|
<H4>File/Merge... (Alt+i)</H4>
|
|
Inserts the contents of another <TT>.fl</TT> file, without changing the name of
|
|
the current <TT>.fl</TT> file. All the functions (even if they have the same
|
|
names as the current ones) are added, and you will have to use cut/paste to
|
|
put the widgets where you want.
|
|
<H4>File/Write Code (Alt+Shift+C)</H4>
|
|
"Compiles" the data into a <TT>.cxx</TT> and <TT>.h</TT>
|
|
file. These are exactly the same as the files you get when you run
|
|
FLUID with the <tt>-c</tt> switch.
|
|
<P>The output file names are the same as the <TT>.fl</TT> file, with
|
|
the leading directory and trailing ".fl" stripped, and
|
|
".h" or ".cxx" appended. </P>
|
|
<H4>File/Quit (Alt+q)</H4>
|
|
Exits FLUID. You are asked for confirmation if you have changed the
|
|
current data.
|
|
<H4>Edit/Undo (Alt+z)</H4>
|
|
This isn't implemented yet. You should do save often so you can
|
|
recover from any mistakes you make.
|
|
<H4>Edit/Cut (Alt+x)</H4>
|
|
Deletes the selected widgets and all of their children. These are saved
|
|
to a "clipboard" file and can be pasted back into any FLUID
|
|
window.
|
|
<H4>Edit/Copy (Alt+c)</H4>
|
|
Copies the selected widgets and all of their children to the "clipboard"
|
|
file.
|
|
<H4>Edit/Paste (Alt+c)</H4>
|
|
Pastes the widgets from the clipboard file.
|
|
<P>If the widget is a window, it is added to whatever function is
|
|
selected, or contained in the current selection. </P>
|
|
<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>
|
|
<P>To avoid confusion, it is best to select exactly one widget before
|
|
doing a paste. </P>
|
|
<P>Cut/paste is the only way to change the parent of a widget. </P>
|
|
<H4>Edit/Select All (Alt+a)</H4>
|
|
Selects 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. </P>
|
|
<H4>Edit/Open... (F1 or double click)</H4>
|
|
Displays the current widget in the attributes panel. If the widget is a window
|
|
and it is not visible then the window is shown instead.
|
|
<H4>Edit/Sort</H4>
|
|
Sorts the selected widgets 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.
|
|
<H4>Edit/Earlier (F2)</H4>
|
|
Moves all of the selected widgets one earlier in order among 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, classes, and windows within functions.
|
|
<H4>Edit/Later (F3)</H4>
|
|
Moves all of the selected widgets one later in order among the
|
|
children of their parent (if possible).
|
|
<P>
|
|
<TABLE WIDTH=100% CELLPADDING=0 CELLSPACING=0>
|
|
<TR>
|
|
<TD VALIGN=TOP>
|
|
<H4>Edit/Group (F7)</H4>
|
|
Creates a new <tt>Fl_Group</tt> and make all the currently selected widgets
|
|
children of it.
|
|
<H4>Edit/Ungroup (F8)</H4>
|
|
Deletes the parent group if all the children of a group are selected.
|
|
<H4>Edit/Overlays on/off (Alt+Shift+O)</H4>
|
|
Toggles 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.
|
|
<H4>Edit/Preferences (Alt+p)</H4>
|
|
Displays the preferences panel. The alignment preferences control the
|
|
grid that all widgets snap to when you move and resize them, and for the
|
|
"snap" which is how far a widget has to be dragged from its original position
|
|
to actually change.
|
|
</TD>
|
|
<TD VALIGN=TOP><IMG SRC="fluid_prefs.gif"></TD>
|
|
</TR>
|
|
</TABLE>
|
|
The output filenames control the extensions or names of the files the are
|
|
generated by FLUID. If you check the "Include .h from .cxx" button the code
|
|
file will include the header file automatically.
|
|
|
|
<H4>New/Code/Function</H4>
|
|
Creates 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 which 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 a Fl_Window pointer. 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 nothing
|
|
(<tt>void</tt>). </P>
|
|
<P>It is possible to make the <TT>.cxx</TT> output be a self-contained
|
|
program that can be compiled and executed. This is done by deleting
|
|
the function name so <tt>main(argc,argv)</tt> is used. The function
|
|
will call <tt>show()</tt> on all the windows it creates and then call
|
|
<tt>Fl::run()</tt>. This can also be used to test resize behavior or
|
|
other parts of the user interface.</P>
|
|
<P>You can change the function name by double-clicking on the function. </P>
|
|
<H4>New/Window</H4>
|
|
Creates a new <tt>Fl_Window</tt> widget. The window is added to the
|
|
currently selected function, or to the function containing the
|
|
currently selected item. The window will appear, sized to 100x100.
|
|
You can resize it to whatever size you require.
|
|
<P>The widget panel will also appear and is described later in this
|
|
chapter.</P>
|
|
<H4>New/...</H4>
|
|
All other items on the New menu are subclasses of <tt>Fl_Widget</tt>. 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,
|
|
which is described later in this chapter. </P>
|
|
<H4>Help/About FLUID</H4>
|
|
Pops up a panel showing the version of FLUID.
|
|
<H3>The Widget Panel</H3>
|
|
<TABLE cellpadding=0 cellspacing=0 width=100%>
|
|
<TR><TD>When you double-click on a widget or a set of widgets you will get
|
|
the "widget attribute panel".
|
|
<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+Shift+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> of 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 such as mismatched parenthesis in any code 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 are undone,
|
|
however.
|
|
</TD><TD><IMG src="fluid_widget.gif"></TD></TR>
|
|
</TABLE>
|
|
<H3><A name=widget_attributes>Widget Attributes</A></H3>
|
|
<H4>Name (text field)</H4>
|
|
Name of a 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. </P>
|
|
<H4>Type (upper-right pulldown menu)</H4>
|
|
Some classes have subtypes that modify their appearance or behavior.
|
|
You pick the subtype off of this menu.
|
|
<H4>Box (pulldown menu)</H4>
|
|
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 may leave unwanted stuff inside the widget. </P>
|
|
<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. Note
|
|
that this checkerboard is not drawn by the resulting program. Instead
|
|
random garbage will be displayed.</P>
|
|
<H4>Color</H4>
|
|
<P>The color to draw the box with. </P>
|
|
<H4>Color2</H4>
|
|
<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. </P>
|
|
<H4>Label</H4>
|
|
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. </P>
|
|
<H4>Label style (pull down menu)</H4>
|
|
How to draw the label. Normal, shadowed, 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=drawing.html#images>
|
|
"Image..."</A>. This lets you use the contents of a GIF, XPM, or
|
|
XBM image file to label the widget. </P>
|
|
<H4>Label Alignment (Buttons)</H4>
|
|
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.
|
|
<H4>Label Font</H4>
|
|
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.
|
|
<H4>Label Size</H4>
|
|
Pixel size (height) 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.
|
|
<H4>Label Color</H4>
|
|
Color to draw the label. Ignored by pixmaps (bitmaps, however, do use
|
|
this color as the foreground color).
|
|
<H4>Text Font, Size, and Color</H4>
|
|
Some widgets display text, such as input fields, pull-down menus, and
|
|
browsers.
|
|
<H4>Visible</H4>
|
|
If you turn this off then the widget is hidden initially. Don't change
|
|
this for windows or for the immediate children of a Tabs group.
|
|
<H4>Active</H4>
|
|
If you turn this off then the widget is deactivated initially.
|
|
<H4>Resizable</H4>
|
|
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
|
|
the other children. </P>
|
|
<P>You can get more complex behavior by making invisible boxes the
|
|
resizable widget, or by using hierarchies of groups. Unfortunately 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. </P>
|
|
<H4>Hotspot</H4>
|
|
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</I>, 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 <tt>show()</tt>.
|
|
<H4>Subclass</H4>
|
|
This is how you use your own subclasses of <tt>Fl_Widget</tt>. Whatever
|
|
identifier you type in here will be the class that is instantiated.
|
|
<P>In addition, no <tt>#include</tt> header file is put in the <TT>.h</TT> file. You
|
|
must provide a <tt>#include</tt> line as the first line of the "Extra
|
|
Code" which declares your subclass. </P>
|
|
<P>The class must 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. </P>
|
|
<H4>Extra Code</H4>
|
|
These four fields let you type in literal lines of code to dump into
|
|
the <TT>.h</TT> or <TT>.cxx</TT> files.
|
|
<P>If the text starts with a <tt>#</tt> or the word <tt>extern</tt> then FLUID thinks
|
|
this is an "include" line, and it is written to the <TT>.h</TT> file. If the
|
|
same include line occurs several times then only one copy is written. </P>
|
|
<P>All other lines are "code" lines. The current widget is
|
|
pointed to by the local variable <tt>o</tt>. The window being constructed is
|
|
pointed to by the local variable <tt>w</tt>. You can also access any
|
|
arguments passed to the function here, and any named widgets that are
|
|
before this one. </P>
|
|
<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 four lines you probably should call a function in
|
|
your own <TT>.cxx</TT> code. </P>
|
|
<H4>Callback</H4>
|
|
This can either be the name of a function, or a small snippet of code.
|
|
If you enter anything but letters, numbers, and the underscore then FLUID
|
|
treats it as code.
|
|
<P>A name names a function in your own code. It must be declared as
|
|
<tt>void name(<class>*,void*)</tt>. </P>
|
|
<P>A code snippet is inserted into a static function in the
|
|
<TT>.cxx</TT> output file. The function prototype is <tt>void
|
|
name(class *o, void *v)</tt> so that you can refer to the widget as
|
|
<tt>o</tt> and the <tt>user_data()</tt> as <tt>v</tt>. 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>
|
|
<P>If the callback is blank then no callback is set. </P>
|
|
<H4>user_data</H4>
|
|
This is a value for the <tt>user_data()</tt> of the widget. If blank the
|
|
default value of zero is used. This can be any piece of C code that
|
|
can be cast to a <tt>void</tt> pointer.
|
|
<H4>User Data Type</H4>
|
|
The <tt>void *</tt> in the callback function prototypes is replaced with this.
|
|
You may want to use <tt>long</tt> for old XForms code. Be warned that
|
|
anything other than <tt>void *</tt> is not guaranteed to work!
|
|
However on most architectures other pointer types are ok, and <tt>long</tt> is
|
|
usually ok, too.
|
|
<H4>When</H4>
|
|
When to do the callback. This can be "never", "changed",
|
|
"release", "enter key", or "no change". 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 other rare but useful values for the <tt>when()</tt> field that are
|
|
not in the menu. You should use the extra code fields to put these
|
|
values in.</P>
|
|
<H3>Selecting and Moving Widgets</H3>
|
|
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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<P>Type Alt+o to temporarily toggle the overlay off without changing
|
|
the selection, so you can see the widget borders. </P>
|
|
<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>
|
|
<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: </P>
|
|
<H4>Border</H4>
|
|
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.
|
|
<H4>xclass</H4>
|
|
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.
|
|
<H3><A name=images>Image Labels</A></H3>
|
|
<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>
|
|
<P>The <I>contents</I> of the image file are written to the <TT>.cxx</TT> file,
|
|
so if you wish to distribute the C code, you only need to copy the <TT>.cxx</TT>
|
|
file, not the images. If many widgets share the same image then only
|
|
one copy is written. </P>
|
|
<P>However the <I>file name</I> is stored in the <TT>.fl</TT> file, so to read
|
|
the <TT>.fl</TT> file you need the image files as well. Filenames are relative
|
|
to the location the <TT>.fl</TT> file is (not necessarily the current
|
|
directory). I recommend you either put the images in the same
|
|
directory as the <TT>.fl</TT> file, or use absolute path names. </P>
|
|
<H4>Notes for all image types</H4>
|
|
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>
|
|
<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 its internal copy, and then set the image
|
|
again. You may find it easier to exit FLUID and run it again. </P>
|
|
<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>
|
|
<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. </P>
|
|
<H4>XBM (X bitmap files)</H4>
|
|
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>
|
|
<P>The program "bitmap" on the X distribution does an ok job of editing
|
|
bitmaps. </P>
|
|
<H4>XPM (X pixmap files)</H4>
|
|
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>
|
|
<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>
|
|
<P>I have not found any good editors for small iconic pictures. For
|
|
pixmaps I have used <A href="http://www.image.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. </P>
|
|
<H4>GIF files</H4>
|
|
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 (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. </P>
|
|
<P>Behavior and performance with large .gif files is not guaranteed! </P>
|
|
</BODY></HTML>
|