Adding Fluid file format README. (#533)

* Adding Fluid file format README.

* Update fluid/README_fd.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fd.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fd.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fd.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fd.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fd.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fd.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fd.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fd.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Typos, changes, restructuring.

* Changed filename.

* More typos,

* Typo.

* Update fluid/README_fl.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fl.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fl.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fl.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fl.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

* Update fluid/README_fl.txt

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

Co-authored-by: Peter0x44 <peter0x44@snopyta.org>

1 files changed, 461 insertions, 0 deletions

diff --git a/fluid/README_fl.txt b/fluid/README_fl.txt
new file mode 100644
index 000000000..49dcc6049
--- /dev/null
+++ b/fluid/README_fl.txt
@@ -0,0 +1,461 @@
+
+Fluid .fl file format version 1.4
+=================================
+
+This text explains the history of the Fluid .fl format and faithfully describes
+all elements of the format and its caveats.
+
+
+History
+-------
+
+Fluid, the Fast Light User Interface Designer was started in the 1990's loosely
+based on 'fdesign', a GUI designer that came with the 'Forms Library', later
+'XForms Library'. Fluid's .fl file format was originally compatible with the
+fdesign '.fd' format, but evolved somewhat ad hoc to become what it is today.
+
+
+Basics
+======
+
+Fluid is a visual editor, storing the user interface description in .fl files
+with the ability to create ready-to-compile C++ code. Fluid can also be used
+as a command line tool to translate .fl files directly into source code. It
+can be integrated into build scripts and most IDEs as an external tool.
+
+.fl files describe a hierarchical graphical user interface for the 'fltk'
+library as a tree structure. Elements in the tree can be fltk Widgets as well
+as functional components like classes, C++ functions, variables, etc. .
+Fluid calls all elements in the hierarchy 'Type'.
+
+
+Line Endings
+------------
+
+Although Fluid writes all line endings as '\n', readers should tolerate '\r\n'
+MSWindows line endings as well. Except for the header, the Fluid reader does not
+differentiate between a line ending and a space character outside of a 'word'.
+
+
+Unicode
+-------
+
+Fluid does not handle UTF8 characters in in any special manner (unescaped),
+but stores and reads them verbatim, making UTF8 character sequences perfectly
+legal in .fl files. Fluid can translate UTF8 into escape sequence when writing
+source code file.
+
+
+File Structure
+--------------
+
+.fl files start with a 'Header', followed by a list of 'Options', followed
+by a hierarchy of 'Type' entires, the 'Tree'. All elements besides the header
+are composed of 'Words', 'Strings', and 'Groups'.
+
+
+Words
+-----
+
+Words can be any sequence of ASCII and UTF8 characters. Words are
+always case-sensitive.
+
+Simple words that are composed of 'a'-'z', 'A'-'Z', '0'-'9', and '_' only are
+writen verbatim, followed by a space or newline.
+
+All other character sequences are bracketed between between ‘{‘ and ‘}’ without
+padding spaces. For example, "" is written as ‘{}’, and ".hello" is written as
+`{.hello}`.
+
+The special characters ‘\’ and ‘#’ are escaped by prepending the ‘\’ character,
+so "#define" is written as '{\#define}`.
+
+The characters ‘{‘ and ‘}’ are also escaped with a '\' unless every opening
+‘{‘ in the word is matched with a closing ‘}’.
+
+Note: line endings are copied verbatim and become significant within a Word.
+
+
+Strings
+-------
+
+Strings are generated with 'printf' statements in the hopes that the
+generated text can be read back as one word, followed by a corresponding
+'scanf' to retrieve the original values.
+
+Note: As there are no defined start and end markers to a string, a reader must
+      know when these strings appear and be prepared to read them correctly,
+      even if the String itself is not useful to the reader.
+
+Note: All Strings that are generated by the current Fluid source code
+      can be read back as a single word.
+
+
+Groups
+------
+
+To create a hierarchy, Types can be grouped within types. A group starts with
+a lone '{' and ends with a lone '}'.
+
+Note: To know whether a '{' character starts a Word or a Group, the reader must
+      know its position within the Type sequence (see 'Types' below).
+
+
+Elements
+========
+
+
+Header
+------
+
+The header for any .fl file is
+
+  # data file for the Fltk User Interface Designer (fluid)
+
+followed by a newline, followed by
+
+  version <float v>
+
+wehere 'v' is the version number as in FL_VERSION (major*1.0 + minor * 0.01
++ patch * 0.0001). So for fltk 1.3.4, 'v' would be 1.0304
+
+Note: the version number corresponds not so much to the version of Fluid, but
+      to the version of the underlying fltk library. So unless the version of
+      fltk is finalised, the file format in the github master branch can still
+      change unexpectedly.
+
+Note: if the version number is above the internal version number, Fluid will
+      report an error and continue reading, hoping for the best.
+      There are no other uses inside the Fluid reader except for fltk2 features
+      which is beyond the scope of this document.
+
+Note: fdesign files (.fd) start with the text "Magic:". Fluid can read these
+      files, but Forms/XForms files are beyond the scope of this document.
+
+
+Options
+-------
+
+Options are usually comprised of a Word, two Words, or a Word and a String. If
+an option is missing, a default value is assumed.
+
+  "Magic:" : used by fdesign, not written by Fluid
+
+  "define_in_struct" : no longer used
+
+  "do_not_include_H_from_C" : don’t generate #include “myDesign.h”
+
+  "use_FL_COMMAND" : use macOS CMD key instead of Ctrl
+
+  "utf8_in_src" : allow utf8 when writing source code, otherwise
+      escape utf8 sequences in source code
+
+  "avoid_early_includes" : generate the #include “myDesign.h” statement late
+
+  "i18n_type" <word> : integer 0=default=none, 1=gettext, 2=catgets
+
+  "i18n_function" <word> : function name, e.g. “gettext”
+
+  "i18n_static_function" <word> : function name, e.g. “gettext_noop”
+
+  "i18n_file" <word> : file name
+
+  "i18n_set" <word> : string
+
+  "i18n_include" <word> : file name, e.g. “<libintl.h>”
+
+  "i18n_conditional" <word> : string
+
+  "header_name" <word> : can be the full filename, or just the
+      extension e.g. “.h” in which case Fluid will use the same filename
+      as the .fl file.
+
+  "code_name" <word> : can be the full filename, or just the
+      extension e.g. “.cxx”
+
+  "snap" <word> : ignored
+
+  "gridx" <word> : ignored
+
+  "gridy" <word> : ignored
+
+  "win_shell_cmd" <word> : string, this is the recommended command when calling
+      the shell on an MSWindows machine. Implementation may be problematic.
+
+  "win_shell_flags" <word> : integer, interpreted as a bit field: bit 0 is set
+      if the .fl must be save before runing the shell command, bit 1 is set for
+      saving the source code, bit 2 is set for saving text strings.
+
+  "linux_shell_cmd" <word> : as above for Linux
+
+  "linux_shell_flags" <word> :  : as above for Linux
+
+  "mac_shell_cmd" <word> : as above for macOS
+
+  "mac_shell_flags" <word> : as above for macOS
+
+Note: There is no keyword that marks the end of the options section. The
+      Tree section starts when a word is not in the options list. If the word
+      is not a vaild type, Fluid will give an error message and try to continue
+      to read the file. Using new option keywords makes .fl files incompatible
+      to earlier versions of Fluid. Due to the forgiving interpreter, files may
+      still be read correctly despite error messages.
+
+
+Tree
+====
+
+If a keyword is read that is not in the option list, we start reading types.
+Types represent all possible entries in the hierarchy including C functions,
+class definitions, and of course all widgets. A type is any of the supported
+widgets classes, or one of the following:
+
+Function, code, codeblock, decl, data, declblock, comment, class, widget_class
+
+Every Type keyword is followed by a word, which is usually interpreted as the
+C++ name of the Type, followed by an opening `{`, a list of properties, and
+a closing ‘}’. If the type has children, they are stored in a Group between
+another opening ‘{‘, followed by a list of types, followed by a closing ‘}’.
+
+  Fl_Group MyGroup {                    type name start_of_options
+    label Surprise ...                    option parameter
+  } {                                   end_of_options start_of_children
+    Fl_Button {} {                        type name start_of_options
+      label {Don't panic...!}               option parameter
+      hide                                  option
+    }                                     end_of_options
+  }                                     end_of_children
+
+The file ends when there are no more types.
+
+Note: the "class" type has an additional Word following immediately after
+      the keyword. It contains the prefix for the class. A class definition may
+      be written as:
+
+        class FL_EXPORT MyClass { ...properties... } { ...children... }
+
+      or without a prefix as
+
+        class {} MyOtherClass { ...properties... } { ...children... }
+
+
+Types
+-----
+
+Type names are based on fltk class names. Types derive properties from super
+types loosely similar to fltk.
+
+Note: the hierarchical dependency is implemented twice and somewhat conflicting
+      in Fluid via the Fl_..._Type hierarchy, and by using '::is_some_type()'
+      virtual functions, which does not always match the type hierarchy.
+
+
+The list of known types and their inheritance is:
+
+  Fl_Type (note: can't be written)
+   +-- Function
+   +-- code
+   +-- codeblock
+   +-- decl
+   +-- data
+   +-- declblock
+   +-- comment
+   +-- class
+   +-- Fl_Widget (note: can't be written)
+   |    +-- Fl_Window
+   |    |    +-- widget_class
+   |    +-- Fl_Group
+   |    |    +-- Fl_Pack
+   |    |    +-- Fl_Flex
+   |    |    +-- Fl_Table
+   |    |    +-- Fl_Tabs
+   |    |    +-- Fl_Scroll
+   |    |    +-- Fl_Tile
+   |    |    +-- Fl_Wizard
+   |    +-- Fl_Menu_Type  (note: can't be written)
+   |    |    +-- Fl_Menu_Button
+   |    |    +-- Fl_Choice
+   |    |    +-- Fl_Input_Choice
+   |    |    +-- Fl_Menu_Bar
+   |    |    +-- Fl_
+   |    +-- Fl_Box
+   |    +-- Fl_Button
+   |    |    +-- Fl_Return_Button
+   |    |    +-- Fl_Light_Button
+   |    |    +-- Fl_Check_Button
+   |    |    +-- Fl_Round_Button
+   |    +-- Fl_Repeat_Button
+   |    +-- Fl_Browser
+   |    +-- Fl_Check_Browser
+   |    +-- Fl_Tree
+   |    +-- Fl_File_Browser
+   |    +-- Fl_Counter
+   |    +-- Fl_Spinner
+   |    +-- Fl_Input
+   |    |    +-- Fl_Output
+   |    +-- Fl_File_Input
+   |    +-- Fl_Text_Display
+   |    +-- Fl_Text_Editor
+   |    |    +-- Fl_Simple_Terminal
+   |    +-- Fl_Clock
+   |    +-- Fl_Help_View
+   |    +-- Fl_Progress
+   |    +-- Fl_Adjuster
+   |    +-- Fl_Dial
+   |    +-- Fl_Roller
+   |    +-- Fl_Slider
+   |    |    +-- Fl_Scrollbar
+   |    |    +-- Fl_Value_Slider
+   |    +-- Fl_Value_Input
+   |    +-- Fl_Value_Output
+   .
+
+
+Properties
+----------
+
+Properties have zero or one words as their arguments. The number of arguments
+are defined per property per type. The content of the argument word is defined
+by the implementation of the property and can contain mutiple values, as
+described above in Strings.
+
+Properties are inherited from super types. They can be limited to certain types
+by calls to 'MyType->is_some_type()'. All properties are optional, some are
+mutually exclusive.
+
+Note: It is possible that the same peroperty by name has different arguments
+      when used in a different type.
+
+
+Type Fl_Type <word>
+
+  “label” <word> : text
+  “user_data” <word> : a value or an expression
+  “user_data_type” <word> : usually “void*” or “long”
+  “callback” <word> : a function name or a function body
+  “comment” <word> : one or many lines of text
+  “open” : group content visible in the Fluid tree browser
+  “selected” : type was selected in tree view
+
+Type "Function" <word> : function signature
+
+  none or "private" or "protected" : for methods in classes, or to mark
+      functions static in a file, default is public
+  “C” : if set, function is extern “C”
+  “return_type” <word> : C or C++ type descriptor, can start with “virtual”
+      and/or “static” to further define the function.
+  ... : inherits more from Fl_Type
+
+Type codeblock <word> : C++ code, usually an 'if
+
+  "after" <word> : C++ code or comment following the closing '}'
+  ... : inherits more from Fl_Type
+
+Type "decl" <word> : C++ code to declare a variable or class member
+
+  none or "public" or "private" or "protected" : for declarations within classes
+      defaults to "private"
+  none or "local" or "global": for declaration in the code body
+      defaults to "global"
+  ... : inherits more from Fl_Type
+
+Type "data" <word> : C++ variable name
+
+  "filename" <word> : name or path as entered by user, forward slashes
+  "textmode" : defaults to binary mode
+  ... : inherits more from decl
+
+Type "declblock" <word> : C++ code
+
+  none or "public" or "protected" : defaults to private
+  "after" <word> : C++ code or comment following the block
+  ... : inherits more from Fl_Type
+
+Type "comment" <word> : comment text
+
+  "in_source" or "not_in_source": default to in_source
+  "in_header" or "not_in_header": default to in_header
+  ... : inherits more from Fl_Type
+
+Type "class" <word> <word> : prefix, class name
+
+  none or "private" or "protected" : defaults to public
+  ":" <word> : name of super class
+  ... : inherits more from Fl_Type
+
+Type "Fl_Widget" <word> : C++ variable name
+
+  none or "private" or "protected" : default is public
+  "xywh" <word> : "{%d %d %d %d}" x, y, w, h
+  "tooltip" <word> : tooltip text
+  "image" <word> : image name
+  "deimage" <word> : deactivated image name
+  "type" <word> : integer
+  "box" <word> : text or integer (see fltk boxtypes)
+  "down_box" <word> : (is_button() or Fl_Input_choice" or is_menu_button())
+      text or integer (see fltk boxtypes)
+  "value" <word> : (is_button()) integer
+  "value" <word> : (is_valuator(), is_spinner()) double
+  "color" <word> :
+      If word starts with "0x", the rest of the field is a hex number.
+      If two integers follow, this is color and selection_color (deprecated).
+      If one integer follows, it's the color index.
+  "selection_color" <word> : integer color index
+  "labeltype" <word> :
+      If the word is "image", TBD.
+      Or one of "NORMAL_LABEL", "SHADOW_LABEL", "ENGRAVED_LABEL",
+      "EMBOSSED_LABEL", or "NO_LABEL"
+  "labelfont" <word> : integer, font index
+  "labelsize" <word> : integer
+  "labelcolor" <word> : integer, color index
+  "align" <word> : integer, see Fl_Align
+  "when" <word> : integer, see Fl_When
+  "minimum" <word> : (is_valuator(), is_spinner()) double
+  "maximum" <word> : (is_valuator(), is_spinner()) double
+  "step" <word> : (is_valuator(), is_spinner()) double
+  "slider_size" <word> : (is_valuator()==2) double
+  "size" <word> : (is_valuator()==2) double
+  "textfont" <word> : integer, font index
+  "textsize" <word> : integer
+  "textcolor" <word> : integer, color index
+  "hide" : default visible
+  "deactivate" : default active
+  "resizable" : default fixed
+  "hotspot" : make hotspot
+  "divider" : make hotspot
+  "class" <word> : superclass
+  "shortcut" <word> : integer
+  "code0" or "code1" or "code2" or "code3" <word> : C++ extra code lines
+  "extra_code" <word> : C++ extra code lines
+  ... : inherits more from Fl_Type
+
+Type "Fl_Flex" <word> : C++ variable name
+
+  "margins" <word> : this word is written with printf as "{%d %d %d %d}",
+      left, top, right, bottom
+  "gap" <word> : integer
+  "set_size_tuples" <word> : this word is written printf "{%d", where %d
+      encodes the number of tuples to follow, and zero or more " %d %d"
+      containing the index and size of that child, followed by a '}'.
+  ... : inherits more from Fl_Group
+
+Type "Fl_Window" <word> : C++ variable name
+
+  none or "modal", or "non_modal": defaults to not modal (which is
+      different to non_modal!)
+  "visible" : show window when opening file in Fluid
+  "noborder" : borderless window
+  "xclass" <word> : see fltk
+  "size_range" : this word is written with printf as "{%d %d %d %d}",
+      min_w, min_h, max_w, max_h
+  "xywh" <word> : this word is written with printf as "{%d %d %d %d}",
+      x, y, w, h. This as actually read in the Fl_Widget Type, but here
+      it ensures that window is not created as a subwindow.
+  ... : inherits more from Fl_Widget (not Fl_Group)
+
+
+Please report errors and omissions to the fltk.cordev or fltk.general
+Google group. Thank you.
+
+ - Matthias
+