mirror of https://github.com/fltk/fltk
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>
This commit is contained in:
Matthias Melcher
GitHub
parent
a6b3903b89
commit
ec47afb7eb
|
|
@ -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
|
||||
|
||||
Loading…
Reference in New Issue