FLUID: Restructures user documentation.

1 files changed, 277 insertions, 0 deletions

diff --git a/fluid/documentation/src/page_appendices.dox b/fluid/documentation/src/page_appendices.dox
new file mode 100644
index 000000000..a78b944c3
--- /dev/null
+++ b/fluid/documentation/src/page_appendices.dox
@@ -0,0 +1,277 @@
+/**
+
+ \page page_appendices Appendices
+
+ \tableofcontents
+
+ \section appendix_code_nodes Functional Node Types
+
+ ## Functions and Methods ##
+
+ ![](flFunction.png) Functions
+
+ Fluid can generate C functions, C++ functions, and methods in classes.
+ Functions can contain widgets to build windows and dialogs. *Code* nodes can
+ be used to add more source code to a function.
+
+ ### Parents ###
+
+ To generate a function, the function node must be created at the top level or
+ inside a declaration block. If added inside a class node, this node generates
+ a method inside that class.
+
+ ### Children ###
+
+ Function nodes can contain code nodes and widget trees. The topmost node of a
+ widget tree must be a window.
+ If the function node has no children, only a forward declaration will be
+ created in the header, but no source code will be generated.
+
+ \image html flFunctionDialog.png "Function/Method Properties"
+ \image latex flFunctionDialog.png "Function/Method Properties"
+
+ ### Declaring a Function ###
+
+ A function node at the top level or inside a declaration block generates a C
+ or C++ function.
+
+ The *Name* field  contains the function name and all arguments.
+ If the *Name* field is left empty, Fluid will generate a typical 'main()' function.
+ ```
+ // .cxx
+ int main(int argc, char **argv) {
+ // code generated by children
+ w->show(argc, argv); // <-- code generated if function has a child widget
+ Fl::run();
+ }
+ ```
+
+ If a function node has a name but no children, a forward declaration is
+ generated in the header, but the implementation in the source file is omited.
+ This is used to reference functions in other modules.
+ ```
+ // .h
+ void make_window();
+ ```
+
+ If the function contains one or more Code nodes, an implementation will also be
+ generated. The default return type is `void`. Text in the *Return Type* field
+ overrides the default type.
+ ```
+ // .cxx
+ void make_window() {
+ // code generated by children
+ }
+ ```
+
+ If the function contains a widget, a pointer to the first widget
+ will be created. The default return type will match the type of the
+ first widget, and a pointer to the widget will be returned.
+ ```
+ // .h
+ Fl_Window* make_window();
+ ```
+
+ ```
+ // .cxx
+ Fl_Window* make_window() {
+ Fl_Window* w;
+ // code generated by children:
+ // w = new Fl_Window(...)
+ return w;
+ }
+ ```
+
+ #### Options for Functions ####
+
+ Choosing *static* in the pulldown menu will declare the function `static` in the
+ source file. No prototype will be generated in the header.
+ ```
+ // .cxx
+ static Fl_Window* make_window() { ...
+ ```
+
+ If the *C* option is checked, the function will be declared as a plain C
+ function in the header file.
+ The options *local* and *C* together are not supported.
+ ```
+ // .h
+ extern "C" { void my_plain_c_function(); }
+ ```
+
+ ### Declaring a Method ###
+
+ A function node inside a class node generates a C++ method. If a method node has
+ no children, the declaration is generated in the header, but no implementation
+ in the source file.
+ ```
+ // .h
+ class UserInterface {
+ public:
+ void make_window();
+ };
+ ```
+
+ If the method contains one or more Code nodes, an implementation will also be
+ generated.
+
+ ```
+ // .cxx
+ void UserInterface::make_window() {
+ printf("Hello, World!\n");
+ }
+ ```
+
+ If the method contains at least on widget, a pointer to the topmost widget
+ will be returned and the return type will be generated accordingly.
+ ```
+ // .h
+ class UserInterface {
+ public:
+ Fl_Double_Window* make_window();
+ };
+ ```
+
+ ```
+ // .cxx
+ Fl_Double_Window* UserInterface::make_window() {
+ Fl_Double_Window* w;
+ // code generated by children
+ return w;
+ }
+ ```
+
+ #### Options for Methods ####
+
+ Class access can be defined with the pulldown menu. It provides a choice of
+ `private`, `protected`, and `public`.
+
+ Fluid recognizes the keyword `static` or `virtual` at the beginning of the
+ *return type* and will generate the declaration including the keyword, but will
+ omit it in the implementation. The return type defaults still apply if there
+ is no text after the keyword.
+
+ #### Further Options ####
+
+ Users can define a comment text in the *comment* field. The first line of the
+ comment will be shown in the widget browser. The comment text will be generated
+ in the source file before the function.
+ ```
+ // .cxx
+ //
+ // My multilen comment will be here... .
+ // Fluid may actually use C style comment markers.
+ //
+ Fl_Window* make_window() {
+ ```
+
+ Fluid recognizes default values in the argument list and geneartes them in the
+ declaration, but omits them in the implementation.
+
+ A short function body can be appended in the *Name* field. With no child, this
+ creates an inlined function in the header file.
+
+ <!-- ---------------------------------------------------------------------- -->
+
+ ## C Source Code ##
+
+ ![](flCode.png) Code
+
+ ...write me.
+
+ ### Parents ###
+
+ ...write me.
+
+ ### Children ###
+
+ ...write me.
+
+ ## Code Block ##
+
+ ...write me.
+
+ ## Declaration ##
+
+ ...write me.
+
+ ## Declaration Block ##
+
+ ...write me.
+
+ ## Classes ##
+
+ ...write me.
+
+ ## Widget Class ##
+
+ ...write me.
+
+ ## Comments ##
+
+ ...write me.
+
+ ## Inlined Data ##
+
+ <!-- ---------------------------------------------------------------------- -->
+
+ \section appendix_app_settings Fluid Application Settings
+
+ ## Options ##
+
+ __Select scheme__ : select a scheme for Fluid. Changes in the scheme will be
+ visible instantly in all windows.
+
+ __Show tooltips__ : if checked, show tooltips for most UI elements in Fluid dialogs.
+
+ __Show completions dialogs__ : if checked, Fluid will pop up a dialog box
+ after generating code, header, and strings files.
+
+ __Open previous file on startup__ : when launching Fluid in its interactive
+ mode, it will load the file that was last open when Fluid was closed.
+
+ __Remember window positions__ : reopen windows and dialogs where they were
+ left when Fluid was last closed.
+
+ __Show comments in browser__ : if a comment has been specified for a type, show
+ the initial line of the comment within the widget tree browser.
+
+ ## External Editor ##
+
+ When you configure the External Editor text field with a shell command and
+ select the "Use for Code Nodes" option, FLUID will launch an external editor
+ for editing the C++ code within a Code Node. After making changes and saving
+ the code in the external editor, it will automatically be transferred back
+ into the Code Node. The shell command is constructed by combining the text
+ field's content with the path and name of a temporary file containing the
+ code snippet. The file name ends in `.cxx`.
+
+ ## Overlays ##
+
+ __Show positioning guides__ :
+
+ When enabled, FLUID will use the existing Layout settings to propose widget
+ positions and dimensions that align with other widgets within the project.
+ It displays red indicator guides on the scene to illustrate the widget's
+ relationship with its neighboring elements. If you drag the widgets with the
+ mouse, they will automatically align with these preferred positions.
+
+ __Show restricted areas__ :
+
+ When selected, FLUID will display a hash pattern when widgets overlap with
+ other widgets within the same group or extend beyond the boundaries of their
+ parent group. Widgets that are invisible will not trigger this effect.
+
+ __Ghosting low contrast groups__ :
+
+ Occasionally, newly created groups can be inconspicuous during the editing
+ process when their background matches that of the parent and no visible
+ box is drawn. However, if you enable the "Show Low Contrast Groups Ghosted"
+ option, groups that lack a box type or have a flat box type with the same
+ color as the parent will be displayed with a faint outline
+ in the editing window.
+
+ During live resizing and after project compilation, all groups will be
+ rendered as originally designed, without the ghosted outline.
+
+ */