Struct StyledText 

pub struct StyledText { /* private fields */ }

Text that is laid out and painted with a different style for each run.

Use StyledText when part of the text needs its own color, weight, font, or decoration. Pass the text to StyledText::new, then add highlights or explicit runs. Text with a single style doesn’t need this type. Pass a &str or SharedString to the element tree directly.

StyledText wraps to the width it is given and paints each run with its own TextRun. Read the laid-out text with StyledText::layout, which returns a TextLayout for hit testing and measurement.

Examples

StyledText::new("Warning: disk almost full").with_highlights([(
    0..8,
    HighlightStyle {
        color: Some(hsla(0., 0.8, 0.5, 1.)),
        font_weight: Some(FontWeight::BOLD),
        ..Default::default()
    },
)])

See text for an overview of text in GPUI.

Implementations

impl StyledText

pub fn new(text: impl Into<SharedString>) -> Self

Creates a styled text element for text, with no styling beyond the inherited text style.

Add styling with StyledText::with_highlights, StyledText::with_default_highlights, StyledText::with_runs, or StyledText::with_font_family_overrides.

pub fn layout(&self) -> &TextLayout

Returns the layout of this element, for mapping between byte indices and pixels.

The layout is filled in while the element is laid out and prepainted. Its query methods panic if called before that, so call them from event handlers or after the frame has been drawn. TextLayout is cheap to clone and shares its state.

pub fn with_default_highlights( self, default_style: &TextStyle, highlights: impl IntoIterator<Item = (Range<usize>, HighlightStyle)>, ) -> Self

Styles the text with default_style, with highlights applied over it.

The runs are computed now, from default_style. Use this when you have a TextStyle in hand. Otherwise use StyledText::with_highlights, which takes the inherited style at layout time.

Each range must lie on character boundaries inside the text. The ranges must be sorted by start and must not overlap.

Panics

Panics in debug builds if a range is outside the text, or if this element already has highlights from StyledText::with_highlights.

pub fn with_highlights( self, highlights: impl IntoIterator<Item = (Range<usize>, HighlightStyle)>, ) -> Self

Applies highlights over the inherited text style of the element.

Each highlight is a byte range and a HighlightStyle. The inherited style is read from the window when the element is laid out, so a highlight changes only the properties it sets. Text outside every range keeps the inherited style.

The ranges must be sorted by start, must not overlap, and must lie on character boundaries. Debug builds check that each range is inside the text. Release builds don’t check, and unsorted ranges give wrong layouts or panic.

Examples

StyledText::new("Press Enter to save").with_highlights([(
    6..11,
    HighlightStyle {
        font_weight: Some(FontWeight::BOLD),
        ..Default::default()
    },
)])

pub fn with_font_family_overrides( self, overrides: impl IntoIterator<Item = (Range<usize>, SharedString)>, ) -> Self

Sets the font family for byte ranges of the text.

The family is applied at layout time, on top of the inherited style. An override changes the family of a run only when that run lies entirely inside the override’s range. Runs are split only at highlight boundaries, so to make an override cover part of the text, add a highlight at each edge of the range. Can be combined with with_highlights.

The overrides must be sorted by range start and non-overlapping. Each override range must fall on character boundaries.

pub fn with_runs(self, runs: Vec<TextRun>) -> Self

Sets the runs that style the text. Each run gives its byte length and its TextRun.

The run lengths must add up to the length of the text exactly, and each run must end on a character boundary.

Panics

Panics if the runs don’t cover the text exactly, or if a run ends inside a character. In debug builds the message includes the text and the run.

Trait Implementations

impl Element for StyledText

type RequestLayoutState = ()

The state that Element::request_layout returns for the later phases.

type PrepaintState = ()

The state that Element::prepaint returns for Element::paint.

fn id(&self) -> Option<ElementId>

Returns the element’s identity, or None if it has none.

fn source_location(&self) -> Option<&'static Location<'static>>

Returns where this element was created, for the inspector and debug output.

fn request_layout( &mut self, _id: Option<&GlobalElementId>, _inspector_id: Option<&InspectorElementId>, window: &mut Window, cx: &mut App, ) -> (LayoutId, Self::RequestLayoutState)

Requests a layout node from Taffy, and returns it with the state the later phases need.

fn prepaint( &mut self, _id: Option<&GlobalElementId>, _inspector_id: Option<&InspectorElementId>, bounds: Bounds<Pixels>, _: &mut Self::RequestLayoutState, window: &mut Window, _cx: &mut App, )

Runs once the element’s bounds are known, and returns the state that paint needs.

fn paint( &mut self, _id: Option<&GlobalElementId>, _inspector_id: Option<&InspectorElementId>, _bounds: Bounds<Pixels>, _: &mut Self::RequestLayoutState, _: &mut Self::PrepaintState, window: &mut Window, cx: &mut App, )

Draws the element. Runs after prepaint, once per frame.

fn a11y_role(&self) -> Option<Role>

Returns the accessible role for this element, if any. Elements that return None have no accessibility node unless Element::is_a11y_hidden returns true.

fn is_a11y_hidden(&self) -> bool

Whether assistive technology should ignore this element and its descendants.

fn write_a11y_info(&self, _node: &mut Node)

Write accessibility properties to the given node. GPUI calls this only when Element::a11y_role returns Some or Element::is_a11y_hidden returns true.

fn a11y_synthetic_children( &mut self, _prepaint: &mut Self::PrepaintState, _builder: &mut A11ySubtreeBuilder<'_>, )

Add synthetic child nodes to an Element. The element must have an .id(). It must also have a .role() or return true from Element::is_a11y_hidden.

fn into_any(self) -> AnyElement

Convert this element into a dynamically-typed AnyElement.

impl IntoElement for StyledText

type Element = StyledText

The element type that this type converts into.

fn into_element(self) -> Self::Element

Converts self into an Element.

fn into_any_element(self) -> AnyElement

Converts self into an AnyElement, with its concrete type erased.