document a bit about treeview selections and freeze/thaw

Change-Id: I38bb84d26f99b845895ba397fa50e534111a114f
Reviewed-on: https://gerrit.libreoffice.org/c/core/+/90104
Tested-by: Jenkins
Reviewed-by: Caolán McNamara <caolanm@redhat.com>

3 files changed, 26 insertions, 22 deletions

diff --git a/include/vcl/weld.hxx b/include/vcl/weld.hxx
index 220fabbd16fa..ee86bf5d37f4 100644
--- a/include/vcl/weld.hxx
+++ b/include/vcl/weld.hxx
@@ -837,6 +837,7 @@ public:
 
     //by index
     virtual int get_selected_index() const = 0;
+    //Don't select when frozen, select after thaw. Note selection doesn't survive a freeze.
     virtual void select(int pos) = 0;
     virtual void unselect(int pos) = 0;
     virtual void remove(int pos) = 0;
@@ -863,6 +864,7 @@ public:
 
     //by text
     virtual int find_text(const OUString& rText) const = 0;
+    //Don't select when frozen, select after thaw. Note selection doesn't survive a freeze.
     void select_text(const OUString& rText) { select(find_text(rText)); }
     void remove_text(const OUString& rText) { remove(find_text(rText)); }
     std::vector<OUString> get_selected_rows_text() const
@@ -878,6 +880,7 @@ public:
     //by id
     virtual OUString get_id(int pos) const = 0;
     virtual int find_id(const OUString& rId) const = 0;
+    //Don't select when frozen, select after thaw. Note selection doesn't survive a freeze.
     void select_id(const OUString& rId) { select(find_id(rId)); }
     void remove_id(const OUString& rText) { remove(find_id(rText)); }
 
@@ -920,6 +923,7 @@ public:
     // returns the number of direct children rIter has
     virtual int iter_n_children(const TreeIter& rIter) const = 0;
     virtual void remove(const TreeIter& rIter) = 0;
+    //Don't select when frozen, select after thaw. Note selection doesn't survive a freeze.
     virtual void select(const TreeIter& rIter) = 0;
     virtual void unselect(const TreeIter& rIter) = 0;
     virtual bool get_row_expanded(const TreeIter& rIter) const = 0;
@@ -1003,7 +1007,7 @@ public:
 
     void connect_drag_begin(const Link<bool&, bool>& rLink) { m_aDragBeginHdl = rLink; }
 
-    //all of them
+    //all of them. Don't select when frozen, select after thaw. Note selection doesn't survive a freeze.
     void select_all() { unselect(-1); }
     void unselect_all() { select(-1); }
 
@@ -1108,7 +1112,7 @@ public:
 
     virtual OUString get_selected_text() const = 0;
 
-    //by index
+    //by index. Don't select when frozen, select after thaw. Note selection doesn't survive a freeze.
     virtual void select(int pos) = 0;
     virtual void unselect(int pos) = 0;
 
@@ -1124,7 +1128,7 @@ public:
     // call func on each selected element until func returns true or we run out of elements
     virtual void selected_foreach(const std::function<bool(TreeIter&)>& func) = 0;
 
-    //all of them
+    //all of them. Don't select when frozen, select after thaw. Note selection doesn't survive a freeze.
     void select_all() { unselect(-1); }
     void unselect_all() { select(-1); }
 
