XU XUv0.13.1
中文

UI / WIDGETS / Selection

MultiSelect

Choose multiple items from a list

Run the Xu example

The example executes in the browser using the Xu/WASM runtime.

What to try

Select several labels and remove one.

Usage notes

Each option has its own selected state. Keep chosen items visible and provide an easy way to remove them.

Create through Screen

The Screen constructor returns a node ID. Pass that ID to Screen layout, state and event APIs. It is separate from the standalone control object documented below.

Native Xu setup fragment: call configure during initialization of an existing Screen. See the complete example for window creation, event dispatch and cleanup.

#ui/widgets

fn configure(screen $&widgets.Screen) int {
    options := ["Design","Develop","Review"]
    id := screen.multi_select(&options) or >>
    screen.place(id,24.0,24.0,320.0,80.0) or >>
    << id
}

($&Screen) multi_select

XuAPI
pub fn (s $&Screen) multi_select(options &[]string) int

Purpose

Create MultiSelect in Screen and return the component node ID; throw on creation failure.

Parameters

s $&Screen
The Screen instance used by this call (exclusive borrow).
options &[]string
options (read-only borrow; caller keeps the original; type &[]string)

Returns

int — component node ID for place and other Screen methods.

Placement, state and events

The application owns the component. Screen.place positions nodes; Screen.set_enabled and Screen.set_visible control availability and visibility. Present again after state changes, handle or errors, and keep topology changes outside paint callbacks. ToastHost uses its own queue API.

Action · Styles · UI lifecycle and styling guide

Screen.place · Screen.set_enabled · Screen.set_visible

Standalone control object API

These types and methods support applications that manage control objects, input and painting directly. Their receiver is a control object, not a Screen node ID. For Screen usage, use the constructor above and the Screen methods in the Widgets module.

($&MultiSelect) set_locale

XuAPI
pub fn (multi $&MultiSelect) set_locale(locale &Locale) int

Purpose

Operation on $&MultiSelect: set locale. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
locale &Locale
locale (read-only borrow; caller keeps the original; type &Locale)

Returns

int — a value of this type

(&MultiSelect) selection_text

XuAPI
pub fn (multi &MultiSelect) selection_text() string

Purpose

Operation on &MultiSelect: selection text. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).

Returns

string — result string

struct MultiSelect

XuAPI
pub struct MultiSelect {

}

Purpose

keyboard cursor; Escape, blur and an outside press close without clearing it.

Public fields

This type has no public fields.

(&MultiSelect) id

XuAPI
pub fn (multi &MultiSelect) id() int

Purpose

Return the unique integer ID of the element or control.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).

Returns

int — a value of this type

(&MultiSelect) bounds

XuAPI
pub fn (multi &MultiSelect) bounds() layout.Rect

Purpose

Return the bounding Rectangle of the control or geometry.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).

Returns

layout.Rect — a value of this type

(&MultiSelect) is_open

XuAPI
pub fn (multi &MultiSelect) is_open() bool

Purpose

Return whether the overlay, menu or dialog is currently open.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).

Returns

bool — true or false

(&MultiSelect) is_enabled

XuAPI
pub fn (multi &MultiSelect) is_enabled() bool

Purpose

Return whether the control is currently enabled.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).

Returns

bool — true or false

(&MultiSelect) is_selectable

XuAPI
pub fn (multi &MultiSelect) is_selectable() bool

Purpose

Operation on &MultiSelect: whether it is selectable.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).

Returns

bool — true or false

($&MultiSelect) set_selectable

XuAPI
pub fn (multi $&MultiSelect) set_selectable(selectable bool)

Purpose

Operation on $&MultiSelect: set selectable.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
selectable bool
selectable (bool)

Returns

This call does not return a value.

(&MultiSelect) needs_paint

XuAPI
pub fn (multi &MultiSelect) needs_paint() bool

Purpose

Return whether the control needs repainting; call painted after painting to clear the flag.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).

Returns

bool — true or false

(&MultiSelect) count

