From 6470be11c3b7abafb50e7f3e86037afa1ccdb3ff Mon Sep 17 00:00:00 2001 From: Seth Hillbrand Date: Fri, 20 Aug 2021 08:49:43 -0700 Subject: [PATCH] Add clarifying comments to EE_RTREE ordering --- eeschema/sch_rtree.h | 13 +++++++++++++ eeschema/sch_screen.h | 8 ++++++++ 2 files changed, 21 insertions(+) diff --git a/eeschema/sch_rtree.h b/eeschema/sch_rtree.h index f18cfc74ef..98d915cf54 100644 --- a/eeschema/sch_rtree.h +++ b/eeschema/sch_rtree.h @@ -242,11 +242,24 @@ public: return EE_TYPE( m_tree, aType, aRect ); } + /** + * Returns a read/write iterator that points to the first + * element in the %EE_RTREE + * N.B. The iteration order of the RTree is not readily apparent and will change + * if/when you add or move items and the RTree is re-balanced. Any exposure of the + * RTree contents to the user MUST be sorted before being presented. See SCH_SEXPR_PLUGIN::Format + * or SCH_EDITOR_CONTROL::nextMatch for examples. + * @return Complete RTree of the screen's items + */ iterator begin() { return m_tree->begin(); } + /** + * Returns a read/write iterator that points to one past the last + * element in the %EE_RTREE + */ iterator end() { return m_tree->end(); diff --git a/eeschema/sch_screen.h b/eeschema/sch_screen.h index f4dc43d795..9e2a4fc617 100644 --- a/eeschema/sch_screen.h +++ b/eeschema/sch_screen.h @@ -99,6 +99,14 @@ public: SCHEMATIC* Schematic() const; + /** + * Gets the full RTree, usually for iterating. + * N.B. The iteration order of the RTree is not readily apparent and will change + * if/when you add or move items and the RTree is re-balanced. Any exposure of the + * RTree contents to the user MUST be sorted before being presented. See SCH_SEXPR_PLUGIN::Format + * or SCH_EDITOR_CONTROL::nextMatch for examples. + * @return Complete RTree of the screen's items + */ EE_RTREE& Items() { return m_rtree; } const EE_RTREE& Items() const { return m_rtree; }