From fd791a068e39e06785adc44693f4c533d3d6c903 Mon Sep 17 00:00:00 2001 From: Matthias Melcher Date: Wed, 17 Apr 2024 17:51:32 +0200 Subject: Separate FLUID user documentation, screen shot automation (#936) * CMake integration, no autotiools * alignment panel is now correctly renamed to setting panel * source view is now correctly renamed to code view * Merge FLTK FLUID docs into FLUID user manual. * Add two simple entry tutorials * Remove FLUID chapter form FLTK docs. * GitHub action to generate HTML and PDF docs and make the available as artefacts --- documentation/src/cubeview.png | Bin 4482 -> 0 bytes documentation/src/examples.dox | 16 +- documentation/src/fltk-options.dox | 8 +- documentation/src/fltk-options.png | Bin 0 -> 160099 bytes documentation/src/fluid-catgets.png | Bin 40651 -> 0 bytes .../src/fluid-edit-global-fltk-settings.png | Bin 160099 -> 0 bytes documentation/src/fluid-edit-gui-settings.png | Bin 70258 -> 0 bytes documentation/src/fluid-edit-proj-settings.png | Bin 55000 -> 0 bytes documentation/src/fluid-gettext.png | Bin 44085 -> 0 bytes .../src/fluid-layout-grid-and-size-settings.png | Bin 88526 -> 0 bytes documentation/src/fluid-org.png | Bin 27580 -> 0 bytes documentation/src/fluid-org.xcf | Bin 110511 -> 0 bytes documentation/src/fluid.dox | 1760 -------------------- documentation/src/fluid1.png | Bin 48759 -> 0 bytes documentation/src/fluid2.png | Bin 117079 -> 0 bytes documentation/src/fluid3-cxx.png | Bin 54533 -> 0 bytes documentation/src/fluid3-gui.png | Bin 77268 -> 0 bytes documentation/src/fluid3-style.png | Bin 52943 -> 0 bytes documentation/src/fluid4.png | Bin 36419 -> 0 bytes documentation/src/fluid_widget_cxx.png | Bin 55645 -> 0 bytes documentation/src/fluid_widget_gui.png | Bin 32441 -> 0 bytes documentation/src/fluid_widget_style.png | Bin 54373 -> 0 bytes documentation/src/index.dox | 5 - documentation/src/intro.dox | 11 + documentation/src/opengl.dox | 8 +- documentation/src/osissues.dox | 2 +- documentation/src/preface.dox | 1 - documentation/src/subclassing.dox | 4 +- 28 files changed, 28 insertions(+), 1787 deletions(-) delete mode 100644 documentation/src/cubeview.png create mode 100644 documentation/src/fltk-options.png delete mode 100644 documentation/src/fluid-catgets.png delete mode 100644 documentation/src/fluid-edit-global-fltk-settings.png delete mode 100644 documentation/src/fluid-edit-gui-settings.png delete mode 100644 documentation/src/fluid-edit-proj-settings.png delete mode 100644 documentation/src/fluid-gettext.png delete mode 100644 documentation/src/fluid-layout-grid-and-size-settings.png delete mode 100644 documentation/src/fluid-org.png delete mode 100644 documentation/src/fluid-org.xcf delete mode 100644 documentation/src/fluid.dox delete mode 100644 documentation/src/fluid1.png delete mode 100644 documentation/src/fluid2.png delete mode 100644 documentation/src/fluid3-cxx.png delete mode 100644 documentation/src/fluid3-gui.png delete mode 100644 documentation/src/fluid3-style.png delete mode 100644 documentation/src/fluid4.png delete mode 100644 documentation/src/fluid_widget_cxx.png delete mode 100644 documentation/src/fluid_widget_gui.png delete mode 100644 documentation/src/fluid_widget_style.png (limited to 'documentation/src') diff --git a/documentation/src/cubeview.png b/documentation/src/cubeview.png deleted file mode 100644 index 877be186c..000000000 Binary files a/documentation/src/cubeview.png and /dev/null differ diff --git a/documentation/src/examples.dox b/documentation/src/examples.dox index fa7bcd9e3..992b85523 100644 --- a/documentation/src/examples.dox +++ b/documentation/src/examples.dox @@ -252,7 +252,7 @@ and shows OpenGL text. \subsection examples_CubeView CubeView \par -\c CubeView shows how to create a UI containing OpenGL with Fluid. +\c CubeView shows how to create a UI containing OpenGL with FLUID. \subsection examples_cursor cursor @@ -577,7 +577,7 @@ come in handy. They remember any kind of data between program launches. \subsection examples_radio radio \par -The \c radio tool was created entirely with fluid. It +The \c radio tool was created entirely with FLUID. It shows some of the available button types and tests radio button behavior. @@ -658,7 +658,7 @@ The \c table demo shows the features of the Fl_Table widget. \subsection examples_tabs tabs \par -The \c tabs tool was created with fluid. It tests +The \c tabs tool was created with FLUID. It tests correct hiding and redisplaying of tabs, navigation across tabs, resize behavior, and no unneeded redrawing of invisible widgets. @@ -733,13 +733,13 @@ font draws each of the Unicode code points ranging between U+0020 and U+FFFF. while the focus stays in the original window. -\subsection examples_fluid fluid +\subsection examples_fluid FLUID \par -\c fluid is not only a big test program, but also a very -useful visual UI designer. Many parts of \c fluid were -created using \c fluid. See the \link fluid Fluid Tutorial \endlink -for more details. +\c FLUID is not only a big test program, but also a very +useful visual UI designer. Many parts of \c FLUID were +created using \c FLUID. Check out the FLUID User Manual and +the tutorials that come with it at https://www.fltk.org/documentation.php . diff --git a/documentation/src/fltk-options.dox b/documentation/src/fltk-options.dox index 047801507..20365d12c 100644 --- a/documentation/src/fltk-options.dox +++ b/documentation/src/fltk-options.dox @@ -41,8 +41,8 @@ tool called fltk-options. `fltk-options` is a hybrid app that is part of FLTK and can be installed on the target system. It includes an up-to-date man page. -\image html fluid-edit-global-fltk-settings.png "fltk-options Application" -\image latex fluid-edit-global-fltk-settings.png "fltk-options Application" width=10cm +\image html fltk-options.png "fltk-options Application" +\image latex fltk-options.png "fltk-options Application" width=10cm When fltk-options is called without any command-line arguments, it opens in interactive mode and provides a user interface to view and alter all @@ -67,9 +67,9 @@ A full list of options can be found in the manual at Fl::Fl_Option. diff --git a/documentation/src/osissues.dox b/documentation/src/osissues.dox index faf7178b7..43e29463e 100644 --- a/documentation/src/osissues.dox +++ b/documentation/src/osissues.dox @@ -968,7 +968,7 @@ internally in the same way. \subsection osissues_mac_files Mac File System Specifics -\par Resource Forks +\par Resource Forks (OS X pre 10.6) FLTK does not access the resource fork of an application. However, a minimal resource fork must be created for OS X diff --git a/documentation/src/preface.dox b/documentation/src/preface.dox index 67304fbd2..0bfc54c55 100644 --- a/documentation/src/preface.dox +++ b/documentation/src/preface.dox @@ -31,7 +31,6 @@ This manual is organized into the following chapters and appendices: \li \ref events \li \ref subclassing \li \ref opengl -\li \ref fluid \li \ref fltk-options \li \ref advanced \li \ref unicode diff --git a/documentation/src/subclassing.dox b/documentation/src/subclassing.dox index bbf750b15..e37924bf9 100644 --- a/documentation/src/subclassing.dox +++ b/documentation/src/subclassing.dox @@ -40,9 +40,7 @@ The constructor should have the following arguments: MyClass(int x, int y, int w, int h, const char *label = 0); \endcode -This will allow the class to be used in -\ref fluid "FLUID" -without problems. +This will allow the class to be used in FLUID without problems. The constructor must call the constructor for the base class and pass the same arguments: -- cgit v1.2.3
- + [Prev] - Programming with FLUID + Using OpenGL diff --git a/documentation/src/fltk-options.png b/documentation/src/fltk-options.png new file mode 100644 index 000000000..fc9bd1d40 Binary files /dev/null and b/documentation/src/fltk-options.png differ diff --git a/documentation/src/fluid-catgets.png b/documentation/src/fluid-catgets.png deleted file mode 100644 index e68b42c96..000000000 Binary files a/documentation/src/fluid-catgets.png and /dev/null differ diff --git a/documentation/src/fluid-edit-global-fltk-settings.png b/documentation/src/fluid-edit-global-fltk-settings.png deleted file mode 100644 index fc9bd1d40..000000000 Binary files a/documentation/src/fluid-edit-global-fltk-settings.png and /dev/null differ diff --git a/documentation/src/fluid-edit-gui-settings.png b/documentation/src/fluid-edit-gui-settings.png deleted file mode 100644 index ce3cadc9d..000000000 Binary files a/documentation/src/fluid-edit-gui-settings.png and /dev/null differ diff --git a/documentation/src/fluid-edit-proj-settings.png b/documentation/src/fluid-edit-proj-settings.png deleted file mode 100644 index 0b44bb199..000000000 Binary files a/documentation/src/fluid-edit-proj-settings.png and /dev/null differ diff --git a/documentation/src/fluid-gettext.png b/documentation/src/fluid-gettext.png deleted file mode 100644 index 70845f035..000000000 Binary files a/documentation/src/fluid-gettext.png and /dev/null differ diff --git a/documentation/src/fluid-layout-grid-and-size-settings.png b/documentation/src/fluid-layout-grid-and-size-settings.png deleted file mode 100644 index a9f441fd9..000000000 Binary files a/documentation/src/fluid-layout-grid-and-size-settings.png and /dev/null differ diff --git a/documentation/src/fluid-org.png b/documentation/src/fluid-org.png deleted file mode 100644 index dd464597c..000000000 Binary files a/documentation/src/fluid-org.png and /dev/null differ diff --git a/documentation/src/fluid-org.xcf b/documentation/src/fluid-org.xcf deleted file mode 100644 index 09e98e67c..000000000 Binary files a/documentation/src/fluid-org.xcf and /dev/null differ diff --git a/documentation/src/fluid.dox b/documentation/src/fluid.dox deleted file mode 100644 index ebfdaaafe..000000000 --- a/documentation/src/fluid.dox +++ /dev/null @@ -1,1760 +0,0 @@ -/** - - - - - \page fluid Programming with FLUID - -This chapter shows how to use the Fast Light User-Interface Designer -("FLUID") to create your GUIs. - -Subchapters: - -\li \ref fluid_what_is_fluid -\li \ref fluid_fluid_under_unix -\li \ref fluid_fluid_under_windows -\li \ref fluid_compiling_fl_files -\li \ref fluid_tutorial -\li \ref fluid_references -\li \ref fluid_templates -\li \ref fluid_i18n -\li \ref fluid_limitations -\li \ref fluid_hotkeys -\li \ref fluid_licenses - -\section fluid_what_is_fluid What is FLUID? - -The Fast Light User Interface Designer, or FLUID, is a -graphical editor that is used to produce FLTK source code. FLUID -edits and saves its state in .fl files. These files -are text, and you can (with care) edit them in a text editor, -perhaps to get some special effects. The .fl file format is explained -in detail in fluid/README_fl.txt - -FLUID can "compile" the .fl file into a -.cxx and a .h file. The .cxx file -defines all the objects from the .fl file and the -.h file declares all the global ones. FLUID also -supports localization (\ref fluid_i18n "Internationalization") -of label strings and tooltips using message files and the GNU gettext or -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 -this, so you write other .cxx files that call the FLUID functions. -These .cxx files must -\p \#include -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 "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. - -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. - -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 .cxx file. - -\section fluid_fluid_under_unix Running FLUID Under UNIX - -To run FLUID under UNIX, type: - -\code -fluid filename.fl & -\endcode - -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 -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: - -\code --display host:n.n --geometry WxH+X+Y --title windowtitle --name classname --iconic --fg color --bg color --bg2 color --scheme schemename -\endcode - -Changing the colors may be useful to see what your interface -will look at if the user calls it with the same switches. -Similarly, using "-scheme plastic" will show how the interface -will look using the "plastic" scheme. - -In the current version, if you don't put FLUID into the -background with '&' then you will be able to abort FLUID by -typing CTRL-C on the terminal. It will exit -immediately, losing any changes. - -\section fluid_fluid_under_windows Running FLUID Under Microsoft Windows - -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 - -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: - -\code -fluid -c filename.fl -\endcode - -This is the same as the menu 'File/Write Code...'. -It will read the filename.fl file and write -filename.cxx and filename.h. Any leading -directory on filename.fl will be stripped, so they are -always written to the current directory. If there are any errors -reading or writing the files, FLUID will print the error and -exit with a non-zero code. You can use the following lines in a -makefile to automate the creation of the source and header -files: - -\code -my_panels.h my_panels.cxx: my_panels.fl - fluid -c my_panels.fl -\endcode - -Most versions of make support rules that cause .fl -files to be compiled: - -\code -.SUFFIXES: .fl .cxx .h -.fl.h .fl.cxx: - fluid -c $< -\endcode - -If you use - -\code -fluid -cs filename.fl -\endcode - -FLUID will also write the "strings" for internationalization in file -'filename.txt' (menu: 'File/Write Strings...'). - -Finally there is another option which is useful for program developers -who have many .fl files and want to upgrade them to the current FLUID -version. FLUID will read the \p filename.fl file, save it, and exit -immediately. This writes the file with current syntax and options and -the current FLTK version in the header of the file. Use - -\code -fluid -u filename.fl -\endcode - -to 'upgrade' \p filename.fl . You may combine this with '-c' or '-cs'. - -\note All these commands overwrite existing files w/o warning. You should -particularly take care when running 'fluid -u' since this overwrites the -original .fl source file. - - -\section fluid_tutorial A Short Tutorial - -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 provided with FLTK. - -\image html cubeview.png "CubeView demo" -\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. - -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 callback member functions of custom widget classes. --# Subclass an Fl_Gl_Window to suit your purposes. - -\subsection fluid_cubeview The CubeView Class - -The CubeView class is a subclass of Fl_Gl_Window. It has methods for -setting the zoom, the \e x and \e y pan, and the rotation angle -about the \e x and \e y axes. - -You can safely skip this section as long as you realize that CubeView -is a sublass of Fl_Gl_Window and will respond to calls from -CubeViewUI, generated by FLUID. - -\par The CubeView Class Definition - -Here is the CubeView class definition, as given by its header file -"test/CubeView.h": -
- - -\code -#include -#include -#include - -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(double angle) { vAng = angle; } - - // Return the rotation about the vertical (y) axis. - double v_angle() const { 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(double angle) { hAng = angle; } - - // The rotation about the horizontal (x) axis. - double h_angle() const { 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(double 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(double y) { yshift = y; } - - /* The widget class draw() override. - * - * The draw() function initializes 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. - */ - void drawCube(); - - double vAng, hAng; - double 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]; -}; -\endcode - -\par The CubeView Class Implementation - -Here is the CubeView implementation. It is very similar to the -"CubeView" demo included with FLTK. -
- - -\code -#include "CubeView.h" -#include - -CubeView::CubeView(int x, int y, int w, int h, const char *l) - : Fl_Gl_Window(x, y, w, h, l) -{ - Fl::use_high_res_GL(1); - vAng = 0.0; - hAng = 0.0; - size = 10.0; - xshift = 0.0; - yshift = 0.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; -} - -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, pixel_w(), pixel_h()); - glOrtho(-10, 10, -10, 10, -20050, 10000); - glEnable(GL_BLEND); - glBlendFunc(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA); - } - - glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); - - glPushMatrix(); - - glTranslatef((GLfloat)xshift, (GLfloat)yshift, 0); - glRotatef((GLfloat)hAng, 0, 1, 0); - glRotatef((GLfloat)vAng, 1, 0, 0); - glScalef(float(size), float(size), float(size)); - - drawCube(); - - glPopMatrix(); -} -\endcode - -\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. - -\par Defining the CubeViewUI Class - -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. - -\image html fluid1.png "FLUID file for CubeView" -\image latex fluid1.png "FLUID file for CubeView" width=10cm - -\par Adding the Class Constructor - -Click on the CubeViewUI class in the FLUID window and add a new method -by selecting New->Code->Function/Method. The name of the -function will also be CubeViewUI. FLUID will understand that this will -be the constructor for the class and will generate the appropriate -code. Make sure you declare the constructor public. - -Then add a window to the CubeViewUI class. Highlight the name of -the constructor in the FLUID browser window and click on -New->Group->Window. In a similar manner add the -following to the CubeViewUI constructor: - -\li A horizontal roller named \p hrot -\li A vertical roller named \p vrot -\li A horizontal slider named \p xpan -\li A vertical slider named \p ypan -\li A horizontal value slider named \p zoom - -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. - -When you are finished you should have something like this: - -\image html fluid2.png "FLUID window containing CubeView demo" -\image latex fluid2.png "FLUID window containing CubeView demo" width=10cm - -We will talk about the \p show() method that is highlighted -shortly. - -\par Adding the CubeView Widget - -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. - -The CubeView class inherits the Fl_Gl_Window class, which -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. - -In the Extra Code: field enter \#include "CubeView.h" - -This \p \#include is important, as we have just included -CubeView as a member of CubeViewUI, so any public CubeView methods are -now available to CubeViewUI. - -\image html fluid3-cxx.png "CubeView methods" -\image latex fluid3-cxx.png "CubeView methods" width=10cm - -\par Defining the Callbacks - -Each of the widgets we defined before adding CubeView can have -callbacks that call CubeView methods. You can call an external -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: - -\code -cube->pany(((Fl_Slider *)o)->value()); -cube->redraw(); -\endcode - -We call cube->redraw() 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. - -There is no reason to 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. - -\par Adding a Class Method - -You can add class methods within FLUID that have nothing to do with the -GUI. As an example add a show function so that CubeViewUI can actually -appear on the screen. - -Make sure the top level CubeViewUI is selected and select -New->Code->Function/Method. Just use the name -\p show(). 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 \p void. - -\image html fluid4.png "CubeView constructor" -\image latex fluid4.png "CubeView constructor" width=10cm - -Once the new method has been added, highlight its name and select -New->Code->Code. Enter the method's code in the code window. - -\subsection fluid_addconst Adding Constructor Initialization Code - -If you need to add code to initialize a class, for example setting -initial values of the horizontal and vertical angles in the -CubeView, you can simply highlight the constructor and select -New->Code->Code. Add any required code. - -\subsection fluid_gencode Generating the Code - -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 Edit->Preferences. - -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. - - - -\section fluid_references FLUID Reference - -The following sections describe each of the windows in FLUID. - -\subsection fluid_browser The Widget Browser - -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 -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 -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 -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 -layout, navigation, and resize purposes. Tab groups provide the -well-known file-card tab interface. - -Widgets are shown in the browser by either their \e name (such -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 -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. - -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 -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: - -\par File/Open... (Ctrl+o) - -\par -Discards the current editing session and reads in a different -.fl file. You are asked for confirmation if you have -changed the current file. - -\par -FLUID can also read .fd 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 .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 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 -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. - -\par File/Save (Ctrl+s) - -\par -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) - -\par -Asks for a new filename and saves the file. - -\par File/Save A Copy... - -\par -Save a copy of the .fl data to a different file. - -\par File/Revert... - -\par -Revert the .fl data to a previously saved state. - -\par File/New From Template... - -\par -Create a new user interface design from a previously saved template. -This can be useful for including a predefined enterprise copyright message -for projects, or for managing boilerplate code for repeating project code. - -\par File/Save As Template... - -\par -Save the current project as a starting point for future projects. - -\par File/Print... (Ctrl-P) - -\par -Generate a printout containing all currently open windows within your project. - -\par File/Write Code (Ctrl+Shift+C) - -\par -"Compiles" the data into a .cxx and .h -file. These are exactly the same as the files you get when you run -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 -".h" or ".cxx" appended. - -\par File/Write Strings (Ctrl+Shift+W) - -\par -Writes a message file for all of the text labels defined in -the current file. - -\par -The output file name is the same as the .fl file, -with the leading directory and trailing ".fl" -stripped, and ".txt", ".po", or ".msg" appended depending on the -\ref fluid_i18n "Internationalization Mode". - -\par File/Quit (Ctrl+q) - -\par -Exits FLUID. You are asked for confirmation if you have -changed the current file. - -\par Edit/Undo (Ctrl+z) and Redo (Shift+Ctrl+z) - -\par -FLUID saves the project state for undo and redo operations after every -major change. - -\par Edit/Cut (Ctrl+x) - -\par -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. - -\par Edit/Copy (Ctrl+c) - -\par -Copies the selected widgets and all of their children to the -"clipboard" file. - -\par Edit/Paste (Ctrl+v) - -\par -Pastes the widgets from the clipboard file. - -\par -If the widget is a window, it is added to whatever function -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 that is the parent of the current selection. - -\par -To avoid confusion, it is best to select exactly one widget -before doing a paste. - -\par -Cut/paste is the only way to change the parent of a -widget. - -\par Edit/Select All (Ctrl+a) - -\par -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 -select larger and larger groups of widgets until everything is -selected. - -\par Edit/Properties... (F1 or double click) - -\par -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. - -\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. - -\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 -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. - -\par Edit/Later (F3) - -\par -Moves all of the selected widgets one later in order among -the children of their parent (if possible). - -\par Edit/Group (F7) - -\par -Creates a new Fl_Group and make all the currently -selected widgets children of it. - -\par Edit/Ungroup (F8) - -\par -Deletes the parent group if all the children of a group are -selected. - -\par Edit/Show or Hide Overlays (Ctrl+Shift+O) - -\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 -change the selection. - -\par Edit/Show or Hide Guides (Ctrl+Shift+G) - -\par -Guides can be used to arrange a widget layout easily and consistently. They -indicating preferred widget positions and sizes with user definable margins, -grids, and gap sizes. See the "Layout" tab in the "Settings" dialog. - -\par -This menu item enables and disable guides and the snapping action when dragging -widgets and their borders. - -\par Edit/Show or Hide Restricted (Ctrl+Shift+R) - -\par -It is recommended to ensure that user interface elements within FLTK do not -exceed the size of their container group or overlap with each other. -By activating this button, a hatch pattern is enabled, visually highlighting -areas where restricted or undefined behavior may occur. - -\par Edit/Show or Hide Widget Bin (Alt+B) - -\par -The widget bin provides quick access to all widget types supported by FLUID. -Layouts can be created by clicking on elements in the widget bin, or by dragging -them from the bin to their position within the layout. This button shows or -hides the widget bin. - -\par Edit/Show or Hide Source Code (Shift+Alt+S) - -\par -This button shows or hides the source code preview window. Any change to the -layout or code in the layout editores can be previewed and verified immediatly -in the Code View window. - -\par Edit/Settings... (Alt+p) - -\par -Displays the FLUID settings panel. The settings panel contains tabs for -general FLUID settings, project setting, layout preferences, custom shell -commands, and the internationalisation settings for GNU Gettext -and POSIX catgets. - -\par -Under the "Project" tab you control the extensions or names of the files -that are generated by FLUID. If you check the "Include Header from Code" -button the code file will include the header file automatically. - -\par -Under the "Locale" tab are the \ref fluid_i18n "internationalization" -options, described later in this chapter. - -\image html fluid-edit-gui-settings.png "FLUID General Settings Tab" -\image latex fluid-edit-gui-settings.png "FLUID General Settings Tab" width=10cm - -\image html fluid-edit-proj-settings.png "FLUID Project Settings Tab" -\image latex fluid-edit-proj-settings.png "FLUID Project Settings Tab" width=10cm - -\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 -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 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 -\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. - -\par -You can change the function name by double-clicking on the -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, -sized to 100x100. You can resize it to whatever size you -require. - -\par -The widget panel will also appear and is described later in -this chapter. - -\par New/... - -\par -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. - -\par -When you create the widget you will get the widget's control -panel, which is described later in this chapter. - -\par Layout/Align/... - -\par -Align all selected widgets to the first widget in the selection. - -\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 -Make all selected widgets the same size as the first selected widget. - -\par Layout/Center in Group/... - -\par -Center all selected widgets relative to their parent widget - -\par Layout/Grid and Size Settings... (Ctrl+g) - -\par -Displays the grid settings panel. - -\par -This panel controls dimensions 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. - -Layout preferences are defined using margins to parent groups and window, gaps -between widget, and /orr by overlaying a grid over a group or window. A layout -comes as a suite of three presets, one for the main application window, one -for dialog boxes, and one for toolboxes. - -FLUID comes with two include layout suites. `FLTK` was used to design FLUID and -other included apps, and `Grid` is a more ridgid grid layout. Users can add -more suites, import and export them, and include them into their .fl -project files. - -\image html fluid-layout-grid-and-size-settings.png "FLUID Layout/Grid Settings Window" -\image latex fluid-layout-grid-and-size-settings.png "FLUID Layout/Grid Settings Window" width=10cm - -\par Shell/Execute Command... (Alt+x) - -\par -Displays the shell command panel. The shell command -is commonly used to run a 'make' script to compile the FLTK output. - -\par Shell/Execute Again (Alt+g) - -\par -Run the shell command again. - -\par Help/Repid development with FLUID - -\par -Shows this chapter of the manual. - -\par Help/FLTK Programmers Manual - -\par -Shows the contents page of the manual - -\par Help/About FLUID - -\par -Pops up a panel showing the version of FLUID. - -\subsection fluid_widget_panel The Widget Panel - -When you double-click on a widget or a set of widgets you -will get the "widget attribute panel". - -When you change attributes using this panel, the changes are -reflected immediately in the window. It is useful to hit the -"Hide Overlays" button (or type Ctrl+Shift+O) to hide the -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 -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. -FLUID checks for simple syntax errors such as mismatched -parenthesis in any code before saving any text. - - - -\image html fluid_widget_gui.png "The FLUID widget GUI attributes" -\image latex fluid_widget_gui.png "The FLUID widget GUI attributes" width=10cm - -\section fluid_widget_attributes GUI Attributes - -\par Not all fields in the Widget attributes dialog will be visible -for all types of widgets. - -\par Label (text field) - -\par -String to print next to or inside the button. You can put -newlines into the string to make multiple lines. The easiest way -is by typing Ctrl+j. - -\par -\ref common_labels "Symbols" -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 -embossed change the appearance of the text. - -\par Image - -\par -The active image for the widget. Click on the -\b Browse... button to pick an image file using the file -chooser. - -\par Inactive - -\par -The inactive image for the widget. Click on the -\b Browse... button to pick an image file using the file -chooser. - -\par Alignment (buttons) - -\par -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. - -\par -The \b clip button clips the label to the widget box, the -\b wrap button wraps any text in the label, and the -text image button puts the text over the image instead of under -the image. - -\par Position (text fields) - -\par -The position fields show the current position and size of the -widget box. Enter new values to move and/or resize a widget. - -\par -These fields understand basic math and variables. -Appending +10 to the X coordinate will move a widget 10 units -to the right without having to reenter the value. -Entering the formula w+3 in the Width field will widen all -selected Widgets by 3 units. -The formula py+i*20 in the Y field will order all selected -widgets vertically in their group by increments of 20 units. - -\par - - - - - - - -
NameValue
`i` zero based counter of selected widgets
`x`, `y`, `w`, `h` position and size of the current widget
`px`, `py`, `pw`, `ph` dimensions of the parent widget
`sx`, `sy`, `sw`, `sh` dimensions of the previous sibling
`cx`, `cy`, `cw`, `ch` bounding box of all children
- -\par Values (text fields) - -\par -The values and limits of the current widget. Depending on the -type of widget, some or all of these fields may be inactive. - -\par Shortcut - -\par -The shortcut key to activate the widget. Click on the -shortcut button and press any key sequence to set the shortcut. - -\par Attributes (buttons) - -\par -The \b Visible button controls whether the widget is -visible (on) or hidden (off) initially. Don't change this for -windows or for the immediate children of a Tabs group. - -\par -The \b Active button controls whether the widget is -activated (on) or deactivated (off) initially. Most widgets -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 -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 -\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 -position is determined when the FLUID function is called, -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(). - -\par -The \b Border 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. - -\par X Class (text field) - -\par -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. - -\image html fluid_widget_style.png "The FLUID widget Style attributes" -\image latex fluid_widget_style.png "The FLUID widget Style attributes" width=10cm - -\subsection fluid_style_attributes Style Attributes - -\par Label Font (pulldown menu) - -\par -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. - -\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 -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, -however, do use this color as the foreground color). - -\par Box (pulldown menu) - -\par -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 -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. - -\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 -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. - -\par Down Box (pulldown menu) - -\par -The boxtype to draw when a button is pressed or for some -parts of other widgets like scrollbars and valuators. - -\par Color (button) - -\par -The color to draw the box with. - -\par Select Color (button) - -\par -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. - -\par Text Font, Size, and Color - -\par -Some widgets display text, such as input fields, pull-down -menus, and browsers. - -\image html fluid_widget_cxx.png "The FLUID widget C++ attributes" -\image latex fluid_widget_cxx.png "The FLUID widget C++ attributes" width=10cm - -\subsection fluid_cpp_attributes C++ Attributes - -\par Class - -\par -This is how you use your own subclasses of -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 -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. 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) - -\par -Some classes have subtypes that modify their appearance or behavior. -You pick the subtype off of this menu. - -\par Name (text field) - -\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 -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 -in the array must be the same type. - -\par Public (button) - -\par -Controls whether the widget is publicly accessible. When -embedding widgets in a C++ class, this controls whether the -widget is \p public or \p private in the class. -Otherwise it controls whether the widget is declared -\p static or global (\p extern ). - -\par Extra Code (text fields) - -\par -These four fields let you type in literal lines of code to -dump into the .h or .cxx files. - -\par -If the text starts with a \# or the word -\p 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. - -\par -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. - -\par -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 .cxx -code. - -\par Callback (text field) - -\par -This can either be the name of a function, or a small snippet -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 -declared as void name(*,void*). - -\par -A code snippet is inserted into a static function in the -.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 -producing an error in the compiler. - -\par -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 -piece of C code that can be cast to a \p void pointer. - -\par Type (text field) - -\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* -is not guaranteed to work! However on most architectures other -pointer types are ok, and \p long is usually ok, too. - -\par When (pulldown menu) - -\par -When to do the callback. This can be \b Never, -\b Changed, \b Release, or \b Enter Key. The value of -Enter Key is only useful for text input fields. - -\par -There are other rare but useful values for the -\p when() field that are not in the menu. You should use -the extra code fields to put these values in. - -\par No Change (button) - -\par -The No Change button means the callback is done on the -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 -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 -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 -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 -defeat the snap-to-grid effect for fine positioning. - -If there is a tab box displayed you can change which child is -visible by clicking on the file tabs. The child you pick is -selected. - -The arrow, tab, and shift+tab keys "navigate" the -selection. Left, right, tab, or shift+tab move to the next or -previous 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. - -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. - -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 -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. - -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: - -\section fluid_images Image Labels - -The \e contents of the image files in the \b Image -and \b Inactive text fields are written to the .cxx -file. If many widgets share the same image then only one copy is -written. Since the image data is embedded in the generated -source code, you need only distribute the C++ code and not the -image files themselves. - -However, the \e filenames are stored in the .fl -file so you will need the image files as well to read the -.fl file. Filenames are relative to the location of the -.fl file and not necessarily the current directory. We -recommend you either put the images in the same directory as the -.fl file, or use absolute path names. - -\par Notes for All Image Types - -\par -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. - -\par -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. - -\par -If you edit an image at the same time you are using it in FLUID, -the only way to convince FLUID to read the image file again is to -remove the image from all widgets that are using it or re-load the -.fl file. - -\par -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. - -\par -To more accurately place images, make a new "box" -widget and put the image in that as the label. - -\par XBM (X Bitmap) Files - -\par -FLUID reads X bitmap files which use C source code to define -a bitmap. Sometimes they are stored with the ".h" or -".bm" extension rather than the standard -".xbm" extension. - -\par -FLUID writes code to construct an Fl_Bitmap image 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 this color in the -FLUID widget attributes panel. The '0' bits are transparent. - -\par -The program "bitmap" on the X distribution does an -adequate job of editing bitmaps. - -\par XPM (X Pixmap) Files - -\par -FLUID reads X pixmap files as used by the \p libxpm -library. These files use C source code to define a pixmap. The -filenames usually have the ".xpm" extension. - -\par -FLUID writes code to construct an Fl_Pixmap image 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. XPM files can -mark a single color as being transparent, and FLTK uses this -information to generate a transparency mask for the image. - -\par -We have not found any good editors for small iconic pictures. -For pixmaps we have used -XPaint -and the KDE icon editor. - -\par BMP Files - -\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 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. - -\par GIF Files - -\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 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 -the first image of an animated GIF file is used. - -\par JPEG Files - -\par -If FLTK is compiled with JPEG support, FLUID can read JPEG -image files which are often used for digital photos. FLUID uses -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 - -\par -If FLTK is compiled with PNG support, FLUID can read PNG -image files which are often used in HTML documents. FLUID uses a -Fl_PNG_Image image to label the widget, and writes uncompressed -RGB or grayscale data to the source file. PNG images can provide -a full alpha channel for partial transparency, and FLTK supports -this as best as possible on each platform. - -\section fluid_templates FLUID Templates - -\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. - -\par -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 "Instance" field. To create the new project click "New". - -\par -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", then select any -existing template, and click "Delete Template". - -\section fluid_i18n Internationalization with FLUID - -FLUID supports internationalization (I18N for short) of label -strings and tooltips used by widgets. The GNU gettext option also -supports deferred translation of statically initialised menu item -labels. The preferences window (Ctrl+p) provides access -to the I18N options. - -\subsection fluid_i18n_methods I18N Methods - -FLUID supports three methods of I18N: none, GNU -gettext, and POSIX catgets. The "none" method is the -default and just passes the label strings as-is to the widget -constructors. - -The "GNU gettext" method uses GNU gettext (or a similar -text-based I18N library) to retrieve a localized string before -calling the widget constructor. - -The "POSIX catgets" method uses the POSIX catgets function to -retrieve a numbered message from a message catalog before -calling the widget constructor. - -\subsection fluid_gettext_i18n Using GNU gettext for I18N - -FLUID's code support for GNU gettext is limited to calling a -function or macro to retrieve the localized label; you still -need to call \p setlocale() and \p textdomain() or -\p bindtextdomain() to select the appropriate language and -message file. - -To use GNU gettext for I18N, open the preferences window and -choose "GNU gettext" from the \b Use: chooser. Four new input -fields will then appear to control the include file and -function/macro names to use when retrieving localized label -strings in dynamic allocation and static initialisation. - - \image html fluid-gettext.png "Internationalization using GNU gettext" - \image latex fluid-gettext.png "Internationalization using GNU gettext" width=10cm - -The \b \#include -field controls the header file to include for -I18N; by default this is \b , the -standard I18N file for GNU gettext. - -If the \b Conditional: field contains a macro name, i18n will only be compiled -into the product if this macro is defined. The build system should define the -macro only if all required headers and libraries are available. If the macro -is not defined, no headers are included and `gettext` passes text through -untranslated. - -The \b Function: field controls the function (or macro) that -will retrieve the localized message; by default the -\p gettext function will be called. - -The **Static Function:** field names a macro that will mark static text -fields for extraction with the `xgettext` tool. The default macro name is -\p gettext_noop and will be defined as `#define gettext_noop(text) text` -right after the `#include` statement. Fluid will do its best to call -`gettext` on static texts later, after the textdomain was set by the user. - -\see [GNU gettext special cases](https://www.gnu.org/software/gettext/manual/html_node/Special-cases.html) - -\subsection fluid_catgets_i18n Using POSIX catgets for I18N - -FLUID's code support for POSIX catgets allows you to use a -global message file for all interfaces or a file specific to -each .fl file; you still need to call -\p setlocale() to select the appropriate language. - -To use POSIX catgets for I18N, open the preferences window -and choose "POSIX catgets" from the \b Use: chooser. Three new -input fields will then appear to control the include file, -catalog file, and set number for retrieving the localized label -strings. - - \image html fluid-catgets.png "Internationalization using POSIX catgets" - \image latex fluid-catgets.png "Internationalization using POSIX catgets" width=10cm - -The \b \#include -field controls the header file to include for -I18N; by default this is \b , the -standard I18N file for POSIX catgets. - -The \b File: field controls the name of the catalog file -variable to use when retrieving localized messages; by default -the file field is empty which forces a local (static) catalog -file to be used for all of the windows defined in your -.fl file. - -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 - -Declaration Blocks can be used to temporarily block out already -designed code using \#if 0 and \#endif -type construction. This will effectively avoid compilation of -blocks of code. However, static code and data generated by this -segment (menu items, images, include statements, etc.) will still -be generated and likely cause compile-time warnings. - -\section fluid_hotkeys Keyboard Shortcuts - -On Apple computers, use the Apple Command key instead of Ctrl. - - - - - - - - - - - - - - - - - - - widget bin - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Key ComboFunction
`F1` widget properties dialog
`F2` move widget earlier in tree
`F3` move widget later in tree
`F7` group widgets
`F8` ungroup widgets
`Delete` delete selected widgets
`Ctrl-1..9` load project from history
`Alt-1` label text tiny
`Alt-2` lLabel text small
`Alt-3` label text normal
`Alt-4` label text medium
`Alt-5` label text large
`Alt-6` label text huge
`Ctrl-A` select all
`Shift-Ctrl-A` select none
`Alt-B`
`Ctrl-C` copy widgets
`Shift-Ctrl-C` generate C code
`Ctrl-G` grid setting dialog
`Alt-G` execute again
`Shift-Alt-G` FLTK settings dialog
`Ctrl-I` insert design into project
`Ctrl-N` new design
`Shift-Ctrl-N` new design from template
`Ctrl-O` open design file
`Shift-Ctrl-O` toggle overlays
`Ctrl-P` print all windows
`Alt-P` project settings
`Shift-Alt-P` Fluid settings dialog
`Ctrl-Q` quit Fluid
`Ctrl-S` save design
`Shift-Ctrl-S` save design with new name
`Shift-Alt-S` source view window
`Ctrl-U` duplicate widgets
`Ctrl-V` paste widgets
`Shift-Ctrl-W` write text strings
`Ctrl-X` cut selected Widgets
`Alt-X` show 'execute command' dialog
`Ctrl-Z` undo
`Shift-Ctrl-Z` redo
Key ComboFunction in interactive Window
`LMB` select one widget
`Shift-LMB` extend widget selection
`Shift-LMB-Drag` window only: resize proportional
`Tab` select next
`Shift-Tab` select previous
`Arrow` move by one unit
`Shift-Arrow` resize by one unit
`Ctrl-Arrow` move by grid units
`Shift-Ctrl-Arrow` resize by grid units
- -\section fluid_licenses Licenses - -FLUID uses graphical images based on the Zendesk Garden Stroke icon set: -https://github.com/zendeskgarden. -Garden Stroke is licensed under the Apache License, Version 2.0: -https://www.apache.org/licenses/LICENSE-2.0.html. - -\htmlonly -
- - - - - - -
- - [Prev] - Using OpenGL - - - [Index] - - - FLTK Runtime Options - [Next] - -
-\endhtmlonly - -*/ diff --git a/documentation/src/fluid1.png b/documentation/src/fluid1.png deleted file mode 100644 index dbded1c3a..000000000 Binary files a/documentation/src/fluid1.png and /dev/null differ diff --git a/documentation/src/fluid2.png b/documentation/src/fluid2.png deleted file mode 100644 index 7c8faca2a..000000000 Binary files a/documentation/src/fluid2.png and /dev/null differ diff --git a/documentation/src/fluid3-cxx.png b/documentation/src/fluid3-cxx.png deleted file mode 100644 index 57ed92d95..000000000 Binary files a/documentation/src/fluid3-cxx.png and /dev/null differ diff --git a/documentation/src/fluid3-gui.png b/documentation/src/fluid3-gui.png deleted file mode 100644 index 48d564c8a..000000000 Binary files a/documentation/src/fluid3-gui.png and /dev/null differ diff --git a/documentation/src/fluid3-style.png b/documentation/src/fluid3-style.png deleted file mode 100644 index b7d02a2ab..000000000 Binary files a/documentation/src/fluid3-style.png and /dev/null differ diff --git a/documentation/src/fluid4.png b/documentation/src/fluid4.png deleted file mode 100644 index 60cec7458..000000000 Binary files a/documentation/src/fluid4.png and /dev/null differ diff --git a/documentation/src/fluid_widget_cxx.png b/documentation/src/fluid_widget_cxx.png deleted file mode 100644 index c5261fb56..000000000 Binary files a/documentation/src/fluid_widget_cxx.png and /dev/null differ diff --git a/documentation/src/fluid_widget_gui.png b/documentation/src/fluid_widget_gui.png deleted file mode 100644 index df26e7316..000000000 Binary files a/documentation/src/fluid_widget_gui.png and /dev/null differ diff --git a/documentation/src/fluid_widget_style.png b/documentation/src/fluid_widget_style.png deleted file mode 100644 index fd44a0fd0..000000000 Binary files a/documentation/src/fluid_widget_style.png and /dev/null differ diff --git a/documentation/src/index.dox b/documentation/src/index.dox index 48494d229..e82bccfd6 100644 --- a/documentation/src/index.dox +++ b/documentation/src/index.dox @@ -67,11 +67,6 @@ \subpage opengl - \subpage fluid - - \ref fluid_widget_attributes - - \ref fluid_selecting_moving - - \ref fluid_images - \subpage fltk-options \subpage advanced diff --git a/documentation/src/intro.dox b/documentation/src/intro.dox index 7e441b502..48eee0dc8 100644 --- a/documentation/src/intro.dox +++ b/documentation/src/intro.dox @@ -142,6 +142,17 @@ the toolkit, which was already in use by several people, Bill came up with "FLTK", including a bogus excuse that it stands for "The Fast Light Toolkit". +\section intro_fluid FLUID + +FLTK comes bundled with FLUID. FLUID, short for Fast Light User Interface +Designer, is a graphical editor capable of generating C++ source code and +header files ready for compilation. These files ultimately create the graphical +user interface for an application. + +The FLUID User Handbook is available at https://www.fltk.org/documentation.php . +It can also be compiled from the FLTK source repository using the `fluid_docs` +target in the CMake build environment. + \section intro_cmake Building and Installing FLTK with CMake Starting with version 1.4, the recommended FLTK building system diff --git a/documentation/src/opengl.dox b/documentation/src/opengl.dox index 6ab4dc2f7..14f33a625 100644 --- a/documentation/src/opengl.dox +++ b/documentation/src/opengl.dox @@ -164,9 +164,7 @@ loading functions by doing: Your main program can now create one of your windows by doing new MyWindow(...). -You can also use your new window class in -\ref fluid "FLUID" -by: +You can also use your new window class in FLUID by: -# Putting your class definition in a \p MyWindow.H file. -# Creating a Fl_Box widget in FLUID. @@ -670,8 +668,8 @@ Link with libGLEW.so (with X11 or Wayland), libglew32.a (with MinGW) or glew32.l [Index] 		- - Programming with FLUID + + FLTK Runtime Options [Next]