diff --git a/vcl/source/app/salvtables.cxx b/vcl/source/app/salvtables.cxx
index c9c2a4cbea4e..0c73fdbba7ca 100644
--- a/vcl/source/app/salvtables.cxx
+++ b/vcl/source/app/salvtables.cxx
@@ -3623,7 +3623,7 @@ public:
 
     virtual void select(int pos) override
     {
-        assert(m_xTreeView->IsUpdateMode() && "don't select when frozen");
+        assert(m_xTreeView->IsUpdateMode() && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         if (pos == -1 || (pos == 0 && n_children() == 0))
             m_xTreeView->SelectAll(false);
@@ -3659,7 +3659,7 @@ public:
 
     virtual void scroll_to_row(int pos) override
     {
-        assert(m_xTreeView->IsUpdateMode() && "don't select when frozen");
+        assert(m_xTreeView->IsUpdateMode() && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         SvTreeListEntry* pEntry = m_xTreeView->GetEntry(nullptr, pos);
         m_xTreeView->MakeVisible(pEntry);
@@ -3674,7 +3674,7 @@ public:
 
     virtual void unselect(int pos) override
     {
-        assert(m_xTreeView->IsUpdateMode() && "don't select when frozen");
+        assert(m_xTreeView->IsUpdateMode() && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         if (pos == -1)
             m_xTreeView->SelectAll(true);
@@ -4157,7 +4157,7 @@ public:
 
     virtual void select(const weld::TreeIter& rIter) override
     {
-        assert(m_xTreeView->IsUpdateMode() && "don't select when frozen");
+        assert(m_xTreeView->IsUpdateMode() && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         const SalInstanceTreeIter& rVclIter = static_cast<const SalInstanceTreeIter&>(rIter);
         m_xTreeView->Select(rVclIter.iter, true);
@@ -4166,7 +4166,7 @@ public:
 
     virtual void scroll_to_row(const weld::TreeIter& rIter) override
     {
-        assert(m_xTreeView->IsUpdateMode() && "don't select when frozen");
+        assert(m_xTreeView->IsUpdateMode() && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         const SalInstanceTreeIter& rVclIter = static_cast<const SalInstanceTreeIter&>(rIter);
         m_xTreeView->MakeVisible(rVclIter.iter);
@@ -4845,7 +4845,7 @@ public:
 
     virtual void select(int pos) override
     {
-        assert(m_xIconView->IsUpdateMode() && "don't select when frozen");
+        assert(m_xIconView->IsUpdateMode() && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         if (pos == -1 || (pos == 0 && n_children() == 0))
             m_xIconView->SelectAll(false);
@@ -4860,7 +4860,7 @@ public:
 
     virtual void unselect(int pos) override
     {
-        assert(m_xIconView->IsUpdateMode() && "don't select when frozen");
+        assert(m_xIconView->IsUpdateMode() && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         if (pos == -1)
             m_xIconView->SelectAll(true);
@@ -4919,7 +4919,7 @@ public:
 
     virtual void scroll_to_item(const weld::TreeIter& rIter) override
     {
-        assert(m_xIconView->IsUpdateMode() && "don't select when frozen");
+        assert(m_xIconView->IsUpdateMode() && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         const SalInstanceTreeIter& rVclIter = static_cast<const SalInstanceTreeIter&>(rIter);
         m_xIconView->MakeVisible(rVclIter.iter);
diff --git a/vcl/unx/gtk3/gtk3gtkinst.cxx b/vcl/unx/gtk3/gtk3gtkinst.cxx
index a79a3b6fa654..cb0fb884affe 100644
--- a/vcl/unx/gtk3/gtk3gtkinst.cxx
+++ b/vcl/unx/gtk3/gtk3gtkinst.cxx
@@ -9430,7 +9430,7 @@ public:
     virtual void make_sorted() override
     {
         // thaw wants to restore sort state of freeze
-        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen");
+        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         m_xSorter.reset(new comphelper::string::NaturalStringSorter(
                             ::comphelper::getProcessComponentContext(),
                             Application::GetSettings().GetUILanguageTag().getLocale()));
@@ -9540,7 +9540,7 @@ public:
 
     virtual void select(int pos) override
     {
-        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen");
+        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         if (pos == -1 || (pos == 0 && n_children() == 0))
         {
@@ -9568,7 +9568,7 @@ public:
 
     virtual void scroll_to_row(int pos) override
     {
-        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen");
+        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         GtkTreePath* path = gtk_tree_path_new_from_indices(pos, -1);
         gtk_tree_view_scroll_to_cell(m_pTreeView, path, nullptr, false, 0, 0);
@@ -9585,7 +9585,7 @@ public:
 
     virtual void unselect(int pos) override
     {
-        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen");
+        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         if (pos == -1 || (pos == 0 && n_children() == 0))
         {
@@ -10105,7 +10105,7 @@ public:
             rGtkIter.iter = tmp;
             return true;
         }
-        // Move up level(s) until we find the level where the next sibling exists.
+        // Move up level(s) until we find the level where the next node exists.
         while (gtk_tree_model_iter_parent(pModel, &tmp, &iter))
         {
             iter = tmp;
@@ -10174,7 +10174,7 @@ public:
 
     virtual void select(const weld::TreeIter& rIter) override
     {
-        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen");
+        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         const GtkInstanceTreeIter& rGtkIter = static_cast<const GtkInstanceTreeIter&>(rIter);
         gtk_tree_selection_select_iter(gtk_tree_view_get_selection(m_pTreeView), const_cast<GtkTreeIter*>(&rGtkIter.iter));
@@ -10183,7 +10183,7 @@ public:
 
     virtual void scroll_to_row(const weld::TreeIter& rIter) override
     {
-        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen");
+        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         const GtkInstanceTreeIter& rGtkIter = static_cast<const GtkInstanceTreeIter&>(rIter);
         GtkTreeModel *pModel = GTK_TREE_MODEL(m_pTreeStore);
@@ -10195,7 +10195,7 @@ public:
 
     virtual void unselect(const weld::TreeIter& rIter) override
     {
-        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen");
+        assert(gtk_tree_view_get_model(m_pTreeView) && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         const GtkInstanceTreeIter& rGtkIter = static_cast<const GtkInstanceTreeIter&>(rIter);
         gtk_tree_selection_unselect_iter(gtk_tree_view_get_selection(m_pTreeView), const_cast<GtkTreeIter*>(&rGtkIter.iter));
@@ -10961,7 +10961,7 @@ public:
 
     virtual void select(int pos) override
     {
-        assert(gtk_icon_view_get_model(m_pIconView) && "don't select when frozen");
+        assert(gtk_icon_view_get_model(m_pIconView) && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         if (pos == -1 || (pos == 0 && n_children() == 0))
         {
@@ -10979,7 +10979,7 @@ public:
 
     virtual void unselect(int pos) override
     {
-        assert(gtk_icon_view_get_model(m_pIconView) && "don't select when frozen");
+        assert(gtk_icon_view_get_model(m_pIconView) && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         if (pos == -1 || (pos == 0 && n_children() == 0))
         {
@@ -11033,7 +11033,7 @@ public:
 
     virtual void scroll_to_item(const weld::TreeIter& rIter) override
     {
-        assert(gtk_icon_view_get_model(m_pIconView) && "don't select when frozen");
+        assert(gtk_icon_view_get_model(m_pIconView) && "don't select when frozen, select after thaw. Note selection doesn't survive a freeze");
         disable_notify_events();
         const GtkInstanceTreeIter& rGtkIter = static_cast<const GtkInstanceTreeIter&>(rIter);
         GtkTreeModel *pModel = GTK_TREE_MODEL(m_pTreeStore);