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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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