Fl_Preferences documentation update.

1 files changed, 119 insertions, 0 deletions

diff --git a/src/Fl_Preferences.cxx b/src/Fl_Preferences.cxx
index d4284af19..a53ef335b 100644
--- a/src/Fl_Preferences.cxx
+++ b/src/Fl_Preferences.cxx
@@ -32,6 +32,125 @@
 #include <string>
 #endif
 
+/*
+ The format of preferences files is not part of the FLTK specification
+ and intentionally undocumented in Doxygen. The following documentation is FOR
+ CORE DEVELOPERS ONLY. Don't let any app developer see this!
+
+ This is the unofficial documentation of the file format as it currently stands.
+ The format may change at any point (although it really should stay backwards
+ compatible). Preferences files are supposed to be edited manually.
+ Nevertheless, here are the docs:
+
+ A .prefs file contains multiple lines. A line is defined a 0 or more ASCII 
+ characters in the range from 0x20 to 0x7e, followed by a single '\n' line
+ ending character. Note that there are no tabs, \0 characters, or '\r'
+ characters anywhere in a line. Some parts of a line may allow 0x80 to 0xff
+ to support Unicode UTF8 octets.
+
+ The first line is always "; FLTK preferences file format 1.0", followed by a 
+ '\n' to indicate the end of the line. The version number may change some time
+ in the future if the file format ever changes.
+
+ The second line contains the vendor information when the file was created: 
+ "; vendor: VENDOR\n"
+
+ The third line contains the application name 
+ "; application: APPLICATION_NAME\n"
+
+ Any following line that starts with a ';' is not relevant for data and seen 
+ as a comment. Fl_Preferences tries to preserve comments, but has no API to set
+ or read comments.
+
+ All data is stored in key/value pairs. All key/value pairs are store inside
+ their group. There can be multiple groups. Group naming is used to
+ indicate a hierarchy.
+
+ A line starting with a '[' starts a group. Before and after a group line, 
+ there is always an empty line (no characters, just a '\n'). A group line ends
+ in "]\n". Directly between the '[] and ']' is the name of the group. The first
+ ("root")-group is always declared with the line "[.]\n".
+
+ Simple group names are written starting with "./", for example "[./name]\n".
+ To generate a hierarchy of groups, deeper nested names are generated by adding
+ more '/name" segments (just like a Unix file path),
+ for example "[./dialog/button/position]\n".
+
+ Remember that there is an empty line after the group line.
+
+ A group line is followed by 0 or more lines containing key/value pairs for the
+ given group.
+
+ A key is a sequence of ASCII letters, numbers, ".", or "_". The key should not
+ be longer than 32 characters. The key is followed by the ":" character and
+ the value. There is no space before or after the ":". The value may contain
+ more ":" characters.
+
+ The value is a text of ASCII characters 0x20 to 0x7e, or UTF8 Unicode octets 
+ 0x80 to 0xff.
+
+ The key/value line ends in a "\n". Key/value lines wrap before or at column 80
+ with a "/n" and continue in the next line, starting with a "+" which indicates
+ that this is an overflow line and is furthermore ignored. The type of a value
+ is not stored in a file. It is not an error to call Fl_Preferences::set with a
+ "double" and read back a string.
+
+ * Integers are written as signed int using "%d".
+ * Floating point values are written with decimal points if C_LOCALE is set 
+   when creating the file.
+ * When text is written, "\r", "\n", and the "\" character are escaped by
+   prepending them with an additional "\", other characters <0x20 and 0x7f
+   are encoded in octal format: "\001", UTF-8 is allowed.
+ * Binary data is written as lower case hex digits, two digits per byte.
+
+ Example data as generated by the test/preferences app:
+
+ ```
+ ; FLTK preferences file format 1.0
+ ; vendor: fltk.org
+ ; application: test/preferences
+
+ [.]
+
+
+ [./Bed]
+
+ ; The value is "8:00". Values can contain a ':' character
+ alarm:8:00
+ ; Some integer values
+ ampm:0
+ wear:2
+ side:1
+ taskFlags:5
+
+ [./Breakfast]
+
+ drink:1
+ wMilk:1
+ bread:1
+ wButter:1
+ nEggs:2
+ ; A floating point value
+ minutes:4.91
+ newspaper:NY Tymes
+ ; A text value containing newlines and two other control codes
+ foo:bar\nfly\rBackslash: \\ and bell: \007 and delete: \177\n
+ ; A key can be numeric, but the numeric value has no special meaning
+ 3:Test3
+ ; Short binary data block. Data is written verbatim,
+ ; CPU endianess has no meaning here
+ binFoo:2387efcd
+ ; A long binary data block, generating wrapped lines
+ binFoo2:7c0802a6bfc1fff8900100089421ff707c3e0b78429f00057fe802a6381e
+ +00487c030378388000013c5f000538a287c43c5f000538c287d04801be31381e0050385e00487c03
+ +03787c4413783c5f000538a287e44801b6f93c5f00053842dc70800200007c030378480450197c69
+ +1b78381e00507c0303783c5f0005388287e87d254b784801ab253c5f00053842dc6c800200007c03
+ +0378480450097c691b78381e00507c0303783c5f0005388287f87d254b784801af8d3c5f00053842
+ +dc14800200007c03037848044fd97c691b78381e00507c0303783c5f0005388288007d254b784801
+ +af5d38000000901e00403c5f00053842db84800200007c030378
+ ```
+ */
+
 char Fl_Preferences::nameBuffer[128];
 char Fl_Preferences::uuidBuffer[40];
 Fl_Preferences *Fl_Preferences::runtimePrefs = 0;