Jason Felds
146 lines
5.1 KiB
Plaintext
146 lines
5.1 KiB
Plaintext
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.
|