include/wx/dcbuffer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/dcbuffer.h
   3 // Purpose:     wxBufferedDC class
   4 // Author:      Ron Lee <ron@debian.org>
   5 // Modified by: Vadim Zeitlin (refactored, added bg preservation)
   6 // Created:     16/03/02
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) Ron Lee
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_DCBUFFER_H_
  13 #define _WX_DCBUFFER_H_
  14
  15 #include "wx/dcmemory.h"
  16 #include "wx/dcclient.h"
  17 #include "wx/window.h"
  18
  19 // Split platforms into two groups - those which have well-working
  20 // double-buffering by default, and those which do not.
  21 #if defined(__WXMAC__) || defined(__WXGTK20__) || defined(__WXDFB__)
  22     #define wxALWAYS_NATIVE_DOUBLE_BUFFER       1
  23 #else
  24     #define wxALWAYS_NATIVE_DOUBLE_BUFFER       0
  25 #endif
  26
  27
  28 // ----------------------------------------------------------------------------
  29 // Double buffering helper.
  30 // ----------------------------------------------------------------------------
  31
  32 // Assumes the buffer bitmap covers the entire scrolled window,
  33 // and prepares the window DC accordingly
  34 #define wxBUFFER_VIRTUAL_AREA       0x01
  35
  36 // Assumes the buffer bitmap only covers the client area;
  37 // does not prepare the window DC
  38 #define wxBUFFER_CLIENT_AREA        0x02
  39
  40 class WXDLLEXPORT wxBufferedDC : public wxMemoryDC
  41 {
  42 public:
  43     // Default ctor, must subsequently call Init for two stage construction.
  44     wxBufferedDC()
  45         : m_dc(NULL),
  46           m_style(0)
  47     {
  48     }
  49
  50     // Construct a wxBufferedDC using a user supplied buffer.
  51     wxBufferedDC(wxDC *dc,
  52                  const wxBitmap& buffer = wxNullBitmap,
  53                  int style = wxBUFFER_CLIENT_AREA)
  54         : m_dc(NULL)
  55     {
  56         Init(dc, buffer, style);
  57     }
  58
  59     // Construct a wxBufferedDC with an internal buffer of 'area'
  60     // (where area is usually something like the size of the window
  61     // being buffered)
  62     wxBufferedDC(wxDC *dc, const wxSize& area, int style = wxBUFFER_CLIENT_AREA)
  63         : m_dc(NULL)
  64     {
  65         Init(dc, area, style);
  66     }
  67
  68     // The usually desired  action in the dtor is to blit the buffer.
  69     virtual ~wxBufferedDC()
  70     {
  71         if ( m_dc )
  72             UnMask();
  73     }
  74
  75     // These reimplement the actions of the ctors for two stage creation
  76     void Init(wxDC *dc,
  77               const wxBitmap& buffer = wxNullBitmap,
  78               int style = wxBUFFER_CLIENT_AREA)
  79     {
  80         InitCommon(dc, style);
  81
  82         m_buffer = buffer;
  83
  84         UseBuffer();
  85     }
  86
  87     void Init(wxDC *dc, const wxSize &area, int style = wxBUFFER_CLIENT_AREA)
  88     {
  89         InitCommon(dc, style);
  90
  91         UseBuffer(area.x, area.y);
  92     }
  93
  94     // Blits the buffer to the dc, and detaches the dc from the buffer (so it
  95     // can be effectively used once only).
  96     //
  97     // Usually called in the dtor or by the dtor of derived classes if the
  98     // BufferedDC must blit before the derived class (which may own the dc it's
  99     // blitting to) is destroyed.
 100     void UnMask()
 101     {
 102         wxCHECK_RET( m_dc, _T("no underlying wxDC?") );
 103         wxASSERT_MSG( m_buffer.IsOk(), _T("invalid backing store") );
 104
 105         wxCoord x = 0,
 106                 y = 0;
 107
 108         if ( m_style & wxBUFFER_CLIENT_AREA )
 109             GetDeviceOrigin(&x, &y);
 110
 111         m_dc->Blit(0, 0, m_buffer.GetWidth(), m_buffer.GetHeight(),
 112                    this, -x, -y );
 113         m_dc = NULL;
 114     }
 115
 116     // Set and get the style
 117     void SetStyle(int style) { m_style = style; }
 118     int GetStyle() const { return m_style; }
 119
 120 private:
 121     // common part of Init()s
 122     void InitCommon(wxDC *dc, int style)
 123     {
 124         wxASSERT_MSG( !m_dc, _T("wxBufferedDC already initialised") );
 125
 126         m_dc = dc;
 127         m_style = style;
 128
 129         // inherit the same layout direction as the original DC
 130         if (dc && dc->IsOk())
 131             SetLayoutDirection(dc->GetLayoutDirection());
 132     }
 133
 134     // check that the bitmap is valid and use it
 135     void UseBuffer(wxCoord w = -1, wxCoord h = -1);
 136
 137     // the underlying DC to which we copy everything drawn on this one in
 138     // UnMask()
 139     //
 140     // NB: Without the existence of a wxNullDC, this must be a pointer, else it
 141     //     could probably be a reference.
 142     wxDC *m_dc;
 143
 144     // the buffer (selected in this DC), initially invalid
 145     wxBitmap m_buffer;
 146
 147     // the buffering style
 148     int m_style;
 149
 150     DECLARE_DYNAMIC_CLASS(wxBufferedDC)
 151     DECLARE_NO_COPY_CLASS(wxBufferedDC)
 152 };
 153
 154
 155 // ----------------------------------------------------------------------------
 156 // Double buffered PaintDC.
 157 // ----------------------------------------------------------------------------
 158
 159 // Creates a double buffered wxPaintDC, optionally allowing the
 160 // user to specify their own buffer to use.
 161 class WXDLLEXPORT wxBufferedPaintDC : public wxBufferedDC
 162 {
 163 public:
 164     // If no bitmap is supplied by the user, a temporary one will be created.
 165     wxBufferedPaintDC(wxWindow *window, const wxBitmap& buffer, int style = wxBUFFER_CLIENT_AREA)
 166         : m_paintdc(window)
 167     {
 168         // If we're buffering the virtual window, scale the paint DC as well
 169         if (style & wxBUFFER_VIRTUAL_AREA)
 170             window->PrepareDC( m_paintdc );
 171
 172         if( buffer.IsOk() )
 173             Init(&m_paintdc, buffer, style);
 174         else
 175             Init(&m_paintdc, window->GetClientSize(), style);
 176     }
 177
 178     // If no bitmap is supplied by the user, a temporary one will be created.
 179     wxBufferedPaintDC(wxWindow *window, int style = wxBUFFER_CLIENT_AREA)
 180         : m_paintdc(window)
 181     {
 182         // If we're using the virtual window, scale the paint DC as well
 183         if (style & wxBUFFER_VIRTUAL_AREA)
 184             window->PrepareDC( m_paintdc );
 185
 186         Init(&m_paintdc, window->GetClientSize(), style);
 187     }
 188
 189     // default copy ctor ok.
 190
 191     virtual ~wxBufferedPaintDC()
 192     {
 193         // We must UnMask here, else by the time the base class
 194         // does it, the PaintDC will have already been destroyed.
 195         UnMask();
 196     }
 197
 198 private:
 199     wxPaintDC m_paintdc;
 200
 201     DECLARE_ABSTRACT_CLASS(wxBufferedPaintDC)
 202     DECLARE_NO_COPY_CLASS(wxBufferedPaintDC)
 203 };
 204
 205
 206
 207 //
 208 // wxAutoBufferedPaintDC is a wxPaintDC in toolkits which have double-
 209 // buffering by default. Otherwise it is a wxBufferedPaintDC. Thus,
 210 // you can only expect it work with a simple constructor that
 211 // accepts single wxWindow* argument.
 212 //
 213 #if wxALWAYS_NATIVE_DOUBLE_BUFFER
 214     #define wxAutoBufferedPaintDCBase           wxPaintDC
 215 #else
 216     #define wxAutoBufferedPaintDCBase           wxBufferedPaintDC
 217 #endif
 218
 219
 220 #ifdef __WXDEBUG__
 221
 222 class wxAutoBufferedPaintDC : public wxAutoBufferedPaintDCBase
 223 {
 224 public:
 225
 226     wxAutoBufferedPaintDC(wxWindow* win)
 227         : wxAutoBufferedPaintDCBase(win)
 228     {
 229         TestWinStyle(win);
 230     }
 231
 232     virtual ~wxAutoBufferedPaintDC() { }
 233
 234 private:
 235
 236     void TestWinStyle(wxWindow* win)
 237     {
 238         // Help the user to get the double-buffering working properly.
 239         wxASSERT_MSG( win->GetBackgroundStyle() == wxBG_STYLE_CUSTOM,
 240                       wxT("In constructor, you need to call SetBackgroundStyle(wxBG_STYLE_CUSTOM), ")
 241                       wxT("and also, if needed, paint the background manually in the paint event handler."));
 242     }
 243
 244     DECLARE_NO_COPY_CLASS(wxAutoBufferedPaintDC)
 245 };
 246
 247 #else // !__WXDEBUG__
 248
 249 // In release builds, just use typedef
 250 typedef wxAutoBufferedPaintDCBase wxAutoBufferedPaintDC;
 251
 252 #endif
 253
 254
 255 // Check if the window is natively double buffered and will return a wxPaintDC
 256 // if it is, a wxBufferedPaintDC otherwise.  It is the caller's responsibility
 257 // to delete the wxDC pointer when finished with it.
 258 inline wxDC* wxAutoBufferedPaintDCFactory(wxWindow* window)
 259 {
 260     if ( window->IsDoubleBuffered() )
 261         return new wxPaintDC(window);
 262     else
 263         return new wxBufferedPaintDC(window);
 264 }
 265
 266 #endif  // _WX_DCBUFFER_H_