interface/dcbuffer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dcbuffer.h
   3 // Purpose:     documentation for wxBufferedDC class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxBufferedDC
  11     @wxheader{dcbuffer.h}
  12
  13     This class provides a simple way to avoid flicker: when drawing on it,
  14     everything is in fact first drawn on an in-memory buffer (a
  15     wxBitmap) and then copied to the screen, using the
  16     associated wxDC, only once, when this object is destroyed. wxBufferedDC itself
  17     is typically associated with wxClientDC, if you want to
  18     use it in your @c EVT_PAINT handler, you should look at
  19     wxBufferedPaintDC instead.
  20
  21     When used like this, a valid @e dc must be specified in the constructor
  22     while the @e buffer bitmap doesn't have to be explicitly provided, by
  23     default this class will allocate the bitmap of required size itself. However
  24     using a dedicated bitmap can speed up the redrawing process by eliminating the
  25     repeated creation and destruction of a possibly big bitmap. Otherwise,
  26     wxBufferedDC can be used in the same way as any other device context.
  27
  28     There is another possible use for wxBufferedDC is to use it to maintain a
  29     backing store for the window contents. In this case, the associated @e dc
  30     may be @NULL but a valid backing store bitmap should be specified.
  31
  32     Finally, please note that GTK+ 2.0 as well as OS X provide double buffering
  33     themselves natively. You can either use wxWindow::IsDoubleBuffered
  34     to determine whether you need to use buffering or not, or use
  35     wxAutoBufferedPaintDC to avoid needless double
  36     buffering on the systems which already do it automatically.
  37
  38     @library{wxcore}
  39     @category{dc}
  40
  41     @seealso
  42     wxDC, wxMemoryDC, wxBufferedPaintDC, wxAutoBufferedPaintDC
  43 */
  44 class wxBufferedDC : public wxMemoryDC
  45 {
  46 public:
  47     //@{
  48     /**
  49         If you use the first, default, constructor, you must call one of the
  50         Init() methods later in order to use the object.
  51
  52         The other constructors initialize the object immediately and @c Init()
  53         must not be called after using them.
  54
  55         @param dc
  56         The underlying DC: everything drawn to this object will be
  57         flushed to this DC when this object is destroyed.  You may pass @NULL
  58         in order to just initialize the buffer, and not flush it.
  59
  60         @param area
  61         The size of the bitmap to be used for buffering (this bitmap is
  62         created internally when it is not given explicitly).
  63
  64         @param buffer
  65         Explicitly provided bitmap to be used for buffering: this is
  66         the most efficient solution as the bitmap doesn't have to be recreated each
  67         time but it also requires more memory as the bitmap is never freed. The bitmap
  68         should have appropriate size, anything drawn outside of its bounds is clipped.
  69
  70         @param style
  71         wxBUFFER_CLIENT_AREA to indicate that just the client area of
  72         the window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the buffer
  73         bitmap
  74         covers the virtual area (in which case PrepareDC is automatically called for
  75         the actual window
  76         device context).
  77     */
  78     wxBufferedDC();
  79     wxBufferedDC(wxDC * dc, const wxSize& area,
  80                  int style = wxBUFFER_CLIENT_AREA);
  81     wxBufferedDC(wxDC * dc, wxBitmap& buffer,
  82                  int style = wxBUFFER_CLIENT_AREA);
  83     //@}
  84
  85     /**
  86         Copies everything drawn on the DC so far to the underlying DC associated with
  87         this object, if any.
  88     */
  89
  90
  91     //@{
  92     /**
  93         These functions initialize the object created using the default constructor.
  94         Please see @ref ctor() "constructors documentation" for details.
  95     */
  96     void Init(wxDC * dc, const wxSize& area,
  97               int style = wxBUFFER_CLIENT_AREA);
  98     void Init(wxDC * dc, wxBitmap& buffer,
  99               int style = wxBUFFER_CLIENT_AREA);
 100     //@}
 101 };
 102
 103
 104 /**
 105     @class wxAutoBufferedPaintDC
 106     @wxheader{dcbuffer.h}
 107
 108     This wxDC derivative can be used inside of an @c OnPaint() event handler to
 109     achieve
 110     double-buffered drawing. Just create an object of this class instead of
 111     wxPaintDC
 112     and make sure wxWindow::SetBackgroundStyle is called
 113     with wxBG_STYLE_CUSTOM somewhere in the class initialization code, and that's
 114     all you have
 115     to do to (mostly) avoid flicker.
 116
 117     The difference between wxBufferedPaintDC and this class,
 118     is the lightweigthness - on platforms which have native double-buffering,
 119     wxAutoBufferedPaintDC is simply
 120     a typedef of wxPaintDC. Otherwise, it is a typedef of wxBufferedPaintDC.
 121
 122     @library{wxbase}
 123     @category{dc}
 124
 125     @seealso
 126     wxDC, wxBufferedPaintDC
 127 */
 128 class wxAutoBufferedPaintDC : public wxBufferedPaintDC
 129 {
 130 public:
 131     /**
 132         Constructor. Pass a pointer to the window on which you wish to paint.
 133     */
 134     wxAutoBufferedPaintDC(wxWindow * window);
 135 };
 136
 137
 138 /**
 139     @class wxBufferedPaintDC
 140     @wxheader{dcbuffer.h}
 141
 142     This is a subclass of wxBufferedDC which can be used
 143     inside of an @c OnPaint() event handler. Just create an object of this class
 144     instead
 145     of wxPaintDC and make sure wxWindow::SetBackgroundStyle
 146     is called with wxBG_STYLE_CUSTOM somewhere in the class initialization code,
 147     and that's all
 148     you have to do to (mostly) avoid flicker. The only thing to watch out for is
 149     that if you are
 150     using this class together with wxScrolledWindow, you probably
 151     do @b not want to call wxScrolledWindow::PrepareDC on it as it
 152     already does this internally for the real underlying wxPaintDC.
 153
 154     @library{wxcore}
 155     @category{dc}
 156
 157     @seealso
 158     wxDC, wxBufferedDC, wxAutoBufferedPaintDC
 159 */
 160 class wxBufferedPaintDC : public wxBufferedDC
 161 {
 162 public:
 163     //@{
 164     /**
 165         As with @ref wxBufferedDC::ctor wxBufferedDC, you may either provide the
 166         bitmap to be used for buffering or let this object create one internally (in
 167         the latter case, the size of the client part of the window is used).
 168
 169         Pass wxBUFFER_CLIENT_AREA for the @e style parameter to indicate that just the
 170         client area of
 171         the window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the buffer
 172         bitmap
 173         covers the virtual area (in which case PrepareDC is automatically called for
 174         the actual window
 175         device context).
 176     */
 177     wxBufferedPaintDC(wxWindow * window, wxBitmap& buffer,
 178                       int style = wxBUFFER_CLIENT_AREA);
 179     wxBufferedPaintDC(wxWindow * window,
 180                       int style = wxBUFFER_CLIENT_AREA);
 181     //@}
 182
 183     /**
 184         Copies everything drawn on the DC so far to the window associated with this
 185         object, using a wxPaintDC.
 186     */
 187 };