Skip to main content

zaxis/components/
split_pane.rs

1//! Single-pass multi-panel layout. See `docs/content/docs/components/split-pane.mdx`.
2mod access;
3#[doc(hidden)]
4pub mod allocation;
5mod interaction;
6mod paint;
7mod show;
8mod style;
9
10use super::Ui;
11use crate::{Id, Layout, Rect, Vec2};
12pub(crate) use interaction::{SplitInput, SplitState};
13use std::hash::Hash;
14pub use style::{SplitHandle, SplitHandleStyle, SplitStyle, SplitSurface};
15
16/// Initial preference, or an authoritative preference when passed to `size`.
17/// Pixels stay fixed across viewport changes; Fraction and Weight are flexible.
18#[derive(Clone, Copy, Debug, PartialEq)]
19pub enum SplitSize {
20    Pixels(f32),
21    Fraction(f32),
22    Weight(f32),
23}
24impl SplitSize {
25    /// Lengths and fractions below zero or not finite become zero; a bad weight becomes one.
26    #[track_caller]
27    pub(crate) fn normalized(self) -> Self {
28        match self {
29            Self::Pixels(n) => Self::Pixels(allocation::dimension(n)),
30            Self::Fraction(n) => Self::Fraction(allocation::dimension(n)),
31            Self::Weight(n) => Self::Weight(super::sanitize::weight("SplitSize::Weight", n)),
32        }
33    }
34}
35
36/// Stable panel identity and sizing policy. Sizes include border and padding.
37#[derive(Clone, Debug)]
38pub struct SplitPanel {
39    pub id: Id,
40    pub initial: SplitSize,
41    pub controlled: Option<SplitSize>,
42    pub minimum: f32,
43    pub maximum: Option<f32>,
44    /// Enables the boundary following this panel; the final panel has no boundary.
45    pub resizable_after: bool,
46    pub surface: Option<SplitSurface>,
47    pub handle: Option<SplitHandleStyle>,
48}
49impl SplitPanel {
50    pub fn new(source: impl Hash) -> Self {
51        Self {
52            id: Id::new(source),
53            initial: SplitSize::Weight(1.0),
54            controlled: None,
55            minimum: 0.0,
56            maximum: None,
57            resizable_after: true,
58            surface: None,
59            handle: None,
60        }
61    }
62    #[track_caller]
63    pub fn default_size(mut self, size: SplitSize) -> Self {
64        self.initial = size.normalized();
65        self
66    }
67    /// Applied every pass. Resize proposes sizes in the output; the application
68    /// must feed those back to accept them. External changes rebase a live drag.
69    #[track_caller]
70    pub fn size(mut self, size: SplitSize) -> Self {
71        self.controlled = Some(size.normalized());
72        self
73    }
74    #[track_caller]
75    pub fn min_size(mut self, size: f32) -> Self {
76        self.minimum = allocation::dimension(size);
77        self
78    }
79    #[track_caller]
80    pub fn max_size(mut self, size: f32) -> Self {
81        self.maximum = Some(allocation::dimension(size));
82        self
83    }
84    pub fn resizable_after(mut self, enabled: bool) -> Self {
85        self.resizable_after = enabled;
86        self
87    }
88    pub fn surface(mut self, surface: SplitSurface) -> Self {
89        self.surface = Some(surface);
90        self
91    }
92    pub fn handle(mut self, handle: SplitHandleStyle) -> Self {
93        self.handle = Some(handle);
94        self
95    }
96}
97
98pub struct SplitPane {
99    id: Id,
100    axis: Layout,
101    panels: Vec<SplitPanel>,
102    style: Option<SplitStyle>,
103    gap: Option<f32>,
104    handle: Option<SplitHandleStyle>,
105    size: Option<Vec2>,
106    resizable: bool,
107    reset: bool,
108    double_click_reset: bool,
109}
110impl SplitPane {
111    pub fn horizontal(source: impl Hash) -> Self {
112        Self::new(source, Layout::Horizontal)
113    }
114    pub fn vertical(source: impl Hash) -> Self {
115        Self::new(source, Layout::Vertical)
116    }
117    pub fn new(source: impl Hash, axis: Layout) -> Self {
118        Self {
119            id: Id::new(source),
120            axis,
121            panels: Vec::new(),
122            style: None,
123            gap: None,
124            handle: None,
125            size: None,
126            resizable: true,
127            reset: false,
128            double_click_reset: false,
129        }
130    }
131    pub fn panels(mut self, panels: impl IntoIterator<Item = SplitPanel>) -> Self {
132        self.panels.extend(panels);
133        self
134    }
135    pub fn panel(mut self, panel: SplitPanel) -> Self {
136        self.panels.push(panel);
137        self
138    }
139    pub fn style(mut self, style: SplitStyle) -> Self {
140        self.style = Some(style);
141        self
142    }
143    pub fn gap(mut self, gap: f32) -> Self {
144        self.gap = Some(allocation::dimension(gap));
145        self
146    }
147    pub fn handle(mut self, handle: SplitHandleStyle) -> Self {
148        self.handle = Some(handle);
149        self
150    }
151    /// Defaults to the remaining Ui rectangle; explicit size is capped to it.
152    pub fn size(mut self, size: Vec2) -> Self {
153        allocation::dimension(size.x);
154        allocation::dimension(size.y);
155        self.size = Some(size);
156        self
157    }
158    /// Disables only boundary interaction; child controls remain enabled.
159    pub fn resizable(mut self, enabled: bool) -> Self {
160        self.resizable = enabled;
161        self
162    }
163    /// Level-triggered reset of retained preferences. Controlled values still win.
164    pub fn reset(mut self, reset: bool) -> Self {
165        self.reset = reset;
166        self
167    }
168    pub fn double_click_reset(mut self, enabled: bool) -> Self {
169        self.double_click_reset = enabled;
170        self
171    }
172}
173
174#[derive(Clone, Debug)]
175pub struct SplitPanelOutput {
176    pub id: Id,
177    pub bounds: Rect,
178    pub content_bounds: Rect,
179    pub size: f32,
180}
181#[derive(Clone, Debug)]
182pub struct SplitBoundaryOutput {
183    pub id: Id,
184    pub before: Id,
185    pub after: Id,
186    pub bounds: Rect,
187    pub enabled: bool,
188    pub hovered: bool,
189    pub focused: bool,
190    pub resize_started: bool,
191    pub changed: bool,
192    pub resize_ended: bool,
193    pub cancelled: bool,
194}
195pub struct SplitOutput<R> {
196    pub inner: R,
197    pub rect: Rect,
198    pub panels: Vec<SplitPanelOutput>,
199    pub boundaries: Vec<SplitBoundaryOutput>,
200    pub resize_started: bool,
201    /// Includes viewport, topology, constraints, external sizes and resets.
202    pub changed: bool,
203    pub resize_ended: bool,
204}
205
206/// Build content by stable panel Id, in any order, at most once per panel.
207pub struct SplitUi<'a, 'ctx> {
208    ui: &'a mut Ui<'ctx>,
209    id: Id,
210    specs: &'a [SplitPanel],
211    outputs: &'a [SplitPanelOutput],
212    style: SplitStyle,
213    built: std::collections::HashSet<Id>,
214    handles: access::Handles,
215}
216impl Ui<'_> {
217    pub fn split_horizontal<R>(
218        &mut self,
219        source: impl Hash,
220        panels: impl IntoIterator<Item = SplitPanel>,
221        build: impl FnOnce(&mut SplitUi<'_, '_>) -> R,
222    ) -> SplitOutput<R> {
223        SplitPane::horizontal(source)
224            .panels(panels)
225            .show(self, build)
226    }
227    pub fn split_vertical<R>(
228        &mut self,
229        source: impl Hash,
230        panels: impl IntoIterator<Item = SplitPanel>,
231        build: impl FnOnce(&mut SplitUi<'_, '_>) -> R,
232    ) -> SplitOutput<R> {
233        SplitPane::vertical(source).panels(panels).show(self, build)
234    }
235}