synchronize GTK2 minimum version in docs

[wxWidgets.git] / include / wx / dcbuffer.h

diff --git a/include/wx/dcbuffer.h b/include/wx/dcbuffer.h
index 3ab1fe3e35ff4934871985bd2f3348966a17de76..40cb8179cd56863608d9e27a5d9f22556ddf1261 100644 (file)
--- a/include/wx/dcbuffer.h
+++ b/include/wx/dcbuffer.h
@@ -2,7 +2,7 @@
 // Name:        wx/dcbuffer.h
 // Purpose:     wxBufferedDC class
 // Author:      Ron Lee <ron@debian.org>
 // Name:        wx/dcbuffer.h
 // Purpose:     wxBufferedDC class
 // Author:      Ron Lee <ron@debian.org>

-// Modified by:
+// Modified by: Vadim Zeitlin (refactored, added bg preservation)

 // Created:     16/03/02
 // RCS-ID:      $Id$
 // Copyright:   (c) Ron Lee
 // Created:     16/03/02
 // RCS-ID:      $Id$
 // Copyright:   (c) Ron Lee


@@ -12,96 +12,238 @@
 #ifndef _WX_DCBUFFER_H_
 #define _WX_DCBUFFER_H_
 
 #ifndef _WX_DCBUFFER_H_
 #define _WX_DCBUFFER_H_
 

-#if defined(__GNUG__) && !defined(__APPLE__)
-#pragma interface "dcbuffer.h"
-#endif
-

 #include "wx/dcmemory.h"
 #include "wx/dcclient.h"
 #include "wx/dcmemory.h"
 #include "wx/dcclient.h"

+#include "wx/window.h"
+
+// Split platforms into two groups - those which have well-working
+// double-buffering by default, and those which do not.
+#if defined(__WXMAC__) || defined(__WXGTK20__) || defined(__WXDFB__)
+    #define wxALWAYS_NATIVE_DOUBLE_BUFFER       1
+#else
+    #define wxALWAYS_NATIVE_DOUBLE_BUFFER       0
+#endif

 
 
 
 

-// ==============================================================
-//   Double buffering helper.
-// --------------------------------------------------------------
+// ----------------------------------------------------------------------------
+// Double buffering helper.
+// ----------------------------------------------------------------------------

 
 

