mwseMCMPercentageSlider⚓︎
A slider that displays values as percentages in the range 0%-100%, while storing values in the range 0.0-1.0. The minimum and maximum range can be changed via the min
and max
parameters.
This type inherits the following: mwseMCMSlider, mwseMCMSetting, mwseMCMComponent
Properties⚓︎
callback
⚓︎
The custom function called when the player interacts with this Setting.
Returns:
result
(nil, fun(self: mwseMCMSetting))
childIndent
⚓︎
The left padding size in pixels. Used on all the child components.
Returns:
result
(integer, nil)
childSpacing
⚓︎
The bottom border size in pixels. Used on all the child components.
Returns:
result
(integer, nil)
class
⚓︎
Every MCM component has a unique string indentifier specific to that component. These strings are the filename of the file implementing a component. These are found in core\\mcm\\components
.
Returns:
result
(string)
componentType
⚓︎
The type of this component.
Returns:
result
("Setting")
config
⚓︎
The config to use when creating a mwseMCMTableVariable
for this Setting
. If provided, it will override the config stored in parentComponent
. Otherwise, the value in parentComponent
will be used.
Returns:
result
(table, nil)
configKey
⚓︎
The configKey
used to create a new mwseMCMTableVariable
. If this is provided, along with a config
(which may be inherited from the parentComponent
), then a new mwseMCMTableVariable
variable will be created for this setting.
Returns:
result
(string, number, nil)
converter
⚓︎
A converter to use for this component's variable
.
Returns:
result
((fun(newValue: unknown): unknown), nil)
createContentsContainer
⚓︎
This method creates the contents of a component. Not every component implements this method.
Returns:
result
(nil, fun(self: mwseMCMComponent, outerContainer: tes3uiElement))
decimalPlaces
⚓︎
The number of decimal places of precision. Must be a positive integer. Default is 2
.
Returns:
result
(integer)
defaultConfig
⚓︎
The defaultConfig
to use when creating a mwseMCMTableVariable
for this Setting
. If provided, it will override the defaultConfig
stored in parentComponent
. Otherwise, the value in parentComponent
will be used.
Returns:
result
(table, nil)
defaultSetting
⚓︎
If defaultSetting
wasn't passed in the variable
table, can be passed here. The new variable will be initialized to this value. If not provided, then the value in defaultConfig
will be used, if possible.
Returns:
result
(unknown, nil)
description
⚓︎
If in a Sidebar Page, the description will be shown on mouseover.
Returns:
result
(string, nil)
elements
⚓︎
This dictionary-style table holds all the UI elements of the Slider, for easy access.
Returns:
result
(mwseMCMSliderElements)
indent
⚓︎
The left padding size in pixels. Only used if the childIndent
isn't set on the parent component.
Returns:
result
(integer)
inGameOnly
⚓︎
If true, the setting is disabled while the game is on main menu. If this is enabled, it will override the value of the inGameOnly
parameter on this setting's variable
.
Returns:
result
(boolean)
jump
⚓︎
How far the slider jumps when you click an area inside the slider. Default is 5 * step
.
Returns:
result
(number)
label
⚓︎
Text shown above the slider. If left as a normal string, it will be shown in the form: [label
]: [self.variable.value
]. If the string contains a '%s' format operator, the value will be formatted into it.
Returns:
result
(string)
makeComponent
⚓︎
This method must be implemented by child classes of mwseMCMSetting.
Returns:
result
(nil, fun(self: mwseMCMSetting, innerContainer: tes3uiElement))
max
⚓︎
Maximum value the variable
should take. The value displayed in the slider will be 100 times greater than this value. Default is 1.0
.
Returns:
result
(number)
min
⚓︎
Minimum value the variable
should take. The value displayed in the slider will be 100 times greater than this value. Default is 0.0
.
Returns:
result
(number)
mouseOvers
⚓︎
This array of UI elements will have an event handler registered to trigger "MCM:MouseOver" event. For more info, see registerMouseOverElements method.
Returns:
result
(tes3uiElement[], nil)
paddingBottom
⚓︎
The bottom border size in pixels. Only used if the childSpacing
is unset on the parent component.
Returns:
result
(integer)
parentComponent
⚓︎
Returns:
result
(mwseMCMComponent, nil)
postCreate
⚓︎
Custom formatting function to make adjustments to any element saved in self.elements
.
Returns:
result
(nil, fun(self: mwseMCMComponent))
restartRequired
⚓︎
If true, updating this Setting will notify the player to restart the game.
Returns:
result
(boolean)
restartRequiredMessage
⚓︎
The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect.".
Returns:
result
(string)
sCancel
⚓︎
Set to the value of sCancel
GMST.
Returns:
result
(string)
showDefaultSetting
⚓︎
If true, then the defaultSetting
of this setting's variable
will be shown below its description.
Returns:
result
(boolean)
sNo
⚓︎
Set to the value of sNo
GMST.
Returns:
result
(string)
sOff
⚓︎
Set to the value of sOff
GMST.
Returns:
result
(string)
sOK
⚓︎
Set to the value of sOK
GMST.
Returns:
result
(string)
sOn
⚓︎
Set to the value of sOn
GMST.
Returns:
result
(string)
step
⚓︎
How far the slider moves when you press the arrows. Default is 0.01
.
Returns:
result
(number)
sYes
⚓︎
Set to the value of sYes
GMST.
Returns:
result
(string)
variable
⚓︎
The Variable this setting will update.
Returns:
result
(mwseMCMVariable, nil)
Methods⚓︎
checkDisabled
⚓︎
Returns true if the component should be disabled.
Componets with a variable:
- True if the Component's variable has
inGameOnly
field set to true, and the game is on the main menu. For components with multiple subcomponent (Category), the check is done for each subcomponent.
Components without a variable:
- True if the Component's
inGameOnly
field is set to true, and the game is on the main menu.
local result = myObject:checkDisabled()
Returns:
result
(boolean)
convertToLabelValue
⚓︎
This function specifies how values stored in the variable
field should correspond to values displayed in the slider label.
The default behavior is to consistently format decimal places (i.e., if decimalPlaces == 2
, make sure two decimal places are shown.)
This can be overwritten in the createNewSlider
method, allowing for custom formatting of variable values.
local labelValue = myObject:convertToLabelValue(variableValue)
Parameters:
variableValue
(number)
Returns:
labelValue
(number, string)
Example: DistanceSlider
The following example shows how the convertToLabelValue
parameter can be used to create a slider for a config setting that handles distances. The config setting will be stored using game units, but the displayed value will be in real-world units. Recall that 1 game unit corresponds to 22.1 feet, and 1 foot is 0.3048 meters.
--- @type tes3uiElement, table
local myPage, myConfig
mwse.mcm.createSlider{
parent = myPage,
label = "My distance slider",
variable = mwse.mcm.createTableVariable{ id = "distance", table = myConfig },
convertToLabelValue = function(self, variableValue)
local feet = variableValue / 22.1
local meters = 0.3048 * feet
if self.decimalPlaces == 0 then
return string.format("%i ft (%.2f m)", feet, meters)
end
return string.format(
-- if `decimalPlaces == 1, then this string will simplify to
-- "%.1f ft (%.3f m)"
string.format("%%.%uf ft (%%.%uf m)", self.decimalPlaces, self.decimalPlaces + 2),
feet, meters
)
end,
max = 22.1 * 10, -- max is 10 feet
step = 22.1, -- increment by 1 foot
jump = 22.1 * 5,
}
Example: SkillSlider
Here is an (admittedly less practical) example to help highlight the different ways convertToLabelValue
can be used. In this example, it will be used to create a slider that stores a tes3.skill
constant in the config, and then displays the name of the corresponding skill.
--- @type tes3uiElement, table
local myPage, myConfig
mwse.mcm.createSlider{
parent = myPage,
label = "My skill slider",
variable = mwse.mcm.createTableVariable{ id = "skillId", table = myConfig },
convertToLabelValue = function(self, variableValue)
local skillName = tes3.getSkillName(math.round(variableValue))
if skillName then
return skillName
end
return "N/A"
end,
max = 26 -- there are 27 skills and indexing starts at 0
}
convertToVariableValue
⚓︎
This function specifies how values stored in the slider widget should correspond to values stored in the variable
field.
This conversion is necessary because the widget can only store whole numbers, and the range of allowed values must start at 0, while the corresponding variable
can store decimal numbers and the range can start at any number.
In the vast majority of use-cases, you do not need to call this method directly.
local variableValue = myObject:convertToVariableValue(widgetValue)
Parameters:
widgetValue
(number)
Returns:
variableValue
(number)
convertToWidgetValue
⚓︎
This method specifies how values stored in the variable
field should correspond to values stored in the slider UI widget.
This conversion is necessary because the widget can only store whole numbers, and the range of allowed values must start at 0, while the corresponding variable
can store decimal numbers and the range can start at any number.
In the vast majority of use-cases, you do not need to call this method directly.
local widgetValue = myObject:convertToWidgetValue(variableValue)
Parameters:
variableValue
(number)
Returns:
widgetValue
(number)
create
⚓︎
This method creates the UI elements that comprise this Setting.
myObject:create(parentBlock)
Parameters:
parentBlock
(tes3uiElement)
createContentsContainer
⚓︎
This method creates the UI elements specific to Slider.
myObject:createContentsContainer(parentBlock)
Parameters:
parentBlock
(tes3uiElement)
createInnerContainer
⚓︎
Creates component's innerContainer UI element inside given parentBlock
, and stores it in the self.elements.innerContainer
. The innerContainer will add self.indent
additional padding on the left if the component has a label.
myObject:createInnerContainer(parentBlock)
Parameters:
parentBlock
(tes3uiElement)
createLabel
⚓︎
Creates component's label UI element.
First, it calls self:createLabelBlock
and creates the label element inside new labelBlock
. Stores both new UI elements in the self.elements
and self.mouseOvers
.
myObject:createLabel(parentBlock)
Parameters:
parentBlock
(tes3uiElement)
createLabelBlock
⚓︎
Creates component's labelBlock UI element inside given parentBlock
, and stores it in the self.elements.labelBlock
and self.mouseOvers
.
myObject:createLabelBlock(parentBlock)
Parameters:
parentBlock
(tes3uiElement)
createOuterContainer
⚓︎
Creates component's outerContainer UI element inside given parentBlock
, and stores it in the self.elements.outerContainer
and self.mouseOvers
. The outerContainer holds all the other UI elements that comprise a component.
myObject:createOuterContainer(parentBlock)
Parameters:
parentBlock
(tes3uiElement)
disable
⚓︎
This method disables the component's UI elements. That includes: changing the color of the UI elements to the tes3.palette.disabledColor
and setting button widget state to tes3.uiState.disabled
.
myObject:disable()
enable
⚓︎
Enables the component's UI elements. That includes: changing the color of the UI elements to the tes3.palette.normalColor
and registering handlers for tes3.uiEvent.mouseClick
for buttons.
myObject:enable()
getMouseOverText
⚓︎
Retrieves the text that this setting should display in any related mouseOverInfo
s. This method currently utilized to display this component's description whenever the component is in a SideBarPage
. If this Setting
has showDefaultSetting == true
, then this method will also include the current defaultSetting
.
Primarily intended for internal use.
local text = myObject:getMouseOverText()
Returns:
text
(string, nil): The text to display. Returningnil
means that themouseOverInfo
should display text from a different source. e.g. from thedescription
of the relevantSideBarPage
.
insertMouseovers
⚓︎
Recursively walks over children of given element
and inserts them into self.mouseOvers
.
myObject:insertMouseovers(element)
Parameters:
element
(tes3uiElement)
makeComponent
⚓︎
Creates the sliderBlock and slider UI elements of the Slider.
myObject:makeComponent(parentBlock)
Parameters:
parentBlock
(tes3uiElement)
new
⚓︎
Creates a new PercentageSlider
.
local slider = myObject:new({ label = ..., variable = ..., defaultSetting = ..., min = ..., max = ..., step = ..., jump = ..., decimalPlaces = ..., description = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ..., class = ..., componentType = ..., parentComponent = ... })
Parameters:
data
(table): Optional.label
(string): Optional. Text shown above the slider. If left as a normal string, it will be shown in the form: [label
]: [self.variable.value
]. If the string contains a '%s' format operator, the value will be formatted into it.variable
(mwseMCMVariable, mwseMCMSettingNewVariable): Optional. A variable for this setting.defaultSetting
(unknown): Optional. IfdefaultSetting
wasn't passed in thevariable
table, can be passed here. The new variable will be initialized to this value.min
(number): Default:0
. Minimum value of slider.max
(number): Default:1
. Maximum value of slider.step
(number): Default:0.01
. How far the slider moves when you press the arrows.jump
(number): Default:0.05
. How far the slider jumps when you click an area inside the slider.decimalPlaces
(integer): Default:0
. The number of decimal places of precision. Must be a nonnegative integer.description
(string): Optional. If in a Sidebar Page, the description will be shown on mouseover.callback
(fun(self: mwseMCMPercentageSlider)): Optional. The custom function called when the player interacts with this Setting.inGameOnly
(boolean): Default:false
. If true, the setting is disabled while the game is on main menu.restartRequired
(boolean): Default:false
. If true, updating this Setting will notify the player to restart the game.restartRequiredMessage
(string): Optional. The message shown if restartRequired is triggered. The default text is a localized version of: "The game must be restarted before this change will come into effect."indent
(integer): Default:12
. The left padding size in pixels. Only used if thechildIndent
isn't set on the parent component.childIndent
(integer): Optional. The left padding size in pixels. Used on all the child components.paddingBottom
(integer): Default:4
. The bottom border size in pixels. Only used if thechildSpacing
is unset on the parent component.childSpacing
(integer): Optional. The bottom border size in pixels. Used on all the child components.postCreate
(fun(self: mwseMCMPercentageSlider)): Optional. Can define a custom formatting function to make adjustments to any element saved inself.elements
.class
(string): Optional.componentType
(string): Optional.parentComponent
(mwseMCMComponent): Optional.
Returns:
slider
(mwseMCMPercentageSlider)
printComponent
⚓︎
Prints the component table to the mwse.log
. If a component is passed, it will be printed. If called without arguments, the component it was called on will be printed.
myObject:printComponent(component)
Parameters:
component
(table): Default:self
.
registerMouseOverElements
⚓︎
Registers an event handler on each given UI element for the tes3.uiEvent.mouseOver
and tes3.uiEvent.mouseLeave
that will trigger "MCM:MouseOver" event. That event is used by the MCM to update the sidebar on the mwseMCMSideBarPage.
myObject:registerMouseOverElements(mouseOverList)
Parameters:
mouseOverList
(tes3uiElement[]): Optional. If this argument isn't passed, does nothing.
registerSliderElement
⚓︎
Registers event handlers for tes3.uiEvent.mouseClick
and tes3.uiEvent.mouseRelease
that call self:update()
.
myObject:registerSliderElement(element)
Parameters:
element
(tes3uiElement)
resetToDefault
⚓︎
This method will reset the variable.value
to the default value.
myObject:resetToDefault()
setVariableValue
⚓︎
Changes the Slider's variable.value
to the given value, updates the Slider's label and widget, and calls self:update
.
myObject:setVariableValue(newValue)
Parameters:
newValue
(number)
update
⚓︎
Calls updateVariableValue
, then calls the Slider's callback
method (if it exists). Then notifies the player to restart the game if restartRequired == true
.
myObject:update()
updateValueLabel
⚓︎
Updates the label text of the slider to show the current value of this slider's variable
.
myObject:updateValueLabel()
updateVariableValue
⚓︎
Updates the value stored in this Slider's variable
field, using the current value of this Slider's widget (after converting that value).
myObject:updateVariableValue()
updateWidgetValue
⚓︎
Updates the value stored in the slider widget, using the current value of this Slider's variable
(after converting that value).
myObject:updateWidgetValue()