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

diff --git a/include/wx/renderer.h b/include/wx/renderer.h
index 3b445390a6d3c1c3f98ab91763661b059aaa064e..c1b744ce61de0f0133190782af4f3927943898c6 100644 (file)
--- a/include/wx/renderer.h
+++ b/include/wx/renderer.h
@@ -83,7 +83,7 @@ enum wxTitleBarButton
 {
     wxTITLEBAR_BUTTON_CLOSE    = 0x01000000,
     wxTITLEBAR_BUTTON_MAXIMIZE = 0x02000000,
-    wxTITLEBAR_BUTTON_ICONIZE =  0x04000000,
+    wxTITLEBAR_BUTTON_ICONIZE  = 0x04000000,
     wxTITLEBAR_BUTTON_RESTORE  = 0x08000000,
     wxTITLEBAR_BUTTON_HELP     = 0x10000000
 };
@@ -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
-    // render standard title bar buttons under the other platforms, the best
-    // can be done is to use normal (only) images which wxArtProvider provides
-    // for wxART_HELP and wxART_CLOSE (but not any other title bar buttons)
+    // This is currently implemented only for MSW and OS X (for the close
+    // button only) because there is no way to render standard title bar
+    // buttons under the other platforms, the best can be done is to use normal
+    // (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,

diff --git a/interface/wx/renderer.h b/interface/wx/renderer.h
index b5d3fd3b83c17f6f61ab31d3082f2c3851dbf453..77d3d8e0e7611ec7d3cc572b4f732a93810f72ff 100644 (file)
--- a/interface/wx/renderer.h
+++ b/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.
     */

diff --git a/samples/render/render.cpp b/samples/render/render.cpp
index 7ac3ecd5bd8d113f644217316a3f79bd2561a5a0..7cb63278bee4df57e1d208d917367c498625b818 100644 (file)
--- a/samples/render/render.cpp
+++ b/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;