interface/wx/dcbuffer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dcbuffer.h
   3 // Purpose:     interface of wxBufferedDC
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 // Assumes the buffer bitmap covers the entire scrolled window,
  10 // and prepares the window DC accordingly
  11 #define wxBUFFER_VIRTUAL_AREA       0x01
  12
  13 // Assumes the buffer bitmap only covers the client area;
  14 // does not prepare the window DC
  15 #define wxBUFFER_CLIENT_AREA        0x02
  16
  17 // Set when not using specific buffer bitmap. Note that this
  18 // is private style and not returned by GetStyle.
  19 #define wxBUFFER_USES_SHARED_BUFFER 0x04
  20
  21
  22 /**
  23     @class wxBufferedDC
  24
  25     This class provides a simple way to avoid flicker: when drawing on it,
  26     everything is in fact first drawn on an in-memory buffer (a wxBitmap) and
  27     then copied to the screen, using the associated wxDC, only once, when this
  28     object is destroyed. wxBufferedDC itself is typically associated with
  29     wxClientDC, if you want to use it in your @c EVT_PAINT handler, you should
  30     look at wxBufferedPaintDC instead.
  31
  32     When used like this, a valid @e DC must be specified in the constructor
  33     while the @e buffer bitmap doesn't have to be explicitly provided, by
  34     default this class will allocate the bitmap of required size itself.
  35     However using a dedicated bitmap can speed up the redrawing process by
  36     eliminating the repeated creation and destruction of a possibly big bitmap.
  37     Otherwise, wxBufferedDC can be used in the same way as any other device
  38     context.
  39
  40     There is another possible use for wxBufferedDC is to use it to maintain a
  41     backing store for the window contents. In this case, the associated @e DC
  42     may be @NULL but a valid backing store bitmap should be specified.
  43
  44     Finally, please note that GTK+ 2.0 as well as OS X provide double buffering
  45     themselves natively. You can either use wxWindow::IsDoubleBuffered() to
  46     determine whether you need to use buffering or not, or use
  47     wxAutoBufferedPaintDC to avoid needless double buffering on the systems
  48     which already do it automatically.
  49
  50     @library{wxcore}
  51     @category{dc}
  52
  53     @see wxDC, wxMemoryDC, wxBufferedPaintDC, wxAutoBufferedPaintDC
  54 */
  55 class wxBufferedDC : public wxMemoryDC
  56 {
  57 public:
  58     /**
  59         Default constructor. You must call one of the Init() methods later in
  60         order to use the device context.
  61     */
  62     wxBufferedDC();
  63
  64     /**
  65         Creates a buffer for the provided @a dc. Init() must not be called when
  66         using this constructor.
  67
  68         @param dc
  69             The underlying DC: everything drawn to this object will be flushed
  70             to this DC when this object is destroyed. You may pass @NULL in
  71             order to just initialize the buffer, and not flush it.
  72         @param area
  73             The size of the bitmap to be used for buffering (this bitmap is
  74             created internally when it is not given explicitly).
  75         @param style
  76             wxBUFFER_CLIENT_AREA to indicate that just the client area of the
  77             window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the
  78             buffer bitmap covers the virtual area.
  79     */
  80     wxBufferedDC(wxDC* dc, const wxSize& area,
  81                  int style = wxBUFFER_CLIENT_AREA);
  82
  83     /**
  84         Creates a buffer for the provided dc. Init() must not be called when
  85         using this constructor.
  86
  87         @param dc
  88             The underlying DC: everything drawn to this object will be flushed
  89             to this DC when this object is destroyed. You may pass @NULL in
  90             order to just initialize the buffer, and not flush it.
  91         @param buffer
  92             Explicitly provided bitmap to be used for buffering: this is the
  93             most efficient solution as the bitmap doesn't have to be recreated
  94             each time but it also requires more memory as the bitmap is never
  95             freed. The bitmap should have appropriate size, anything drawn
  96             outside of its bounds is clipped.
  97         @param style
  98             wxBUFFER_CLIENT_AREA to indicate that just the client area of the
  99             window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the
 100             buffer bitmap covers the virtual area.
 101     */
 102     wxBufferedDC(wxDC* dc, wxBitmap& buffer = wxNullBitmap,
 103                  int style = wxBUFFER_CLIENT_AREA);
 104
 105     /**
 106         Copies everything drawn on the DC so far to the underlying DC
 107         associated with this object, if any.
 108     */
 109     virtual ~wxBufferedDC();
 110
 111     //@{
 112     /**
 113         Initializes the object created using the default constructor. Please
 114         see the constructors for parameter details.
 115     */
 116     void Init(wxDC* dc, const wxSize& area,
 117               int style = wxBUFFER_CLIENT_AREA);
 118     void Init(wxDC* dc, wxBitmap& buffer = wxNullBitmap,
 119               int style = wxBUFFER_CLIENT_AREA);
 120     //@}
 121
 122
 123     /**
 124        Blits the buffer to the dc, and detaches the dc from the buffer (so it
 125        can be effectively used once only).
 126
 127        Usually only called in the destructor or by the destructor of derived
 128        classes if the BufferedDC must blit before the derived class (which may
 129        own the dc it's blitting to) is destroyed.
 130     */
 131     void UnMask();
 132
 133     /**
 134        Set the style.
 135     */
 136     void SetStyle(int style);
 137
 138     /**
 139        Get the style.
 140     */
 141     int GetStyle() const;
 142 };
 143
 144
 145
 146 /**
 147     @class wxAutoBufferedPaintDC
 148
 149     This wxDC derivative can be used inside of an @c EVT_PAINT() event handler
 150     to achieve double-buffered drawing. Just use this class instead of
 151     wxPaintDC and make sure wxWindow::SetBackgroundStyle() is called with
 152     wxBG_STYLE_PAINT somewhere in the class initialization code, and that's
 153     all you have to do to (mostly) avoid flicker.
 154
 155     The difference between wxBufferedPaintDC and this class is that this class
 156     won't double-buffer on platforms which have native double-buffering
 157     already, avoiding any unnecessary buffering to avoid flicker.
 158
 159     wxAutoBufferedPaintDC is simply a typedef of wxPaintDC on platforms that
 160     have native double-buffering, otherwise, it is a typedef of
 161     wxBufferedPaintDC.
 162
 163     @library{wxcore}
 164     @category{dc}
 165
 166     @see wxDC, wxBufferedPaintDC, wxPaintDC
 167 */
 168 class wxAutoBufferedPaintDC : public wxBufferedPaintDC
 169 {
 170 public:
 171     /**
 172         Constructor. Pass a pointer to the window on which you wish to paint.
 173     */
 174     wxAutoBufferedPaintDC(wxWindow* window);
 175 };
 176
 177
 178 /**
 179  * Check if the window is natively double buffered and will return a wxPaintDC
 180  * if it is, a wxBufferedPaintDC otherwise.  It is the caller's responsibility
 181  * to delete the wxDC pointer when finished with it.
 182  */
 183 wxDC* wxAutoBufferedPaintDCFactory(wxWindow* window);
 184
 185
 186 /**
 187     @class wxBufferedPaintDC
 188
 189     This is a subclass of wxBufferedDC which can be used inside of an
 190     @c EVT_PAINT() event handler to achieve double-buffered drawing. Just use
 191     this class instead of wxPaintDC and make sure
 192     wxWindow::SetBackgroundStyle() is called with wxBG_STYLE_PAINT somewhere
 193     in the class initialization code, and that's all you have to do to (mostly)
 194     avoid flicker. The only thing to watch out for is that if you are using
 195     this class together with wxScrolled, you probably do @b not want to call
 196     wxScrolled::PrepareDC() on it as it already does this internally for the
 197     real underlying wxPaintDC.
 198
 199     @library{wxcore}
 200     @category{dc}
 201
 202     @see wxDC, wxBufferedDC, wxAutoBufferedPaintDC, wxPaintDC
 203 */
 204 class wxBufferedPaintDC : public wxBufferedDC
 205 {
 206 public:
 207     //@{
 208     /**
 209         As with wxBufferedDC, you may either provide the bitmap to be used for
 210         buffering or let this object create one internally (in the latter case,
 211         the size of the client part of the window is used).
 212
 213         Pass wxBUFFER_CLIENT_AREA for the @a style parameter to indicate that
 214         just the client area of the window is buffered, or
 215         wxBUFFER_VIRTUAL_AREA to indicate that the buffer bitmap covers the
 216         virtual area.
 217     */
 218     wxBufferedPaintDC(wxWindow* window, wxBitmap& buffer,
 219                       int style = wxBUFFER_CLIENT_AREA);
 220     wxBufferedPaintDC(wxWindow* window,
 221                       int style = wxBUFFER_CLIENT_AREA);
 222     //@}
 223
 224     /**
 225         Copies everything drawn on the DC so far to the window associated with
 226         this object, using a wxPaintDC.
 227     */
 228     virtual ~wxBufferedPaintDC();
 229 };
 230