Struct DockArea 

pub struct DockArea { /* private fields */ }

Panels in tab groups, side by side or stacked, that the user rearranges: click a tab to show its panel, drag it along its bar to reorder, onto another group to join that group, or near a group’s edge to split the group, and drag the gaps between groups to resize them. Tabs that do not fit their bar shrink, and the shown tab always stays in view.

The panels are the dock’s children, added with DockArea::add_panel and removed with DockArea::remove_panel (a panel removed from the Ui directly is forgotten at the dock’s next event). The dock owns their styles, which place and hide them, so style what goes inside a panel rather than the panel itself, and leave the dock’s own padding at zero. A hidden panel keeps its state, scroll positions included. Give the dock DockArea::style.

The arrangement of panels added with keys (DockPanel::with_key) is saved with DockArea::layout and put back, in this run or the next, with DockArea::restore_layout; a DockLayout reads and writes itself as a line of text.

use densa_core::Size;
use densa_paragraph::TextSystem;
use densa_ui::Ui;
use densa_widgets::{DockArea, DockAt, DockPanel, DockSide, Label, Panel};

let mut ui = Ui::new(TextSystem::new()?);
ui.resize(Size::new(1200.0, 800.0));
let dock = ui.add(ui.root(), DockArea::new(), DockArea::style())?;
let quotes = DockArea::add_panel(&mut ui, dock, Panel::new(), "Quotes", DockAt::First)?;
let right = DockAt::Beside(quotes, DockSide::Right);
let chart = DockPanel::new("Chart").with_key("chart");
let chart = DockArea::add_panel(&mut ui, dock, Panel::new(), chart, right)?;
DockArea::add_panel(&mut ui, dock, Panel::new(), "Trades", DockAt::With(quotes))?;
ui.add(chart, Label::new("Panel content goes inside the panel"), Default::default())?;
ui.layout();
let area = ui.widget::<DockArea>(dock).unwrap();
assert_eq!(area.group_count(), 2);
assert!(!area.is_shown(quotes), "Trades, added last, is the tab shown");
assert_eq!(area.panel_with_key("chart"), Some(chart));

It reports ActionKind::Selected with the panel’s position in DockArea::panels (valid until a panel is removed) when a click shows a panel, and ActionKind::Changed when a drag moved a tab or a divider.

Implementations

impl DockArea

pub fn layout(&self) -> Option<DockLayout>

How the panels with keys are arranged now; None if none has a key. Panels without a key are left out, and a group with none of them with them.

pub fn restore_layout( ui: &mut Ui, dock: WidgetId, layout: &DockLayout, ) -> Result<(), UiError>

Arranges dock’s panels as layout says, matching them by key; see set_layout.

Errors

UiError::NoSuchWidget if dock is gone or is not a DockArea.

