interface/wx/dcbuffer.h

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