Add wxPreferencesPage::GetIcon() returning wxBitmapBundle

Allow returning a wxBitmapBundle rather than an individual wxBitmap.

Also make GetLargeIcon() non-pure even in wxOSX, as it now doesn't need
to be overridden if GetIcon() is -- but don't make GetIcon() pure
virtual neither to allow the existing code overriding GetLargeIcon() to
keep working.

This incidentally fixes the icons for the standard pages under macOS
broken by 388d322b68 (carry changes to toolbar over to prefs on osx,
2021-09-28), which replaced return statements with assignments,
resulting in the icon being set to the last value assigned to it instead
of the correct one -- this commit restores the previous control flow in
wxStockPreferencesPage::GetLargeIcon() (now called GetIcon()).

Closes #22187.

include/wx/preferences.h

@@ -50,14 +50,15 @@ public:
     // Name of the page, used e.g. for tabs
     virtual wxString GetName() const = 0;
 
-    // Return 32x32 icon used for the page. Currently only used on OS X, where
+    // Return the icon to use for the page. Currently only used on OS X, where
     // implementation is required; unused on other platforms. Because of this,
-    // the method is only pure virtual on platforms that use it.
-#ifdef wxHAS_PREF_EDITOR_ICONS
-    virtual wxBitmap GetLargeIcon() const = 0;
-#else
+    // these methods are not pure virtual but must be implemented if OS X is
+    // supported.
+    //
+    // New code should override GetIcon(), GetLargeIcon() only exists for
+    // backwards compatibility.
+    virtual wxBitmapBundle GetIcon() const { return GetLargeIcon(); }
     virtual wxBitmap GetLargeIcon() const { return wxBitmap(); }
-#endif
 
     // Create a window (usually a wxPanel) for this page. The caller takes
     // ownership of the returned window.
@@ -82,7 +83,7 @@ public:
 
     virtual wxString GetName() const wxOVERRIDE;
 #ifdef __WXOSX_COCOA__
-    virtual wxBitmap GetLargeIcon() const wxOVERRIDE;
+    virtual wxBitmapBundle GetIcon() const wxOVERRIDE;
 #endif
 
 private:

interface/wx/preferences.h

@@ -147,15 +147,21 @@ public:
     virtual wxString GetName() const = 0;
 
     /**
-        Return 32x32 icon used for the page on some platforms.
+        Return the icon to be used for the page on some platforms.
 
         Currently only used on macOS.
 
-        @note This method is only pure virtual on platforms that require it
-              (macOS). On other platforms, it has default implementation that
-              returns an invalid bitmap. The preprocessor symbol
+        @note This method is not pure virtual, but must be implemented on the
+              platforms that require it (macOS). The preprocessor symbol
               `wxHAS_PREF_EDITOR_ICONS` is defined if this method must be
               implemented.
+
+        @since 3.1.6
+     */
+    virtual wxBitmapBundle GetIcon() const = 0;
+
+    /**
+        @deprecated This function is deprecated, override GetIcon() instead.
      */
     virtual wxBitmap GetLargeIcon() const = 0;
 
@@ -187,7 +193,7 @@ public:
     Instead of reimplementing this behaviour yourself, you can inherit from
     wxStockPreferencesPage and get correct title and icon.
 
-    Notice that this class only implements GetName() and GetLargeIcon(), you
+    Notice that this class only implements GetName() and GetIcon(), you
     still have to provide the rest of wxPreferencesPage implementation.
 
     @library{wxcore}
@@ -215,5 +221,5 @@ public:
     /// Reimplemented to return suitable name for the page's kind.
     virtual wxString GetName() const;
     /// Reimplemented to return stock icon on macOS.
-    virtual wxBitmap GetLargeIcon() const;
+    virtual wxBitmapBundle GetIcon() const;
 };

samples/preferences/preferences.cpp

@@ -268,8 +268,8 @@ class PrefsPageTopics : public wxPreferencesPage
 {
 public:
     virtual wxString GetName() const wxOVERRIDE { return "Topics"; }
-    virtual wxBitmap GetLargeIcon() const wxOVERRIDE
-        { return wxArtProvider::GetBitmap(wxART_HELP, wxART_TOOLBAR); }
+    virtual wxBitmapBundle GetIcon() const wxOVERRIDE
+        { return wxArtProvider::GetBitmapBundle(wxART_HELP, wxART_TOOLBAR); }
     virtual wxWindow *CreateWindow(wxWindow *parent) wxOVERRIDE
         { return new PrefsPageTopicsPanel(parent); }
 };

src/osx/cocoa/preferences.mm

@@ -38,18 +38,17 @@
 #import <AppKit/NSWindow.h>
 
 
-wxBitmap wxStockPreferencesPage::GetLargeIcon() const
+wxBitmapBundle wxStockPreferencesPage::GetIcon() const
 {
-    wxBitmapBundle bundle;
 #if __MAC_OS_X_VERSION_MAX_ALLOWED >= MAC_OS_X_VERSION_10_16
     if ( WX_IS_MACOS_AVAILABLE(11, 0) )
     {
         switch ( m_kind )
         {
             case Kind_General:
-                bundle = wxOSXMakeBundleFromImage([NSImage imageWithSystemSymbolName:@"gearshape" accessibilityDescription:nil]);
+                return wxOSXMakeBundleFromImage([NSImage imageWithSystemSymbolName:@"gearshape" accessibilityDescription:nil]);
             case Kind_Advanced:
-                bundle = wxOSXMakeBundleFromImage([NSImage imageWithSystemSymbolName:@"gearshape.2" accessibilityDescription:nil]);
+                return wxOSXMakeBundleFromImage([NSImage imageWithSystemSymbolName:@"gearshape.2" accessibilityDescription:nil]);
         }
     }
 #endif
@@ -57,12 +56,12 @@ wxBitmap wxStockPreferencesPage::GetLargeIcon() const
     switch ( m_kind )
     {
         case Kind_General:
-            bundle = wxOSXMakeBundleFromImage([NSImage imageNamed:NSImageNamePreferencesGeneral]);
+            return wxOSXMakeBundleFromImage([NSImage imageNamed:NSImageNamePreferencesGeneral]);
         case Kind_Advanced:
-            bundle = wxOSXMakeBundleFromImage([NSImage imageNamed:NSImageNameAdvanced]);
+            return wxOSXMakeBundleFromImage([NSImage imageNamed:NSImageNameAdvanced]);
     }
 
-    return bundle.IsOk() ? bundle.GetBitmap(bundle.GetDefaultSize()) : wxNullBitmap;
+    return wxBitmapBundle();
 }
 
 
@@ -100,7 +99,7 @@ public:
                       "can't add more preferences pages after showing the window" );
 
         const wxString title = page->GetName();
-        wxBitmapBundle bmp(page->GetLargeIcon());
+        wxBitmapBundle bmp(page->GetIcon());
         wxASSERT_MSG( bmp.IsOk(), "OS X requires valid bitmap for preference page" );
 
         int toolId = wxIdManager::ReserveId();