Crate egui_tiles

source ·
Expand description

§egui hierarchial tile manager

Tiles that can be arranges in horizontal, vertical, and grid-layouts, or put in tabs. The tiles can be resized and re-arranged by drag-and-drop.

§Overview

The fundamental unit is the Tile which is either a Container or a Pane (a leaf). The Tiles are put into a Tree. Everything is generic over the type of panes, leaving up to the user what to store in the tree.

Each Tile is identified by a (random) TileId. The tiles are stored in Tiles.

The entire state is stored in a single Tree struct which consists of a Tiles and a root TileId.

The behavior and the look of the Tree is controlled by the Behavior trait. The user needs to implement this in order to specify the ui of each Pane and the tab name of panes (if there are tab tiles).

§Example

See Tree for how to construct a tree.

// This specifies how you want to represent your panes in memory.
// Implementing serde is optional, but will make the entire tree serializable.
#[derive(serde::Serialize, serde::Deserialize)]
enum Pane {
    Settings,
    Text(String),
}

fn tree_ui(ui: &mut egui::Ui, tree: &mut egui_tiles::Tree<Pane>, settings: &mut Settings) {
    let mut behavior = MyBehavior { settings };
    tree.ui(&mut behavior, ui);
}

struct MyBehavior<'a> {
    settings: &'a mut Settings
}

impl<'a> egui_tiles::Behavior<Pane> for MyBehavior<'a> {
    fn tab_title_for_pane(&mut self, pane: &Pane) -> egui::WidgetText {
        match pane {
            Pane::Settings => "Settings".into(),
            Pane::Text(text) => text.clone().into(),
        }
    }

    fn pane_ui(
        &mut self,
        ui: &mut egui::Ui,
        _tile_id: egui_tiles::TileId,
        pane: &mut Pane,
    ) -> egui_tiles::UiResponse {
        match pane {
            Pane::Settings => self.settings.ui(ui),
            Pane::Text(text) => {
                ui.text_edit_singleline(text);
            },
        }

        Default::default()
    }

    // you can override more methods to customize the behavior further
}

struct Settings {
    checked: bool,
}

impl Settings {
    fn ui(&mut self, ui: &mut egui::Ui) {
        ui.checkbox(&mut self.checked, "Checked");
    }
}

§Invisible tiles

Tiles can be made invisible with Tree::set_visible and Tiles::set_visible. Invisible tiles still retain their ordering in the container their in until they are made visible again.

§Shares

The relative sizes of linear layout (horizontal or vertical) and grid columns and rows are specified by shares. If the shares are 1,2,3 it means the first element gets 1/6 of the space, the second 2/6, and the third 3/6. The default share size is 1, and when resizing the shares are restributed so that the total shares are always approximately the same as the number of rows/columns. This makes it easy to add new rows/columns.

§Shortcomings

The implementation is recursive, so if your trees get too deep you will get a stack overflow.

§Future improvements

  • Easy per-tab close-buttons
  • Scrolling of tab-bar
  • Vertical tab bar

Structs§

  • Grid
    A grid of tiles.
  • Linear
    Horizontal or vertical container.
  • Shares
    How large of a share of space each child has, on a 1D axis.
  • SimplificationOptions
    What are the rules for simplifying the tree?
  • Tabs
    A container with tabs. Only one tab is open (active) at a time.
  • TileId
    An identifier for a Tile in the tree, be it a Container or a pane.
  • Tiles
    Contains all tile state, but no root.
  • Tree
    The top level type. Contains all persistent state, including layouts and sizes.

Enums§

Traits§