UI text
Show and update text in the UI: Text and TextSpan, fonts and font sizes, colour, weight, justification and wrapping, shadows and decorations, and text input.
Text is a UI node that shows text. It sizes itself to its content and takes part in layout like any other node, so you place it with Node fields or by nesting it in a container. The same font and style components also work for Text2d, which places text in the world; see Text in 2D.
Show text#
commands.spawn((
Text::new("hello\nNEO!"),
TextFont {
font: asset_server.load("fonts/FiraSans-Bold.ttf").into(),
font_size: FontSize::Px(42.0),
..default()
},
TextColor(Color::WHITE),
TextLayout::justify(Justify::Center),
Node { position_type: PositionType::Absolute, bottom: px(5), right: px(5), ..default() },
));Components#
| Component | What it does |
|---|---|
Text | The text. It derefs to a String. |
TextSpan | A child with more text in its own style; see Spans. |
TextFont | font, font_size, weight, width, style, font_smoothing, font_features and font_variations. |
TextColor | The colour. |
TextLayout | justify and linebreak. TextLayout::no_wrap() keeps it on one line. |
LineHeight | LineHeight::Px(..) or RelativeToFont(..). |
LetterSpacing | LetterSpacing::Px(..) or Rem(..). |
TextShadow | A drop shadow: offset and color. |
TextBackgroundColor | A colour behind the glyphs. |
Underline, Strikethrough | Decorations, with UnderlineColor and StrikethroughColor to colour them. |
Font sizes#
font_size is a FontSize:
FontSize:: | Size |
|---|---|
Px(32.0) | Logical pixels, scaled by UiScale and the window's scale factor. |
Vw(5.0), Vh(5.0) | Percent of the viewport's width or height, so text grows with the window. |
VMin(..), VMax(..) | Percent of the viewport's smaller or larger side. |
Rem(1.5) | A multiple of the root font size. |
Each distinct size of each font gets its own glyph atlas, so avoid animating font_size every frame; animate a UiTransform scale instead.
Fonts#
TextFont::font is a FontSource. A font handle converts into one with .into().
FontSource:: | What it uses |
|---|---|
Default | The built-in font. It only has ASCII characters. |
Handle(handle) | A .ttf or .otf file loaded through the asset server. |
Family("Inter".into()) | A font installed on the device, by family name. |
serif(), sans_serif(), monospace(), cursive(), fantasy() | The device's font for a generic family. |
Using installed fonts needs the system_font_discovery cargo feature, which NEO's game builds turn on. Which fonts are installed differs from device to device, so ship font files for any text that must look the same everywhere, and for every language you support.
FontWeight (FontWeight::BOLD, or any value from 1 to 1000) only changes the weight of variable fonts; for other fonts, load the bold file. FontSmoothing::None (in neo::text) turns antialiasing off for pixel fonts.
Update text#
Query the component and assign to it:
#[derive(Component)]
struct ScoreText;
fn show_score(score: Res<Score>, mut texts: Query<&mut Text, With<ScoreText>>) {
for mut text in &mut texts {
**text = format!("Score: {}", score.0);
}
}Run systems like this only when the value changes (for example with run_if(resource_changed::<Score>)): changing text re-runs its layout.
Spans#
Give a Text entity TextSpan children to style parts of it differently. The spans follow the parent's own text, in child order:
commands
.spawn((Text::new("FPS: "), TextFont::from_font_size(FontSize::Px(42.0))))
.with_child((TextSpan::default(), TextColor(Color::srgb(1.0, 0.84, 0.0)), FpsText));
fn update_fps(fps: Res<Fps>, mut spans: Query<&mut TextSpan, With<FpsText>>) {
for mut span in &mut spans {
**span = format!("{:.0}", fps.0);
}
}The TextUiWriter system parameter (in neo::ui::widget) edits a text block by span index: *writer.text(entity, 0) is the root's text, 1 the first span, and writer.color(entity, 1) its colour.
Text input#
TextInput (from neo::ui_widgets) with EditableText (from neo::text) makes an editable field: cursor, selection, keyboard editing, copy and paste, and IME for languages that need it. It needs input focus to receive keys; see Focus and navigation.
use neo::{text::{EditableText, TextCursorStyle}, ui_widgets::TextInput};
commands.spawn((
TextInput,
EditableText { allow_newlines: false, ..default() },
TextLayout::no_wrap(),
TextCursorStyle::default(),
Node { border: px(2).all(), width: px(240), ..default() },
BorderColor::all(Color::WHITE),
));Read the text with editable_text.value() and empty it with clear().
Examples#
| Example | What it shows |
|---|---|
text | Text with one and several sections, updated every frame. |
font_weights, font_variations | Weights and variable-font axes. |
system_fonts, generic_font_families | Installed fonts. Need --features system_font_discovery. |
letter_spacing, strikethrough_and_underline, text_background_colors | Spacing and decorations. |
text_wrap_debug | Every line-break mode. |
inline_image | Images inside a line of text. |
text_input, multiple_text_inputs, multiline_text_input | Text fields. |
ime_support | Typing with an input method editor. Needs --features system_font_discovery. |
Run one from the engine core's workspace: cargo run --example text.