From 006d71c663112316c49ff50f395f7d0aef8ebfe8 Mon Sep 17 00:00:00 2001 From: Matthias Melcher Date: Sat, 11 Jan 2020 00:19:58 +0100 Subject: Improved documentation of Fl_Preferences. Detailed information on how preference file paths are generated, and preliminary docs what happens if that fails. Documentation, on what FLTK die pre 1.4 when any of this failed. Also, a little TODO list for me that I will hopefully get to in the next days. --- src/Fl_Preferences.cxx | 97 ++++++++++++++++++++++++++++++++++---------------- 1 file changed, 67 insertions(+), 30 deletions(-) diff --git a/src/Fl_Preferences.cxx b/src/Fl_Preferences.cxx index 4ac4d8a69..d30ed2e7b 100644 --- a/src/Fl_Preferences.cxx +++ b/src/Fl_Preferences.cxx @@ -98,31 +98,69 @@ unsigned int Fl_Preferences::file_access() } /** - The constructor creates a group that manages name/value pairs and - child groups. Groups are ready for reading and writing at any time. - The root argument is either Fl_Preferences::USER - or Fl_Preferences::SYSTEM. - - This constructor creates the base instance for all - following entries and reads existing databases into memory. The - vendor argument is a unique text string identifying the - development team or vendor of an application. A domain name or - an EMail address are great unique names, e.g. - "researchATmatthiasm.com" or "fltk.org". The - application argument can be the working title or final - name of your application. Both vendor and - application must be valid relative UNIX pathnames and - may contain '/'s to create deeper file structures. - - A set of Preferences marked "run-time" exists exactly one per application and - only as long as the application runs. It can be used as a database for - volatile information. FLTK uses it to register plugins at run-time. - - \param[in] root can be \c USER or \c SYSTEM for user specific or system wide - preferences - \param[in] vendor unique text describing the company or author of this file - \param[in] application unique text describing the application -*/ + The constructor creates a group that manages name/value pairs and + child groups. Groups are ready for reading and writing at any time. + The root argument is either Fl_Preferences::USER + or Fl_Preferences::SYSTEM. + + This constructor creates the base instance for all + following entries and reads existing databases into memory. The + vendor argument is a unique text string identifying the + development team or vendor of an application. A domain name or + an EMail address are great unique names, e.g. + "research.matthiasm.com" or "fluid.fltk.org". The + application argument can be the working title or final + name of your application. Both vendor and + application must be valid UNIX path segments and + may contain forward slashes to create deeper file structures. + + A set of Preferences marked "run-time" exists exactly once per application and + only as long as the application runs. It can be used as a database for + volatile information. FLTK uses it to register plugins at run-time. + + \note On \b MSWindows, the directory is constructed by querying the Common AppData + or AppData key of the Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders + registry entry. The filename and path is then constructed as $(query)/$(vendor)/$(application).prefs . + If the query call fails, data will be stored in RAM only and be lost when the app exits. + + \par In FLTK versions before 1.4.0, if querying the registry failed, preferences would be written to + C:\FLTK\$(vendor)\$(application).prefs . + + \note On \b Linux, the \c USER directory is constructed by reading \c $HOME . If \c $HOME is not set + or not pointing to an existing directory, we are checking the path member of the passwd struct returned by + \c getpwuid(getuid()) . If all attempts fail, data will be stored in RAM only and be lost when the app exits. + The filename and path is then constructed as $(directory)/.fltk/$(vendor)/$(application).prefs . + The \c SYSTEM directory is hardcoded as /etc/fltk/$(vendor)/$(application).prefs . + + \par In FLTK versions before 1.4.0, if \c $HOME was not set, the \c USER path would be empty, + generating $(vendor)/$(application).prefs, which was used relative the the current working directory. + + \note On \b MacOS, the \c USER directory is constructed by reading \c $HOME . If \c $HOME is not set + or not pointing to an existing directory, we check the path returned by \c NSHomeDirectory() , and + finally checking the path member of the passwd struct returned by \c getpwuid(getuid()) . + If all attempts fail, data will be stored in RAM only and be lost when the app exits. + The filename and path is then constructed as $(directory)/Library/Preferences/$(vendor)/$(application).prefs . + The \c SYSTEM directory is hardcoded as /Library/Preferences/$(vendor)/$(application).prefs . + + \par In FLTK versions before 1.4.0, if \c $HOME was not set, the \c USER path would be \c NULL , + generating \/Library/Preferences/$(vendor)/$(application).prefs, which would silently fail to + create a prefrences file. + + \param[in] root can be \c USER or \c SYSTEM for user specific or system wide preferences + \param[in] vendor unique text describing the company or author of this file, must be a valid filepath segment + \param[in] application unique text describing the application, must be a valid filepath segment + + \todo Before the release of 1.4.0, I want to make a failed attempt to write a preferences file smarter. I + plan to use a subgroup of the "runtime" preferences to store data and stay accessable until the application + exits. Data would be stored under ./$(vendor)/$(application).prefs in RAM, but not on disk. + + \todo I want a way to access the type of the root preferences (SYSTEM, USER, MEMORY), and the state of + the file access (OK, FILE_SYSTEM_FAIL, PERMISSION_FAIL, etc.), and probably the dirty() flag as well. + + \todo Also, I need to explain runtime preferences. + + \todo Lastly, I think I have to put short sample code in the Doxygen docs. The test app ist just not enough. + */ Fl_Preferences::Fl_Preferences( Root root, const char *vendor, const char *application ) { node = new Node( "." ); rootNode = new RootNode( this, root, vendor, application ); @@ -133,13 +171,12 @@ Fl_Preferences::Fl_Preferences( Root root, const char *vendor, const char *appli \brief Use this constructor to create or read a preferences file at an arbitrary position in the file system. - The file name is generated in the form - path/application.prefs. If \p application - is \c NULL, \p path must contain the full file name. + The file name is generated in the form $(path)/$(application).prefs. + If \p application is \c NULL, \p path is taken literally as the file path and name. \param[in] path path to the directory that contains the preferences file - \param[in] vendor unique text describing the company or author of this file - \param[in] application unique text describing the application + \param[in] vendor unique text describing the company or author of this file, must be a valid filepath segment + \param[in] application unique text describing the application, must be a valid filepath segment */ Fl_Preferences::Fl_Preferences( const char *path, const char *vendor, const char *application ) { node = new Node( "." ); -- cgit v1.2.3