XU XUv0.13.1
中文

UI / WIDGETS / Text & status

StyledLabel

Text labels with cached layout and theme styles

Run the Xu example

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

What to try

Edit the title and font size in the example, then rerun to compare the layout.

Usage notes

Labels display content rather than edit it. Remeasure after text or font changes to avoid clipping and incorrect wrapping.

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 {
    id := screen.label("Make room for ideas.",20.0,false) or >>
    screen.place(id,24.0,24.0,320.0,80.0) or >>
    << id
}

($&Screen) label

XuAPI
pub fn (s $&Screen) label(text string,size f64,muted bool) int

Purpose

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

Parameters

s $&Screen
The Screen instance used by this call (exclusive borrow).
text string
text (string)
size f64
size (f64)
muted bool
muted (bool)

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.

($&StyledLabel) paint_ellipsized_styled

XuAPI
pub fn (label $&StyledLabel) paint_ellipsized_styled(frame $&draw.Frame,bounds &layout.Rect,styles &Styles,fallback &ControlStyle,state int) int

Purpose

End ellipsis uses shaped cluster boundaries. The label retains its full text callers can associate a Tooltip or render the full wrapped text on demand. Throws on failure; handle the error or propagate it to the caller.

Parameters

label $&StyledLabel
The StyledLabel instance used by this call (exclusive borrow).
frame $&draw.Frame
frame (exclusive borrow; may modify the original; type $&draw.Frame)
bounds &layout.Rect
bounds (read-only borrow; caller keeps the original; type &layout.Rect)
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)
fallback &ControlStyle
fallback (read-only borrow; caller keeps the original; type &ControlStyle)
state int
state (int)

Returns

int — a value of this type

struct StyledLabel

XuAPI
pub struct StyledLabel {

}

Purpose

Owned text and native layout cache. Palette changes reuse layout; font changes rebuild it. Dispose when finished.

Public fields

This type has no public fields.

See usage example

($&StyledLabel) set_font_stack

XuAPI
pub fn (label $&StyledLabel) set_font_stack(stack font.FontStack)

Purpose

Operation on $&StyledLabel: set font stack.

Parameters

label $&StyledLabel
The StyledLabel instance used by this call (exclusive borrow).
stack font.FontStack
stack (font.FontStack)

Returns

This call does not return a value.

($&StyledLabel) add_ttf_bytes

XuAPI
pub fn (label $&StyledLabel) add_ttf_bytes(ttf_bytes &[]u8,font_index int,face_id int) int

Purpose

Operation on $&StyledLabel: add ttf bytes. Throws on failure; handle the error or propagate it to the caller.

Parameters

label $&StyledLabel
The StyledLabel instance used by this call (exclusive borrow).
ttf_bytes &[]u8
ttf_bytes (read-only borrow; caller keeps the original; type &[]u8)
font_index int
font_index (int)
face_id int
face_id (int)

Returns

int — a value of this type

(&StyledLabel) paint_layout_at

XuAPI
pub fn (label &StyledLabel) paint_layout_at(frame $&draw.Frame,shaped &draw.TextLayout,x f64,y f64,color draw.Color) int

Purpose

Operation on &StyledLabel: paint layout at. Throws on failure; handle the error or propagate it to the caller.

Parameters

label &StyledLabel
The StyledLabel instance used by this call (borrow).
frame $&draw.Frame
frame (exclusive borrow; may modify the original; type $&draw.Frame)
shaped &draw.TextLayout
shaped (read-only borrow; caller keeps the original; type &draw.TextLayout)
x f64
value (f64)
y f64
value (f64)
color draw.Color
color (draw.Color)

Returns

int — a value of this type

(&StyledLabel) text

XuAPI
pub fn (label &StyledLabel) text() string

Purpose

Operation on &StyledLabel: return the current text.

Parameters

label &StyledLabel
The StyledLabel instance used by this call (borrow).

Returns

string — result string

(&StyledLabel) has_style

XuAPI
pub fn (label &StyledLabel) has_style() bool

Purpose

Operation on &StyledLabel: whether it has style.

Parameters

label &StyledLabel
The StyledLabel instance used by this call (borrow).

