From 70ce08e0cb5f7f1d0e004e99c2b0f725bf0d377d Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Wed, 8 Apr 2020 00:54:36 +0200 Subject: [PATCH] Improve fluid documentation - remove trailing whitespace - reformat for better readability - fix typos --- documentation/src/fluid.dox | 345 ++++++++++++++++++------------------ 1 file changed, 168 insertions(+), 177 deletions(-) diff --git a/documentation/src/fluid.dox b/documentation/src/fluid.dox index b6218974d..1978ce636 100644 --- a/documentation/src/fluid.dox +++ b/documentation/src/fluid.dox @@ -39,7 +39,7 @@ POSIX catgets interfaces. A simple program can be made by putting all your code (including a \p main() function) into the .fl file and thus making the .cxx file a -single source file to compile. Most programs are more complex than +single source file to compile. Most programs are more complex than this, so you write other .cxx files that call the FLUID functions. These .cxx files must \p \#include @@ -47,23 +47,22 @@ the .h file or they can \p \#include the .cxx file so it still appears to be a single source file. - \image html fluid-org.png "Figure 9-1: FLUID organization" - \image latex fluid-org.png "FLUID organization" width=12cm + \image html fluid-org.png "Figure 9-1: FLUID organization" + \image latex fluid-org.png "FLUID organization" width=12cm Normally the FLUID file defines one or more functions or classes which -output C++ code. Each function defines one or more FLTK -windows, and all the widgets that go inside those windows. +output C++ code. Each function defines one or more FLTK +windows and all the widgets that go inside those windows. 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 +"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 +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. +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. 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 @@ -80,11 +79,11 @@ fluid filename.fl & to edit the .fl file filename.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 file of that name. You can run FLUID without any name, in +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). -You can provide any of the standard FLTK switches before the filename: +You can provide any of the standard FLTK switches before the filename: \code -display host:n.n @@ -114,11 +113,11 @@ To run FLUID under Windows, double-click on the \e FLUID.exe file. You can also run FLUID from the Command Prompt window. FLUID always runs in the background under Windows. -\section fluid_compiling_fl_files Compiling .fl files +\section fluid_compiling_fl_files Compiling .fl Files FLUID can also be called as a command-line "compiler" to create the .cxx and .h -file from a .fl file. To do this type: +file from a .fl file. To do this type: \code fluid -c filename.fl @@ -186,19 +185,16 @@ FLUID that is used for the CubeView program provided with FLTK. \image latex cubeview.png "CubeView demo" width=10cm 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. +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. -At the completion of this tutorial you will (hopefully) understand -how to: +At the completion of this tutorial you will (hopefully) understand how to: -# Use FLUID to create a complete user interface class, including constructor and any member functions necessary. --# Use FLUID to set callbacks member functions of a custom widget - classes. +-# Use FLUID to set callback member functions of custom widget classes. -# Subclass an Fl_Gl_Window to suit your purposes. \subsection fluid_cubeview The CubeView Class @@ -222,22 +218,21 @@ class CubeView : public Fl_Gl_Window { 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. + /* 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. + // Return the rotation about the vertical (y) axis. float v_angle(){return vAng;}; - /* Set the rotation about the horizontal (x ) axis. + /* Set the rotation about the horizontal (x) axis. * * This function is called by the vertical roller in CubeViewUI - and the - * initialize button in CubeViewUI. + * and the initialize button in CubeViewUI. */ void h_angle(float angle){hAng=angle;}; - // the rotation about the horizontal (x ) axis. + // the rotation about the horizontal (x) axis. float h_angle(){return hAng;}; /* Sets the x shift of the cube view camera. * @@ -265,7 +260,7 @@ class CubeView : public Fl_Gl_Window { * CUBECOLOR. */ void drawCube(); - + float vAng,hAng; float xshift,yshift; float boxv0[3];float boxv1[3]; float boxv2[3];float boxv3[3]; @@ -288,12 +283,14 @@ CubeView::CubeView(int x,int y,int w,int h,const char *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; + 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. @@ -397,7 +394,7 @@ void CubeView::draw() { }; \endcode -\subsection fluid_cubevieui The CubeViewUI Class +\subsection fluid_cubeview_ui The CubeViewUI Class We will completely construct a window to display and control the CubeView defined in the previous section using FLUID. @@ -406,12 +403,11 @@ CubeView defined in the previous section using FLUID. Once you have started FLUID, the first step in defining a class is to create a new class within FLUID using the New->Code->Class -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. +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. -\image html fluid1.png "Figure 9-3: FLUID file for CubeView" +\image html fluid1.png "Figure 9-3: FLUID file for CubeView" \image latex fluid1.png "FLUID file for CubeView" width=10cm \par Adding the Class Constructor @@ -452,14 +448,14 @@ defined the CubeView class and we would like to show it within the CubeViewUI. The CubeView class inherits the Fl_Gl_Window class, which -is created in the same way as a Fl_Box widget. Use +is created in the same way as an Fl_Box widget. Use New->Other->Box to add a square box to the main window. This will be no ordinary box, however. 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 Fl_Box, but a -similar widget with the same constructor. +similar widget with the same constructor. In the Extra Code: field enter \#include "CubeView.h" @@ -474,7 +470,7 @@ now available to CubeViewUI. 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 +function or put a short amount of code in the Callback field of the widget panel. For example, the callback for the \p ypan slider is: @@ -541,22 +537,22 @@ The main window shows a menu bar and a scrolling browser of all the defined widgets. The name of the .fl file being edited is shown in the window title. -The widgets are stored in a hierarchy. You can open and close a +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 \e parents, and all the widgets -listed below them are their \e children. Parents don't have to have +listed below them are their \e children. Parents don't have to have any children. The top level of the hierarchy is composed of \e functions and -\e classes. Each of these will produce a single C++ public -function or class in the output .cxx file. Calling the function or +\e classes. Each of these will produce a single C++ public function +or class in the output .cxx file. Calling the function or instantiating the class will create all of the child widgets. The second level of the hierarchy contains the \e windows. Each of these produces an instance of class Fl_Window. Below that are either \e widgets (subclasses of Fl_Widget) or -\e groups of widgets (including other groups). Plain groups are for +\e groups of widgets (including other groups). Plain groups are for layout, navigation, and resize purposes. Tab groups provide the well-known file-card tab interface. @@ -565,21 +561,21 @@ as "main_panel" in the example), or by their \e type and \e label (such as "Button "the green""). You \e select widgets by clicking on their names, which highlights -them (you can also select widgets from any displayed window). You can +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 +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. You \e open widgets by double-clicking on them, or (to open several -widgets you have picked) by typing the F1 key. A control panel will appear +widgets you have picked) by typing the F1 key. A control panel will appear so you can change the widget(s). \subsection fluid_menu_items Menu Items The menu bar at the top is duplicated as a pop-up menu on any -displayed window. The shortcuts for all the menu items work in any -window. The menu items are: +displayed window. The shortcuts for all the menu items work in any +window. The menu items are: \par File/Open... (Ctrl+o) @@ -597,14 +593,13 @@ 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 its own format, which fdesign cannot -read! +.fd file with its own format, which fdesign cannot read! \par File/Insert... (Ctrl+i) \par Inserts the contents of another .fl file, without -changing the name of the current .fl file. All the +changing the name of the current .fl 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. @@ -612,7 +607,7 @@ where you want. \par File/Save (Ctrl+s) \par -Writes the current data to the .fl file. If the +Writes the current data to the .fl file. If the file is unnamed then FLUID will ask for a filename. \par File/Save As... (Ctrl+Shift+S) @@ -629,7 +624,7 @@ FLUID with the \c -c switch. \par The output file names are the same as the .fl file, with -the leading directory and trailing ".fl" stripped, and +the leading directory and trailing ".fl" stripped, and ".h" or ".cxx" appended. \par File/Write Strings (Ctrl+Shift+W) @@ -640,7 +635,7 @@ the current file. \par The output file name is the same as the .fl file, -with the leading directory and trailing ".fl" +with the leading directory and trailing ".fl" stripped, and ".txt", ".po", or ".msg" appended depending on the \ref fluid_i18n "Internationalization Mode". @@ -659,7 +654,7 @@ recover from any mistakes you make. \par Edit/Cut (Ctrl+x) \par -Deletes the selected widgets and all of their children. +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. @@ -669,7 +664,7 @@ pasted back into any FLUID window. Copies the selected widgets and all of their children to the "clipboard" file. -\par Edit/Paste (Ctrl+c) +\par Edit/Paste (Ctrl+v) \par Pastes the widgets from the clipboard file. @@ -680,7 +675,7 @@ is selected, or contained in the current selection. \par 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 is selected. If none is, it is added to the window or group that is the parent of the current selection. \par @@ -698,7 +693,7 @@ Selects all widgets in the same group as the current selection. \par If they are all selected already then this selects all -widgets in that group's parent. Repeatedly typing Ctrl+a will +widgets in that group's parent. Repeatedly typing Ctrl+a will select larger and larger groups of widgets until everything is selected. @@ -712,20 +707,19 @@ shown instead. \par Edit/Sort \par -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. +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. \par Edit/Earlier (F2) \par Moves all of the selected widgets one earlier in order among -the children of their parent (if possible). This will affect +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 +one. You can also use this to reorder functions, classes, and windows within functions. \par Edit/Later (F3) @@ -750,8 +744,8 @@ selected. \par 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 +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. \par Edit/Project Settings... (Alt+p) @@ -798,26 +792,26 @@ At the lower-right, "User Settings" causes changes to only affect the current us \par New/Code/Function \par -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 +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. \par 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 +declared as returning an 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 (\c void ). \par It is possible to make the .cxx output be a -self-contained program that can be compiled and executed. This -is done by deleting the function name so -\p main(argc,argv) is used. The function will call +self-contained program that can be compiled and executed. This +is done by deleting the function name so +\p main(argc,argv) is used. The function will call \p show() on all the windows it creates and then call -\p Fl::run(). This can also be used to test resize -behavior or other parts of the user interface. +\p Fl::run(). This can also be used to test resize +behavior or other parts of the user interface. \par You can change the function name by double-clicking on the @@ -826,9 +820,9 @@ function. \par New/Window \par -Creates a new Fl_Window widget. The window is added -to the currently selected function, or to the function -containing the currently selected item. The window will appear, +Creates a new Fl_Window 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. @@ -840,9 +834,9 @@ this chapter. \par All other items on the New menu are subclasses of -Fl_Widget. Creating them will add them to the +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 +containing the currently selected widget. The initial dimensions and position are chosen by copying the current widget, if possible. @@ -850,23 +844,23 @@ widget, if possible. When you create the widget you will get the widget's control panel, which is described later in this chapter. -\par Layout/Align/... +\par Layout/Align/... \par Align all selected widgets to the first widget in the selection. -\par Layout/Space Evenly/... +\par Layout/Space Evenly/... \par Space all selected widgets evenly inside the selected space. Widgets will be sorted from first to last. -\par Layout/Make Same Size/... +\par Layout/Make Same Size/... \par Make all selected widgets the same size as the first selected widget. -\par Layout/Center in Group/... +\par Layout/Center in Group/... \par Center all selected widgets relative to their parent widget @@ -874,7 +868,7 @@ Center all selected widgets relative to their parent widget \par Layout/Grid and Size Settings... (Ctrl+g) \par -Displays the grid settings panel. +Displays the grid settings panel. \par This panel controls the grid that all widgets snap to when you move @@ -922,20 +916,20 @@ red overlay so you can see the widgets more accurately, especially when setting the box type. If you have several widgets selected, they may have different -values for the fields. In this case the value for \e one of -the widgets is shown. But if you change this value, \e all +values for the fields. In this case the value for \e one of +the widgets is shown. But if you change this value, \e all of the selected widgets are changed to the new value. -Hitting "OK" makes the changes permanent. -Selecting a different widget also makes the changes permanent. +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. "Revert" or "Cancel" put everything back -to when you last brought up the panel or hit OK. However in the +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 +revert or cancel. Changes to code like the callbacks are undone, however. @@ -962,7 +956,7 @@ can be added to the label using the at sign ("@"). \par Label (pull down menu) \par -How to draw the label. Normal, shadowed, engraved, and +How to draw the label. Normal, shadowed, engraved, and embossed change the appearance of the text. \par Image @@ -982,7 +976,7 @@ chooser. \par Alignment (buttons) \par -Where to draw the label. The arrows put it on that side of the +Where to draw the label. The arrows put it on that side of the widget, you can combine them to put it in the corner. The "box" button puts the label inside the widget, rather than outside. @@ -1014,7 +1008,7 @@ shortcut button and press any key sequence to set the shortcut. \par The \b Visible button controls whether the widget is -visible (on) or hidden (off) initially. Don't change this for +visible (on) or hidden (off) initially. Don't change this for windows or for the immediate children of a Tabs group. \par @@ -1025,19 +1019,19 @@ appear greyed out when deactivated. \par The \b Resizable button controls whether the window is resizeable. In addition all the size changes of a window or -group will go "into" the resizable child. If you have +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. 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 +using hierarchies of groups. Unfortunately the only way to test +it is to compile the program. Resizing the FLUID window is \e not the same as what will happen in the user program. \par The \b Hotspot button causes the parent window to be -positioned with that widget centered on the mouse. This +positioned with that widget centered on the mouse. This position is determined when the FLUID function is called, -so you should call it immediately before showing the window. If +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 \p show(). @@ -1051,7 +1045,7 @@ window and reopen it to see the effect. \par The string typed into here is passed to the X window manager -as the class. This can change the icon or window decorations. +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. @@ -1063,7 +1057,7 @@ and reopen it to see the effect. \par Label Font (pulldown menu) \par -Font to draw the label in. Ignored by symbols, bitmaps, and +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. @@ -1071,14 +1065,14 @@ provided. \par Label Size (pulldown menu) \par -Pixel size (height) for the font to draw the label in. -Ignored by symbols, bitmaps, and pixmaps. To see the result +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. \par Label Color (button) \par -Color to draw the label. Ignored by pixmaps (bitmaps, +Color to draw the label. Ignored by pixmaps (bitmaps, however, do use this color as the foreground color). \par Box (pulldown menu) @@ -1088,15 +1082,15 @@ The boxtype to draw as a background for the widget. \par Many widgets will work, and draw faster, with a -"frame" instead of a "box". A frame does +"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 +there visible. Be careful, as FLUID may draw this ok but the real program may leave unwanted stuff inside the widget. \par 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 +"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. @@ -1115,7 +1109,7 @@ The color to draw the box with. \par Select Color (button) \par -Some widgets will use this color for certain parts. FLUID +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. @@ -1135,23 +1129,22 @@ menus, and browsers. \par This is how you use your own subclasses of -Fl_Widget. Whatever identifier you type in here will +Fl_Widget. Whatever identifier you type in here will be the class that is instantiated. \par In addition, no \p \#include header file is put in the -.h file. You must provide a \p \#include line as +.h file. You must provide a \p \#include line as the first line of the "Extra Code" which declares your subclass. \par -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 -\code #include \endcode -to the extra code. +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. For windows you can select either +\p Single or \p Double in the drop-down box right to the "Class:" field +to get a normal window (Fl_Window) or a double-buffered window +(Fl_Double_Window), respectively. \par Type (upper-right pulldown menu) @@ -1163,13 +1156,13 @@ You pick the subtype off of this menu. \par Name of a variable to declare, and to store a pointer to this -widget into. This variable will be of type "*". If the name is +widget into. This variable will be of type "*". If the name is blank then no variable is created. \par -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 +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 in the array must be the same type. \par Public (button) @@ -1195,16 +1188,15 @@ include line occurs several times then only one copy is written. \par -All other lines are "code" lines. The current -widget is pointed to by the local variable \p o. The +All other lines are "code" lines. The current +widget is pointed to by the local variable \p o. The window being constructed is pointed to by the local variable -\p w. You can also access any arguments passed to the -function here, and any named widgets that are before this -one. +\p w. You can also access any arguments passed to the +function here, and any named widgets that are before this one. \par FLUID will check for matching parenthesis, braces, and -quotes, but does not do much other error checking. Be careful +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 .cxx @@ -1218,17 +1210,17 @@ of code. If you enter anything other than letters, numbers, and the underscore then FLUID treats it as code. \par -A name refers to a function in your own code. It must be +A name refers to a function in your own code. It must be declared as void name(*,void*). \par A code snippet is inserted into a static function in the -.cxx output file. The function prototype is +.cxx output file. The function prototype is void name(class *o, void *v) so that you can refer to the widget as \p o and the \p user_data() -as \p 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 +as \p 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. \par @@ -1237,8 +1229,8 @@ If the callback is blank then no callback is set. \par User Data (text field) \par -This is a value for the \p user_data() of the widget. -If blank the default value of zero is used. This can be any +This is a value for the \p 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 cast to a \p void pointer. \par Type (text field) @@ -1246,7 +1238,7 @@ piece of C code that can be cast to a \p void pointer. \par The \p void* in the callback function prototypes is replaced with this. You may want to use \p long for old -XForms code. Be warned that anything other than \p void* +XForms code. Be warned that anything other than \p void* is not guaranteed to work! However on most architectures other pointer types are ok, and \p long is usually ok, too. @@ -1271,39 +1263,39 @@ matching event even if the data is not changed. \section fluid_selecting_moving Selecting and Moving Widgets Double-clicking a window name in the browser will display it, -if not displayed yet. From this display you can select widgets, -sets of widgets, and move or resize them. To close a window +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 \c ESC. To select a widget, click it. To select several widgets drag -a rectangle around them. Holding down shift will toggle the +a rectangle around them. Holding down shift will toggle the selection of the widgets instead. -You cannot pick hidden widgets. You also cannot choose some -widgets if they are completely overlapped by later widgets. Use +You cannot pick hidden widgets. You also cannot choose some +widgets if they are completely overlapped by later widgets. Use the browser to select these widgets. The selected widgets are shown with a red "overlay" -line around them. You can move the widgets by dragging this -box. Or you can resize them by dragging the outer edges and -corners. Hold down the Alt key while dragging the mouse to +line around them. You can move the widgets by dragging this +box. Or you can resize them by dragging the outer edges and +corners. Hold down the Alt key while dragging the mouse to defeat the snap-to-grid effect for fine positioning. If there is a tab box displayed you can change which child is -visible by clicking on the file tabs. The child you pick is +visible by clicking on the file tabs. The child you pick is selected. The arrow, tab, and shift+tab keys "navigate" the -selection. Left, right, tab, or shift+tab move to the next or -previous widgets in the hierarchy. Hit the right arrow enough -and you will select every widget in the window. Up/down widgets -move to the previous/next widgets that overlap horizontally. If +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 +"Sort" the widgets. This is important if you have input fields, as FLTK uses the same rules when using arrow keys to move between input fields. -To "open" a widget, double click it. To open +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. @@ -1311,16 +1303,16 @@ Type Ctrl+o to temporarily toggle the overlay off without changing the selection, so you can see the widget borders. You can resize the window by using the window manager border -controls. FLTK will attempt to round the window size to the +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!). +so it is possible it will barf with some window managers!). Notice that the actual window in your program may not be resizable, and if it is, the effect on child widgets may be different. The panel for the window (which you get by double-clicking -it) is almost identical to the panel for any other Fl_Widget. +it) is almost identical to the panel for any other Fl_Widget. There are three extra items: \section fluid_images Image Labels @@ -1412,7 +1404,7 @@ and the KDE icon editor. \par FLUID reads Windows BMP image files which are often used in Windows applications for icons. FLUID converts BMP files into -(modified) XPM format and uses a Fl_BMP_Image image to label the +(modified) XPM format and uses an Fl_BMP_Image image to label the widget. Transparency is handled the same as for XPM files. All image data is uncompressed when written to the source file, so the code may be much bigger than the .bmp file. @@ -1422,7 +1414,7 @@ the code may be much bigger than the .bmp file. \par FLUID reads GIF image files which are often used in HTML documents to make icons. FLUID converts GIF files into -(modified) XPM format and uses a Fl_GIF_Image image to label the +(modified) XPM format and uses an Fl_GIF_Image image to label the widget. Transparency is handled the same as for XPM files. All image data is uncompressed when written to the source file, so the code may be much bigger than the .gif file. Only @@ -1433,7 +1425,7 @@ the first image of an animated GIF file is used. \par If FLTK is compiled with JPEG support, FLUID can read JPEG image files which are often used for digital photos. FLUID uses -a Fl_JPEG_Image image to label the widget, and writes +an Fl_JPEG_Image image to label the widget, and writes uncompressed RGB or grayscale data to the source file. \par PNG (Portable Network Graphics) Files @@ -1451,8 +1443,7 @@ this as best as possible on each platform. \par Fluid can store a number of project templates. Project templates are great for storing often used boilerplate code for fast access. -A common use would be projects with readily prepared copyright -messages. +A common use would be projects with readily prepared copyright messages. \par A sample template for FLTK projects is included with Fluid. @@ -1460,17 +1451,17 @@ A sample template for FLTK projects is included with Fluid. \par Choose "File > New From Template..." to create a new project based on a template file. In the template dialog, select one of -the existing templates. All occurrences of the word -"@INSTANCE@" in the template are replaced with the text in +the existing templates. All occurrences of the word +"@INSTANCE@" in the template are replaced with the text in the "Instance" field. To create the new project click "New". \par -To add your current project as a new template, choose +To add your current project as a new template, choose "File > Save As Template...", fill in a name, and click "Save". \par -To delete a template, open the template dialog using -"New from Template" or "Save As Template", the select any +To delete a template, open the template dialog using +"New from Template" or "Save As Template", then select any existing template, and click "Delete Template". \section fluid_i18n Internationalization with FLUID @@ -1550,7 +1541,7 @@ file to be used for all of the windows defined in your The \b Set: field controls the set number in the catalog file. The default set is 1 and rarely needs to be changed. -\section fluid_limitations Known limitations +\section fluid_limitations Known Limitations Declaration Blocks can be used to temporarily block out already designed code using \#if 0 and \#endif