mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Remove unfinished FLUID documentation.

Browse Source 
A copy of the docs exists in my repo clone and
will be merged back when the docs are useful and
part of the CMake setup.
This commit is contained in:
Matthias Melcher 2024-02-20 15:00:49 +01:00
parent 8cce99b2c7
commit fe9ecec1be
28 changed files with 0 additions and 5908 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2587
fluid/Doxyfile
View File

File diff suppressed because it is too large Load Diff

2591
fluid/Doxyfile-dev
View File

File diff suppressed because it is too large Load Diff

BIN
fluid/documentation/src-dev/fluid-128.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 9.9 KiB

42
fluid/documentation/src-dev/index.dox
View File

@ -1,42 +0,0 @@
/**
\mainpage FLUID Developer Documentation
<TABLE CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="100%" BORDER="0">
<TR>
<TD><CENTER>
\image html fluid-128.png
\image latex fluid-128.png "" width=3cm
<B>FLUID 1.4.0 Developer Documentation</B>
By F.&nbsp;Costantini, D.&nbsp;Gibson, M.&nbsp;Melcher,
A.&nbsp;Schlosser, B.&nbsp;Spitzak and M.&nbsp;Sweet.
Copyright © 1998 - 2023 by Bill Spitzak and others.
</CENTER></TD>
</TR>
</TABLE>
<TABLE CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="100%" BORDER="0">
<TR>
<TD style="text-align: center;">
This software and manual are provided under the terms of the GNU
Library General Public License. Permission is granted to reproduce
this manual or any portion for any purpose, provided this copyright
and permission notice are preserved.
</TD>
</TR>
</TABLE>
<TABLE CELLPADDING="8" CELLSPACING="0" SUMMARY="Table of Contents" WIDTH="100%" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">
\subpage page_introduction
</TD>
</TR>
</TABLE>
*/

86
fluid/documentation/src-dev/page_introduction.dox
View File

@ -1,86 +0,0 @@
/**
\page page_introduction Introduction
\tableofcontents
## Light User Interface Design ##
FLUID is the Fast Light User Interface Designer that accompanies the fltk
user interface library. FLUID relies on panels and dialogs that are generated
within FLUID. Consequently, developers are required to consistently assess the
user-friendliness and code integrity of the application.
This document presumes you are familiar with FLUID, have read the most
important parts the FLUID User Manual, and have created some user interfaces
in FLUID already.
## History ##
FLUID is an application that grew over time with fltk. In its original design,
it was meant to allow users to drag and resize a limited number of widgets
for small dialog boxes. As the feature set grew over time, new concept and
designs were introduced by new authors. In its current state, FLUID's source
code is largely undocumented and difficult to read and understand.
This should not stop you from diving into the code though. The concepts and
ideas behind FLUID are great. The software itself is very usable and stable.
And while digging through the code, any addition to the documentation is
highly appreciated.
## Future ##
As we approach the imminent release of FLTK 1.4.0, FLUID will no longer undergo
significant feature enhancements. Instead, the focus will shift towards
documentation improvements, addressing bugs, and enhancing usability for
recent FLTK additions such as Fl_Grid and Fl_Flex. Following the release of
1.4.0, FLUID will undergo a comprehensive restructuring and modernization,
streamlining maintenance and simplifying the process of integrating
support for new widgets.
## Quick Glossary ##
__Project__ : a project is a single design, stored in a project file ending in
`.fl`. A project contains a bunch of settings and a tree of Types. One
project can contain multiple UI designs.
__Code File__, __Header File__ : by default, FLUID generates C++ source code
that is stored in two files with the same basename as the project. The
C++ declarations go into the header file ending in `.h`, and the
implementation is stored in the `.cxx` source code file.
__Strings File__ : FLUID supports internationalization (in short i18n) of all
know text elements in a project. The Strings file can be generated as a
base for adding new languages. The file extension depend on the chosen
i18ns library.
__Types__ : a type is a node in a tree that manages a widget or a functional
node like Class, Function, CodeBlock, etc.
__Panels__ : in its interactive incarnation, FLUID provides a number of panels
(dialog boxes) for editing all aspects of Types.
## Basic Structure ##
...
## Wish List ##
I call this a wish list because I write my wishes down as I go. There is no
verification yet, or alternative ideas.
- group source files into subdirectories
- all panels should have their own folder
- all custom widgets
- all file and stream operations
- all utilities and tools
- move to C++17 and use std::string, vector, map, ...
- Fl_Type::write#() could go into a single write function with an enum to
describe what needs to be written to make thing logical and expandable
- better error handling in all file classes
- separate FLUID generated files form the core and build a shell-only version
- individual event handling for types
- individual overlay drawing for types
- plug-ins for new types
*/

BIN
fluid/documentation/src/flCode.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 311 B

BIN
fluid/documentation/src/flFunction.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 388 B

BIN
fluid/documentation/src/flFunctionDialog.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

BIN
fluid/documentation/src/fluid-128.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 9.9 KiB

BIN
fluid/documentation/src/fluid_flow_chart.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 81 KiB

BIN
fluid/documentation/src/fluid_flow_chart_800.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 41 KiB

