From d50de995a411710c15b0c92d58e0ffea9ab166d5 Mon Sep 17 00:00:00 2001 From: Matthias Melcher Date: Sun, 17 Mar 2024 14:19:34 +0100 Subject: [PATCH] Finished docs for non-widget nodes. --- fluid/Fl_Function_Type.cxx | 16 +- fluid/autodoc.cxx | 30 +--- fluid/documentation/src/page_appendices.dox | 169 ++++++++++++++++---- 3 files changed, 149 insertions(+), 66 deletions(-) diff --git a/fluid/Fl_Function_Type.cxx b/fluid/Fl_Function_Type.cxx index f7a7f30d8e..d92a3fe3c0 100644 --- a/fluid/Fl_Function_Type.cxx +++ b/fluid/Fl_Function_Type.cxx @@ -1534,9 +1534,11 @@ void Fl_DeclBlock_Type::open() { */ void Fl_DeclBlock_Type::write_code1(Fd_Code_Writer& f) { const char* c = name(); - if (public_) - f.write_h("%s\n", c); - f.write_c("%s\n", c); + if (c && *c) { + if (public_) + f.write_h("%s\n", c); + f.write_c("%s\n", c); + } } /** @@ -1544,9 +1546,11 @@ void Fl_DeclBlock_Type::write_code1(Fd_Code_Writer& f) { */ void Fl_DeclBlock_Type::write_code2(Fd_Code_Writer& f) { const char* c = after; - if (public_) - f.write_h("%s\n", c); - f.write_c("%s\n", c); + if (c && *c) { + if (public_) + f.write_h("%s\n", c); + f.write_c("%s\n", c); + } } // ---- Fl_Comment_Type declaration diff --git a/fluid/autodoc.cxx b/fluid/autodoc.cxx index ea2b1baf0a..460a50a022 100644 --- a/fluid/autodoc.cxx +++ b/fluid/autodoc.cxx @@ -351,7 +351,11 @@ void run_autodoc(const Fl_String &target_dir) { Fl_Margin win_margin(0, 0, 0, 0); Fl_Margin win_blend(10, 10, 10, 10); - printf("Writing documentation snapshots to %s\n", target_dir.c_str()); + the_panel = make_widget_panel(); + // fl_snapshot(target_dir + "data_panel.png", widget_x_input, widget_h_input, + // Fl_Margin(FL_SNAP_TO_WINDOW, 4, FL_SNAP_TO_WINDOW, 4), + // Fl_Margin(0, 10, 0, 10)); + // fl_open_uri(("file://" + target_dir + "data_panel.png").c_str()); // TODO: take a snapshot of FLUID in a desktop situation // (main, toolbar, document, widget editor, source view) @@ -432,30 +436,6 @@ void run_autodoc(const Fl_String &target_dir) { // TODO: settings dialog // show and explain all tabs - - - the_panel = make_widget_panel(); -// fl_snapshot("/Users/matt/test1.png", widget_browser, Fl_Rect(10, 20, 30, 40), Fl_Rect(40, 30, 20, 10)); -// fl_snapshot("/Users/matt/test2.png", the_panel, Fl_Rect(10, 10, 10, 10), Fl_Rect(20, 0, 0, 0)); -// fl_snapshot("/Users/matt/test.png", widget_x_input, widget_h_input, 70, 12, 10, 10, 20, 2.0); -// fl_snapshot("/Users/matt/test.png", Main_Menu+1, Main_Menu+1, Main_Menu+4, 10, 10, 20, 2.0); -// Fl_Menu_Item *mi1 = (Fl_Menu_Item*)main_menubar->find_item("&Layout/&Align"); -// Fl_Menu_Item *mi2 = (Fl_Menu_Item*)main_menubar->find_item("&Layout/Presets"); -// fl_snapshot("/Users/matt/test.png", mi1, mi1, mi2, 10, 10, 20, 2.0); -// fl_snapshot("/Users/matt/test.png", New_Menu+1, New_Menu+1, New_Menu+4, 10, 10, 20, 2.0); - - -// widget_tabs->value(widget_tab_grid_child); -// fl_snapshot("/Users/matt/test1.png", the_panel, Fl_Rect(-1, -1, -1, -1), Fl_Rect(40, 40, 40, 40), 1.0f); -// fl_snapshot("/Users/matt/test1.png", -// widget_x_input, widget_h_input, -// Fl_Margin(0, 0, 0, 0), -// Fl_Margin(10, 10, 10, 10)); - -// fl_open_uri("file:///Users/matt/test1.png"); -// fl_open_uri("file:///Users/matt/test2.png"); - fl_open_uri(("file://" + target_dir + "data_panel.png").c_str()); - } diff --git a/fluid/documentation/src/page_appendices.dox b/fluid/documentation/src/page_appendices.dox index bc0b693159..5b24810589 100644 --- a/fluid/documentation/src/page_appendices.dox +++ b/fluid/documentation/src/page_appendices.dox @@ -47,7 +47,7 @@ ``` 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 ommited. + generated in the header, but the implementation in the source file is omitted. This is used to reference functions in other modules. ``` // .h @@ -60,7 +60,7 @@ ``` // .cxx void make_window() { - // code generated by children + // code generated by children } ``` @@ -88,7 +88,7 @@ source file. No prototype will be generated in the header. ``` // .cxx - static Fl_Window* make_window() { ... + static Fl_Window* make_window() { ... } ``` If the *C* option is checked, the function will be declared as a plain C @@ -108,7 +108,7 @@ // .h class UserInterface { public: - void make_window(); + void make_window(); }; ``` @@ -118,7 +118,7 @@ ``` // .cxx void UserInterface::make_window() { - printf("Hello, World!\n"); + printf("Hello, World!\n"); } ``` @@ -128,16 +128,16 @@ // .h class UserInterface { public: - Fl_Double_Window* make_window(); + Fl_Double_Window* make_window(); }; ``` ``` // .cxx Fl_Double_Window* UserInterface::make_window() { - Fl_Double_Window* w; - // code generated by children - return w; + Fl_Double_Window* w; + // code generated by children + return w; } ``` @@ -200,100 +200,197 @@ ![](flCodeBlock.png) Code Block + Code Blocks are used when a single function generates different GUI elements + conditionally. + ### Parents ### - ...write me. + Code Blocks are used inside functions and methods. ### Children ### - ...write me. + Code Blocks can contain widgets, code, or more code blocks. \image html codeblock_panel.png "Code Block Properties" \image latex codeblock_panel.png "Code Block Properties" + The two field expect the code before and after the `{ ... }` statements. The + second field can be empty. + + Two consecutive Code Blocks can be used to generate `else`/`else if` + statements by leaving the second field of the first node empty. + ## Declaration ## -![](flDeclaration.png) Declaration + ![](flDeclaration.png) Declaration ### Parents ### - ...write me. - - ### Children ### - - ...write me. + Declarations can be added at the top level or inside classes and widget classes. \image html decl_panel.png "Declaration Properties" \image latex decl_panel.png "Declaration Properties" + Declaration nodes are quite flexible and can be a simple variable declaration + such as `int i;`. But include statements are also allowed, as are type + declarations, and comments. FLUID does its best to understand user intention, + but the generated code should be verified by the user. + + Declarations nodes at the top level can selectively generate code in the header + and /or in the source file. If a declaration is inside a class, the user can + select if the class member is *private*, *protected*, or *public* instead. + ## Declaration Block ## -![](flDeclarationBlock.png) Declaration Block + ![](flDeclarationBlock.png) Declaration Block + + Declaration Blocks are a way to selectively compile child nodes via + preprocessor commands, typically `#ifdef TEST` and `#endif`. ### Parents ### - ...write me. + Declaration Blocks can be created at the top level or inside classes. ### Children ### - ...write me. + Declaration Blocks can contain classes, functions, methods, declarations, and + comments. \image html declblock_panel.png "Declaration Block Properties" \image latex declblock_panel.png "Declaration Block Properties" + Users can select if the block is generated in the source file only, or in the + header file as well. The two input fields are used to enter the line of code + before and after the child nodes. Two consecutive Declaration Blocks can be + used to generate `#else`/`#elif` style code by leaving the second field of + the first node empty. + + \note Declaration Blocks are not smart, and child nodes may still generate + unexpected code outside the scope of this block. This may change in future + versions of FLUID. + ## Classes ## ![](flClass.png) Class + FLUID can generate code to implement C++ classes. Classes can be used to keep + dialogs and groups of UI elements organized. See Widget Class nodes as an + alternative to implement compound widgets. + ### Parents ### - ...write me. + Class nodes can be created at top level or inside a Class or Widget + Class node. ### Children ### - ...write me. + Class nodes can contain Functions, Declarations, Widgets, Data, and + other classes. \image html class_panel.png "Class Properties" \image latex class_panel.png "Class Properties" + The *Name:* and *Subclass of:* fields should be set to standard C++ class + names. + + Function nodes inside classes are implemented as methods. Constructors and + destructors are recognized and implemented as such. Inlined data is declared + as a static class member. + + Note that methods without a code or widget node are only declared in the + header file, but no code is generated for them in the source file. + ## Widget Class ## -![](flWidgetClass.png) Widget Class + ![](flWidgetClass.png) Widget Class + + Widget Class node creates a new widget type by deriving a class from another + widget class. These are often compound widgets derived from `Fl_Group`. A less + automated but more flexible way to implement compound widgets is the Class node. ### Parents ### - ...write me. + Widget Class nodes can be created at top level or inside a Class or Widget + Class node. ### Children ### - ...write me. + Widget Class nodes can contain Functions, Declarations, Widgets, Data, and + other classes. + + ### Properties ### + Widget Class nodes use the Widget panel to edit their properties. The super + class can be set in the *C++* tab in the *Class* field. If that field is empty, + FLUID derives from `Fl_Group`. + + The Widget Class always creates a constructor with the common widget parameters: + ``` + MyWidget::MyWidget(int X, int Y, int W, int H, const char *L) + : Fl_Group(X, Y, W, H, L) { ... } + ``` + + If the super class name contains the text `Window`, two more constructors + and a common initializer method are created: + ``` + MyWidget::MyWidget(int W, int H, const char *L) : + Fl_Window(0, 0, W, H, L) { ... } + + MyWidget::MyWidget() : + Fl_Window(0, 0, 480, 320, 0) { ... } + + void MyWidget::_MyWidget() { ... } + ``` + + Code and Widget nodes are then added to the constructor. Function nodes are + added as methods to the class. Declarations are added as class members. + Data nodes generate static class members. + + It may be useful to design compound widgets with a variable size. The Widget + Panel provides a choice menu in the *GUI* tab's *Position* row under + *Children*. The options *resize* and *reposition* generate code to fix up + the coordinates of the widget after instantiation. + + Note that methods without a code or widget node are only declared in the + header file, but no code is generated for them in the source file. ## Comments ## -![](flComment.png) Comment - - ### Parents ### + ![](flComment.png) Comment - ...write me. + This node adds a comment block to the generated source code. - ### Children ### + ### Parents ### - ...write me. + Comment nodes can be added inside Functions, Code Blocks, and Widget Classes. + If a Comment node is the top node in a tree, it will appear in the source + files even before the `// generated by FLUID ...` line. \image html comment_panel.png "Comment Properties" \image latex comment_panel.png "Comment Properties" + Comment blocks are generated by adding `// ` to the start of each line unless + the first line of a comment starts with `/*`. In that case, FLUID assumes + a correct block comment and will copy the text verbatim. + + Comments can be generated in the header file, the source file, or both. + + FLUID keeps a small database of predefined comments. Users can add reoccurring + comment blocks, license information for example, to this database via the + pulldown menu. + + Comments can also be imported from an external file. + ## Inlined Data ## @@ -308,10 +405,6 @@ Data nodes can be added at the top level or inside Widget Classes, Classes, and Declaration Blocks. - ### Children ### - - ...write me. - \image html data_panel.png "Data Properties" \image latex data_panel.png "Data Properties" @@ -329,6 +422,12 @@ in an `unsigned char` array. A second variable, holding the original data size, is declared `int` by appending `_size` to the variable name. + ``` + // .cxx + int myInlineData_size = 12034; + unsigned char myInlineData[380] = { 65, 128, ... }; + ``` + The Variable Name should be a regular C++ name. The Filename field expects the path and name of a file, relative to the location of the .fl file.