Struct bevy::ui::Outline

pub struct Outline {
    pub width: Val,
    pub offset: Val,
    pub color: Color,
}

Expand description

The Outline component adds an outline outside the edge of a UI node. Outlines do not take up space in the layout.

To add an Outline to a ui node you can spawn a (NodeBundle, Outline) tuple bundle:

fn setup_ui(mut commands: Commands) {
    commands.spawn((
        NodeBundle {
            style: Style {
                width: Val::Px(100.),
                height: Val::Px(100.),
                ..Default::default()
            },
            background_color: BLUE.into(),
            ..Default::default()
        },
        Outline::new(Val::Px(10.), Val::ZERO, RED.into())
    ));
}

Outline components can also be added later to existing UI nodes:

fn outline_hovered_button_system(
    mut commands: Commands,
    mut node_query: Query<(Entity, &Interaction, Option<&mut Outline>), Changed<Interaction>>,
) {
    for (entity, interaction, mut maybe_outline) in node_query.iter_mut() {
        let outline_color =
            if matches!(*interaction, Interaction::Hovered) {
                Color::WHITE
            } else {
                Color::NONE
            };
        if let Some(mut outline) = maybe_outline {
            outline.color = outline_color;
        } else {
            commands.entity(entity).insert(Outline::new(Val::Px(10.), Val::ZERO, outline_color));
        }
    }
}

Inserting and removing an Outline component repeatedly will result in table moves, so it is generally preferable to set Outline::color to Color::NONE to hide an outline.

Fields§

§width: Val

The width of the outline.

Percentage Val values are resolved based on the width of the outlined Node.

§offset: Val

The amount of space between a node’s outline the edge of the node.

Percentage Val values are resolved based on the width of the outlined Node.

§color: Color

The color of the outline.

If you are frequently toggling outlines for a UI node on and off it is recommended to set Color::NONE to hide the outline. This avoids the table moves that would occur from the repeated insertion and removal of the Outline component.

Implementations§

§

impl Outline

pub const fn new(width: Val, offset: Val, color: Color) -> Outline

Create a new outline

Examples found in repository ?

examples/ui/ui_texture_atlas.rs (line 64)

fn setup(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut texture_atlases: ResMut<Assets<TextureAtlasLayout>>,
) {
    // Camera
    commands.spawn(Camera2dBundle::default());

    let text_style = TextStyle {
        font_size: 20.,
        ..default()
    };

    let texture_handle = asset_server.load("textures/rpg/chars/gabe/gabe-idle-run.png");
    let texture_atlas = TextureAtlasLayout::from_grid(UVec2::splat(24), 7, 1, None, None);
    let texture_atlas_handle = texture_atlases.add(texture_atlas);

    // root node
    commands
        .spawn(NodeBundle {
            style: Style {
                width: Val::Percent(100.0),
                height: Val::Percent(100.0),
                flex_direction: FlexDirection::Column,
                justify_content: JustifyContent::Center,
                align_items: AlignItems::Center,
                row_gap: Val::Px(text_style.font_size * 2.),
                ..default()
            },
            ..default()
        })
        .with_children(|parent| {
            parent.spawn((
                ImageBundle {
                    style: Style {
                        width: Val::Px(256.),
                        height: Val::Px(256.),
                        ..default()
                    },
                    image: UiImage::new(texture_handle),
                    ..default()
                },
                TextureAtlas::from(texture_atlas_handle),
                BackgroundColor(ANTIQUE_WHITE.into()),
                Outline::new(Val::Px(8.0), Val::ZERO, CRIMSON.into()),
            ));
            parent.spawn(TextBundle::from_sections([
                TextSection::new("press ".to_string(), text_style.clone()),
                TextSection::new(
                    "space".to_string(),
                    TextStyle {
                        color: YELLOW.into(),
                        ..text_style.clone()
                    },
                ),
                TextSection::new(" to advance frames".to_string(), text_style),
            ]));
        });
}

More examples

Hide additional examples

examples/animation/animation_graph.rs (line 315)

fn setup_node_rects(commands: &mut Commands) {
    for (node_rect, node_type) in NODE_RECTS.iter().zip(NODE_TYPES.iter()) {
        let node_string = match *node_type {
            NodeType::Clip(ref clip) => clip.text,
            NodeType::Blend(text) => text,
        };

        let text = commands
            .spawn(TextBundle {
                text: Text::from_section(
                    node_string,
                    TextStyle {
                        font_size: 16.0,
                        color: ANTIQUE_WHITE.into(),
                        ..default()
                    },
                )
                .with_justify(JustifyText::Center),
                ..default()
            })
            .id();

        let container = {
            let mut container = commands.spawn((
                NodeBundle {
                    style: Style {
                        position_type: PositionType::Absolute,
                        bottom: Val::Px(node_rect.bottom),
                        left: Val::Px(node_rect.left),
                        height: Val::Px(node_rect.height),
                        width: Val::Px(node_rect.width),
                        align_items: AlignItems::Center,
                        justify_items: JustifyItems::Center,
                        align_content: AlignContent::Center,
                        justify_content: JustifyContent::Center,
                        ..default()
                    },
                    border_color: WHITE.into(),
                    ..default()
                },
                Outline::new(Val::Px(1.), Val::ZERO, Color::WHITE),
            ));

            if let NodeType::Clip(ref clip) = node_type {
                container.insert((
                    Interaction::None,
                    RelativeCursorPosition::default(),
                    (*clip).clone(),
                ));
            }

            container.id()
        };

        // Create the background color.
        if let NodeType::Clip(_) = node_type {
            let background = commands
                .spawn(NodeBundle {
                    style: Style {
                        position_type: PositionType::Absolute,
                        top: Val::Px(0.),
                        left: Val::Px(0.),
                        height: Val::Px(node_rect.height),
                        width: Val::Px(node_rect.width),
                        ..default()
                    },
                    background_color: DARK_GREEN.into(),
                    ..default()
                })
                .id();

            commands.entity(container).add_child(background);
        }

        commands.entity(container).add_child(text);
    }
}