Skip to content

mwseMCMKeyBinder⚓︎

This button allows the player to bind a key combination for use with hotkeys. The binder allows specifying if mouse buttons and scroll wheel bindings are allowed and wether modifier keys Shift, Alt and Ctrl are allowed.

When the player presses the button with current hotkey, a prompt asks them to press a new key (or key combination using Shift, Ctrl or Alt) to bind.

If this KeyBinder is set to only accept keyboard keys, key combos are stored in the following format (mwseKeyCombo):

1
2
3
4
5
6
{
    keyCode = tes3.scanCode.{key},
    isShiftDown = true,
    isAltDown = false,
    isControlDown = false,
},

On the other hand, if the KeyBinder allows binding mouse keys in addition to keyboard keys, key combos are stored in the following format(mwseKeyMouseCombo):

1
2
3
4
5
6
7
8
{
    keyCode = tes3.scanCode.{key},
    isShiftDown = true,
    isAltDown = false,
    isControlDown = false,
    mouseWheel = -1 - down, 1 - up, nil
    mouseButton = number|nil
},

This type inherits the following: mwseMCMButton, mwseMCMSetting, mwseMCMComponent

Example: Filtering out key presses that aren't equal to the bound key combination 
-- An example of a simple configuration setup
local defaultConfig = {
    ---@type mwseKeyMouseCombo
    combo = {
        -- Alt + Left mouse button
        mouseButton = 0,
        isAltDown = true,
        isControlDown = false,
        isShiftDown = false,
    },
}
local config = mwse.loadConfig("myModConfig", defaultConfig)

local function registerModConfig()
    local template = mwse.mcm.createTemplate({ name = "Test Mod" })
    template:register()

    local page = template:createSideBarPage({ label = "Settings" })

    page:createKeyBinder({
        label = "My combo",
        description = "This combo does...",
        allowMouse = true,
        variable = mwse.mcm.createTableVariable({
            id = "combo",
            table = config
        }),
    })
end
event.register(tes3.event.modConfigReady, registerModConfig)


--- @param e keyDownEventData|mouseButtonDownEventData|mouseWheelEventData
local function sayHi(e)
    if not tes3.isKeyEqual({ expected = config.combo, actual = e }) then
        -- Nothing to do if the pressed combination isn't equal to our expected combination.
        return
    end

    -- Now do our logic
    tes3.messageBox("Hi!")
end

event.register(tes3.event.keyDown, sayHi)
event.register(tes3.event.mouseButtonDown, sayHi)
event.register(tes3.event.mouseWheel, sayHi)

Properties⚓︎

allowCombinations⚓︎

If true, the keybinder will let the user use modification keys: Shift, Ctrl, and Alt when rebinding.

Returns:

  • result (boolean)

allowMouse⚓︎

If true, the keybinder will let the user use mouse buttons and scroll wheel in this keybinder.

Returns:

  • result (boolean)

buttonText⚓︎

The text shown on the button.

Returns:

  • result (string)

callback⚓︎

The custom function called when the player interacts with this Setting.

Returns:

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")

createContentsContainer⚓︎

This method creates the contents of a component. Not every component implements this method.

Returns:

description⚓︎

If in a Sidebar Page, the description will be shown on mouseover.

Returns:

  • result (string, nil)

disabledText⚓︎

This text is shown on the button if the buttonText isn't set.

Returns:

  • result (string)

elements⚓︎

This dictionary-style table holds all the UI elements of the Button, for easy access.

Returns:

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)

keybindName⚓︎

The keybind name. Shown in the popup menu header. This string is formatted into a localized version of "SET %s KEYBIND.". If none is provided the popup has "SET NEW KEYBIND." as header text.

Returns:

  • result (string, nil)

label⚓︎

The text shown next to the button.

Returns:

  • result (string)

leftSide⚓︎

If true, the Button is created on the left, while the label text is created on the right. If false, label text is on the left.

Returns:

  • result (boolean)

makeComponent⚓︎

This method must be implemented by child classes of mwseMCMSetting.

Returns:

mouseOvers⚓︎

This array of UI elements will have an event handler registered to trigger "MCM:MouseOver" event. For more info, see registerMouseOverElements method.

Returns:

paddingBottom⚓︎

The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.

Returns:

  • result (integer)

parentComponent⚓︎

Returns:

postCreate⚓︎

Custom formatting function to make adjustments to any element saved in self.elements.

Returns:

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)

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)

sYes⚓︎

Set to the value of sYes GMST.

Returns:

  • result (string)

variable⚓︎

The Variable this setting will update.

Returns:

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 by this setting.

local labelValue = myObject:convertToLabelValue(variableValue)

Parameters:

  • variableValue (number)

Returns:

  • labelValue (number, string)

create⚓︎

This method creates the UI elements that comprise this Setting.

myObject:create(parentBlock)

Parameters:

createContentsContainer⚓︎

This method creates the Button's button and label UI elements.

myObject:createContentsContainer(parentBlock)

Parameters:

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:

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:

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:

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:

createPopupMenu⚓︎

Creates the popup menu.

local menu = myObject:createPopupMenu()

Returns:

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()

getComboString⚓︎

Returns a string representing given keyCombo. For example, "Ctrl - C".

local result = myObject:getComboString(keyCombo)

