Move tutorial over, overview.

MatthiasWM · Mar 24, 2024 · 08cada2 · 08cada2
1 parent bfc00a1
commit 08cada2
Show file tree

Hide file tree

Showing 13 changed files with 614 additions and 541 deletions.
diff --git a/documentation/src/fluid.dox b/documentation/src/fluid.dox
diff --git a/fluid/documentation/Doxyfile.in b/fluid/documentation/Doxyfile.in
@@ -783,13 +783,16 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/src/index.dox \
+                         @CMAKE_CURRENT_SOURCE_DIR@/src/page_introduction.dox \
+                         @CMAKE_CURRENT_SOURCE_DIR@/src/page_commandline.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_main_window.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_widgetbin_panel.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_edit_window.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_functional_nodes.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_widget_panel.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_setting_dialog.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_sourceview_panel.dox \
+                         @CMAKE_CURRENT_SOURCE_DIR@/src/page_tutorial.dox \
                          @CMAKE_CURRENT_SOURCE_DIR@/src/page_appendices.dox
 
 #                         @CMAKE_CURRENT_SOURCE_DIR@/src/page_appendices.dox

diff --git a/documentation/src/cubeview.png → fluid/documentation/src/cubeview.png b/documentation/src/cubeview.png → fluid/documentation/src/cubeview.png
diff --git a/documentation/src/fluid1.png → fluid/documentation/src/fluid1.png b/documentation/src/fluid1.png → fluid/documentation/src/fluid1.png
diff --git a/documentation/src/fluid2.png → fluid/documentation/src/fluid2.png b/documentation/src/fluid2.png → fluid/documentation/src/fluid2.png
diff --git a/documentation/src/fluid3-cxx.png → fluid/documentation/src/fluid3-cxx.png b/documentation/src/fluid3-cxx.png → fluid/documentation/src/fluid3-cxx.png
diff --git a/documentation/src/fluid4.png → fluid/documentation/src/fluid4.png b/documentation/src/fluid4.png → fluid/documentation/src/fluid4.png
diff --git a/fluid/documentation/src/index.dox b/fluid/documentation/src/index.dox
@@ -89,7 +89,13 @@
  _not yet_
 -->
 
- \subpage page_fluid_commandline
+ \subpage page_introduction
+ - \ref introduction_workflow
+
+ \subpage page_commandline
+ - \ref commandline_options
+ - \ref commandline_passive
+ - \ref commandline_windows
 
  \subpage page_fluid_gui
 
@@ -113,9 +119,6 @@
  - \ref widget_panel_grid
  - \ref widget_panel_gridc
 
- </TD>
- <TD ALIGN="LEFT" VALIGN="TOP">
-
  \subpage page_functional_nodes
  - \ref functional_function
  - \ref functional_code
@@ -127,6 +130,9 @@
  - \ref functional_comment
  - \ref functional_data
 
+ </TD>
+ <TD ALIGN="LEFT" VALIGN="TOP">
+
  \subpage page_sourceview_panel
  - \ref codeview_find
  - \ref codeview_settings
@@ -139,8 +145,15 @@
  - \ref setting_i18n
  - \ref setting_user
 
+ \subpage page_tutorial
+ - \ref fluid_cubeview
+ - \ref fluid_cubeview_ui
+ - \ref fluid_addconst
+ - \ref fluid_gencode
+
  \subpage page_appendices
  - \ref appendix_keyboard_shortcuts
+ - \ref appendix_fileformat
  - \ref appendix_licenses
 
 

diff --git a/fluid/documentation/src/page_appendices.dox b/fluid/documentation/src/page_appendices.dox
@@ -64,6 +64,15 @@ On Apple computers, use the Apple Command key instead of Ctrl.
 | `Shift-Ctrl-Arrow` | resize by grid units |
 
 
+<!-- ---------------------------------------------------------------------- -->
+
+\section appendix_fileformat .fl File Format
+
+FLUID edits and saves its state in `.fl` project 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 described in detail in the file
+`fluid/README_fl.txt` which is part of the FLTK source code repository.
+
 <!-- ---------------------------------------------------------------------- -->
 
 \section appendix_licenses External Licenses

