Skip to content

Commit

Permalink
Finished docs for non-widget nodes.
Browse files Browse the repository at this point in the history
  • Loading branch information
@MatthiasWM
MatthiasWM committed Mar 17, 2024
1 parent fb05298 commit d50de99
Show file tree
Hide file tree
Showing 3 changed files with 149 additions and 66 deletions.
16 changes: 10 additions & 6 deletions fluid/Fl_Function_Type.cxx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1534,19 +1534,23 @@ 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);
}
}

/**
Write the \b after code to the source file, and to the header file if declared public.
*/
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
Expand Down
30 changes: 5 additions & 25 deletions fluid/autodoc.cxx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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());

}


Expand Down
169 changes: 134 additions & 35 deletions fluid/documentation/src/page_appendices.dox
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -60,7 +60,7 @@
```
// .cxx
void make_window() {
// code generated by children
// code generated by children
}
```

Expand Down Expand Up @@ -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
Expand All @@ -108,7 +108,7 @@
// .h
class UserInterface {
public:
void make_window();
void make_window();
};
```

Expand All @@ -118,7 +118,7 @@
```
// .cxx
void UserInterface::make_window() {
printf("Hello, World!\n");
printf("Hello, World!\n");
}
```

Expand All @@ -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;
}
```

Expand Down Expand Up @@ -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 ##
Expand All @@ -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"

Expand All @@ -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.

Expand Down

0 comments on commit d50de99

Please sign in to comment.