pub fn set_layout(&mut self, cx: &mut EventCx<'_>, layout: &DockLayout)

Arranges the panels as layout says (from an Ui::update on the dock): each key takes the next panel with that key. Keys without a panel are passed over (a group left empty goes, its space to its neighbor), and panels the layout does not name (without a key, or added since it was saved) join the first group, so none is lost. Ratios are kept from 0 to 1, and a group shows its first tab if its shown one is missing. Either part of a split keeps at least 1% of it, so no group vanishes. A drag in progress ends, and the keyboard stays with the group of the panel it was on.

impl DockArea

pub fn new() -> Self

An empty dock.

pub fn style() -> Style

A dock filling its parent’s free space, allowed to be smaller than its panels’ content and clipping them.

pub fn add_panel( ui: &mut Ui, dock: WidgetId, widget: impl Widget, panel: impl Into<DockPanel>, at: DockAt, ) -> Result<WidgetId, UiError>

Adds widget to dock as a panel (a title, or a DockPanel), placed at, and shows it.

Errors

UiError::NoSuchWidget if dock is gone or is not a DockArea, or if at names a widget that is not one of its panels; UiError::TooManyWidgets as for Ui::add.

pub fn remove_panel( ui: &mut Ui, dock: WidgetId, panel: WidgetId, ) -> Result<(), UiError>

Removes panel from dock and from the Ui; its group shows its next tab, and an emptied group’s space goes to its neighbor.

Errors

UiError::NoSuchWidget if dock is gone or is not a DockArea, or panel is not one of its panels.

pub fn show_panel( ui: &mut Ui, dock: WidgetId, panel: WidgetId, ) -> Result<(), UiError>

Shows panel in its group.

Errors

UiError::NoSuchWidget if dock is gone or is not a DockArea, or panel is not one of its panels.

pub fn panels(&self) -> impl ExactSizeIterator<Item = WidgetId> + '_

The panels’ widgets, in the order they were added (removals close the gaps).

pub fn is_shown(&self, panel: WidgetId) -> bool

Whether panel is the one its group shows.

pub fn show(&mut self, cx: &mut EventCx<'_>, panel: WidgetId) -> bool

Shows panel in its group (from an Ui::update on the dock); false if it is not one of the dock’s panels.

pub fn set_title( &mut self, cx: &mut EventCx<'_>, panel: WidgetId, title: impl Into<String>, ) -> bool

Changes panel’s tab title (from an Ui::update on the dock); false if it is not one of the dock’s panels.

pub fn title(&self, panel: WidgetId) -> Option<&str>

panel’s tab title.

pub fn key_of(&self, panel: WidgetId) -> Option<&str>

The key panel was added with.

pub fn panel_with_key(&self, key: &str) -> Option<WidgetId>

The first panel added with key.

pub fn group_count(&self) -> usize

How many groups the panels are in.

pub fn tabs_with(&self, panel: WidgetId) -> impl Iterator<Item = WidgetId> + '_

The panels sharing panel’s group, in tab order; none if it is not a panel.

pub fn tab_rect(&self, panel: WidgetId, dock: Rect, scale: f32) -> Option<Rect>

Where panel’s tab is drawn when the dock is at dock (its rectangle) and scale; None if it is not a panel or its tab is scrolled out of its bar.

Trait Implementations

impl Debug for DockArea

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for DockArea

fn default() -> Self

Returns the “default value” for a type.

impl Widget for DockArea

fn accepts_focus(&self) -> bool

Reachable by Tab, as a tab list; clicks on panels do not focus it (a tab press does).

fn accessibility(&self, cx: &PaintCx<'_>, node: &mut AccessNode)

Describes the widget to assistive technology: fills node, which starts as a Role::Group with the widget’s rectangle. Called only while assistive technology is listening; it may allocate.

fn access_action( &mut self, cx: &mut EventCx<'_>, request: &AccessRequest<'_>, ) -> Handled

Does what assistive technology asks (only actions the widget’s node lists are asked of it). Focus and scrolling into view are done for every widget; a request the widget does not handle goes on to its parent if it is a scroll.

fn focus_on_press(&self) -> bool

Whether a press on the widget, or on a widget inside it that takes no focus, focuses it (if it accepts focus). A container reachable by Tab, such as a dock’s tab list, says no, so clicks on its contents do not focus it; it can still ask for focus itself.

fn layout(&mut self, cx: &mut LayoutCx<'_>, size: Size)

Layout decided the widget’s size: re-wrap text or recompute anything that depends on it. Called after every layout pass that changed the size.

fn paint(&mut self, cx: &PaintCx<'_>, canvas: &mut Canvas<'_>)

Paints the widget below its children.

fn paint_over(&mut self, cx: &PaintCx<'_>, canvas: &mut Canvas<'_>)

Paints the widget over its children: scroll bars, focus rings, overlays.

fn event(&mut self, cx: &mut EventCx<'_>, event: &Event<'_>) -> Handled

Handles event. An event the widget does not handle goes on to its parent.

fn measure(&mut self, cx: &mut LayoutCx<'_>, constraints: Constraints) -> Size

The size the widget wants within constraints, for a widget without children (one with children is sized by its style and its children). Physical pixels.