From 83f6bb50b292df155a11aae630f5b8f8064fdcae Mon Sep 17 00:00:00 2001 From: Matthias Melcher Date: Thu, 9 Dec 2021 18:25:43 +0100 Subject: Fluid: sample documentation, please check http://messagepad.org/fluid/code.html --- fluid/Doxyfile | 2 +- fluid/Fl_Function_Type.cxx | 2 + fluid/documentation/src/code.dox | 165 +++++++++++++++++++++++++-- fluid/documentation/src/flCode.png | Bin 0 -> 311 bytes fluid/documentation/src/flFunction.png | Bin 0 -> 388 bytes fluid/documentation/src/flFunctionDialog.png | Bin 0 -> 19989 bytes fluid/function_panel.cxx | 2 +- fluid/function_panel.fl | 14 ++- 8 files changed, 168 insertions(+), 17 deletions(-) create mode 100644 fluid/documentation/src/flCode.png create mode 100644 fluid/documentation/src/flFunction.png create mode 100644 fluid/documentation/src/flFunctionDialog.png 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 Binary files /dev/null and b/fluid/documentation/src/flCode.png differ diff --git a/fluid/documentation/src/flFunction.png b/fluid/documentation/src/flFunction.png new file mode 100644 index 000000000..3cf7a7b3a Binary files /dev/null and b/fluid/documentation/src/flFunction.png differ diff --git a/fluid/documentation/src/flFunctionDialog.png b/fluid/documentation/src/flFunctionDialog.png new file mode 100644 index 000000000..bc3d90fb4 Binary files /dev/null and b/fluid/documentation/src/flFunctionDialog.png differ 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 } -- cgit v1.2.3