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