From: Vadim Zeitlin <vadim@wxwidgets.org>
Date: Mon, 19 Oct 2009 08:59:25 +0000 (+0000)
Subject: Document wxRendererNative::DrawTitleBarBitmap() and use it properly.
X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/3427bc784ec7dae7d3830e8f2c61565587e8f791

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 3b445390a6..c1b744ce61 100644
--- 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 b5d3fd3b83..77d3d8e0e7 100644
--- 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 7ac3ecd5bd..7cb63278be 100644
--- 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;