108
fluid/documentation/src/index.dox
View File

@ -1,108 +0,0 @@
/**
\mainpage FLUID User Manual
<TABLE CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="100%" BORDER="0">
<TR>
<TD><CENTER>
\image html fluid-128.png
\image latex fluid-128.png "" width=3cm
<B>FLUID 1.4.0 User Manual</B>
By F.&nbsp;Costantini, D.&nbsp;Gibson, M.&nbsp;Melcher,
A.&nbsp;Schlosser, B.&nbsp;Spitzak and M.&nbsp;Sweet.
Copyright © 1998 - 2023 by Bill Spitzak and others.
</CENTER></TD>
</TR>
</TABLE>
<TABLE CELLPADDING="8" CELLSPACING="0" SUMMARY="TITLE BAR" WIDTH="100%" BORDER="0">
<TR>
<TD style="text-align: center;">
This software and manual are provided under the terms of the GNU
Library General Public License. Permission is granted to reproduce
this manual or any portion for any purpose, provided this copyright
and permission notice are preserved.
</TD>
</TR>
</TABLE>
<TABLE CELLPADDING="8" CELLSPACING="0" SUMMARY="Table of Contents" WIDTH="100%" BORDER="0">
<TR>
<TD ALIGN="LEFT" VALIGN="TOP">
\subpage page_introduction
- \ref introduction_workflow
\subpage page_getting_started
_not yet_
\subpage page_ui_overview
_not yet_
\subpage page_basics
_not yet_
\subpage page_widget_types
_not yet_
\subpage page_layout
_not yet_
\subpage page_code_integration
_not yet_
\subpage page_build_integration
_not yet_
\subpage page_advanced
_not yet_
</TD>
<TD ALIGN="LEFT" VALIGN="TOP">
\subpage page_shortcuts
_not yet_
\subpage page_faqs
_not yet_
\subpage page_glossary
_not yet_
\subpage page_appendices
- \ref appendix_code_nodes
- \ref appendix_app_settings
\subpage page_index
_not yet_
\subpage page_legal
_not yet_
\subpage page_conclusion
_not yet_
</TD>
</TR>
</TABLE>
*/

9
fluid/documentation/src/page_advanced.dox
View File

@ -1,9 +0,0 @@
/**
\page page_advanced Advanced Features
\tableofcontents
- Describe any advanced or less commonly used features of FLUID, such as custom scripting, animations, or specialized widgets.
*/

277
fluid/documentation/src/page_appendices.dox
View File

@ -1,277 +0,0 @@
/**
\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.
*/

8
fluid/documentation/src/page_basics.dox
View File

@ -1,8 +0,0 @@
/**
\page page_basics Basic Operations
\tableofcontents
- Provide step-by-step instructions for common tasks, such as creating a new project, opening existing projects, and saving work.
*/

10
fluid/documentation/src/page_build_integration.dox
View File

@ -1,10 +0,0 @@
/**
\page page_build_integration Integration into Build Systems
\tableofcontents
- Explain how to integrate FLUID into build systems like Makefiles, CMake,
or IDEs.
*/

9
fluid/documentation/src/page_code_integration.dox
View File

@ -1,9 +0,0 @@
/**
\page page_code_integration Code Integration
\tableofcontents
- Explain how to integrate code into FLUID, including code nodes and event handling.
*/

15
fluid/documentation/src/page_conclusion.dox
View File

@ -1,15 +0,0 @@
/**
\page page_conclusion Conclusion
\tableofcontents
- Wrap up the manual with a thank-you message, encouraging users to explore FLUID further.
## Feedback and Contact Information ##
- Encourage users to provide feedback and include contact information for support or inquiries.
## Revision History ##
- If you plan to update the manual over time, maintain a section for revision history to track changes and updates.
*/

9
fluid/documentation/src/page_faqs.dox
View File

@ -1,9 +0,0 @@
/**
\page page_faqs FAQs
\tableofcontents
- Include a section with frequently asked questions and their answers.
*/

10
fluid/documentation/src/page_getting_started.dox
View File

@ -1,10 +0,0 @@
/**
\page page_getting_started Getting Started
\tableofcontents
- Walk users through the initial setup and installation process.
- Explain how to launch the FLUID editor.
*/

9
fluid/documentation/src/page_glossary.dox
View File

@ -1,9 +0,0 @@
/**
\page page_glossary Glossary
\tableofcontents
- Define any technical terms or jargon used in FLUID.
*/

7
fluid/documentation/src/page_index.dox
View File

@ -1,7 +0,0 @@
/**
\page page_index Index
- Include an index to help users quickly find specific topics or terms within the manual.
*/

35
fluid/documentation/src/page_introduction.dox
View File

