diff options
Diffstat (limited to 'fluid')
| -rw-r--r-- | fluid/README_fl.txt | 87 |
1 files changed, 43 insertions, 44 deletions
diff --git a/fluid/README_fl.txt b/fluid/README_fl.txt index 96c0cae71..9021ad410 100644 --- a/fluid/README_fl.txt +++ b/fluid/README_fl.txt @@ -24,7 +24,7 @@ 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 +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'. @@ -40,10 +40,10 @@ 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. +Fluid does not handle UTF-8 characters in any special manner (unescaped), +but stores and reads them verbatim, making UTF-8 character sequences perfectly +legal in .fl files. Fluid can translate UTF-8 into escape sequence when writing +source code files. File Structure @@ -57,11 +57,11 @@ are composed of 'Words', 'Strings', and 'Groups'. Words ----- -Words can be any sequence of ASCII and UTF8 characters. Words are -always case-sensitive. +Words can be any sequence of ASCII and UTF-8 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. +Simple Words that are composed of 'a'-'z', 'A'-'Z', '0'-'9', and '_' only are +written 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 @@ -79,22 +79,22 @@ 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 +Strings are generated with 'printf' statements in the hope 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, +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. + can be read back as a single Word. Groups ------ -To create a hierarchy, Types can be grouped within types. A group starts with +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 @@ -121,7 +121,7 @@ wehere 'v' is the version number as in FL_VERSION (major*1.0 + minor * 0.01 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 + 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 @@ -147,10 +147,10 @@ an option is missing, a default value is assumed. "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 + "utf8_in_src" : allow UTF-8 when writing source code, otherwise + escape UTF-8 sequences in source code - "avoid_early_includes" : generate the #include “myDesign.h” statement late + "avoid_early_includes" : generate the '#include <FL/Fl.H>' statement late "i18n_type" <word> : integer 0=default=none, 1=gettext, 2=catgets @@ -180,46 +180,46 @@ an option is missing, a default value is assumed. "gridy" <word> : ignored Note: There is no keyword that marks the end of the options section. The - option list ends when a word is not in the options list and it is in - the list of known types. - + option list ends when a word is not in the options list and it is in + the list of known types. + If the word is neither an option nor 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. + keywords makes .fl files incompatible to earlier versions of Fluid. Due to the forgiving interpreter, files may still be read correctly despite error messages. - - If a word is in the list of know types, the type is read, including + + If a word is in the list of known types, the type is read, including optional children. No more options are allowed beyond this point. Tree ==== -If a keyword is read that is not in the option list, we start reading types. +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 +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 +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 ‘}’. +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 + 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 + 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. +The file ends when there are no more Types. -Note: the "class" type has an additional Word following immediately after +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: @@ -234,7 +234,7 @@ Types ----- Type names are based on fltk class names. Types derive properties from super -types loosely similar to fltk. +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()' @@ -263,7 +263,7 @@ The list of known types and their inheritance is: | | +-- Fl_Scroll | | +-- Fl_Tile | | +-- Fl_Wizard - | +-- Fl_Menu_Type (note: can't be written) + | +-- Fl_Menu_Type (note: can't be written) | | +-- Fl_Menu_Button | | +-- Fl_Choice | | +-- Fl_Input_Choice @@ -305,17 +305,17 @@ The list of known types and their inheritance is: 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 +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 +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. +Note: It is possible that the same property by name has different arguments + when used in a different Type. Type Fl_Type <word> @@ -425,7 +425,7 @@ 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 + "set_size_tuples" <word> : this word is written with 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 @@ -445,8 +445,7 @@ Type "Fl_Window" <word> : C++ variable name ... : inherits more from Fl_Widget (not Fl_Group) -Please report errors and omissions to the fltk.cordev or fltk.general +Please report errors and omissions to the fltk.coredev or fltk.general Google group. Thank you. - Matthias - |