Jason Felds
89 lines
3.2 KiB
Plaintext
89 lines
3.2 KiB
Plaintext
ThemePrefs, v0.7
|
|
----------------
|
|
|
|
ThemePrefs is a system for handling theme-specific preferences in a standard,
|
|
efficient, and predictable way. All you do, basically, is declare a table of
|
|
preferences and options and use GetThemePref(name) to get your preference
|
|
values as needed. This system will handle all disk I/O as well.
|
|
|
|
Additionally, it can work in combination with ThemePrefsRows to generate
|
|
OptionsRows for all preferences, saving you (most of) the trouble with
|
|
integrating it into your theme. More on that later.
|
|
|
|
The prefs are written, using IniFile, into Save/ThemePrefs.ini, written under
|
|
the section corresponding to your theme name (if ThemeInfo exists, it will
|
|
use the Name field listed there; otherwise, it will use the folder name).
|
|
|
|
----------------------
|
|
Section 1: Declaration
|
|
----------------------
|
|
|
|
To declare preferences for your theme to use, make a table with named
|
|
tables in it; its name is used for the preference, and the tables hold
|
|
the options for that preference. All you need to know for now is that
|
|
Default is required; for more options, check ThemePrefsRows.
|
|
|
|
After the table is declared, pass it to the function ThemePrefs.InitAll().
|
|
(If you're planning not to use any OptionsRows at all, you can just use
|
|
ThemePrefs.Init() to save some processing time, but seriously give the
|
|
ThemePrefsRows system a look before you disregard it.)
|
|
|
|
[code]
|
|
local Prefs =
|
|
{
|
|
BoolPref = { Default = false },
|
|
IntPref = { Default = 3 },
|
|
}
|
|
|
|
ThemePrefs.InitAll( Prefs )
|
|
[/code]
|
|
|
|
If your theme is "default", this will generate a ThemePrefs.ini like so:
|
|
|
|
[default]
|
|
BoolPref=false
|
|
IntPref=3
|
|
|
|
----------------
|
|
Section 2: Usage
|
|
----------------
|
|
|
|
You can access the value with ThemePrefs.Get(name) or GetThemePref(name):
|
|
both calls work identically. The return type will be based on whatever you set
|
|
it to, but the subsystem will always try number, then bool, then string, in
|
|
that order. Use true and false for bools, not 1 and 0.
|
|
|
|
For example, if you wanted to branch something in the metrics based on
|
|
the value of BoolPref (which is a boolean), you could use the following:
|
|
|
|
NextScreen=GetThemePref('BoolPref') and "ScreenTrue" or "ScreenFalse"
|
|
|
|
If you want to set a preference value for some reason, you can use either
|
|
ThemePrefs.Set(name, value) or SetThemePref(name, value), but the point of
|
|
this API is to simplify and standardize prefs handling, so you really should
|
|
not need it. (Use ThemePrefsRows instead.)
|
|
|
|
-----------------------
|
|
Section 3: Localization
|
|
-----------------------
|
|
|
|
ThemePrefs has two strings that can be localized, to be placed under
|
|
[ThemePrefs] in the appropriate language INI.
|
|
|
|
IniFileMissing - displayed when IniFile.lua is not found, which means
|
|
ThemePrefs cannot be loaded from or written to disk
|
|
|
|
UnknownPreference - displayed when an attempt is made to read or write
|
|
a preference that does not exist in the system. Uses %s for the
|
|
name of the unknown preference.
|
|
|
|
---------------------
|
|
Section 4: Disclaimer
|
|
---------------------
|
|
|
|
Though this is working fine so far, it is still experimental! If you run
|
|
into problems, or have suggestions, comments, questions, etc., please talk
|
|
to "vyhd" in #sm-ssc on irc.badnik.net, as it's his code to maintain; he
|
|
hates subjecting other people to his code (and occasionally vice versa),
|
|
but will gladly address concerns that come up.
|