@ -1,35 +0,0 @@
/**
\page page_introduction Introduction
\tableofcontents
The Fast Light User Interface Designer, or FLUID, is a graphical editor that
can produce ready to compile C++ source code and header files.
This user manual will introduce FLUID, starting with the installation process,
an overview of the main application window, and how to compile and run a
simple program. I will explain how to generate a more complex user interface
with three short tutorial, followed by some advanced subject like creating
integrated reusable widget classes. The appendices will sum up node types
and code generation in more detail.
\section introduction_workflow Workflow
FLUID has two modes of operation. When started from the shell without command
line arguments, or when launched from the desktop, FLUID will open in
interactive mode.
If FLUID is started from the command line with `-u`, `-c`, or `cs`, it will
not open any user interface, but instead behave like any shell-only tool that
can be easily integrated into Makefiles and build systems like CMake.
\image html fluid_flow_chart_800.png
\image latex fluid_flow_chart.png "" width=10cm
FLUID organization
More details on the command line arguments of FLUID can be found
in the chapter \ref page_build_integration .
*/

10
fluid/documentation/src/page_layout.dox
View File

@ -1,10 +0,0 @@
/**
\page page_layout Layout and Design
\tableofcontents
- Discuss how to arrange and design UI elements in the editor.
- Cover alignment, grouping, and layout management.
*/

9
fluid/documentation/src/page_legal.dox
View File

@ -1,9 +0,0 @@
/**
\page page_legal Legal and Copyright Information
\tableofcontents
- Include legal disclaimers, copyright information, and any terms of use or licensing agreements.
*/

59
fluid/documentation/src/page_shortcuts.dox
View File

@ -1,59 +0,0 @@
/**
\page page_shortcuts Keyboard Shortcuts
On Apple computers, use the Apple Command key instead of Ctrl.
| | Shortcut | Location | Function |
|:-:|----------|----------|----------|
|A| Ctrl-A | Edit > Select All | extend selection to all siblings and descendants |
|^| Shift-Ctrl-A | Edit > Select None | deselect all types |
|B| Alt-B | Edit > Widget Bin | show or hide the widget bin |
|C| Ctrl-C | Edit > Copy | copy selected types and all descendants |
|^| Shift-Ctrl-C | File > Code | generate the code and header files |
|G| Ctrl-G | Layout > Grid and Size... | show grid and size setting dialog |
|^| Shift-Ctrl-G | Edit > Guides | show or hide alignment guides |
|^| Alt-G | Shell > Sample Script | custom shortcut for a default sample script |
|I| Ctrl-I | File > Insert... | merge a project file into the current project |
|N| Ctrl-N | File > New | start a new project |
|^| Shift-Ctrl-N | File > New From Template.. | open a dialog with a list of project templates |
|O| Ctrl-O | File > Open... | open a project file |
|^| Shift-Ctrl-O | Edit > Overlays | show or hide overlay in interactive windows |
|P| Ctrl-P | File > Print... | print a snapshot of every project window |
|^| Alt-P | Edit > Settings... | show settings dialog |
|Q| Ctrl-Q | File > Quit | Fluid beenden |
|R| Shift-Ctrl-R | Edit > Restricted | show or hide restricted or conflicting areas |
|S| Ctrl-S | File > Save | write the current project to a file |
|^| Shift-Ctrl-S | File > Save As... | write the current project using a new filename |
|^| Shift-Alt-S | Edit > Source Code | show or hide source code live preview |
|U| Ctrl-U | Edit > Duplicate | duplicate selected types |
|V| Ctrl-V | Edit > Paste | paste copied type into selected type |
|W| Shift-Ctrl-W | File > Write Strings | generate the strings for internationalisation |
|X| Ctrl-X | Edit > Cut | cut selected types |
|^| Alt-X | Shell > Customize... | open shell settings dialog |
|Z| Ctrl-Z | Edit > Undo | undo last operation |
|^| Shift-Ctrl-Z | Edit > Redo | undo the previous undo |
| | | | |
|#| Ctrl-1..9 | File > (history) | load project from previous file history |
| | Del | Edit > Delete | delete selected types |
| | | | |
|fn| F1 | Edit > Properties | open the properties dialog for selected types |
|^| F2 | Edit > Earlier | move selected type up in the sibling list |
|^| F3 | Edit > Later | move selected type down in the sibling list |
|^| F7 | Edit > Group | enclose selected type in a new group |
|^| F8 | Edit > Ungroup | move all selected types out of a group and delete the group |
| Action | Function in interactive Window |
|--------|--------------------------------|
| LMB | select one widget |
| Shift-LMB | extend widget selection |
| Shift-LMB-Drag | window type only: resize proportional |
| Tab | select next |
| Shift-Tab | select previous |
| Arrow Key | move widget by one unit |
| Shift-Arrow | resize by one unit |
| Ctrl-Arrow | move by grid units |
| Shift-Ctrl-Arrow | resize by grid units |
| Alt-Arrow | rearrange widget inside a layout group like Fl_Grid or Fl_Flex |
*/

8
fluid/documentation/src/page_ui_overview.dox
View File

@ -1,8 +0,0 @@
/**
\page page_ui_overview User Interface Overview
\tableofcontents
- Describe the main components of the FLUID user interface, including menus, toolbars, panels, and any unique features.
*/

10
fluid/documentation/src/page_widget_types.dox
View File

@ -1,10 +0,0 @@
/**
\page page_widget_types Widgets and Elements
\tableofcontents
- Explain how to add, modify, and delete widgets and UI elements.
- Detail the available widget libraries and their usage.
*/