Iterators overhaul (#196)

* Remove the deprecated `DockState::iter` * Rename `iter_nodes{,_mut}` to `iter_all_nodes{,_mut}` and deprecate `iter_nodes` * Add iterators over surfaces * Expand `iter_all_nodes{,_mut}` to include containing surface indices * Deprecated `iter_main_surface_nodes{,_mut}` * Add iterators for all tabs and containing surface and node indices * Update changelog * Add node and tab iterators to `Surface` * Add tab iterators to `Node` * Update changelog * Update changelog
Adanos020 · Oct 31, 2023 · 73bd81b · 73bd81b
1 parent 10bac37
commit 73bd81b
Show file tree

Hide file tree

Showing 6 changed files with 196 additions and 66 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,23 @@
 # egui_dock changelog
 
+## 0.9.0 - undetermined
+
+### Added
+- `DockArea::surfaces_count`
+- `DockArea::iter_surfaces[_mut]`
+- `DockArea::iter_all_tabs[_mut]`
+- `DockArea::iter_all_nodes[_mut]`
+- `Node::iter_tabs[_mut]`
+- `Surface::iter_nodes[_mut]`
+- `Surface::iter_all_tabs[_mut]`
+
+### Breaking changes
+- Removed the deprecated `DockState::iter`
+
+### Deprecated
+- `DockState::iter_nodes` – use `iter_all_nodes` instead.
+- `DockState::iter_main_surface_nodes[_mut]` – use `dock_state.main_surface().iter()` (and corresponding `mut` versions) instead.
+
 ## 0.8.1 - 2023-10-04
 
 ### Fixed

diff --git a/src/dock_state/mod.rs b/src/dock_state/mod.rs
@@ -77,16 +77,16 @@ impl<Tab> DockState<Tab> {
         self
     }
 
-    /// Get a mutable borrow to the tree at the main surface.
-    pub fn main_surface_mut(&mut self) -> &mut Tree<Tab> {
-        &mut self[SurfaceIndex::main()]
-    }
-
     /// Get an immutable borrow to the tree at the main surface.
     pub fn main_surface(&self) -> &Tree<Tab> {
         &self[SurfaceIndex::main()]
     }
 
+    /// Get a mutable borrow to the tree at the main surface.
+    pub fn main_surface_mut(&mut self) -> &mut Tree<Tab> {
+        &mut self[SurfaceIndex::main()]
+    }
+
     /// Get the [`WindowState`] which corresponds to a [`SurfaceIndex`].
     ///
     /// Returns `None` if the surface is [`Empty`](Surface::Empty), [`Main`](Surface::Main), or doesn't exist.
@@ -186,7 +186,7 @@ impl<Tab> DockState<Tab> {
         &mut self,
         (surface_index, node_index, tab_index): (SurfaceIndex, NodeIndex, TabIndex),
     ) {
-        if let Some(Node::Leaf { active, .. }) = self[surface_index].tree.get_mut(node_index.0) {
+        if let Some(Node::Leaf { active, .. }) = self[surface_index].nodes.get_mut(node_index.0) {
             *active = tab_index;
         }
     }
@@ -368,37 +368,91 @@ impl<Tab> DockState<Tab> {
         self[SurfaceIndex::main()].push_to_first_leaf(tab);
     }
 
-    /// Returns an `Iterator` of the underlying collection of nodes on the **main surface**.
-    #[deprecated = "Use `iter_main_surface_nodes` or `iter_nodes` instead"]
-    pub fn iter(&self) -> std::slice::Iter<'_, Node<Tab>> {
-        self.iter_main_surface_nodes()
+    /// Returns the current number of surfaces.
+    pub fn surfaces_count(&self) -> usize {
+        self.surfaces.len()
+    }
+
+    /// Returns an [`Iterator`] over all surfaces.
+    pub fn iter_surfaces(&self) -> impl Iterator<Item = &Surface<Tab>> {
+        self.surfaces.iter()
+    }
+
+    /// Returns a mutable [`Iterator`] over all surfaces.
+    pub fn iter_surfaces_mut(&mut self) -> impl Iterator<Item = &mut Surface<Tab>> {
+        self.surfaces.iter_mut()
+    }
+
+    /// Returns an [`Iterator`] of **all** underlying nodes in the dock state,
+    /// and the indices of containing surfaces.
+    pub fn iter_all_nodes(&self) -> impl Iterator<Item = (SurfaceIndex, &Node<Tab>)> {
+        self.iter_surfaces()
+            .enumerate()
+            .flat_map(|(surface_index, surface)| {
+                surface
+                    .iter_nodes()
+                    .map(move |node| (SurfaceIndex(surface_index), node))
+            })
+    }
+
+    /// Returns a mutable [`Iterator`] of **all** underlying nodes in the dock state,
+    /// and the indices of containing surfaces.
+    pub fn iter_all_nodes_mut(&mut self) -> impl Iterator<Item = (SurfaceIndex, &mut Node<Tab>)> {
+        self.iter_surfaces_mut()
+            .enumerate()
+            .flat_map(|(surface_index, surface)| {
+                surface
+                    .iter_nodes_mut()
+                    .map(move |node| (SurfaceIndex(surface_index), node))
+            })
+    }
+
+    /// Returns an [`Iterator`] of **all** tabs in the dock state,
+    /// and the indices of containing surfaces and nodes.
+    pub fn iter_all_tabs(&self) -> impl Iterator<Item = ((SurfaceIndex, NodeIndex), &Tab)> {
+        self.iter_surfaces()
+            .enumerate()
+            .flat_map(|(surface_index, surface)| {
+                surface
+                    .iter_all_tabs()
+                    .map(move |(node_index, tab)| ((SurfaceIndex(surface_index), node_index), tab))
+            })
     }
 
-    /// Returns an `Iterator` of the underlying collection of nodes on the main surface.
-    pub fn iter_main_surface_nodes(&self) -> std::slice::Iter<'_, Node<Tab>> {
+    /// Returns a mutable [`Iterator`] of **all** tabs in the dock state,
+    /// and the indices of containing surfaces and nodes.
+    pub fn iter_all_tabs_mut(
+        &mut self,
+    ) -> impl Iterator<Item = ((SurfaceIndex, NodeIndex), &mut Tab)> {
+        self.iter_surfaces_mut()
+            .enumerate()
+            .flat_map(|(surface_index, surface)| {
+                surface
+                    .iter_all_tabs_mut()
+                    .map(move |(node_index, tab)| ((SurfaceIndex(surface_index), node_index), tab))
+            })
+    }
+
+    /// Returns an [`Iterator`] of the underlying collection of nodes on the main surface.
+    #[deprecated = "Use `dock_state.main_surface().iter()` instead"]
+    pub fn iter_main_surface_nodes(&self) -> impl Iterator<Item = &Node<Tab>> {
         self[SurfaceIndex::main()].iter()
     }
 
-    /// Returns a mutable `Iterator` of the underlying collection of nodes on the main surface.
-    pub fn iter_main_surface_nodes_mut(&mut self) -> std::slice::IterMut<'_, Node<Tab>> {
+    /// Returns a mutable [`Iterator`] of the underlying collection of nodes on the main surface.
+    #[deprecated = "Use `dock_state.main_surface_mut().iter_mut()` instead"]
+    pub fn iter_main_surface_nodes_mut(&mut self) -> impl Iterator<Item = &mut Node<Tab>> {
         self[SurfaceIndex::main()].iter_mut()
     }
 
-    /// Returns an `Iterator` of **all** underlying nodes in the dock state and all subsequent trees.
+    /// Returns an [`Iterator`] of **all** underlying nodes in the dock state and all subsequent trees.
+    #[deprecated = "Use `iter_all_nodes` instead"]
     pub fn iter_nodes(&self) -> impl Iterator<Item = &Node<Tab>> {
         self.surfaces
             .iter()
-            .filter_map(|tree| tree.node_tree())
+            .filter_map(|surface| surface.node_tree())
             .flat_map(|nodes| nodes.iter())
     }
-
-    /// Returns a mutable `Iterator` of **all** underlying nodes in the dock state and all subsequent trees.
-    pub fn iter_nodes_mut(&mut self) -> impl Iterator<Item = &mut Node<Tab>> {
-        self.surfaces
-            .iter_mut()
-            .filter_map(|tree| tree.node_tree_mut())
-            .flat_map(|nodes| nodes.iter_mut())
-    }
 }
 
 impl<Tab> DockState<Tab>

diff --git a/src/dock_state/surface.rs b/src/dock_state/surface.rs
@@ -1,4 +1,4 @@
-use crate::{Tree, WindowState};
+use crate::{Node, NodeIndex, Tree, WindowState};
 
 /// A [`Surface`] is the highest level component in a [`DockState`](crate::DockState). [`Surface`]s represent an area
 /// in which nodes are placed. Typically, you're only using one surface, which is the main surface. However, if you drag
@@ -22,21 +22,57 @@ impl<Tab> Surface<Tab> {
         matches!(self, Self::Empty)
     }
 
-    /// Get mutable access to the node tree of this surface.
-    pub fn node_tree_mut(&mut self) -> Option<&mut Tree<Tab>> {
+    /// Get access to the node tree of this surface.
+    pub fn node_tree(&self) -> Option<&Tree<Tab>> {
         match self {
             Surface::Empty => None,
             Surface::Main(tree) => Some(tree),
             Surface::Window(tree, _) => Some(tree),
         }
     }
 
-    /// Get access to the node tree of this surface.
-    pub fn node_tree(&self) -> Option<&Tree<Tab>> {
+    /// Get mutable access to the node tree of this surface.
+    pub fn node_tree_mut(&mut self) -> Option<&mut Tree<Tab>> {
         match self {
             Surface::Empty => None,
             Surface::Main(tree) => Some(tree),
             Surface::Window(tree, _) => Some(tree),
         }
     }
+
+    /// Returns an [`Iterator`] of nodes in this surface's tree.
+    ///
+    /// If the surface is [`Empty`](Self::Empty), then the returned [`Iterator`] will be empty.
+    pub fn iter_nodes(&self) -> impl Iterator<Item = &Node<Tab>> {
+        match self.node_tree() {
+            Some(tree) => tree.iter(),
+            None => core::slice::Iter::default(),
+        }
+    }
+
+    /// Returns a mutable [`Iterator`] of nodes in this surface's tree.
+    ///
+    /// If the surface is [`Empty`](Self::Empty), then the returned [`Iterator`] will be empty.
+    pub fn iter_nodes_mut(&mut self) -> impl Iterator<Item = &mut Node<Tab>> {
+        match self.node_tree_mut() {
+            Some(tree) => tree.iter_mut(),
+            None => core::slice::IterMut::default(),
+        }
+    }
+
+    /// Returns an [`Iterator`] of **all** tabs in this surface's tree,
+    /// and indices of containing nodes.
+    pub fn iter_all_tabs(&self) -> impl Iterator<Item = (NodeIndex, &Tab)> {
+        self.iter_nodes()
+            .enumerate()
+            .flat_map(|(index, node)| node.iter_tabs().map(move |tab| (NodeIndex(index), tab)))
+    }
+
+    /// Returns a mutable [`Iterator`] of **all** tabs in this surface's tree,
+    /// and indices of containing nodes.
+    pub fn iter_all_tabs_mut(&mut self) -> impl Iterator<Item = (NodeIndex, &mut Tab)> {
+        self.iter_nodes_mut()
+            .enumerate()
+            .flat_map(|(index, node)| node.iter_tabs_mut().map(move |tab| (NodeIndex(index), tab)))
+    }
 }