XuAPI
pub fn (multi &MultiSelect) count() int

Purpose

Return the number of items in this control.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).

Returns

int — a value of this type

(&MultiSelect) selected

XuAPI
pub fn (multi &MultiSelect) selected(index int) bool

Purpose

Check whether one option is selected, for example after receiving a change action.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).
index int
Zero-based index in the original option list.

Returns

true if checked, otherwise false.

Error handling

  • An invalid index throws widgets: choice index out of range.

(&MultiSelect) values

XuAPI
pub fn (multi &MultiSelect) values() []int

Purpose

Return a slice containing all values in the collection.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).

Returns

[]int — slice result

($&MultiSelect) set_selected

XuAPI
pub fn (multi $&MultiSelect) set_selected(index int,selected bool) int

Purpose

Set one option's checked state without changing other choices, for example when restoring form data.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
index int
Zero-based index in the original option list.
selected bool
true checks and false unchecks the option.

Returns

Returns 0 on success; failure throws rather than returning a nonzero status.

Error handling

  • A disposed control or index outside 0..count()-1 throws.

(&MultiSelect) style_or

XuAPI
pub fn (multi &MultiSelect) style_or(styles &Styles) ControlStyle

Purpose

Operation on &MultiSelect: style or.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)

Returns

ControlStyle — a value of this type

($&MultiSelect) set_style

XuAPI
pub fn (multi $&MultiSelect) set_style(style &ControlStyle) int

Purpose

Operation on $&MultiSelect: set style. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
style &ControlStyle
style (read-only borrow; caller keeps the original; type &ControlStyle)

Returns

int — a value of this type

($&MultiSelect) set_enabled

XuAPI
pub fn (multi $&MultiSelect) set_enabled(enabled bool)

Purpose

Operation on $&MultiSelect: set enabled.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
enabled bool
enabled (bool)

Returns

This call does not return a value.

($&MultiSelect) set_read_only

XuAPI
pub fn (multi $&MultiSelect) set_read_only(read_only bool) int

Purpose

Operation on $&MultiSelect: set read only. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
read_only bool
read_only (bool)

Returns

int — a value of this type

($&MultiSelect) set_invalid

XuAPI
pub fn (multi $&MultiSelect) set_invalid(invalid bool)

Purpose

Operation on $&MultiSelect: set invalid.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
invalid bool
invalid (bool)

Returns

This call does not return a value.

($&MultiSelect) set_focus

XuAPI
pub fn (multi $&MultiSelect) set_focus(focused bool)

Purpose

Operation on $&MultiSelect: set focus.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
focused bool
focused (bool)

Returns

This call does not return a value.

($&MultiSelect) set_open

XuAPI
pub fn (multi $&MultiSelect) set_open(open bool)

Purpose

Set whether the option list is open.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
open bool
true requests opening and false closes it; disabled or read-only controls remain closed.

Returns

No return value; read the resulting state with is_open().

Usage notes

  • Opening and painting are separate: call paint_popup_styled in an appropriate overlay pass.

($&MultiSelect) set_popup_above

XuAPI
pub fn (multi $&MultiSelect) set_popup_above(above bool)

Purpose

Operation on $&MultiSelect: set popup above.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
above bool
above (bool)

Returns

This call does not return a value.

($&MultiSelect) set_bounds

XuAPI
pub fn (multi $&MultiSelect) set_bounds(bounds &layout.Rect) int

Purpose

Operation on $&MultiSelect: set bounds. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
bounds &layout.Rect
bounds (read-only borrow; caller keeps the original; type &layout.Rect)

Returns

int — a value of this type

($&MultiSelect) apply_styles

XuAPI
pub fn (multi $&MultiSelect) apply_styles(styles &Styles) int

Purpose

Resolve and apply theme metrics to the control. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)

Returns

int — a value of this type

(&MultiSelect) popup_bounds

XuAPI
pub fn (multi &MultiSelect) popup_bounds() layout.Rect

Purpose

Read the option-list rectangle in canvas coordinates for overlay hit testing or layout.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).

