core.ui.view

This module provides the base view component for the terminal UI system.

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

::: 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 view module is the base class for all UI components. It extends object and provides core view functionality including drawing, event handling, state management, option management, and attribute management.

view:new

Create a new view instance

Function Prototype

::: tip API

view:new(name: <string>, bounds: <rect>, ...)

:::

Parameter Description

Parameter	Description
name	Required. View name string
bounds	Required. View bounds rectangle
...	Variable arguments

Return Value

Type	Description
view	Returns a view instance

Usage

Create a view instance:

import("core.ui.view")
import("core.ui.rect")

local v = view:new("myview", rect{1, 1, 80, 25})

view:name

Get the view name

Function Prototype

::: tip API

view:name()

:::

Parameter Description

No parameters

Return Value

Type	Description
string	Returns the view name

Usage

Get the view name:

local name = v:name()
print(name)  -- Output: myview

view:bounds

Get the view bounds rectangle

Function Prototype

::: tip API

view:bounds()

:::

Parameter Description

No parameters

Return Value

Type	Description
rect	Returns the view bounds rectangle

Usage

Get the view bounds:

local bounds = v:bounds()
print(bounds:sx(), bounds:sy(), bounds:ex(), bounds:ey())

view:bounds_set

Set the view bounds rectangle

Function Prototype

::: tip API

view:bounds_set(bounds: <rect>)

:::

Parameter Description

Parameter	Description
bounds	Required. New bounds rectangle

Return Value

No return value

Usage

Set the view bounds:

v:bounds_set(rect{10, 5, 50, 20})

view:width

Get the view width

Function Prototype

::: tip API

view:width()

:::

Parameter Description

No parameters

Return Value

Type	Description
number	Returns the view width

Usage

Get the view width:

local w = v:width()

view:height

Get the view height

Function Prototype

::: tip API

view:height()

:::

Parameter Description

No parameters

Return Value

Type	Description
number	Returns the view height

Usage

Get the view height:

local h = v:height()

view:parent

Get the parent view

Function Prototype

::: tip API

view:parent()

:::

Parameter Description

No parameters

Return Value

Type	Description
view	Returns the parent view instance or `nil`

Usage

Get the parent view:

local parent = v:parent()

view:application

Get the application instance

Function Prototype

::: tip API

view:application()

:::

Parameter Description

No parameters

Return Value

Type	Description
application	Returns the application instance

Usage

Get the application instance:

local app = v:application()
app:quit()

view:canvas

Get the view canvas

Function Prototype

::: tip API

view:canvas()

:::

Parameter Description

No parameters

Return Value

Type	Description
canvas	Returns the canvas instance

Usage

Get the canvas for drawing operations:

local canvas = v:canvas()
canvas:move(0, 0):putstr("Hello")

view:state

Get the view state

Function Prototype

::: tip API

view:state(name: <string>)

:::

Parameter Description

Parameter	Description
name	Required. State name

Return Value

Type	Description
any	Returns the state value

Usage

Get the view state. Common states include:

visible: Whether visible
cursor_visible: Whether cursor is visible
selected: Whether selected
focused: Whether focused
```
local is_visible = v:state("visible")
```

view:state_set

Set the view state

Function Prototype

::: tip API

view:state_set(name: <string>, enable: <boolean>)

:::

Parameter Description

Parameter	Description
name	Required. State name
enable	Required. Whether to enable

Return Value

Type	Description
view	Returns the view instance (for chaining)

Usage

Set the view state:

v:state_set("visible", true)

view:option

Get the view option

Function Prototype

::: tip API

view:option(name: <string>)

:::

Parameter Description

Parameter	Description
name	Required. Option name

Return Value

Type	Description
any	Returns the option value

Usage

Get the view option. Common options include:

selectable: Whether selectable

mouseable: Whether mouse support

local is_selectable = v:option("selectable")

view:option_set

Set the view option

Function Prototype

::: tip API

view:option_set(name: <string>, enable: <boolean>)

:::

Parameter Description

Parameter	Description
name	Required. Option name
enable	Required. Whether to enable

Return Value

No return value

Usage

Set the view option:

v:option_set("selectable", true)

view:attr

Get the view attribute

Function Prototype

::: tip API

view:attr(name: <string>)

:::

Parameter Description

Parameter	Description
name	Required. Attribute name

Return Value

Type	Description
any	Returns the attribute value

Usage

Get the view attribute:

local bg = v:attr("background")

view:attr_set

Set the view attribute

Function Prototype

::: tip API

view:attr_set(name: <string>, value: <any>)

:::

Parameter Description

Parameter	Description
name	Required. Attribute name
value	Required. Attribute value

Return Value

Type	Description
view	Returns the view instance (for chaining)

Usage

Set the view attribute:

v:attr_set("background", "blue")

view:background

Get the background color

Function Prototype

::: tip API

view:background()

:::

Parameter Description

No parameters

Return Value

Type	Description
string	Returns the background color name

Usage

Get the background color:

local bg = v:background()

view:background_set

Set the background color

Function Prototype

::: tip API

view:background_set(color: <string>)

:::

Parameter Description

Parameter	Description
color	Required. Color name

Return Value

Type	Description
view	Returns the view instance (for chaining)

Usage

Set the background color:

v:background_set("blue")

view:action_set

Set the action handler

Function Prototype

::: tip API

view:action_set(name: <string>, on_action: <function>)

:::

Parameter Description

Parameter	Description
name	Required. Action name
on_action	Required. Action handler function

Return Value

Type	Description
view	Returns the view instance (for chaining)

Usage

Set the action handler:

import("core.ui.action")

v:action_set(action.ac_on_clicked, function (view)
    print("View clicked")
end)

view:action_on

