Add GetPanel(), GetPanelById() and GetPanelCount() to ribbon page

This provides parity with the ribbon bar's GetPage() set of functions,
and adds an easy way to find a panel and show/hide it.

Also, add example and discussion about showing/hiding panels on a
ribbon.

Closes #24319.

include/wx/ribbon/page.h

@@ -62,6 +62,10 @@ public:
 
     void HideIfExpanded();
 
+    wxRibbonPanel* GetPanel(int n);
+    wxRibbonPanel* GetPanelById(wxWindowID id);
+    size_t GetPanelCount();
+
 protected:
     virtual wxSize DoGetBestSize() const override;
     virtual wxBorder GetDefaultBorder() const override { return wxBORDER_NONE; }

interface/wx/ribbon/page.h

@@ -197,4 +197,29 @@ public:
         @return wxHORIZONTAL or wxVERTICAL (never wxBOTH).
     */
     wxOrientation GetMajorAxis() const;
+
+    /**
+        Get a panel by index.
+
+        @NULL will be returned if the given index is out of range.
+
+        @since 3.3.0
+    */
+    wxRibbonPanel* GetPanel(int n);
+
+    /**
+        Get a panel by window ID.
+
+        @NULL will be returned if no panel with the ID is found.
+
+        @since 3.3.0
+    */
+    wxRibbonPanel* GetPanelById(wxWindowID id);
+
+    /**
+        Get the number of panels in this page.
+
+        @since 3.3.0
+    */
+    size_t GetPanelCount() const;
 };

interface/wx/ribbon/panel.h

@@ -65,12 +65,28 @@ wxEventType wxEVT_RIBBONPANEL_EXTBUTTON_ACTIVATED;
     A panel adds a border and label to a group of controls, and can be
     minimised (either automatically to conserve space, or manually by the user).
 
-    Non ribbon controls can be placed on a panel using wxSizers to manage
+    Non-ribbon controls can be placed on a panel using wxSizers to manage
     layout. Panel size is governed by the sizer's minimum calculated size and
-    the parent wxRibbonPage's dimensions. For functional and aesthetic reasons
-    it is recommended that ribbon and non ribbon controls are not mixed in one
+    the parent wxRibbonPage's dimensions. For functional and aesthetic reasons,
+    it is recommended that ribbon and non-ribbon controls are not mixed in one
     panel.
 
+    A wxRibbonPage can show or hide its panels to offer a dynamic experience
+    for the end user. For example, a page can hide certain panels and show others
+    when the user interacts with other elements in the application. As an example
+    of toggling the visibility of a panel:
+
+    @code
+        wxRibbonPanel* panel = m_ribbon->GetPage(0)->GetPanelById(ID_EDITOR_PANEL);
+        if ( panel != nullptr )
+        {
+            panel->Show(!panel->IsShown());
+        }
+        // Update the UI
+        m_ribbon->Realise();
+        m_ribbon->Layout();
+    @endcode
+
     @see wxRibbonPage
 
     @beginStyleTable

src/ribbon/page.cpp

@@ -1102,6 +1102,56 @@ bool wxRibbonPage::CollapsePanels(wxOrientation direction, int minimum_amount)
     return minimum_amount <= 0;
 }
 
+wxRibbonPanel* wxRibbonPage::GetPanel(int n)
+{
+    int currentPanelIndex = 0;
+    for ( wxWindowList::compatibility_iterator node = GetChildren().GetFirst();
+          node;
+          node = node->GetNext() )
+    {
+        wxRibbonPanel* panel = wxDynamicCast(node->GetData(), wxRibbonPanel);
+        if ( panel != nullptr )
+        {
+            if ( n == currentPanelIndex )
+            {
+                return panel;
+            }
+            ++currentPanelIndex;
+        }
+    }
+    return nullptr;
+}
+
+wxRibbonPanel* wxRibbonPage::GetPanelById(wxWindowID id)
+{
+    for ( wxWindowList::compatibility_iterator node = GetChildren().GetFirst();
+          node;
+          node = node->GetNext() )
+    {
+        wxRibbonPanel* panel = wxDynamicCast(node->GetData(), wxRibbonPanel);
+        if ( panel != nullptr && panel->GetId() == id )
+        {
+            return panel;
+        }
+    }
+    return nullptr;
+}
+
+size_t wxRibbonPage::GetPanelCount()
+{
+    size_t panelCount = 0;
+    for ( wxWindowList::compatibility_iterator node = GetChildren().GetFirst();
+          node;
+          node = node->GetNext() )
+    {
+        if ( node->GetData()->IsKindOf(CLASSINFO(wxRibbonPanel)) )
+        {
+            ++panelCount;
+        }
+    }
+    return panelCount;
+}
+
 bool wxRibbonPage::DismissExpandedPanel()
 {
     for ( wxWindowList::compatibility_iterator node = GetChildren().GetFirst();