diff --git a/fluid/documentation/src/page_commandline.dox b/fluid/documentation/src/page_commandline.dox
@@ -0,0 +1,127 @@
+/**
+
+ \page page_commandline Command Line Tool
+
+ \tableofcontents
+
+ FLUID can be used in interactive and in command line mode. If launched with
+ `-c`, followed by a project filename, it will convert the project file
+ into C++ source files without ever opening a window (or opening an X11 server
+ connection under Linux/X11). This makes FLUID a great command line tool
+ for build processes with complex project files that reference
+ external resources.
+
+ For example, a graphical image referenced by a `.fl` file can be modified
+ and recompiled into the application binary without the need to reload it into
+ an interactive FLUID session.
+
+ <!-- ---------------------------------------------------------------------- -->
+ \section commandline_options Command Line Options
+
+ To launch FLUID from the command line, you can give it an optional name
+ of a project file. If no name is given, it will launch with an empty project,
+ or with the last open project, if so selected in the application setting dialog.
+
+ The ampersand `&` is optional on Linux machines and lets FLUID run in its
+ own new process, giving the shell back to the caller.
+
+ ```
+ fluid 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.
+
+FLUID understands all of the standard FLTK switches before the filename:
+
+```
+-display host:n.n
+-geometry WxH+X+Y
+-title windowtitle
+-name classname
+-iconic
+-fg color
+-bg color
+-bg2 color
+-scheme schemename
+```
+
+ <!-- ---------------------------------------------------------------------- -->
+ \section commandline_passive Compile Tool Options
+
+FLUID can also be called as a command-line tool to create the `.cxx` and `.h`
+file from a `.fl` file. To do this type:
+
+```
+fluid -c filename.fl
+```
+
+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:
+
+<!-- continue here -->
+
+\code
+my_panels.h my_panels.cxx: my_panels.fl
+        fluid -c my_panels.fl
+\endcode
+
+Most versions of make support rules that cause <tt>.fl</tt>
+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 commandline_windows MS Windows specifics
+
+ FLTK uses Linux-style forward slashes to separate path segments in file names.
+ When running on Windows, FLUID will understand Microsoft drive names and
+ backward slashes as path separators and convert them internally into
+ forward slashes.
+
+ Under Windows, binaries can only be defined either as command line tools, or
+ as interactive apps. FLTK generates two almost identical binaries under
+ Windows. `fluid.exe` is meant to be used in interactive mode, and
+ `fluid-cmd.exe` is generated for the command line. Both tools do exactly the
+ same thing, except `fluid-cmd.exe` can use stdio to output error messages.
+
+*/
diff --git a/fluid/documentation/src/page_introduction.dox b/fluid/documentation/src/page_introduction.dox
@@ -4,32 +4,72 @@
 
  \tableofcontents
 
- The Fast Light User Interface Designer, or FLUID, is a graphical editor that
- can produce ready to compile C++ source code and header files.
+<!-- ---------------------------------------------------------------------- -->
 
- This user manual will introduce FLUID, starting with the installation process,
- an overview of the main application window, and how to compile and run a
- simple program. I will explain how to generate a more complex user interface
- with three short tutorial, followed by some advanced subject like creating
- integrated reusable widget classes. The appendices will sum up node types
- and code generation in more detail.
+ 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.
+
+ This manual provides instructions on launching FLUID as a command line tool
+ and integrating `.fl` project files into the application build process.
+ FLTK utilizes `cmake`, but other build systems and IDEs capable of running
+ external tools can also build applications based on FLUID.
+
+ The majority of the manual focuses on using FLUID as an interactive GUI
+ design tool. It covers an overview of windows, menu items, and dialog boxes,
+ detailing how to create visually appealing and consistent user experiences
+ through drag and drop functionality, a "what you see is what you get" editor,
+ and alignment tools. The Setting section will detail the process of initiating
+ a new project, creating an alignment template, and incorporating
+ internationalization.
+
+ In a few tutorials, we will explain how to generate small apps in FLUID alone,
+ and how to create more complex user interfaces, followed by some advanced
+ subject like creating integrated reusable widget classes.
+
+ Several tutorials demonstrate creating simple applications using FLUID
+ exclusively, as well as developing more intricate user interfaces. Advanced
+ topics such as creating reusable widget classes are also discussed.
+
+ The appendices contain additional technical information for reference.
+
+<!-- ---------------------------------------------------------------------- -->
 
  \section introduction_workflow Workflow
 
- FLUID has two modes of operation. When started from the shell without command
- line arguments, or when launched from the desktop, FLUID will open in
- interactive mode.
+ FLUID stores user interface designs in `.fl` project files. To generate
+ a working application in for of a binary program, `.fl` files are converted
+ into a C++ source file and a header file by FLUID, then compiled into an
+ object file, that is finally linked with other object files into an executable
+ binary file. Header files generated by FLUID can be referenced by other C++
+ modules in a project to get access to user interface elements. Conversely,
+ FLUID can generate reference to external variables and callback function.
+
+ FLUID stores user interface designs within `.fl` project files. These files
+ are transformed into a binary application through a multi-step process.
+ Initially, FLUID converts `.fl` files into C++ source and header files.
+ Subsequently, these files are compiled into object files, which are then
+ linked with other object files to form an executable binary.
+ FLUID-generated header files give access to UI elements from other C++ modules
+ within the project. Conversely, FLUID can also generate references to
+ variables and callback functions in other C++ modules.
 
- If FLUID is started from the command line with `-u`, `-c`, or `cs`, it will
- not open any user interface, but instead behave like any shell-only tool that
- can be easily integrated into Makefiles and build systems like CMake.
+ \image html fluid_flow_chart_800.png "FLUID Workflow"
+ \image latex fluid_flow_chart.png "FLUID Workflow"
 
- \image html fluid_flow_chart_800.png
- \image latex fluid_flow_chart.png "" width=10cm
+ Small applications can be fully designed and developed within FLUID. Users
+ have the option to include shell scripts in FLUID projects, enabling them to
+ directly call compilers and linkers to produce the binaries.
 
- FLUID organization
+ For medium-sized projects, a build systems such as `cmake` or IDEs
+ with integrated build setups is recommended. FLUID in interactive mode
+ can pre-generate C++ code files for direct compilation by the IDE.
 
- More details on the command line arguments of FLUID can be found
- in the chapter \ref page_build_integration .
+ In larger projects, FLUID projects frequently reference external resources
+ such as graphics, binary data, and internationalized text.
+ In such scenarios,it is very useful to distribute the `.fl` project files
+ instead of prebuilt source files. FLUID in command-line mode can then be
+ called as an external tool, dynamically generating C++ source code from all
+ external resources during compile time.
 
  */