Trigger an action

Function Prototype

::: tip API

view:action_on(name: <string>, ...)

:::

Parameter Description

Parameter	Description
name	Required. Action name
...	Variable arguments, passed to action handler

Return Value

Type	Description
any	Returns the action handler's return value

Usage

Trigger an action:

import("core.ui.action")

v:action_on(action.ac_on_clicked)

view:invalidate

Invalidate the view (needs redraw)

Function Prototype

::: tip API

view:invalidate(bounds?: <boolean>)

:::

Parameter Description

Parameter	Description
bounds	Optional. Whether resize is needed

Return Value

No return value

Usage

Invalidate the view to trigger redraw:

v:invalidate()        -- Mark as needing redraw
v:invalidate(true)    -- Mark as needing resize

view:show

Show or hide the view

Function Prototype

::: tip API

view:show(visible: <boolean>, opt?: <table>)

:::

Parameter Description

Parameter	Description
visible	Required. Whether to show
opt	Optional. Option table, supports: `{focused = true}`

Return Value

No return value

Usage

Show or hide the view:

v:show(true)                          -- Show
v:show(false)                         -- Hide
v:show(true, {focused = true})        -- Show and focus

view:cursor_move

Move cursor position

Function Prototype

::: tip API

view:cursor_move(x: <number>, y: <number>)

:::

Parameter Description

Parameter	Description
x	Required. Cursor X coordinate
y	Required. Cursor Y coordinate

Return Value

Type	Description
view	Returns the view instance (for chaining)

Usage

Move cursor position:

v:cursor_move(10, 5)

view:cursor_show

Show or hide cursor

Function Prototype

::: tip API

view:cursor_show(visible: <boolean>)

:::

Parameter Description

Parameter	Description
visible	Required. Whether to show cursor

Return Value

Type	Description
view	Returns the view instance (for chaining)

Usage

Show or hide cursor:

v:cursor_show(true)   -- Show cursor
v:cursor_show(false)  -- Hide cursor

view:on_draw

Draw the view

Function Prototype

::: tip API

view:on_draw(transparent: <boolean>)

:::

Parameter Description

Parameter	Description
transparent	Optional. Whether to draw transparently

Return Value

No return value

Usage

This method is automatically called when drawing the view. Override in subclasses to implement custom drawing:

function my_view:on_draw(transparent)
    -- Call parent method to draw background
    view.on_draw(self, transparent)
    
    -- Custom drawing content
    local canvas = self:canvas()
    canvas:move(0, 0):putstr("My View")
end

view:on_event

Handle events

Function Prototype

::: tip API

view:on_event(e: <event>)

:::

Parameter Description

Parameter	Description
e	Required. Event object

Return Value

Type	Description
boolean	Returns `true` if event was handled, otherwise returns `false`

Usage

This method is automatically called when handling events. Override in subclasses to implement custom event handling:

function my_view:on_event(e)
    if e.type == event.ev_keyboard and e.key_name == "Enter" then
        -- Handle Enter key
        return true
    end
    return view.on_event(self, e)
end

Here is a complete custom view example:

import("core.ui.view")
import("core.ui.window")
import("core.ui.rect")
import("core.ui.application")
import("core.ui.event")
import("core.ui.action")

-- Define custom view
local myview = myview or view()

function myview:init(name, bounds)
    view.init(self, name, bounds)
    self:background_set("cyan")
    self:option_set("selectable", true)
end

function myview:on_draw(transparent)
    view.on_draw(self, transparent)
    
    local canvas = self:canvas()
    local textattr = curses.calc_attr({"yellow", "bold"})
    canvas:attr(textattr):move(0, 0):putstr("Custom View")
end

function myview:on_event(e)
    if e.type == event.ev_keyboard and e.key_name == "Enter" then
        print("Custom view activated")
        return true
    end
    return view.on_event(self, e)
end

-- Use custom view
local demo = application()

function demo:init()
    application.init(self, "demo")
    self:background_set("blue")
    
    -- Create window
    local win = window:new("main", rect{1, 1, self:width() - 1, self:height() - 1}, "Custom View Demo")
    
    -- Create custom view
    local custom = myview:new("custom", rect{10, 5, 40, 10})
    
    -- Add view to window panel
    local panel = win:panel()
    panel:insert(custom)
    panel:select(custom)
    
    self:insert(win)
    self._win = win
end

function demo:on_resize()
    self._win:bounds_set(rect{1, 1, self:width() - 1, self:height() - 1})
    application.on_resize(self)
end

function main(...)
    demo:run(...)
end

view.md 14 KB История Исходник

core.ui.view

view:new

Function Prototype

Parameter Description

Return Value

Usage

view:name

Function Prototype

Parameter Description

Return Value

Usage

view:bounds

Function Prototype

Parameter Description

Return Value

Usage

view:bounds_set

Function Prototype

Parameter Description

Return Value

Usage

view:width

Function Prototype

Parameter Description

Return Value

Usage

view:height

Function Prototype

Parameter Description

Return Value

Usage

view:parent

Function Prototype

Parameter Description

Return Value

Usage

view:application

Function Prototype

Parameter Description

Return Value

Usage

view:canvas

Function Prototype

Parameter Description

Return Value

Usage

view:state

Function Prototype

Parameter Description

Return Value

Usage

view:state_set

Function Prototype

Parameter Description

Return Value

Usage

view:option

Function Prototype

Parameter Description

Return Value

Usage

view:option_set

Function Prototype

Parameter Description

Return Value

Usage

view:attr

Function Prototype

Parameter Description

Return Value

Usage

view:attr_set

Function Prototype

Parameter Description

Return Value

Usage

view:background

Function Prototype

Parameter Description

view.md 14 KB

История Исходник