Line endings...be normalized!
This commit is contained in:
Jason Felds
+145
-145
@@ -1,145 +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.
|
||||
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