]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/dcbuffer.h
added the possibility to rescale the image during loading, especially useful with...
[wxWidgets.git] / interface / wx / dcbuffer.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: dcbuffer.h
e54c96f1 3// Purpose: interface of wxBufferedDC
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxBufferedDC
7c913512 11
23324ae1 12 This class provides a simple way to avoid flicker: when drawing on it,
f09b5681
BP
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
23324ae1 20 while the @e buffer bitmap doesn't have to be explicitly provided, by
f09b5681
BP
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.
7c913512 26
23324ae1 27 There is another possible use for wxBufferedDC is to use it to maintain a
f09b5681 28 backing store for the window contents. In this case, the associated @e DC
23324ae1 29 may be @NULL but a valid backing store bitmap should be specified.
7c913512 30
23324ae1 31 Finally, please note that GTK+ 2.0 as well as OS X provide double buffering
f09b5681
BP
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.
7c913512 36
23324ae1
FM
37 @library{wxcore}
38 @category{dc}
7c913512 39
e54c96f1 40 @see wxDC, wxMemoryDC, wxBufferedPaintDC, wxAutoBufferedPaintDC
23324ae1
FM
41*/
42class wxBufferedDC : public wxMemoryDC
43{
44public:
f09b5681
BP
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
23324ae1
FM
51 //@{
52 /**
4050e98d 53 Creates a buffer for the provided @a dc. Init() must not be called when
f09b5681 54 using this constructor.
3c4f71cc 55
7c913512 56 @param dc
f09b5681
BP
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.
7c913512 60 @param area
4cc4bfaf
FM
61 The size of the bitmap to be used for buffering (this bitmap is
62 created internally when it is not given explicitly).
4050e98d
BP
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);
98ccd545 70
4050e98d
BP
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.
7c913512 79 @param buffer
f09b5681
BP
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.
4cc4bfaf 85 @param style
f09b5681
BP
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.
23324ae1 89 */
4cc4bfaf 90 wxBufferedDC(wxDC* dc, wxBitmap& buffer,
7c913512 91 int style = wxBUFFER_CLIENT_AREA);
23324ae1
FM
92 //@}
93
94 /**
f09b5681
BP
95 Copies everything drawn on the DC so far to the underlying DC
96 associated with this object, if any.
23324ae1 97 */
98ccd545 98 virtual ~wxBufferedDC();
23324ae1
FM
99
100 //@{
101 /**
f09b5681
BP
102 Initializes the object created using the default constructor. Please
103 see the constructors for parameter details.
23324ae1 104 */
4cc4bfaf 105 void Init(wxDC* dc, const wxSize& area,
23324ae1 106 int style = wxBUFFER_CLIENT_AREA);
4cc4bfaf 107 void Init(wxDC* dc, wxBitmap& buffer,
7c913512 108 int style = wxBUFFER_CLIENT_AREA);
23324ae1
FM
109 //@}
110};
111
112
e54c96f1 113
23324ae1
FM
114/**
115 @class wxAutoBufferedPaintDC
7c913512 116
f09b5681
BP
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.
7c913512 126
f09b5681
BP
127 wxAutoBufferedPaintDC is simply a typedef of wxPaintDC on platforms that
128 have native double-buffering, otherwise, it is a typedef of
129 wxBufferedPaintDC.
7c913512 130
23324ae1
FM
131 @library{wxbase}
132 @category{dc}
7c913512 133
f09b5681 134 @see wxDC, wxBufferedPaintDC, wxPaintDC
23324ae1
FM
135*/
136class wxAutoBufferedPaintDC : public wxBufferedPaintDC
137{
138public:
139 /**
140 Constructor. Pass a pointer to the window on which you wish to paint.
141 */
4cc4bfaf 142 wxAutoBufferedPaintDC(wxWindow* window);
23324ae1
FM
143};
144
145
e54c96f1 146
23324ae1
FM
147/**
148 @class wxBufferedPaintDC
7c913512 149
f09b5681
BP
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.
7c913512 159
23324ae1
FM
160 @library{wxcore}
161 @category{dc}
7c913512 162
f09b5681 163 @see wxDC, wxBufferedDC, wxAutoBufferedPaintDC, wxPaintDC
23324ae1
FM
164*/
165class wxBufferedPaintDC : public wxBufferedDC
166{
167public:
168 //@{
169 /**
f09b5681
BP
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.
23324ae1 178 */
4cc4bfaf 179 wxBufferedPaintDC(wxWindow* window, wxBitmap& buffer,
23324ae1 180 int style = wxBUFFER_CLIENT_AREA);
4cc4bfaf 181 wxBufferedPaintDC(wxWindow* window,
7c913512 182 int style = wxBUFFER_CLIENT_AREA);
23324ae1
FM
183 //@}
184
185 /**
f09b5681
BP
186 Copies everything drawn on the DC so far to the window associated with
187 this object, using a wxPaintDC.
23324ae1 188 */
98ccd545 189 virtual ~wxBufferedPaintDC();
23324ae1 190};
e54c96f1 191