fly/fgdata
1
0
Fork 0
Code Activity

Docs/README.add-ons: document addon.storagePath and addon.createStorageDir()

Browse source 
These were added in FlightGear commit
9a044a474bdb6ccc471cbe4c69dced5d2a9f447e.
This commit is contained in:
Florent Rougon 2018-03-21 08:39:47 +01:00
parent 779ffe8d78
commit 82417eb962
1 changed files with 54 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
Docs/README.add-ons
View file

@ -22,16 +22,18 @@ Contents
4. Resources under the add-on directory
5. Add-on-specific menus and dialogs
5. Persistent storage location for add-ons
6. Add-on-specific menus and dialogs
a) Add-on-specific menus
b) Add-on-specific dialogs
6. How to run code after an add-on is loaded
7. How to run code after an add-on is loaded
7. Overview of the C++ API
8. Overview of the C++ API
8. Nasal API
9. Nasal API
Introduction
@ -456,7 +458,42 @@ hardcode the add-on identifier every time you need to access a resource
inside the add-on directory.
5. Add-on-specific menus and dialogs
5. Persistent storage location for add-ons
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If an add-on needs to store data that persists across FlightGear
sessions, it can use a specific directory tree whose path is obtained
with addon.storagePath, where 'addon' is an addons.Addon instance. This
corresponds to $FG_HOME/Export/Addons/ADDON_ID, however it is simpler
and better to use addon.storagePath instead of hardcoding and manually
assembling this path in each add-on. Since the directory is likely not
to exist until the add-on creates it, the recommended usage pattern is
the following:
1) Create the add-on-specific storage directory if it doesn't already
exist, and optionally get its path at the same time:
storageDir = addon.createStorageDir();
Typically, you'll run this in the add-on main() function (at least,
early enough) if your add-on uses the storage directory. Note that
there is no need to check yourself whether the directory already
exists: addon.createStorageDir() does that for you.
2) At any time, you can get a path to the add-on-specific storage
directory with:
storageDir = addon.storagePath
Accessing addon.storagePath doesn't check for the existence nor the
type of $FG_HOME/Export/Addons/ADDON_ID, thus it is a bit faster
than addon.createStorageDir(). Use addon.storagePath whenever you
know that the directory has already been created.
The features described in this section were added in FlightGear 2018.2.
6. Add-on-specific menus and dialogs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
a) Add-on-specific menus
@ -555,7 +592,7 @@ dialogs.
This feature was added in FlightGear 2018.2.
6. How to run code after an add-on is loaded
7. How to run code after an add-on is loaded
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You may want to set up Nasal code to be run after an add-on is loaded;
@ -583,7 +620,7 @@ here is how to do that:
}
7. Overview of the C++ API
8. Overview of the C++ API
~~~~~~~~~~~~~~~~~~~~~~~
The add-on C++ infrastructure mainly relies on the following classes:
@ -631,7 +668,7 @@ the appropriate error message with SG_LOG() and
fatalMessageBoxThenExit().
8. Nasal API
9. Nasal API
~~~~~~~~~
The Nasal add-on API all lives in the 'addons' namespace. It gives Nasal
@ -715,6 +752,9 @@ Read-only data members (attributes) of addons.Addon objects:
licenseUrl stable, official URL for the add-on license text
(string)
basePath path to the add-on base directory (string)
storagePath path to the add-on storage directory (string)
This is $FG_HOME/Export/Addons/ADDON_ID.
[added in FlightGear 2018.2]
minFGVersionRequired minimum required FG version for the add-on (string)
maxFGVersionRequired max. required FG version... or "none" (string)
homePage add-on home page (string)
@ -731,6 +771,12 @@ Read-only data members (attributes) of addons.Addon objects:
Member functions (methods) of addons.Addon objects:
createStorageDir() -> string
Create the add-on storage directory if it
doesn't already exist (that is,
$FG_HOME/Export/Addons/ADDON_ID). Return its
path as a string.
[added in FlightGear 2018.2]
resourcePath(string relPath) -> string
Return a resource path suitable for use with the
simgear::ResourceManager. 'relPath' must be