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
 125 /**
 126     @class wxAutoBufferedPaintDC
 127
 128     This wxDC derivative can be used inside of an @c EVT_PAINT() event handler
 129     to achieve double-buffered drawing. Just use this class instead of
 130     wxPaintDC and make sure wxWindow::SetBackgroundStyle() is called with
 131     wxBG_STYLE_PAINT somewhere in the class initialization code, and that's
 132     all you have to do to (mostly) avoid flicker.
 133
 134     The difference between wxBufferedPaintDC and this class is that this class
 135     won't double-buffer on platforms which have native double-buffering
 136     already, avoiding any unnecessary buffering to avoid flicker.
 137
 138     wxAutoBufferedPaintDC is simply a typedef of wxPaintDC on platforms that
 139     have native double-buffering, otherwise, it is a typedef of
 140     wxBufferedPaintDC.
 141
 142     @library{wxcore}
 143     @category{dc}
 144
 145     @see wxDC, wxBufferedPaintDC, wxPaintDC
 146 */
 147 class wxAutoBufferedPaintDC : public wxBufferedPaintDC
 148 {
 149 public:
 150     /**
 151         Constructor. Pass a pointer to the window on which you wish to paint.
 152     */
 153     wxAutoBufferedPaintDC(wxWindow* window);
 154 };
 155
 156
 157 /**
 158  * Check if the window is natively double buffered and will return a wxPaintDC
 159  * if it is, a wxBufferedPaintDC otherwise.  It is the caller's responsibility
 160  * to delete the wxDC pointer when finished with it.
 161  */
 162 wxDC* wxAutoBufferedPaintDCFactory(wxWindow* window);
 163
 164
 165 /**
 166     @class wxBufferedPaintDC
 167
 168     This is a subclass of wxBufferedDC which can be used inside of an
 169     @c EVT_PAINT() event handler to achieve double-buffered drawing. Just use
 170     this class instead of wxPaintDC and make sure
 171     wxWindow::SetBackgroundStyle() is called with wxBG_STYLE_PAINT somewhere
 172     in the class initialization code, and that's all you have to do to (mostly)
 173     avoid flicker. The only thing to watch out for is that if you are using
 174     this class together with wxScrolled, you probably do @b not want to call
 175     wxScrolled::PrepareDC() on it as it already does this internally for the
 176     real underlying wxPaintDC.
 177
 178     @library{wxcore}
 179     @category{dc}
 180
 181     @see wxDC, wxBufferedDC, wxAutoBufferedPaintDC, wxPaintDC
 182 */
 183 class wxBufferedPaintDC : public wxBufferedDC
 184 {
 185 public:
 186     //@{
 187     /**
 188         As with wxBufferedDC, you may either provide the bitmap to be used for
 189         buffering or let this object create one internally (in the latter case,
 190         the size of the client part of the window is used).
 191
 192         Pass wxBUFFER_CLIENT_AREA for the @a style parameter to indicate that
 193         just the client area of the window is buffered, or
 194         wxBUFFER_VIRTUAL_AREA to indicate that the buffer bitmap covers the
 195         virtual area.
 196     */
 197     wxBufferedPaintDC(wxWindow* window, wxBitmap& buffer,
 198                       int style = wxBUFFER_CLIENT_AREA);
 199     wxBufferedPaintDC(wxWindow* window,
 200                       int style = wxBUFFER_CLIENT_AREA);
 201     //@}
 202
 203     /**
 204         Copies everything drawn on the DC so far to the window associated with
 205         this object, using a wxPaintDC.
 206     */
 207     virtual ~wxBufferedPaintDC();
 208 };
 209