-class WXDLLIMPEXP_ADV wxBufferedDC : public wxMemoryDC
-{
-private:
+// Assumes the buffer bitmap covers the entire scrolled window,
+// and prepares the window DC accordingly
+#define wxBUFFER_VIRTUAL_AREA       0x01

 
 

-        // Without the existence of a wxNullDC, this must be
-        // a pointer, else it could probably be a reference.
+// Assumes the buffer bitmap only covers the client area;
+// does not prepare the window DC
+#define wxBUFFER_CLIENT_AREA        0x02

 
 

-    wxDC        *m_dc;
-    wxBitmap    m_buffer;
+// Set when not using specific buffer bitmap. Note that this
+// is private style and not returned by GetStyle.
+#define wxBUFFER_USES_SHARED_BUFFER 0x04

 
 

+class WXDLLIMPEXP_CORE wxBufferedDC : public wxMemoryDC
+{

 public:
 public:

-
-        // Default ctor, must subsequently call Init for
-        // two stage construction.
-
+    // Default ctor, must subsequently call Init for two stage construction.

     wxBufferedDC()
     wxBufferedDC()

-        : m_dc( 0 )
-    {}
-
-        // Construct a wxBufferedDC using a user supplied buffer.
-
-    wxBufferedDC( wxDC *dc, const wxBitmap &buffer );
-
-        // Construct a wxBufferedDC with an internal buffer of 'area'
-        // (where area is usually something like the size of the window
-        // being buffered)
+        : m_dc(NULL),
+          m_buffer(NULL),
+          m_style(0)
+    {
+    }
+
+    // Construct a wxBufferedDC using a user supplied buffer.
+    wxBufferedDC(wxDC *dc,
+                 wxBitmap& buffer = wxNullBitmap,
+                 int style = wxBUFFER_CLIENT_AREA)
+        : m_dc(NULL), m_buffer(NULL)
+    {
+        Init(dc, buffer, style);
+    }
+
+    // Construct a wxBufferedDC with an internal buffer of 'area'
+    // (where area is usually something like the size of the window
+    // being buffered)
+    wxBufferedDC(wxDC *dc, const wxSize& area, int style = wxBUFFER_CLIENT_AREA)
+        : m_dc(NULL), m_buffer(NULL)
+    {
+        Init(dc, area, style);
+    }
+
+    // The usually desired  action in the dtor is to blit the buffer.
+    virtual ~wxBufferedDC()
+    {
+        if ( m_dc )
+            UnMask();
+    }
+
+    // These reimplement the actions of the ctors for two stage creation
+    void Init(wxDC *dc,
+              wxBitmap& buffer = wxNullBitmap,
+              int style = wxBUFFER_CLIENT_AREA)
+    {
+        InitCommon(dc, style);
+
+        m_buffer = &buffer;
+
+        UseBuffer();
+    }
+
+    void Init(wxDC *dc, const wxSize &area, int style = wxBUFFER_CLIENT_AREA)
+    {
+        InitCommon(dc, style);
+
+        UseBuffer(area.x, area.y);
+    }
+
+    // Blits the buffer to the dc, and detaches the dc from the buffer (so it
+    // can be effectively used once only).
+    //
+    // Usually called in the dtor or by the dtor of derived classes if the
+    // BufferedDC must blit before the derived class (which may own the dc it's
+    // blitting to) is destroyed.
+    void UnMask();

 
 

-    wxBufferedDC( wxDC *dc, const wxSize &area );
+    // Set and get the style
+    void SetStyle(int style) { m_style = style; }
+    int GetStyle() const { return m_style & ~wxBUFFER_USES_SHARED_BUFFER; }

 
 

-    // default copy ctor ok.
+private:
+    // common part of Init()s
+    void InitCommon(wxDC *dc, int style)
+    {
+        wxASSERT_MSG( !m_dc, wxT("wxBufferedDC already initialised") );
+
+        m_dc = dc;
+        m_style = style;
+    }
+
+    // check that the bitmap is valid and use it
+    void UseBuffer(wxCoord w = -1, wxCoord h = -1);
+
+    // the underlying DC to which we copy everything drawn on this one in
+    // UnMask()
+    //
+    // NB: Without the existence of a wxNullDC, this must be a pointer, else it
+    //     could probably be a reference.
+    wxDC *m_dc;
+
+    // the buffer (selected in this DC), initially invalid
+    wxBitmap *m_buffer;
+
+    // the buffering style
+    int m_style;
+
+    wxSize m_area;
+    
+    DECLARE_DYNAMIC_CLASS(wxBufferedDC)
+    wxDECLARE_NO_COPY_CLASS(wxBufferedDC);
+};

 
 

-        // The usually desired  action in the dtor is to blit the buffer.

 
 

-    ~wxBufferedDC();
+// ----------------------------------------------------------------------------
+// Double buffered PaintDC.
+// ----------------------------------------------------------------------------

 
 

-        // These reimplement the actions of the ctors for
-        // two stage creation, but are not used by the ctors
-        // themselves to save a few cpu cycles.
+// Creates a double buffered wxPaintDC, optionally allowing the
+// user to specify their own buffer to use.
+class WXDLLIMPEXP_CORE wxBufferedPaintDC : public wxBufferedDC
+{
+public:
+    // If no bitmap is supplied by the user, a temporary one will be created.
+    wxBufferedPaintDC(wxWindow *window, wxBitmap& buffer, int style = wxBUFFER_CLIENT_AREA)
+        : m_paintdc(window)
+    {
+        // If we're buffering the virtual window, scale the paint DC as well
+        if (style & wxBUFFER_VIRTUAL_AREA)
+            window->PrepareDC( m_paintdc );
+
+        if( buffer.IsOk() )
+            Init(&m_paintdc, buffer, style);
+        else
+            Init(&m_paintdc, GetBufferedSize(window, style), style);
+    }
+
+    // If no bitmap is supplied by the user, a temporary one will be created.
+    wxBufferedPaintDC(wxWindow *window, int style = wxBUFFER_CLIENT_AREA)
+        : m_paintdc(window)
+    {
+        // If we're using the virtual window, scale the paint DC as well
+        if (style & wxBUFFER_VIRTUAL_AREA)
+            window->PrepareDC( m_paintdc );
+
+        Init(&m_paintdc, GetBufferedSize(window, style), style);
+    }

 
 

-    void Init( wxDC *dc, const wxBitmap &bitmap );
-    void Init( wxDC *dc, const wxSize &area );
+    // default copy ctor ok.

 
 

-        // Blits the buffer to the dc, and detaches the dc from
-        // the buffer.  Usually called in the dtor or by the dtor
-        // of derived classes if the BufferedDC must blit before
-        // the derived class (which may own the dc it's blitting
-        // to) is destroyed.
+    virtual ~wxBufferedPaintDC()
+    {
+        // We must UnMask here, else by the time the base class
+        // does it, the PaintDC will have already been destroyed.
+        UnMask();
+    }
+
+protected:
+    // return the size needed by the buffer: this depends on whether we're
+    // buffering just the currently shown part or the total (scrolled) window
+    static wxSize GetBufferedSize(wxWindow *window, int style)
+    {
+        return style & wxBUFFER_VIRTUAL_AREA ? window->GetVirtualSize()
+                                             : window->GetClientSize();
+    }

 
 

-    void UnMask();
+private:
+    wxPaintDC m_paintdc;

 
 

-    DECLARE_NO_COPY_CLASS(wxBufferedDC)
+    DECLARE_ABSTRACT_CLASS(wxBufferedPaintDC)
+    wxDECLARE_NO_COPY_CLASS(wxBufferedPaintDC);

 };
 
 
 };
 
 

