merge
This commit is contained in:
AJ Kelly
@@ -0,0 +1,88 @@
|
||||
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.
|
||||
@@ -0,0 +1,145 @@
|
||||
ThemePrefsRows, v0.5
|
||||
--------------------
|
||||
|
||||
ThemePrefsRows is an optional system that works with ThemePrefs to generate
|
||||
Lua-based OptionsRows for every preference used in the system. All you do is
|
||||
declare a table of preferences and pass it to ThemePrefs.InitAll(), which will
|
||||
also initialize ThemePrefs. Note that you do need to add an entry for each
|
||||
preference in [OptionTitles] and [OptionExplanations] to give the row its name
|
||||
and describe what it does; I hope to find a (clean) way to do it from Lua.
|
||||
|
||||
----------------------
|
||||
Section 1: Declaration
|
||||
----------------------
|
||||
|
||||
Declaring preferences is the same basic concept as ThemePrefs; see that doc
|
||||
for the basics. So I'll go into the stuff that's important to this API.
|
||||
|
||||
As mentioned in ThemePrefs, the table contains options. The possible options
|
||||
and their types are outlaid here. (The pref's type is defined by Default.)
|
||||
|
||||
Default: whatever the value is set to by default. For sanity's sake, you
|
||||
should have this in your Choices table.
|
||||
|
||||
Choices (table): an indexed array containing all the possible OptionsRow
|
||||
choices. If you're using a Values table, the array values should be
|
||||
strings. If not, you can use any type that can cast to a string.
|
||||
|
||||
Values (table): indexed array of the pref's type containing the value used when
|
||||
the Choices entry with the same index is chosen in the row. If that
|
||||
confused you, don't worry: it'll make more sense in the example.
|
||||
This is optional, if your pref type can cast to strings.
|
||||
|
||||
Params (table): optional modifications to the OptionsRow. I'll cover this in
|
||||
more detail in a later section. You probably won't need it.
|
||||
|
||||
To make this clearer, have an example of a valid prefs table:
|
||||
|
||||
[code]
|
||||
local prefs =
|
||||
{
|
||||
BoolPref =
|
||||
{
|
||||
Default = false,
|
||||
Choices = { "On", "Off" },
|
||||
Values = { true, false },
|
||||
},
|
||||
|
||||
IntPref =
|
||||
{
|
||||
Default = 3,
|
||||
Choices = { 1, 2, 3, 4, 5 },
|
||||
Params = { SelectType = "ShowOneInRow" }
|
||||
}
|
||||
}
|
||||
|
||||
ThemePrefs.InitAll( prefs )
|
||||
[/code]
|
||||
|
||||
So when "On" is selected, BoolPref will be set to true, and selecting "Off"
|
||||
will set it false. Simple enough, yeah? This will scale to any type you like.
|
||||
Enumerations, strings, whatever.
|
||||
|
||||
-----------------
|
||||
Section 2: Params
|
||||
-----------------
|
||||
|
||||
We did promise a more in-depth look at Params, so here it is.
|
||||
|
||||
The following arguments and values are currently accepted for Params:
|
||||
|
||||
LayoutType (string): "ShowAllInRow" (default), "ShowOneInRow".
|
||||
|
||||
ExportOnChange (bool): currently disabled in the source, but available to
|
||||
set in case it's enabled later. If true, the Save function (which
|
||||
handles actually setting the preference) is called whenever a value
|
||||
is changed rather than when the screen changes.
|
||||
|
||||
EnabledForPlayers (function): has 'self' as an argument, returns a table of
|
||||
PlayerNumbers who are allowed to select stuff. Not important yet.
|
||||
|
||||
ReloadRowMessages (table): contains an indexed array of strings. Whenever
|
||||
any of the messages in this table are broadcast, the Load function
|
||||
(which loads the list of possible options and sets the selected
|
||||
value/s) is called again.
|
||||
|
||||
LoadSelections (function): takes self, list, pn, overrides the default
|
||||
function. This is advanced usage, so you should probably know
|
||||
what you're doing to use it. Probably unnecessary.
|
||||
|
||||
SaveSelections (function): takes self, list, pn, and overrides the default
|
||||
function. This is advanced as well, for the same reasons. Fortunately,
|
||||
you probably won't need it.
|
||||
|
||||
----------------
|
||||
Section 3: Usage
|
||||
----------------
|
||||
|
||||
To get the OptionsRow for the preference you want, use ThemePrefRow(name)
|
||||
or ThemePrefsRows.GetRow(name); they're the same function. You'd use this
|
||||
as, for example in the metrics:
|
||||
|
||||
Line1="lua,ThemePrefRow('BoolPref')"
|
||||
|
||||
Unfortunately, you do need to do some more work with the Language INIs too.
|
||||
For each declared preference, you need an entry under [OptionTitles] for its
|
||||
title and an entry under [OptionExplanations] for its description. The key for
|
||||
both is the name of the preference. With the above example, that'd be e.g.
|
||||
|
||||
[OptionTitles]
|
||||
(...)
|
||||
BoolPref=BoolPref
|
||||
IntPref=IntPref
|
||||
|
||||
[OptionExplanations]
|
||||
(...)
|
||||
BoolPref=Toggles a simple boolean preference between true and false.
|
||||
IntPref=Sets an integer value between 1 and 5.
|
||||
|
||||
-----------------------
|
||||
Section 4: Localization
|
||||
-----------------------
|
||||
|
||||
ThemePrefsRows has three themable strings:
|
||||
|
||||
NoDefaultInValues - if the default value isn't actually in choices or values,
|
||||
this is displayed. Takes %s for the affected preference's name.
|
||||
|
||||
TypeMismatch - if the default type and a value type mismatch, this is shown.
|
||||
Takes %s, %d, and %s for the default's type, the index of the
|
||||
mismatching value, and the value's type respectively.
|
||||
|
||||
ChoicesSizeMismatch - if the Choices and Values arrays have different
|
||||
lengths, this is displayed. Takes %d and %d for the size of
|
||||
Choices and Values, respectively.
|
||||
|
||||
---------------------
|
||||
Section 5: Disclaimer
|
||||
---------------------
|
||||
|
||||
This isn't as tested as I'd like. For this version, it remains experimental.
|
||||
Quite experimental. If you run into problems, please let me know so I can
|
||||
fix them.
|
||||
|
||||
Please direct all questions, comments, complaints, bug reports, etc. to "vyhd"
|
||||
in #sm-ssc on irc.badnik.net or whatever other form of communication you like.
|
||||
Reference in New Issue
Block a user