xmake-docs/docs/api/scripts/extension-modules/core/ui/event.md

core.ui.event

This module provides event types and classes for the terminal UI system.

::: tip TIP To use this module, you need to import it first: import("core.ui.event") :::

::: tip NOTE The UI module is primarily used for xmake's internal xmake f --menu menu-based visual configuration. It provides basic UI components that can also be used by users to implement their own terminal UIs. :::

The event module provides a unified way to handle different types of events in the terminal UI, including keyboard events, mouse events, command events, text events, and idle events.

Event Types

The module defines the following event types:

Event Type	Value	Description
event.ev_keyboard	1	Keyboard key press/release event
event.ev_mouse	2	Mouse button/movement event
event.ev_command	3	Command event
event.ev_text	4	Text input event
event.ev_idle	5	Idle event (no user input)
event.ev_max	5	Maximum event type value

Command Event Types

The module defines the following command event types:

Command Type	Value	Description
event.cm_quit	1	Quit application
event.cm_exit	2	Exit current view
event.cm_enter	3	Enter/confirm action
event.cm_max	3	Maximum command type value

event:is_key

• Check if event is a keyboard event with specific key

Function Prototype

::: tip API

event:is_key(key_name: <string>)

:::

Parameter Description

Parameter	Description
key_name	Required. Name of the key to check (e.g., "Enter", "Esc", "Tab")

Return Value

Type	Description
boolean	Returns true if event is keyboard event for specified key, false otherwise

Usage

Check if the event is a specific keyboard event:

import("core.ui.event")

function view:on_event(e)
    if e:is_key("Enter") then
        print("Enter key pressed")
        return true  -- Event handled
    elseif e:is_key("Esc") then
        self:quit()
        return true
    end
    return false
end

event:is_command

• Check if event is a command event with specific command

Function Prototype

::: tip API

event:is_command(command: <string>)

:::

Parameter Description

Parameter	Description
command	Required. Command name to check (e.g., "cm_quit", "cm_enter")

Return Value

Type	Description
boolean	Returns true if event is command event for specified command, false otherwise

Usage

Check if the event is a specific command event:

import("core.ui.event")

function view:on_event(e)
    if e:is_command("cm_quit") then
        self:quit()
        return true
    elseif e:is_command("cm_enter") then
        self:on_confirm()
        return true
    end
    return false
end

event:dump

• Dump event information for debugging

Function Prototype

::: tip API

event:dump()

:::

Parameter Description

No parameters

Return Value

No return value

Usage

Print event information for debugging:

import("core.ui.event")

function view:on_event(e)
    e:dump()  -- Output: event(key): Enter 10 .. or event(cmd): cm_quit ..
end

Event Objects

event.keyboard

• Create a keyboard event object

Function Prototype

::: tip API

event.keyboard(key_code: <number>, key_name: <string>, key_meta: <boolean>)

:::

Parameter Description

Parameter	Description
key_code	Required. Numeric key code
key_name	Required. Key name string (e.g., "Enter", "Esc", "Tab")
key_meta	Required. true if ALT key was pressed, false otherwise

Return Value

Type	Description
event	Returns a keyboard event object with type = event.ev_keyboard

Usage

Create a keyboard event (typically done internally):

import("core.ui.event")

-- This is typically created by the UI framework
-- when a key is pressed, but you can create one manually:
local e = event.keyboard(10, "Enter", false)

event.mouse

• Create a mouse event object

Function Prototype

::: tip API

event.mouse(btn_code: <number>, x: <number>, y: <number>, btn_name: <string>)

:::

Parameter Description

Parameter	Description
btn_code	Required. Mouse button event code
x	Required. X coordinate
y	Required. Y coordinate
btn_name	Required. Button name string

Return Value

Type	Description
event	Returns a mouse event object with type = event.ev_mouse

Usage

Create a mouse event (typically done internally):

import("core.ui.event")

-- This is typically created by the UI framework
-- when mouse is used, but you can create one manually:
local e = event.mouse(1, 10, 20, "btn_left")

event.command

• Create a command event object

Function Prototype

::: tip API

event.command(command: <string>, extra?: <table>)

:::

Parameter Description

Parameter	Description
command	Required. Command name string
extra	Optional. Additional data table

Return Value

Type	Description
event	Returns a command event object with type = event.ev_command

Usage

Create and send a command event:

import("core.ui.event")
import("core.ui.action")

-- Create a quit command event
local e = event.command("cm_quit")

-- Send the event to the view
view:on_event(e)

event.idle

• Create an idle event object

Function Prototype

::: tip API

event.idle()

:::

Parameter Description

No parameters

Return Value

Type	Description
event	Returns an idle event object with type = event.ev_idle

Usage

Create an idle event (typically done internally):

import("core.ui.event")

-- This is typically created by the UI framework
-- when there's no user input:
local e = event.idle()