keyDown

keydown

The key event fires when a key is pressed.

--- @param e keyDownEventData
local function keyDownCallback(e)
end
event.register(tes3.event.keyDown, keyDownCallback)

Tip

This event can be filtered based on the keyCode event data.

Tip

An event can be claimed by setting e.claim to true, or by returning false from the callback. Claiming the event prevents any lower priority callbacks from being called.

Event Data

• element (tes3uiElement): Read-only. The UI element that the key is going to be dispatched to, or nil if one is not in focus.
• isAltDown (boolean): Read-only. True if either alt key is held.
• isControlDown (boolean): Read-only. True if either control key is held.
• isShiftDown (boolean): Read-only. True if either shift key is held.
• isSuperDown (boolean): Read-only. True if super (Windows key) is held.
• keyCode (tes3.scanCode): Read-only. The scan code of the key that raised the event. Maps to values in tes3.scanCode table.

Examples

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",
        config = config
    })
    template:register()

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

    page:createKeyBinder({
        label = "My combo",
        description = "This combo does...",
        allowMouse = true,
        configKey = "combo",
    })
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)

Example: Show a Message when Ctrl-Z is Pressed

Displays a simple message when Z is pressed while control is held.

local function myOnKeyCallback(e)
    if( e.isControlDown ) then
        tes3.messageBox({ message = "You pressed Ctrl-Z, but you can't undo all your mistakes." })
    end
end

-- Filter by the scan code to get Z key presses only.
event.register(tes3.event.keyDown, myOnKeyCallback, { filter = tes3.scanCode.z } )

Related events

keyUp