-// ==============================================================
-//   Double buffered PaintDC.
-// --------------------------------------------------------------

 
 

-// Creates a double buffered wxPaintDC, optionally allowing the
-// user to specify their own buffer to use.
+//
+// wxAutoBufferedPaintDC is a wxPaintDC in toolkits which have double-
+// buffering by default. Otherwise it is a wxBufferedPaintDC. Thus,
+// you can only expect it work with a simple constructor that
+// accepts single wxWindow* argument.
+//
+#if wxALWAYS_NATIVE_DOUBLE_BUFFER
+    #define wxAutoBufferedPaintDCBase           wxPaintDC
+#else
+    #define wxAutoBufferedPaintDCBase           wxBufferedPaintDC
+#endif

 
 

-class WXDLLIMPEXP_ADV wxBufferedPaintDC : public wxBufferedDC
+class WXDLLIMPEXP_CORE wxAutoBufferedPaintDC : public wxAutoBufferedPaintDCBase

 {
 {

-private:
-
-    wxPaintDC    m_paintdc;
-

 public:
 
 public:
 

-    wxBufferedPaintDC( wxWindow *window, const wxBitmap &buffer = wxNullBitmap );
-
-    // default copy ctor ok.
+    wxAutoBufferedPaintDC(wxWindow* win)
+        : wxAutoBufferedPaintDCBase(win)
+    {
+        wxASSERT_MSG( win->GetBackgroundStyle() == wxBG_STYLE_PAINT,
+            "You need to call SetBackgroundStyle(wxBG_STYLE_PAINT) in ctor, "
+            "and also, if needed, paint the background in wxEVT_PAINT handler."
+        );
+    }

 
 

-    ~wxBufferedPaintDC();
+    virtual ~wxAutoBufferedPaintDC() { }

 
 

-    DECLARE_NO_COPY_CLASS(wxBufferedPaintDC)
+private:
+    wxDECLARE_NO_COPY_CLASS(wxAutoBufferedPaintDC);

 };
 
 
 };
 
 

-#endif  // _WX_DCBUFFER_H_

 
 

+// Check if the window is natively double buffered and will return a wxPaintDC
+// if it is, a wxBufferedPaintDC otherwise.  It is the caller's responsibility
+// to delete the wxDC pointer when finished with it.
+inline wxDC* wxAutoBufferedPaintDCFactory(wxWindow* window)
+{
+    if ( window->IsDoubleBuffered() )
+        return new wxPaintDC(window);
+    else
+        return new wxBufferedPaintDC(window);
+}
+
+#endif  // _WX_DCBUFFER_H_