| 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{wxbase} |
| 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 | |