Add two simple entry tutorials

fluid/documentation/src/index.dox

@@ -97,10 +97,12 @@
  - \ref setting_user
 
  \subpage page_tutorial
- - \ref fluid_cubeview
- - \ref fluid_cubeview_ui
- - \ref fluid_addconst
- - \ref fluid_gencode
+ - \ref fluid_hello_world_tutorial
+ - \ref fluid_1of7guis_tutorial
+ - \ref fluid_cubeview_tutorial
+   - \ref fluid_cubeview_ui
+   - \ref fluid_addconst
+   - \ref fluid_gencode
 
  \subpage page_appendices
  - \ref appendix_keyboard_shortcuts

fluid/documentation/src/page_tutorial.dox

@@ -6,11 +6,148 @@
 
 <!-- ---------------------------------------------------------------------- -->
 
-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.
+ \section fluid_hello_world_tutorial Hello, World!
+
+ The first FLUID tutorial explains the FLUID basics. It creates a single
+ `main()` function that opens an application window with a static text box
+ inside.
+
+ After launching FLUID we want to make sure that two tool windows are open.
+ The "Widget Bin" gives quick access to all available widgets and functional
+ types. It can be opened via the main menu: __Edit > Show Widget Bin__, or
+ using the shortcut __Alt-B__.
+
+ The second very helpful tool box is the "Source View". The source view gives
+ a preview of the code as it will be generated by FLUID. All changes in the
+ scene graph or in attributes are reflected immediately in the source view.
+ Choose __Edit > Show Source View__ or press __SHift-Alt-S__ to get this
+ toolbox. Make sure that _Auto-Refresh_ and _Auto-Position_ are active in
+ the source view.
+
+ Let's start Hello World from scratch. If there is already a previous project
+ loaded, select __File > New__ or __Ctrl-N__.
+
+ Before we can create a window, we need a "C" function that can be called
+ when we run the program. Select __New > Code > Function/Method...__ or click on
+ the
+ \image{inline} html flFunction.png "Function/Method"
+ \image{inline} latex flFunction.png
+ image in the widget bin.
+
+ A function is added as a first line to the widget tree in the main window,
+ and a "Function/Method Properties" dialog box will pop up. For our Hello World
+ program, delete all text in the top "Name(args)" text field. If this field
+ is left empty, FLUID will generate a `main(argc, argv)` function for us.
+
+ \image html fluid4.png "the Function/Method Properties dialog"
+ \image latex fluid4.png "the Function/Method Properties dialog"
+
+ Note that the function will not show up in the source view yet. FLUID will
+ not generate code for functions that don't have any content, and only create
+ a forward declaration in the header file, assuming that the function will
+ be implemented inside another module.
+
+ You can get this dialog back at any time by selecting the function in the
+ main window and pressing __F1__, or by double-clicking it.
+
+ Keep the function selected and add an `Fl_Window` to the function by selecting
+ __New > Group > Window...__, by clicking the
+ \image{inline} html flWindow.png "Group/Window"
+ \image{inline} latex flWindow.png
+ image in the widget bin, or by dragging the Group/Window image from the
+ widget bin onto the desktop.
+
+ A new application window will open up on the desktop. The thin red outline
+ around the window indicates that it is selected. Dragging the red line will
+ resize the window. Take a look at the source view: the main function
+ is now generated, including code to instantiate our `Fl_Window`.
+
+ To edit all the attributes of our window, make sure it is selected and press
+ __F1__, or double-click the entry in the main FLUID window, or double-click
+ the window itself. The "Widget Properties" dialog box will pop up. Enter
+ some text in the "Label:" text box and see how the label is updated immediately
+ in the window itself, in the widget list, and in the source view.
+
+ Adding a static text to our window is just as easy. Add an `Fl_Box` to our
+ window by selecting __New > Other > Box__, or by clicking on the
+ \image{inline} html flBox.png "Other/Box"
+ \image{inline} latex flBox.png
+ image in the widget bin, or by dragging the Other/Box image from the
+ widget bin into our newly created window.
+
+ Most importantly, enter the text "Hello, World!" in the "Label:" field
+ of the Box Widget Properties panel to achieve the goal of this tutorial. Now
+ is also a great time to experiment with label styles, label fonts, sizes,
+ colors, etc. .
+
+ Finally, we should save our project as an `.fl` project file somewhere. Once
+ the project is saved, select __File > Write Code__ or press __Shift-Ctrl-C__
+ to write our source code and header file to the same directory.
+
+ Compile the program using a Makefile, CMake file, or fltk-config as described
+ in the FLTK manual and the `README.txt` files in the FLTK source tree.
+
+<!-- ---------------------------------------------------------------------- -->
+
+ \section fluid_1of7guis_tutorial 7GUIs, Task 1
+
+ In the first "Hello World" tutorial, we built an entire application in FLUID.
+ It's a boring application though that does nothing except quitting when the
+ close button in the window border is clicked.
+
+ \image html 1of7GUIs.png "Task 1 of 7GUIs"
+ \image latex 1of7GUIs.png "Task 1 of 7GUIs" width=5cm
+
+ The second tutorial will introduce callbacks by implementing task 1, "Counter",
+ of 7GUIs. 7GUIs has been created as a spin-off of my master’s thesis
+ Comparison of Object-Oriented and Functional Programming for GUI Development
+ at the Human-Computer Interaction group of the Leibniz Universität Hannover
+ in 2014. 7GUIs defines seven tasks that represent typical challenges in GUI
+ programming. https://eugenkiss.github.io/7guis/ .
+
+ Task 1 requires "Understanding the basic ideas of a language/toolkit. The
+ task is to build a frame containing a label or read-only textfield T and a
+ button B. Initially, the value in T is “0” and each click of B increases the
+ value in T by one."
+
+ Our knowledge from tutorial 1 is enough to generate the `main()` function, and
+ add an `Fl_Window`, an `Fl_Output`, and an `Fl_Button`. To make life easy,
+ FLUID comes with a built-in template for this tutorial. Just select
+ __File > New from Template...__ and double-click "1of7GUIs".
+
+ We will need to reference the output widget in our callback, so let's assign a
+ pointer to the widget to a global variable and give that variable a name.
+ Open the Widget Properties dialog by double-clicking the output widget.
+ Change to the "C++" tab, and enter "counter_widget" in the "Name:" field.
+
+ The "Count" button is the active element in our application. To tell the
+ app what to do when the user clicks the button, we create a callback function
+ for that button. Open the widget properties dialog for the button.
+ In the "C++" tab, we find the input field "Callback:".
+
+ The callback is called exactly once after every click on the button. Our
+ strategy here is to read the current value from the `counter_widget`,
+ increment it by 1, and write it back to `counter_widget`.
+ The FLTK documentation tells us that we can use `Fl_Output::ivalue()` to get
+ text in `Fl_Output` as an integer, and we can write it back by calling
+ `Fl_Output::value(int)`. When the value is changed, FLTK will automatically
+ redraw the output widget for us. So here is the callback code:
+
+ ```
+ int i = counter_widget->ivalue();
+ i++;
+ counter_widget->value(i);
+ ```
+
+ That's it. This is a complete interactive desktop application. Compile, link,
+ run, and test it to see how it works.
+
+<!-- ---------------------------------------------------------------------- -->
+
+\section fluid_cubeview_tutorial Cube VIew
+
+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
@@ -28,7 +165,7 @@ At the completion of this tutorial you will (hopefully) understand how to:
 -# Use FLUID to set callback member functions of custom widget classes.
 -# Subclass an Fl_Gl_Window to suit your purposes.
 
-\section fluid_cubeview The CubeView Class
+\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
@@ -260,7 +397,7 @@ void CubeView::draw() {
 }
 \endcode
 
-\section fluid_cubeview_ui 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.
@@ -372,14 +509,14 @@ type of \p void.
 Once the new method has been added, highlight its name and select
 <b>New->Code->Code.</b> Enter the method's code in the code window.
 
-\section fluid_addconst Adding Constructor Initialization Code
+\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
 <b>New->Code->Code</b>. Add any required code.
 
-\section fluid_gencode Generating the 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