diff options
| author | Michael R Sweet <michael.r.sweet@gmail.com> | 1998-12-29 14:21:17 +0000 |
|---|---|---|
| committer | Michael R Sweet <michael.r.sweet@gmail.com> | 1998-12-29 14:21:17 +0000 |
| commit | 87dd7f0d23eba5c09e71ec6efeb34c6844f5e95f (patch) | |
| tree | ecd25b3fbecdd2d1c6abf106d0c94ac2b1e9926e /documentation/fluid.html | |
| parent | 20adb6834b22523e9d1fecdb7bb8a117f7b6179a (diff) | |
Revised documentation files.
git-svn-id: file:///fltk/svn/fltk/trunk@177 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
Diffstat (limited to 'documentation/fluid.html')
| -rw-r--r-- | documentation/fluid.html | 894 |
1 files changed, 894 insertions, 0 deletions
diff --git a/documentation/fluid.html b/documentation/fluid.html new file mode 100644 index 000000000..47cb7d7fd --- /dev/null +++ b/documentation/fluid.html @@ -0,0 +1,894 @@ +<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> |