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

core.ui.application

This module provides the main application container for the terminal UI system. You can inherit from application to implement your own terminal UI applications.

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

::: 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 application module uses inheritance. You create your own application instance and customize its behavior:

import("core.ui.application")

local app = application()

function app:init()
    -- Your initialization code
end

application:new

• Create a new application instance

Function Prototype

::: tip API

local app = application()

:::

Parameter Description

No parameters for constructor

Return Value

Type	Description
application	Returns a new application instance

Usage

Create an application instance that you can customize:

import("core.ui.application")

local demo = application()

application:init

• Initialize the application

Function Prototype

::: tip API

application:init(name: <string>, argv?: <table>)

:::

Parameter Description

Parameter	Description
name	Required. Application name string
argv	Optional. Command line arguments table

Return Value

No return value

Usage

Initialize your custom application. This is called automatically by run():

function demo:init()
    application.init(self, "myapp")
    self:background_set("blue")
    
    -- Add your UI components here
    self:insert(self:main_dialog())
end

application:run

• Run the application and start the event loop

Function Prototype

::: tip API

application:run(...)

:::

Parameter Description

Parameter	Description
...	Optional. Additional arguments

Return Value

No return value

Usage

Start your application. This initializes the UI, calls init(), and starts the event loop:

local demo = application()

function demo:init()
    application.init(self, "demo")
    self:background_set("blue")
    self:insert(self:main_dialog())
end

-- Start the application
demo:run()

application:background_set

• Set the application background color

Function Prototype

::: tip API

application:background_set(color: <string>)

:::

Parameter Description

Parameter	Description
color	Required. Color name (e.g., "blue", "red")

Return Value

No return value

Usage

Set the background color for your application:

self:background_set("blue")

application:insert

• Insert a view into the application

Function Prototype

::: tip API

application:insert(view: <view>, opt?: <table>)

:::

Parameter Description

Parameter	Description
view	Required. View to insert
opt	Optional. Options table, supports: {centerx = true, centery = true}

Return Value

No return value

Usage

Add views to your application with optional positioning:

-- Add a dialog
self:insert(self:main_dialog())

-- Add a centered dialog
self:insert(self:input_dialog(), {centerx = true, centery = true})

application:on_resize

• Handle window resize events

Function Prototype

::: tip API

application:on_resize()

:::

Parameter Description

No parameters

Return Value

No return value

Usage

Override this method to handle resize events and update your UI layout:

function demo:on_resize()
    self:main_dialog():bounds_set(rect{1, 1, self:width() - 1, self:height() - 1})
    self:center(self:input_dialog(), {centerx = true, centery = true})
    application.on_resize(self)
end

application:menubar

• Get the application's menu bar

Function Prototype

::: tip API

application:menubar()

:::

Parameter Description

No parameters

Return Value

Type	Description
menubar	Returns the menu bar instance

Usage

Access the menu bar component:

local menubar = app:menubar()

application:desktop

• Get the application's desktop area

Function Prototype

::: tip API

application:desktop()

:::

Parameter Description

No parameters

Return Value

Type	Description
desktop	Returns the desktop instance

Usage

Access the desktop area for placing views:

local desktop = app:desktop()

application:statusbar

• Get the application's status bar

Function Prototype

::: tip API

application:statusbar()

:::

Parameter Description

No parameters

Return Value

Type	Description
statusbar	Returns the status bar instance

Usage

Access the status bar component:

local statusbar = app:statusbar()
statusbar:text_set("Ready")