path: root/fluid/documentation/src/page_appendices.dox

/**

 \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.

 */