Parameters:

Returns:

  • result (string)

getComponent⚓︎

Creates a new Component of given class or returns the given Component.

local component = myObject:getComponent({ class = ..., label = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., inGameOnly = ..., postCreate = ..., parentComponent = ... })

Parameters:

  • componentData (mwseMCMComponent, table)
    • class (string): The component type to get. On of the following:
      • "Template"
      • "ExclusionsPage"
      • "FilterPage"
      • "MouseOverPage"
      • "Page"
      • "SideBarPage"
      • "Category"
      • "SideBySideBlock"
      • "ActiveInfo"
      • "Hyperlink"
      • "Info"
      • "MouseOverInfo"
      • "Setting"
      • "Button"
      • "OnOffButton"
      • "YesNoButton"
      • "CycleButton"
      • "KeyBinder"
      • "Dropdown"
      • "TextField"
      • "ParagraphField"
      • "Slider"
      • "DecimalSlider"
      • "PercentageSlider"
    • label (string): Optional. The label text to set for the new component. Not all component types have a label.
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent 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 the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • inGameOnly (boolean): Default: false.
    • postCreate (fun(self: mwseMCMComponent)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.
    • parentComponent (mwseMCMComponent): Optional.

Returns:

getLetter⚓︎

Returns the letter the provided keyCode represents.

local letter = myObject:getLetter(keyCode)

Parameters:

  • keyCode (integer, nil)

Returns:

  • letter (string, nil)

getMouseButtonText⚓︎

Returns a localized name for the mouse button of given index.

local result = myObject:getMouseButtonText(buttonIndex)

Parameters:

  • buttonIndex (number, nil)

Returns:

  • result (string, nil)

getMouseWheelText⚓︎

Returns a localized version of "Mouse wheel up" if wheel is 1 and "Mouse wheel down" if wheel is -1.

local result = myObject:getMouseWheelText(wheel)

Parameters:

  • wheel (integer, nil)

Returns:

  • result (string, nil)

getText⚓︎

Returns a string representing the key combo currently store in variable. For example, "Ctrl - C".

local result = myObject:getText()

Returns:

  • result (string)

insertMouseovers⚓︎

Recursively walks over children of given element and inserts them into self.mouseOvers.

myObject:insertMouseovers(element)

Parameters:

keySelected⚓︎

Changes the variable.value to the key combination from given input event data.

myObject:keySelected(e)

Parameters:

  • e (keyUpEventData, mouseButtonDownEventData, mouseWheelEventData)

makeComponent⚓︎

This method creates the Button's button UI element and stores it in self.elements.button and self.mouseOvers.

myObject:makeComponent(parentBlock)

Parameters:

new⚓︎

Creates a new KeyBinder.

local button = myObject:new({ label = ..., description = ..., allowCombinations  = ..., allowMouse  = ..., keybindName = ..., leftSide  = ..., variable = ..., defaultSetting = ..., callback = ..., inGameOnly = ..., restartRequired = ..., restartRequiredMessage = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., postCreate = ..., class = ..., componentType = ..., parentComponent = ... })

Parameters:

  • data (table): Optional.
    • label (string): Optional. Text shown next to the button.
    • description (string): Optional. If in a Sidebar Page, the description will be shown on mouseover.
    • allowCombinations (boolean): Default: true. If true, the keybinder will let the user use modification keys: Shift, Ctrl, and Alt when rebinding.
    • allowMouse (boolean): Default: false. If true, the keybinder will let the user use mouse buttons and scroll wheel in this keybinder. In that case the variable will have mwseKeyMouseCombo layout, mwseKeyCombo otherwise.
    • keybindName (string): Optional. The keybind name. Shown in the popup menu header. This string is formatted into a localized version of "SET %s KEYBIND.". If none is provided the popup has "SET NEW KEYBIND." as header text.
    • leftSide (boolean): Default: true. If true, the button will be created on the left and label on the right.
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): Optional. A variable for this KeyBinder.
    • defaultSetting (mwseKeyCombo): Optional. If defaultSetting wasn't passed in the variable table, can be passed here. The new variable will be initialized to this value.
    • callback (fun(self: mwseMCMKeyBinder)): Optional. The custom function called when the player interacts with this KeyBinder.
    • 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 the childIndent 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 the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • postCreate (fun(self: mwseMCMKeyBinder)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.
    • class (string): Optional.
    • componentType (string): Optional.
    • parentComponent (mwseMCMComponent): Optional.

Returns:

prepareData⚓︎

Prepares the provided parameters table and sets the parentComponent field to mwseMCMComponent.

local data = myObject:prepareData(data)

Parameters:

  • data (string, mwseMCMComponent.new.data): Optional.

Returns:

  • data (mwseMCMComponent.new.data)

press⚓︎

Calls showKeyBindMessage method.

myObject:press()

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.

setText⚓︎

Sets the text on the mwseMCMButton's button UI Element.

myObject:setText(newText)

Parameters:

  • newText (string)

showKeyBindMessage⚓︎

Shows the rebind prompt popup. The popup is active until some valid input is given.

myObject:showKeyBindMessage()

update⚓︎

Sets the button UI element text to self.buttonText. Calls the Button's callback method and if restartRequired is set to true, notifies the player to restart the game.

myObject:update()