Add labels to improve wxRibbonGallery items accessibility

Gallery items have just a bitmap, an ID and the application's client
data, so there is nothing a screen reader can announce for them and they
are read as "list item 3 of 39", which is useless.

Add Append(bitmap, id, label) and Set/GetItemLabel() and use the label
as the accessible name of the item. The label is not drawn, as the items
of a gallery are bitmaps by design, it only exists to be announced. It
could also be used for tooltips later, which the items don't have
either.

The ribbon sample already knows the names of the colours it puts in its
galleries, so it passes them as the labels now, which also makes them a
useful test case.

Closes #27100.

include/wx/ribbon/gallery.h

@@ -46,11 +46,15 @@ public:
     unsigned int GetCount() const;
     wxRibbonGalleryItem* GetItem(unsigned int n);
     wxRibbonGalleryItem* Append(const wxBitmapBundle& bitmap, int id);
+    wxRibbonGalleryItem* Append(const wxBitmapBundle& bitmap, int id, const wxString& label);
     wxRibbonGalleryItem* Append(const wxBitmapBundle& bitmap, int id, void* clientData);
     wxRibbonGalleryItem* Append(const wxBitmapBundle& bitmap, int id, wxClientData* clientData);
 
     void SetItemClientObject(wxRibbonGalleryItem* item, wxClientData* data);
     wxClientData* GetItemClientObject(const wxRibbonGalleryItem* item) const;
+    void SetItemLabel(wxRibbonGalleryItem* item, const wxString& label);
+    wxString GetItemLabel(const wxRibbonGalleryItem* item) const;
+
     void SetItemClientData(wxRibbonGalleryItem* item, void* data);
     void* GetItemClientData(const wxRibbonGalleryItem* item) const;
 

interface/wx/ribbon/gallery.h

@@ -124,6 +124,26 @@ public:
     */
     wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id);
 
+    /**
+        Add an item to the gallery with a label.
+
+        The label is not shown in the gallery itself, but it is used as the
+        accessible name of the item, allowing the screen readers to announce it,
+        so it is recommended to specify it for all the items.
+
+        @param bitmap
+            The bitmap to display for the item. Note that all items must
+            have equally sized bitmaps.
+        @param id
+            ID number to associate with the item. Not currently used for
+            anything important.
+        @param label
+            The label of the item.
+
+        @since 3.3.4
+    */
+    wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id, const wxString& label);
+
     /**
         Add an item to the gallery (with simple client data).
         @param bitmap
@@ -153,6 +173,22 @@ public:
     */
     wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id, wxClientData* clientData);
 
+    /**
+        Set the label of a gallery item.
+
+        See Append() for the description of the label.
+
+        @since 3.3.4
+    */
+    void SetItemLabel(wxRibbonGalleryItem* item, const wxString& label);
+
+    /**
+        Return the label of a gallery item.
+
+        @since 3.3.4
+    */
+    wxString GetItemLabel(const wxRibbonGalleryItem* item) const;
+
     /**
         Set the client object associated with a gallery item.
     */

samples/ribbon/ribbondemo.cpp

@@ -1276,7 +1276,7 @@ wxRibbonGalleryItem* MyFrame::AddColourToGallery(wxRibbonGallery *gallery,
             (iHeight - size.GetHeight()) / 2);
         dc.SelectObjectAsSource(wxNullBitmap);
 
-        item = gallery->Append(bitmap, wxID_ANY);
+        item = gallery->Append(bitmap, wxID_ANY, colour);
         gallery->SetItemClientObject(item, new ColourClientData(colour, c));
     }
     return item;

src/ribbon/gallery.cpp

@@ -50,6 +50,9 @@ public:
     bool IsVisible() const {return m_is_visible;}
     const wxRect& GetPosition() const {return m_position;}
 
+    void SetLabel(const wxString& label) {m_label = label;}
+    const wxString& GetLabel() const {return m_label;}
+
     void SetClientObject(wxClientData *data) {m_client_data.SetClientObject(data);}
     wxClientData *GetClientObject() const {return m_client_data.GetClientObject();}
     void SetClientData(void *data) {m_client_data.SetClientData(data);}
@@ -57,6 +60,7 @@ public:
 
 protected:
     wxBitmapBundle m_bitmap;
+    wxString m_label;
     wxClientDataContainer m_client_data;
     wxRect m_position;
     int m_id = 0;
@@ -801,6 +805,14 @@ wxRibbonGalleryItem* wxRibbonGallery::Append(const wxBitmapBundle& bitmap, int i
     return item;
 }
 
+wxRibbonGalleryItem* wxRibbonGallery::Append(const wxBitmapBundle& bitmap, int id,
+                                             const wxString& label)
+{
+    wxRibbonGalleryItem *item = Append(bitmap, id);
+    item->SetLabel(label);
+    return item;
+}
+
 wxRibbonGalleryItem* wxRibbonGallery::Append(const wxBitmapBundle& bitmap, int id,
                                              void* clientData)
 {
@@ -817,6 +829,21 @@ wxRibbonGalleryItem* wxRibbonGallery::Append(const wxBitmapBundle& bitmap, int i
     return item;
 }
 
+void wxRibbonGallery::SetItemLabel(wxRibbonGalleryItem* item,
+                                   const wxString& label)
+{
+    wxCHECK_RET( item, "invalid gallery item" );
+
+    item->SetLabel(label);
+}
+
+wxString wxRibbonGallery::GetItemLabel(const wxRibbonGalleryItem* item) const
+{
+    wxCHECK_MSG( item, wxString(), "invalid gallery item" );
+
+    return item->GetLabel();
+}
+
 void wxRibbonGallery::Clear()
 {
     size_t item_count = m_items.Count();
@@ -1240,7 +1267,17 @@ public:
         wxCHECK(gallery, wxACC_FAIL);
 
         if ( childId >= 0 && static_cast<unsigned>(childId) <= gallery->GetCount() )
-            return wxACC_NOT_IMPLEMENTED;
+        {
+            wxRibbonGalleryItem* item = gallery->GetItem(childId - 1);
+            wxCHECK(item, wxACC_FAIL);
+
+            const wxString label = gallery->GetItemLabel(item);
+            if ( label.empty() )
+                return wxACC_NOT_IMPLEMENTED;
+
+            *name = label;
+            return wxACC_OK;
+        }
 
         *name = _("More");
         return wxACC_OK;