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() : m_dc( 0 ), m_buffer(NULL), m_style(0)
  45     {
  46     }
  47
  48     // Construct a wxBufferedDC using a user supplied buffer.
  49     wxBufferedDC(wxDC *dc,
  50                  const wxBitmap &buffer = wxNullBitmap,
  51                  int style = wxBUFFER_CLIENT_AREA)
  52         : m_dc( dc ),
  53           m_buffer( &buffer ),
  54           m_style(style)
  55     {
  56         UseBuffer();
  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( dc ),
  64           m_buffer(NULL),
  65           m_style(style)
  66
  67     {
  68         UseBuffer(area.x, area.y);
  69     }
  70
  71     // default copy ctor ok.
  72
  73     // The usually desired  action in the dtor is to blit the buffer.
  74     virtual ~wxBufferedDC()
  75     {
  76         if ( m_dc ) UnMask();
  77     }
  78
  79     // These reimplement the actions of the ctors for two stage creation, but
  80     // are not used by the ctors themselves to save a few cpu cycles.
  81     void Init(wxDC *dc,
  82               const wxBitmap &buffer=wxNullBitmap,
  83               int style = wxBUFFER_CLIENT_AREA)
  84     {
  85         wxASSERT_MSG( m_dc == 0 && m_buffer == NULL,
  86                       _T("wxBufferedDC already initialised") );
  87         m_dc = dc;
  88         m_buffer = &buffer;
  89         m_style = style;
  90         UseBuffer();
  91     }
  92
  93     void Init(wxDC *dc, const wxSize &area, int style = wxBUFFER_CLIENT_AREA)
  94     {
  95         wxASSERT_MSG( m_dc == 0 && m_buffer == NULL,
  96                       _T("wxBufferedDC already initialised") );
  97         m_dc = dc;
  98         m_buffer = NULL;
  99         m_style = style;
 100         UseBuffer(area.x, area.y);
 101     }
 102
 103     // Blits the buffer to the dc, and detaches the dc from the buffer (so it
 104     // can be effectively used once only).
 105     //
 106     // Usually called in the dtor or by the dtor of derived classes if the
 107     // BufferedDC must blit before the derived class (which may own the dc it's
 108     // blitting to) is destroyed.
 109     void UnMask()
 110     {
 111         wxASSERT_MSG( m_dc != 0,
 112                       _T("No underlying DC associated with wxBufferedDC (anymore)") );
 113
 114         wxCoord x=0, y=0;
 115
 116         if (m_style & wxBUFFER_CLIENT_AREA)
 117             GetDeviceOrigin(&x, &y);
 118
 119         m_dc->Blit( 0, 0,
 120                     m_buffer->GetWidth(), m_buffer->GetHeight(), this,
 121                     -x, -y );
 122         m_dc = NULL;
 123     }
 124
 125     // Set and get the style
 126     void SetStyle(int style) { m_style = style; }
 127     int GetStyle() const { return m_style; }
 128
 129 private:
 130     // check that the bitmap is valid and use it
 131     void UseBuffer(wxCoord w = -1, wxCoord h = -1);
 132
 133     // the underlying DC to which we copy everything drawn on this one in
 134     // UnMask()
 135     //
 136     // NB: Without the existence of a wxNullDC, this must be a pointer, else it
 137     //     could probably be a reference.
 138     wxDC *m_dc;
 139
 140     // the buffer (selected in this DC)
 141     const wxBitmap *m_buffer;
 142
 143     // the buffering style
 144     int m_style;
 145
 146     DECLARE_DYNAMIC_CLASS(wxBufferedDC)
 147     DECLARE_NO_COPY_CLASS(wxBufferedDC)
 148 };
 149
 150
 151 // ----------------------------------------------------------------------------
 152 // Double buffered PaintDC.
 153 // ----------------------------------------------------------------------------
 154
 155 // Creates a double buffered wxPaintDC, optionally allowing the
 156 // user to specify their own buffer to use.
 157 class WXDLLEXPORT wxBufferedPaintDC : public wxBufferedDC
 158 {
 159 public:
 160     // If no bitmap is supplied by the user, a temporary one will be created.
 161     wxBufferedPaintDC(wxWindow *window, const wxBitmap& buffer, int style = wxBUFFER_CLIENT_AREA)
 162         : m_paintdc(window)
 163     {
 164         // If we're buffering the virtual window, scale the paint DC as well
 165         if (style & wxBUFFER_VIRTUAL_AREA)
 166             window->PrepareDC( m_paintdc );
 167
 168         if( buffer != wxNullBitmap )
 169             Init(&m_paintdc, buffer, style);
 170         else
 171             Init(&m_paintdc, window->GetClientSize(), style);
 172     }
 173
 174     // If no bitmap is supplied by the user, a temporary one will be created.
 175     wxBufferedPaintDC(wxWindow *window, int style = wxBUFFER_CLIENT_AREA)
 176         : m_paintdc(window)
 177     {
 178         // If we're using the virtual window, scale the paint DC as well
 179         if (style & wxBUFFER_VIRTUAL_AREA)
 180             window->PrepareDC( m_paintdc );
 181
 182         Init(&m_paintdc, window->GetClientSize(), style);
 183     }
 184
 185     // default copy ctor ok.
 186
 187     virtual ~wxBufferedPaintDC()
 188     {
 189         // We must UnMask here, else by the time the base class
 190         // does it, the PaintDC will have already been destroyed.
 191         UnMask();
 192     }
 193
 194 private:
 195     wxPaintDC m_paintdc;
 196
 197     DECLARE_ABSTRACT_CLASS(wxBufferedPaintDC)
 198     DECLARE_NO_COPY_CLASS(wxBufferedPaintDC)
 199 };
 200
 201
 202
 203 //
 204 // wxAutoBufferedPaintDC is a wxPaintDC in toolkits which have double-
 205 // buffering by default. Otherwise it is a wxBufferedPaintDC. Thus,
 206 // you can only expect it work with a simple constructor that
 207 // accepts single wxWindow* argument.
 208 //
 209 #if wxALWAYS_NATIVE_DOUBLE_BUFFER
 210     #define wxAutoBufferedPaintDCBase           wxPaintDC
 211 #else
 212     #define wxAutoBufferedPaintDCBase           wxBufferedPaintDC
 213 #endif
 214
 215
 216 #ifdef __WXDEBUG__
 217
 218 class wxAutoBufferedPaintDC : public wxAutoBufferedPaintDCBase
 219 {
 220 public:
 221
 222     wxAutoBufferedPaintDC(wxWindow* win)
 223         : wxAutoBufferedPaintDCBase(win)
 224     {
 225         TestWinStyle(win);
 226     }
 227
 228     virtual ~wxAutoBufferedPaintDC() { }
 229
 230 private:
 231
 232     void TestWinStyle(wxWindow* win)
 233     {
 234         // Help the user to get the double-buffering working properly.
 235         wxASSERT_MSG( win->GetBackgroundStyle() == wxBG_STYLE_CUSTOM,
 236                       wxT("In constructor, you need to call SetBackgroundStyle(wxBG_STYLE_CUSTOM), ")
 237                       wxT("and also, if needed, paint the background manually in the paint event handler."));
 238     }
 239
 240     DECLARE_NO_COPY_CLASS(wxAutoBufferedPaintDC)
 241 };
 242
 243 #else // !__WXDEBUG__
 244
 245 // In release builds, just use typedef
 246 typedef wxAutoBufferedPaintDCBase wxAutoBufferedPaintDC;
 247
 248 #endif
 249
 250
 251 // Check if the window is natively double buffered and will return a wxPaintDC
 252 // if it is, a wxBufferedPaintDC otherwise.  It is the caller's responsibility
 253 // to delete the wxDC pointer when finished with it.
 254 inline wxDC* wxAutoBufferedPaintDCFactory(wxWindow* window)
 255 {
 256     if ( window->IsDoubleBuffered() )
 257         return new wxPaintDC(window);
 258     else
 259         return new wxBufferedPaintDC(window);
 260 }
 261
 262
 263 #endif  // _WX_DCBUFFER_H_