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