diff options
| -rw-r--r-- | fluid/README_fl.txt | 461 |
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 + |