Returns

bool — true or false

(&StyledLabel) style_or

XuAPI
pub fn (label &StyledLabel) style_or(fallback &ControlStyle) ControlStyle

Purpose

Operation on &StyledLabel: style or.

Parameters

label &StyledLabel
The StyledLabel instance used by this call (borrow).
fallback &ControlStyle
fallback (read-only borrow; caller keeps the original; type &ControlStyle)

Returns

ControlStyle — a value of this type

($&StyledLabel) set_style

XuAPI
pub fn (label $&StyledLabel) set_style(style &ControlStyle) int

Purpose

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

Parameters

label $&StyledLabel
The StyledLabel 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

($&StyledLabel) clear_style

XuAPI
pub fn (label $&StyledLabel) clear_style()

Purpose

Operation on $&StyledLabel: clear style.

Parameters

label $&StyledLabel
The StyledLabel instance used by this call (exclusive borrow).

Returns

This call does not return a value.

($&StyledLabel) set_text

XuAPI
pub fn (label $&StyledLabel) set_text(value &string)

Purpose

Replace owned text; also call View.mark_measure when used in a View.

Parameters

label $&StyledLabel
The StyledLabel instance used by this call (exclusive borrow).
value &string
value (read-only borrow; caller keeps the original; type &string)

Returns

This call does not return a value.

($&StyledLabel) measure_styled

XuAPI
pub fn (label $&StyledLabel) measure_styled(styles &Styles,control &ControlStyle) layout.Size

Purpose

Measure StyledLabel with the effective font, density, content and minimum size.

Parameters

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

Returns

intrinsic logical size; throws if native shaping fails

($&StyledLabel) measure_wrapped

XuAPI
pub fn (label $&StyledLabel) measure_wrapped(styles &Styles,control &ControlStyle,width f64) layout.Size

Purpose

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

Parameters

label $&StyledLabel
The StyledLabel instance used by this call (exclusive borrow).
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)
control &ControlStyle
control (read-only borrow; caller keeps the original; type &ControlStyle)
width f64
width (f64)

Returns

layout.Size — a value of this type

($&StyledLabel) measure_box_styled

XuAPI
pub fn (label $&StyledLabel) measure_box_styled(styles &Styles,fallback &ControlStyle) layout.Size

Purpose

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

Parameters

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

Returns

layout.Size — a value of this type

($&StyledLabel) paint_text_styled

XuAPI
pub fn (label $&StyledLabel) paint_text_styled(frame $&draw.Frame,bounds &layout.Rect,styles &Styles,fallback &ControlStyle,state int) int

Purpose

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

Parameters

label $&StyledLabel
The StyledLabel instance used by this call (exclusive borrow).
frame $&draw.Frame
frame (exclusive borrow; may modify the original; type $&draw.Frame)
bounds &layout.Rect
bounds (read-only borrow; caller keeps the original; type &layout.Rect)
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)
fallback &ControlStyle
fallback (read-only borrow; caller keeps the original; type &ControlStyle)
state int
state (int)

Returns

int — a value of this type

($&StyledLabel) paint_styled

XuAPI
pub fn (label $&StyledLabel) paint_styled(frame $&draw.Frame,bounds &layout.Rect,styles &Styles,fallback &ControlStyle,state int) int

Purpose

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

Parameters

label $&StyledLabel
The StyledLabel instance used by this call (exclusive borrow).
frame $&draw.Frame
frame (exclusive borrow; may modify the original; type $&draw.Frame)
bounds &layout.Rect
bounds (read-only borrow; caller keeps the original; type &layout.Rect)
styles &Styles
styles (read-only borrow; caller keeps the original; type &Styles)
fallback &ControlStyle
fallback (read-only borrow; caller keeps the original; type &ControlStyle)
state int
state (int)

Returns

int — a value of this type

($&StyledLabel) dispose

XuAPI
pub fn (label $&StyledLabel) dispose()

Purpose

Release the native layout cache owned by the label.

Parameters

label $&StyledLabel
The StyledLabel instance used by this call (exclusive borrow).

Returns

This call does not return a value.

Complete native example

Component Workshop · Back to Widgets