Returns

The list's layout.Rect; reading it does not open the list, so also check is_open().

(&MultiSelect) option_bounds

XuAPI
pub fn (multi &MultiSelect) option_bounds(index int) layout.Rect

Purpose

Operation on &MultiSelect: option bounds. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi &MultiSelect
The MultiSelect instance used by this call (borrow).
index int
index (int)

Returns

layout.Rect — a value of this type

($&MultiSelect) input

XuAPI
pub fn (multi $&MultiSelect) input(event &ui.InputEvent) Action

Purpose

Process opening, multiple selection and selected-chip interaction, updating control state.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
event &ui.InputEvent
Input event for the same window, canvas and generation, with coordinates in the control's canvas space.

Returns

An Action: kind identifies the action, consumed marks a handled event, request_focus requests focus, and needs_paint requests repainting.

Usage notes

  • Toggling an option yields ACTION_CHANGE with the changed option index; call selected(index) for its new checked state.

($&MultiSelect) route

XuAPI
pub fn (multi $&MultiSelect) route(kind int,event &ui.InputEvent) Action

Purpose

Route and dispatch the input event to matching targets. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
kind int
kind tag (int)
event &ui.InputEvent
event (read-only borrow; caller keeps the original; type &ui.InputEvent)

Returns

Action — input result with kind, id, repaint and focus requests.

($&MultiSelect) event

XuAPI
pub fn (multi $&MultiSelect) event(event &ui.Event) Action

Purpose

Receive native window events, routing input to input and other events to the internal editor or base control.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
event &ui.Event
Full native ui.Event; use this entry point for IME, blur and lifecycle handling.

Returns

An Action: kind identifies the action, consumed marks a handled event, request_focus requests focus, and needs_paint requests repainting.

Usage notes

  • The option list closes when its internal control loses focus.

($&MultiSelect) measure_styled

XuAPI
pub fn (multi $&MultiSelect) measure_styled(styles &Styles) layout.Size

Purpose

Operation on $&MultiSelect: measure styled. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)

Returns

layout.Size — a value of this type

($&MultiSelect) paint_styled

XuAPI
pub fn (multi $&MultiSelect) paint_styled(frame $&draw.Frame,styles &Styles) int

Purpose

Operation on $&MultiSelect: paint styled. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
frame $&draw.Frame
frame (exclusive borrow; may modify the original; type $&draw.Frame)
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)

Returns

int — a value of this type

($&MultiSelect) paint_popup_styled

XuAPI
pub fn (multi $&MultiSelect) paint_popup_styled(frame $&draw.Frame,styles &Styles) int

Purpose

Paint the expanded option list separately from the field so it can appear above other controls.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
frame $&draw.Frame
Current frame to receive drawing commands.
styles &Styles
Effective styles supplying colors, spacing, fonts and state appearance.

Returns

Returns 0 on success; failure throws rather than returning a nonzero status.

Usage notes

  • Paint in canvas coordinates, normally after regular controls. A field-local transform or clip can shift or cut off the list.

Error handling

  • Frame, text or style failures propagate as errors.

($&MultiSelect) dispose

XuAPI
pub fn (multi $&MultiSelect) dispose()

Purpose

Release and dispose native resources and underlying handles.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).

Returns

This call does not return a value.

($&MultiSelect) set_filter

XuAPI
pub fn (multi $&MultiSelect) set_filter(query &string) int

Purpose

Operation on $&MultiSelect: set filter. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
query &string
query (read-only borrow; caller keeps the original; type &string)

Returns

int — a value of this type

($&MultiSelect) select_all

XuAPI
pub fn (multi $&MultiSelect) select_all(selected bool) int

Purpose

Operation on $&MultiSelect: select all. Throws on failure; handle the error or propagate it to the caller.

Parameters

multi $&MultiSelect
The MultiSelect instance used by this call (exclusive borrow).
selected bool
selected (bool)

Returns

int — a value of this type

Complete native example

Component Workshop · Back to Widgets