Document wxRendererNative::DrawTitleBarBitmap() and use it properly.

Comment and document the (non obvious) requirement for the PNG image handler
to be enabled when using this function under OS X. In fact, document the
entire function itself which was forgotten previously.

Do enable PNG image handler when using DrawTitleBarBitmap() in the sample.

Closes #11345.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@62455 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

include/wx/renderer.h

@@ -304,10 +304,13 @@ public:
 #ifdef wxHAS_DRAW_TITLE_BAR_BITMAP
     // Draw one of the standard title bar buttons
     //
-    // This is currently implemented only for MSW because there is no way to
+    // This is currently implemented only for MSW and OS X (for the close
-    // render standard title bar buttons under the other platforms, the best
+    // button only) because there is no way to render standard title bar
-    // can be done is to use normal (only) images which wxArtProvider provides
+    // buttons under the other platforms, the best can be done is to use normal
-    // for wxART_HELP and wxART_CLOSE (but not any other title bar buttons)
+    // (only) images which wxArtProvider provides for wxART_HELP and
+    // wxART_CLOSE (but not any other title bar buttons)
+    //
+    // NB: make sure PNG handler is enabled if using this function under OS X
     virtual void DrawTitleBarBitmap(wxWindow *win,
                                     wxDC& dc,
                                     const wxRect& rect,

interface/wx/renderer.h

@@ -56,6 +56,18 @@ enum
     wxCONTROL_UNDETERMINED = wxCONTROL_CHECKABLE
 };
 
+/**
+    Title bar buttons supported by wxRendererNative::DrawTitleBarBitmap().
+ */
+enum wxTitleBarButton
+{
+    wxTITLEBAR_BUTTON_CLOSE    = 0x01000000,
+    wxTITLEBAR_BUTTON_MAXIMIZE = 0x02000000,
+    wxTITLEBAR_BUTTON_ICONIZE  = 0x04000000,
+    wxTITLEBAR_BUTTON_RESTORE  = 0x08000000,
+    wxTITLEBAR_BUTTON_HELP     = 0x10000000
+};
+
 /**
     @struct wxSplitterRenderParams
 
@@ -426,6 +438,30 @@ public:
     */
     virtual void DrawRadioBitmap(wxWindow* win, wxDC& dc, const wxRect& rect, int flags = 0) = 0;
 
+    /**
+        Draw a title bar button in the given state.
+
+        This function is currently only available under MSW and OS X (and only
+        for wxTITLEBAR_BUTTON_CLOSE under the latter), its best replacement for
+        the other platforms is to use wxArtProvider to retrieve the bitmaps for
+        @c wxART_HELP and @c wxART_CLOSE (but not any other title bar buttons
+        and not for any state but normal, i.e. not pressed and not current one).
+
+        The presence of this function is indicated by @c
+        wxHAS_DRAW_TITLE_BAR_BITMAP symbol being defined.
+
+        Also notice that PNG handler must be enabled using wxImage::AddHandler()
+        to use this function under OS X currently as the bitmaps are embedded
+        in the library itself in PNG format.
+
+        @since 2.9.1
+     */
+    virtual void DrawTitleBarBitmap(wxWindow *win,
+                                    wxDC& dc,
+                                    const wxRect& rect,
+                                    wxTitleBarButton button,
+                                    int flags = 0) = 0;
+
     /**
         Return the currently used renderer.
     */

samples/render/render.cpp

@@ -35,6 +35,7 @@
     #include "wx/log.h"
     #include "wx/msgdlg.h"
     #include "wx/icon.h"
+    #include "wx/image.h"
 #endif
 
 #include "wx/apptrait.h"
@@ -297,6 +298,13 @@ bool MyApp::OnInit()
     if ( !wxApp::OnInit() )
         return false;
 
+#ifdef __WXOSX__
+    // currently the images used by DrawTitleBarBitmap() are hard coded as PNG
+    // images inside the library itself so we need to enable PNG support to use
+    // this function
+    wxImage::AddHandler(new wxPNGHandler);
+#endif // OS X
+
     // create the main application window
     new MyFrame;