interface/dcbuffer.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dcbuffer.h
   3 // Purpose:     interface of wxBufferedDC
   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     @see wxDC, wxMemoryDC, wxBufferedPaintDC, wxAutoBufferedPaintDC
  42 */
  43 class wxBufferedDC : public wxMemoryDC
  44 {
  45 public:
  46     //@{
  47     /**
  48         If you use the first, default, constructor, you must call one of the
  49         Init() methods later in order to use the object.
  50         The other constructors initialize the object immediately and @c Init()
  51         must not be called after using them.
  52
  53         @param dc
  54             The underlying DC: everything drawn to this object will be
  55             flushed to this DC when this object is destroyed.  You may pass @NULL
  56             in order to just initialize the buffer, and not flush it.
  57         @param area
  58             The size of the bitmap to be used for buffering (this bitmap is
  59             created internally when it is not given explicitly).
  60         @param buffer
  61             Explicitly provided bitmap to be used for buffering: this is
  62             the most efficient solution as the bitmap doesn't have to be recreated each
  63             time but it also requires more memory as the bitmap is never freed. The
  64         bitmap
  65             should have appropriate size, anything drawn outside of its bounds is
  66         clipped.
  67         @param style
  68             wxBUFFER_CLIENT_AREA to indicate that just the client area of
  69             the window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the
  70         buffer bitmap
  71             covers the virtual area (in which case PrepareDC is automatically called
  72         for the actual window
  73             device context).
  74     */
  75     wxBufferedDC();
  76     wxBufferedDC(wxDC* dc, const wxSize& area,
  77                  int style = wxBUFFER_CLIENT_AREA);
  78     wxBufferedDC(wxDC* dc, wxBitmap& buffer,
  79                  int style = wxBUFFER_CLIENT_AREA);
  80     //@}
  81
  82     /**
  83         Copies everything drawn on the DC so far to the underlying DC associated with
  84         this object, if any.
  85     */
  86
  87
  88     //@{
  89     /**
  90         These functions initialize the object created using the default constructor.
  91         Please see @ref ctor() "constructors documentation" for details.
  92     */
  93     void Init(wxDC* dc, const wxSize& area,
  94               int style = wxBUFFER_CLIENT_AREA);
  95     void Init(wxDC* dc, wxBitmap& buffer,
  96               int style = wxBUFFER_CLIENT_AREA);
  97     //@}
  98 };
  99
 100
 101
 102 /**
 103     @class wxAutoBufferedPaintDC
 104     @wxheader{dcbuffer.h}
 105
 106     This wxDC derivative can be used inside of an @c OnPaint() event handler to
 107     achieve
 108     double-buffered drawing. Just create an object of this class instead of
 109     wxPaintDC
 110     and make sure wxWindow::SetBackgroundStyle is called
 111     with wxBG_STYLE_CUSTOM somewhere in the class initialization code, and that's
 112     all you have
 113     to do to (mostly) avoid flicker.
 114
 115     The difference between wxBufferedPaintDC and this class,
 116     is the lightweigthness - on platforms which have native double-buffering,
 117     wxAutoBufferedPaintDC is simply
 118     a typedef of wxPaintDC. Otherwise, it is a typedef of wxBufferedPaintDC.
 119
 120     @library{wxbase}
 121     @category{dc}
 122
 123     @see wxDC, wxBufferedPaintDC
 124 */
 125 class wxAutoBufferedPaintDC : public wxBufferedPaintDC
 126 {
 127 public:
 128     /**
 129         Constructor. Pass a pointer to the window on which you wish to paint.
 130     */
 131     wxAutoBufferedPaintDC(wxWindow* window);
 132 };
 133
 134
 135
 136 /**
 137     @class wxBufferedPaintDC
 138     @wxheader{dcbuffer.h}
 139
 140     This is a subclass of wxBufferedDC which can be used
 141     inside of an @c OnPaint() event handler. Just create an object of this class
 142     instead
 143     of wxPaintDC and make sure wxWindow::SetBackgroundStyle
 144     is called with wxBG_STYLE_CUSTOM somewhere in the class initialization code,
 145     and that's all
 146     you have to do to (mostly) avoid flicker. The only thing to watch out for is
 147     that if you are
 148     using this class together with wxScrolledWindow, you probably
 149     do @b not want to call wxScrolledWindow::PrepareDC on it as it
 150     already does this internally for the real underlying wxPaintDC.
 151
 152     @library{wxcore}
 153     @category{dc}
 154
 155     @see wxDC, wxBufferedDC, wxAutoBufferedPaintDC
 156 */
 157 class wxBufferedPaintDC : public wxBufferedDC
 158 {
 159 public:
 160     //@{
 161     /**
 162         As with @ref wxBufferedDC::ctor wxBufferedDC, you may either provide the
 163         bitmap to be used for buffering or let this object create one internally (in
 164         the latter case, the size of the client part of the window is used).
 165         Pass wxBUFFER_CLIENT_AREA for the @a style parameter to indicate that just the
 166         client area of
 167         the window is buffered, or wxBUFFER_VIRTUAL_AREA to indicate that the buffer
 168         bitmap
 169         covers the virtual area (in which case PrepareDC is automatically called for
 170         the actual window
 171         device context).
 172     */
 173     wxBufferedPaintDC(wxWindow* window, wxBitmap& buffer,
 174                       int style = wxBUFFER_CLIENT_AREA);
 175     wxBufferedPaintDC(wxWindow* window,
 176                       int style = wxBUFFER_CLIENT_AREA);
 177     //@}
 178
 179     /**
 180         Copies everything drawn on the DC so far to the window associated with this
 181         object, using a wxPaintDC.
 182     */
 183 };
 184