Fluid: sample documentation, please check http://messagepad.org/fluid/code.html

8 files changed, 168 insertions, 17 deletions

diff --git a/fluid/Doxyfile b/fluid/Doxyfile
index 3aed35683..9e2bc37aa 100644
--- a/fluid/Doxyfile
+++ b/fluid/Doxyfile
@@ -962,7 +962,7 @@ EXAMPLE_RECURSIVE      = NO
 # that contain images that are to be included in the documentation (see the
 # \image command).
 
-IMAGE_PATH             =
+IMAGE_PATH             = documentation/src/
 
 # The INPUT_FILTER tag can be used to specify a program that doxygen should
 # invoke to filter for each input file. Doxygen will invoke the filter program
diff --git a/fluid/Fl_Function_Type.cxx b/fluid/Fl_Function_Type.cxx
index 0f6c3ba34..0046d2e98 100644
--- a/fluid/Fl_Function_Type.cxx
+++ b/fluid/Fl_Function_Type.cxx
@@ -250,10 +250,12 @@ void Fl_Function_Type::open() {
     f_public_member_choice->value(public_);
     f_public_member_choice->show();
     f_public_choice->hide();
+    f_c_button->hide();
   } else {
     f_public_choice->value(public_>0);
     f_public_choice->show();
     f_public_member_choice->hide();
+    f_c_button->show();
   }
   f_c_button->value(cdecl_);
   const char *c = comment();
diff --git a/fluid/documentation/src/code.dox b/fluid/documentation/src/code.dox
index 58b041d11..d07420dce 100644
--- a/fluid/documentation/src/code.dox
+++ b/fluid/documentation/src/code.dox
@@ -6,15 +6,163 @@
 
  Overview of code nodes.
 
- \section function Functions and Methods
 
- Creating functions and methods.
-
- \code
- #include "test.fl"
- \endcode
-
- \section code Code
+\section function 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 ###
+
+Fluid recognizes default values in the argument list and geneartes them in the
+declaration, but omits them in the implementation.
+
+<!-- ----------------------------------------------------------------------- -->
+
+\section code C Source Code
+
+![](flCode.png) Code
+
+...write me.
 
  \section codeblock Code Block
 
@@ -24,7 +172,6 @@
 
  \section class Classes
 
- Fluid can create a new C++ class.
 
  \section widgetclass Widget Class
 
diff --git a/fluid/documentation/src/flCode.png b/fluid/documentation/src/flCode.png
new file mode 100644
index 000000000..a45ece9d3
--- /dev/null
+++ b/fluid/documentation/src/flCode.png
diff --git a/fluid/documentation/src/flFunction.png b/fluid/documentation/src/flFunction.png
new file mode 100644
index 000000000..3cf7a7b3a
--- /dev/null
+++ b/fluid/documentation/src/flFunction.png
diff --git a/fluid/documentation/src/flFunctionDialog.png b/fluid/documentation/src/flFunctionDialog.png
new file mode 100644
index 000000000..bc3d90fb4
--- /dev/null
+++ b/fluid/documentation/src/flFunctionDialog.png
diff --git a/fluid/function_panel.cxx b/fluid/function_panel.cxx
index 6cb60bcd0..ab3e177b1 100644
--- a/fluid/function_panel.cxx
+++ b/fluid/function_panel.cxx
@@ -45,7 +45,7 @@ Fl_Menu_Item menu_f_public_member_choice[] = {
 Fl_Choice *f_public_choice=(Fl_Choice *)0;
 
 Fl_Menu_Item menu_f_public_choice[] = {
- {"local", 0,  0, (void*)(0), 0, (uchar)FL_NORMAL_LABEL, 0, 11, 0},
+ {"static", 0,  0, (void*)(0), 0, (uchar)FL_NORMAL_LABEL, 0, 11, 0},
  {"global", 0,  0, (void*)(1), 0, (uchar)FL_NORMAL_LABEL, 0, 11, 0},
  {0,0,0,0,0,0,0,0,0}
 };
diff --git a/fluid/function_panel.fl b/fluid/function_panel.fl
index d0750b87d..6c0933361 100644
--- a/fluid/function_panel.fl
+++ b/fluid/function_panel.fl
@@ -2,6 +2,8 @@
 version 1.0400
 header_name {.h}
 code_name {.cxx}
+mac_shell_cmd {echo "I love Fluid"}
+mac_shell_flags 3
 comment {//
 // Code dialogs for the Fast Light Tool Kit (FLTK).
 //
@@ -32,7 +34,7 @@ decl {\#include "factory.h"} {private local
 decl {\#include "Fl_Type.h"} {private local
 }
 
-decl {\#include "widget_browser.h"} {selected private local
+decl {\#include "widget_browser.h"} {private local
 }
 
 decl {\#include "undo.h"} {private local
@@ -47,18 +49,18 @@ Function {use_tab_navigation(int, Fl_Text_Editor*)} {
 Function {make_function_panel()} {open
 } {
   Fl_Window function_panel {
-    label {Function/Method Properties}
+    label {Function/Method Properties} open
     xywh {101 713 343 232} type Double resizable modal visible
   } {
     Fl_Group {} {open
       xywh {10 10 270 20}
     } {
-      Fl_Choice f_public_member_choice {
+      Fl_Choice f_public_member_choice {open
         tooltip {Change member access attribute.} xywh {10 10 75 20} down_box BORDER_BOX labelsize 11 when 1 textsize 11
       } {
         MenuItem {} {
           label private
-          user_data 0 user_data_type long
+          user_data 0 user_data_type long selected
           xywh {5 5 100 20} labelsize 11
         }
         MenuItem {} {
@@ -72,11 +74,11 @@ Function {make_function_panel()} {open
           xywh {5 5 100 20} labelsize 11
         }
       }
-      Fl_Choice f_public_choice {
+      Fl_Choice f_public_choice {open
         tooltip {Change widget accessibility.} xywh {10 10 75 20} down_box BORDER_BOX labelsize 11 when 1 textsize 11
       } {
         MenuItem {} {
-          label local
+          label static
           user_data 0 user_data_type long
           xywh {15 15 100 20} labelsize 11
         }