]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: dc.h | |
e54c96f1 | 3 | // Purpose: interface of wxDC |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
526954c5 | 6 | // Licence: wxWindows licence |
23324ae1 FM |
7 | ///////////////////////////////////////////////////////////////////////////// |
8 | ||
97929f6b FM |
9 | |
10 | /** | |
11 | Logical raster operations which can be used with wxDC::SetLogicalFunction | |
12 | and some other wxDC functions (e.g. wxDC::Blit and wxDC::StretchBlit). | |
13 | ||
14 | The description of the values below refer to how a generic @e src source pixel | |
15 | and the corresponding @e dst destination pixel gets combined together to produce | |
16 | the final pixel. E.g. @c wxCLEAR and @c wxSET completely ignore the source | |
17 | and the destination pixel and always put zeroes or ones in the final surface. | |
18 | */ | |
19 | enum wxRasterOperationMode | |
20 | { | |
21 | wxCLEAR, //!< 0 | |
22 | wxXOR, //!< @e src XOR @e dst | |
23 | wxINVERT, //!< NOT @e dst | |
24 | wxOR_REVERSE, //!< @e src OR (NOT @e dst) | |
25 | wxAND_REVERSE, //!< @e src AND (NOT @e dst) | |
26 | wxCOPY, //!< @e src | |
27 | wxAND, //!< @e src AND @e dst | |
28 | wxAND_INVERT, //!< (NOT @e src) AND @e dst | |
29 | wxNO_OP, //!< @e dst | |
30 | wxNOR, //!< (NOT @e src) AND (NOT @e dst) | |
31 | wxEQUIV, //!< (NOT @e src) XOR @e dst | |
32 | wxSRC_INVERT, //!< (NOT @e src) | |
33 | wxOR_INVERT, //!< (NOT @e src) OR @e dst | |
34 | wxNAND, //!< (NOT @e src) OR (NOT @e dst) | |
35 | wxOR, //!< @e src OR @e dst | |
36 | wxSET //!< 1 | |
37 | }; | |
38 | ||
39 | /** | |
40 | Flood styles used by wxDC::FloodFill. | |
41 | */ | |
42 | enum wxFloodFillStyle | |
43 | { | |
44 | /** The flooding occurs until a colour other than the given colour is encountered. */ | |
45 | wxFLOOD_SURFACE = 1, | |
46 | ||
47 | /** The area to be flooded is bounded by the given colour. */ | |
48 | wxFLOOD_BORDER | |
49 | }; | |
50 | ||
51 | /** | |
e65a6cc1 FM |
52 | The mapping used to transform @e logical units to @e device units. |
53 | See wxDC::SetMapMode. | |
97929f6b FM |
54 | */ |
55 | enum wxMappingMode | |
56 | { | |
e65a6cc1 FM |
57 | /** |
58 | Each logical unit is 1 device pixel. | |
59 | This is the default mapping mode for all wxDC-derived classes. | |
60 | */ | |
97929f6b FM |
61 | wxMM_TEXT = 1, |
62 | ||
e65a6cc1 FM |
63 | /** Each logical unit is 1 millimeter. */ |
64 | wxMM_METRIC, | |
97929f6b | 65 | |
e65a6cc1 FM |
66 | /** Each logical unit is 1/10 of a millimeter. */ |
67 | wxMM_LOMETRIC, | |
97929f6b | 68 | |
e65a6cc1 FM |
69 | /** |
70 | Each logical unit is 1/20 of a @e "printer point", or 1/1440 of an inch | |
71 | (also known as "twip"). Equivalent to about 17.64 micrometers. | |
72 | */ | |
97929f6b FM |
73 | wxMM_TWIPS, |
74 | ||
e65a6cc1 FM |
75 | /** |
76 | Each logical unit is a @e "printer point" i.e. 1/72 of an inch. | |
77 | Equivalent to about 353 micrometers. | |
78 | */ | |
79 | wxMM_POINTS | |
80 | }; | |
97929f6b | 81 | |
e29bf4b0 VZ |
82 | /** |
83 | Simple collection of various font metrics. | |
84 | ||
85 | This object is returned by wxDC::GetFontMetrics(). | |
86 | ||
87 | @since 2.9.2 | |
88 | ||
89 | @library{wxcore} | |
90 | @category{dc,gdi} | |
91 | */ | |
92 | struct wxFontMetrics | |
93 | { | |
94 | /// Constructor initializes all fields to 0. | |
95 | wxFontMetrics(); | |
96 | ||
97 | int height, ///< Total character height. | |
98 | ascent, ///< Part of the height above the baseline. | |
99 | descent, ///< Part of the height below the baseline. | |
100 | internalLeading, ///< Intra-line spacing. | |
101 | externalLeading, ///< Inter-line spacing. | |
102 | averageWidth; ///< Average font width, a.k.a. "x-width". | |
103 | }; | |
97929f6b | 104 | |
97929f6b | 105 | |
23324ae1 FM |
106 | /** |
107 | @class wxDC | |
7c913512 | 108 | |
f09b5681 | 109 | A wxDC is a @e "device context" onto which graphics and text can be drawn. |
318b0bd5 RR |
110 | It is intended to represent different output devices and offers a common |
111 | abstract API for drawing on any of them. | |
edc51344 | 112 | |
318b0bd5 | 113 | wxWidgets offers an alternative drawing API based on the modern drawing |
12133c3b | 114 | backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer |
6d99a337 | 115 | and related classes. There is also a wxGCDC linking the APIs by offering |
403695b3 | 116 | the wxDC API on top of a wxGraphicsContext. |
7c913512 | 117 | |
318b0bd5 RR |
118 | wxDC is an abstract base class and cannot be created directly. |
119 | Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or | |
edc51344 VZ |
120 | wxPrinterDC. Notice that device contexts which are associated with windows |
121 | (i.e. wxClientDC, wxWindowDC and wxPaintDC) use the window font and colours | |
122 | by default (starting with wxWidgets 2.9.0) but the other device context | |
123 | classes use system-default values so you always must set the appropriate | |
124 | fonts and colours before using them. | |
f09b5681 | 125 | |
318b0bd5 RR |
126 | In addition to the versions of the methods documented below, there |
127 | are also versions which accept single wxPoint parameter instead | |
128 | of the two wxCoord ones or wxPoint and wxSize instead of the four | |
129 | wxCoord parameters. | |
f09b5681 | 130 | |
318b0bd5 RR |
131 | Beginning with wxWidgets 2.9.0 the entire wxDC code has been |
132 | reorganized. All platform dependent code (actually all drawing code) | |
133 | has been moved into backend classes which derive from a common | |
134 | wxDCImpl class. The user-visible classes such as wxClientDC and | |
135 | wxPaintDC merely forward all calls to the backend implementation. | |
f09b5681 | 136 | |
e65a6cc1 FM |
137 | |
138 | @section dc_units Device and logical units | |
139 | ||
140 | In the wxDC context there is a distinction between @e logical units and @e device units. | |
141 | ||
142 | @b Device units are the units native to the particular device; e.g. for a screen, | |
143 | a device unit is a @e pixel. For a printer, the device unit is defined by the | |
144 | resolution of the printer (usually given in @c DPI: dot-per-inch). | |
145 | ||
4c51a665 | 146 | All wxDC functions use instead @b logical units, unless where explicitly |
e65a6cc1 FM |
147 | stated. Logical units are arbitrary units mapped to device units using |
148 | the current mapping mode (see wxDC::SetMapMode). | |
149 | ||
150 | This mechanism allows to reuse the same code which prints on e.g. a window | |
151 | on the screen to print on e.g. a paper. | |
152 | ||
153 | ||
e3995493 FM |
154 | @section dc_alpha_support Support for Transparency / Alpha Channel |
155 | ||
403695b3 VZ |
156 | In general wxDC methods don't support alpha transparency and the alpha |
157 | component of wxColour is simply ignored and you need to use wxGraphicsContext | |
158 | for full transparency support. There are, however, a few exceptions: first, | |
159 | under Mac OS X colours with alpha channel are supported in all the normal | |
160 | wxDC-derived classes as they use wxGraphicsContext internally. Second, | |
161 | under all platforms wxSVGFileDC also fully supports alpha channel. In both | |
162 | of these cases the instances of wxPen or wxBrush that are built from | |
163 | wxColour use the colour's alpha values when stroking or filling. | |
e3995493 FM |
164 | |
165 | ||
e71508e1 VZ |
166 | @section Support for Transformation Matrix |
167 | ||
168 | On some platforms (currently only under MSW and only on Windows NT, i.e. | |
169 | not Windows 9x/ME, systems) wxDC has support for applying an arbitrary | |
170 | affine transformation matrix to its coordinate system. Call | |
171 | CanUseTransformMatrix() to check if this support is available and then call | |
172 | SetTransformMatrix() if it is. If the transformation matrix is not | |
173 | supported, SetTransformMatrix() always simply returns false and doesn't do | |
174 | anything. | |
175 | ||
176 | ||
23324ae1 | 177 | @library{wxcore} |
c0cc7004 | 178 | @category{dc,gdi} |
7c913512 | 179 | |
382f12e4 FM |
180 | @see @ref overview_dc, wxGraphicsContext, wxDCFontChanger, wxDCTextColourChanger, |
181 | wxDCPenChanger, wxDCBrushChanger, wxDCClipper | |
f09b5681 BP |
182 | |
183 | @todo Precise definition of default/initial state. | |
184 | @todo Pixelwise definition of operations (e.g. last point of a line not | |
185 | drawn). | |
23324ae1 FM |
186 | */ |
187 | class wxDC : public wxObject | |
188 | { | |
189 | public: | |
190 | /** | |
e3995493 | 191 | @name Coordinate conversion functions |
23324ae1 | 192 | */ |
e3995493 | 193 | //@{ |
23324ae1 FM |
194 | |
195 | /** | |
e3995493 FM |
196 | Convert @e device X coordinate to logical coordinate, using the current |
197 | mapping mode, user scale factor, device origin and axis orientation. | |
23324ae1 | 198 | */ |
e3995493 | 199 | wxCoord DeviceToLogicalX(wxCoord x) const; |
23324ae1 FM |
200 | |
201 | /** | |
e3995493 FM |
202 | Convert @e device X coordinate to relative logical coordinate, using the |
203 | current mapping mode and user scale factor but ignoring the | |
204 | axis orientation. Use this for converting a width, for example. | |
23324ae1 | 205 | */ |
e3995493 | 206 | wxCoord DeviceToLogicalXRel(wxCoord x) const; |
23324ae1 | 207 | |
23324ae1 | 208 | /** |
e3995493 FM |
209 | Converts @e device Y coordinate to logical coordinate, using the current |
210 | mapping mode, user scale factor, device origin and axis orientation. | |
23324ae1 | 211 | */ |
e3995493 | 212 | wxCoord DeviceToLogicalY(wxCoord y) const; |
23324ae1 FM |
213 | |
214 | /** | |
e3995493 FM |
215 | Convert @e device Y coordinate to relative logical coordinate, using the |
216 | current mapping mode and user scale factor but ignoring the | |
217 | axis orientation. Use this for converting a height, for example. | |
23324ae1 | 218 | */ |
e3995493 | 219 | wxCoord DeviceToLogicalYRel(wxCoord y) const; |
23324ae1 FM |
220 | |
221 | /** | |
e3995493 | 222 | Converts logical X coordinate to device coordinate, using the current |
63408203 | 223 | mapping mode, user scale factor, device origin and axis orientation. |
23324ae1 | 224 | */ |
e3995493 | 225 | wxCoord LogicalToDeviceX(wxCoord x) const; |
23324ae1 FM |
226 | |
227 | /** | |
e3995493 | 228 | Converts logical X coordinate to relative device coordinate, using the |
63408203 VZ |
229 | current mapping mode and user scale factor but ignoring the |
230 | axis orientation. Use this for converting a width, for example. | |
23324ae1 | 231 | */ |
e3995493 | 232 | wxCoord LogicalToDeviceXRel(wxCoord x) const; |
23324ae1 FM |
233 | |
234 | /** | |
e3995493 | 235 | Converts logical Y coordinate to device coordinate, using the current |
63408203 | 236 | mapping mode, user scale factor, device origin and axis orientation. |
23324ae1 | 237 | */ |
e3995493 | 238 | wxCoord LogicalToDeviceY(wxCoord y) const; |
23324ae1 FM |
239 | |
240 | /** | |
e3995493 | 241 | Converts logical Y coordinate to relative device coordinate, using the |
63408203 VZ |
242 | current mapping mode and user scale factor but ignoring the |
243 | axis orientation. Use this for converting a height, for example. | |
23324ae1 | 244 | */ |
e3995493 FM |
245 | wxCoord LogicalToDeviceYRel(wxCoord y) const; |
246 | ||
247 | //@} | |
248 | ||
249 | ||
250 | ||
251 | /** | |
252 | @name Drawing functions | |
253 | */ | |
254 | //@{ | |
255 | ||
256 | /** | |
257 | Clears the device context using the current background brush. | |
258 | */ | |
259 | void Clear(); | |
23324ae1 FM |
260 | |
261 | /** | |
f09b5681 | 262 | Draws an arc of a circle, centred on (@a xc, @a yc), with starting |
12194090 FM |
263 | point (@a xStart, @a yStart) and ending at (@a xEnd, @a yEnd). |
264 | The current pen is used for the outline and the current brush for | |
265 | filling the shape. | |
f09b5681 BP |
266 | |
267 | The arc is drawn in a counter-clockwise direction from the start point | |
268 | to the end point. | |
23324ae1 | 269 | */ |
12194090 | 270 | void DrawArc(wxCoord xStart, wxCoord yStart, wxCoord xEnd, wxCoord yEnd, |
e3995493 | 271 | wxCoord xc, wxCoord yc); |
23324ae1 | 272 | |
83b4d26c VZ |
273 | /** |
274 | @overload | |
275 | */ | |
12194090 | 276 | void DrawArc(const wxPoint& ptStart, const wxPoint& ptEnd, const wxPoint& centre); |
83b4d26c | 277 | |
23324ae1 | 278 | /** |
f09b5681 BP |
279 | Draw a bitmap on the device context at the specified point. If |
280 | @a transparent is @true and the bitmap has a transparency mask, the | |
281 | bitmap will be drawn transparently. | |
282 | ||
283 | When drawing a mono-bitmap, the current text foreground colour will be | |
284 | used to draw the foreground of the bitmap (all bits set to 1), and the | |
285 | current text background colour to draw the background (all bits set to | |
286 | 0). | |
287 | ||
288 | @see SetTextForeground(), SetTextBackground(), wxMemoryDC | |
23324ae1 FM |
289 | */ |
290 | void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y, | |
408776d0 | 291 | bool useMask = false); |
23324ae1 | 292 | |
83b4d26c VZ |
293 | /** |
294 | @overload | |
295 | */ | |
296 | void DrawBitmap(const wxBitmap &bmp, const wxPoint& pt, | |
297 | bool useMask = false); | |
298 | ||
23324ae1 FM |
299 | /** |
300 | Draws a check mark inside the given rectangle. | |
301 | */ | |
f09b5681 | 302 | void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height); |
e3995493 FM |
303 | |
304 | /** | |
305 | @overload | |
306 | */ | |
4cc4bfaf | 307 | void DrawCheckMark(const wxRect& rect); |
23324ae1 | 308 | |
23324ae1 FM |
309 | /** |
310 | Draws a circle with the given centre and radius. | |
3c4f71cc | 311 | |
4cc4bfaf | 312 | @see DrawEllipse() |
23324ae1 FM |
313 | */ |
314 | void DrawCircle(wxCoord x, wxCoord y, wxCoord radius); | |
e3995493 FM |
315 | |
316 | /** | |
317 | @overload | |
318 | */ | |
7c913512 | 319 | void DrawCircle(const wxPoint& pt, wxCoord radius); |
23324ae1 | 320 | |
23324ae1 | 321 | /** |
f09b5681 BP |
322 | Draws an ellipse contained in the rectangle specified either with the |
323 | given top left corner and the given size or directly. The current pen | |
324 | is used for the outline and the current brush for filling the shape. | |
3c4f71cc | 325 | |
4cc4bfaf | 326 | @see DrawCircle() |
23324ae1 | 327 | */ |
f09b5681 | 328 | void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height); |
e3995493 FM |
329 | |
330 | /** | |
331 | @overload | |
332 | */ | |
7c913512 | 333 | void DrawEllipse(const wxPoint& pt, const wxSize& size); |
e3995493 FM |
334 | |
335 | /** | |
336 | @overload | |
337 | */ | |
7c913512 | 338 | void DrawEllipse(const wxRect& rect); |
23324ae1 FM |
339 | |
340 | /** | |
f09b5681 BP |
341 | Draws an arc of an ellipse. The current pen is used for drawing the arc |
342 | and the current brush is used for drawing the pie. | |
343 | ||
344 | @a x and @a y specify the x and y coordinates of the upper-left corner | |
345 | of the rectangle that contains the ellipse. | |
346 | ||
347 | @a width and @a height specify the width and height of the rectangle | |
348 | that contains the ellipse. | |
349 | ||
350 | @a start and @a end specify the start and end of the arc relative to | |
351 | the three-o'clock position from the center of the rectangle. Angles are | |
352 | specified in degrees (360 is a complete circle). Positive values mean | |
353 | counter-clockwise motion. If @a start is equal to @e end, a complete | |
354 | ellipse will be drawn. | |
23324ae1 | 355 | */ |
f09b5681 BP |
356 | void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height, |
357 | double start, double end); | |
23324ae1 | 358 | |
83b4d26c VZ |
359 | /** |
360 | @overload | |
361 | */ | |
362 | void DrawEllipticArc(const wxPoint& pt, const wxSize& sz, | |
363 | double sa, double ea); | |
364 | ||
23324ae1 | 365 | /** |
f09b5681 BP |
366 | Draw an icon on the display (does nothing if the device context is |
367 | PostScript). This can be the simplest way of drawing bitmaps on a | |
368 | window. | |
23324ae1 FM |
369 | */ |
370 | void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y); | |
371 | ||
83b4d26c VZ |
372 | /** |
373 | @overload | |
374 | */ | |
375 | void DrawIcon(const wxIcon& icon, const wxPoint& pt); | |
376 | ||
23324ae1 | 377 | /** |
f09b5681 BP |
378 | Draw optional bitmap and the text into the given rectangle and aligns |
379 | it as specified by alignment parameter; it also will emphasize the | |
380 | character with the given index if it is != -1 and return the bounding | |
381 | rectangle if required. | |
23324ae1 | 382 | */ |
9a077460 | 383 | void DrawLabel(const wxString& text, const wxBitmap& bitmap, |
882678eb FM |
384 | const wxRect& rect, |
385 | int alignment = wxALIGN_LEFT | wxALIGN_TOP, | |
386 | int indexAccel = -1, wxRect* rectBounding = NULL); | |
e3995493 FM |
387 | |
388 | /** | |
389 | @overload | |
390 | */ | |
7c913512 FM |
391 | void DrawLabel(const wxString& text, const wxRect& rect, |
392 | int alignment = wxALIGN_LEFT | wxALIGN_TOP, | |
393 | int indexAccel = -1); | |
23324ae1 FM |
394 | |
395 | /** | |
f09b5681 BP |
396 | Draws a line from the first point to the second. The current pen is |
397 | used for drawing the line. Note that the point (@a x2, @a y2) is not | |
398 | part of the line and is not drawn by this function (this is consistent | |
399 | with the behaviour of many other toolkits). | |
23324ae1 FM |
400 | */ |
401 | void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2); | |
402 | ||
83b4d26c VZ |
403 | /** |
404 | @overload | |
405 | */ | |
406 | void DrawLine(const wxPoint& pt1, const wxPoint& pt2); | |
407 | ||
23324ae1 | 408 | /** |
f09b5681 BP |
409 | Draws lines using an array of points of size @a n adding the optional |
410 | offset coordinate. The current pen is used for drawing the lines. | |
411 | ||
412 | @beginWxPythonOnly | |
413 | The wxPython version of this method accepts a Python list of wxPoint | |
414 | objects. | |
415 | @endWxPythonOnly | |
1058f652 MB |
416 | |
417 | @beginWxPerlOnly | |
418 | Not supported by wxPerl. | |
419 | @endWxPerlOnly | |
23324ae1 FM |
420 | */ |
421 | void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0, | |
422 | wxCoord yoffset = 0); | |
f09b5681 BP |
423 | /** |
424 | This method uses a list of wxPoints, adding the optional offset | |
425 | coordinate. The programmer is responsible for deleting the list of | |
426 | points. | |
427 | ||
428 | @beginWxPythonOnly | |
429 | The wxPython version of this method accepts a Python list of wxPoint | |
430 | objects. | |
431 | @endWxPythonOnly | |
1058f652 MB |
432 | |
433 | @beginWxPerlOnly | |
434 | The wxPerl version of this method accepts | |
435 | as its first parameter a reference to an array | |
436 | of wxPoint objects. | |
437 | @endWxPerlOnly | |
f09b5681 | 438 | */ |
4cc4bfaf | 439 | void DrawLines(const wxPointList* points, |
f09b5681 | 440 | wxCoord xoffset = 0, wxCoord yoffset = 0); |
23324ae1 FM |
441 | |
442 | /** | |
443 | Draws a point using the color of the current pen. Note that the other | |
f09b5681 | 444 | properties of the pen are not used, such as width. |
23324ae1 FM |
445 | */ |
446 | void DrawPoint(wxCoord x, wxCoord y); | |
447 | ||
83b4d26c VZ |
448 | /** |
449 | @overload | |
450 | */ | |
451 | void DrawPoint(const wxPoint& pt); | |
452 | ||
23324ae1 | 453 | /** |
f09b5681 BP |
454 | Draws a filled polygon using an array of points of size @a n, adding |
455 | the optional offset coordinate. The first and last points are | |
456 | automatically closed. | |
23324ae1 | 457 | |
f09b5681 BP |
458 | The last argument specifies the fill rule: @b wxODDEVEN_RULE (the |
459 | default) or @b wxWINDING_RULE. | |
460 | ||
461 | The current pen is used for drawing the outline, and the current brush | |
462 | for filling the shape. Using a transparent brush suppresses filling. | |
1058f652 MB |
463 | |
464 | @beginWxPerlOnly | |
465 | Not supported by wxPerl. | |
466 | @endWxPerlOnly | |
f09b5681 BP |
467 | */ |
468 | void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0, | |
89efaf2b FM |
469 | wxCoord yoffset = 0, |
470 | wxPolygonFillMode fill_style = wxODDEVEN_RULE); | |
23324ae1 | 471 | /** |
f09b5681 BP |
472 | This method draws a filled polygon using a list of wxPoints, adding the |
473 | optional offset coordinate. The first and last points are automatically | |
474 | closed. | |
475 | ||
23324ae1 FM |
476 | The last argument specifies the fill rule: @b wxODDEVEN_RULE (the |
477 | default) or @b wxWINDING_RULE. | |
f09b5681 | 478 | |
23324ae1 | 479 | The current pen is used for drawing the outline, and the current brush |
f09b5681 BP |
480 | for filling the shape. Using a transparent brush suppresses filling. |
481 | ||
23324ae1 | 482 | The programmer is responsible for deleting the list of points. |
f09b5681 BP |
483 | |
484 | @beginWxPythonOnly | |
485 | The wxPython version of this method accepts a Python list of wxPoint | |
486 | objects. | |
487 | @endWxPythonOnly | |
1058f652 MB |
488 | |
489 | @beginWxPerlOnly | |
490 | The wxPerl version of this method accepts | |
491 | as its first parameter a reference to an array | |
492 | of wxPoint objects. | |
493 | @endWxPerlOnly | |
23324ae1 | 494 | */ |
4cc4bfaf | 495 | void DrawPolygon(const wxPointList* points, |
f09b5681 | 496 | wxCoord xoffset = 0, wxCoord yoffset = 0, |
89efaf2b | 497 | wxPolygonFillMode fill_style = wxODDEVEN_RULE); |
f09b5681 BP |
498 | |
499 | /** | |
500 | Draws two or more filled polygons using an array of @a points, adding | |
501 | the optional offset coordinates. | |
502 | ||
503 | Notice that for the platforms providing a native implementation of this | |
504 | function (Windows and PostScript-based wxDC currently), this is more | |
505 | efficient than using DrawPolygon() in a loop. | |
506 | ||
507 | @a n specifies the number of polygons to draw, the array @e count of | |
508 | size @a n specifies the number of points in each of the polygons in the | |
509 | @a points array. | |
510 | ||
511 | The last argument specifies the fill rule: @b wxODDEVEN_RULE (the | |
512 | default) or @b wxWINDING_RULE. | |
513 | ||
514 | The current pen is used for drawing the outline, and the current brush | |
515 | for filling the shape. Using a transparent brush suppresses filling. | |
516 | ||
517 | The polygons maybe disjoint or overlapping. Each polygon specified in a | |
518 | call to DrawPolyPolygon() must be closed. Unlike polygons created by | |
519 | the DrawPolygon() member function, the polygons created by this | |
520 | method are not closed automatically. | |
521 | ||
522 | @beginWxPythonOnly | |
523 | Not implemented yet. | |
524 | @endWxPythonOnly | |
525 | */ | |
526 | void DrawPolyPolygon(int n, int count[], wxPoint points[], | |
527 | wxCoord xoffset = 0, wxCoord yoffset = 0, | |
89efaf2b | 528 | wxPolygonFillMode fill_style = wxODDEVEN_RULE); |
23324ae1 FM |
529 | |
530 | /** | |
531 | Draws a rectangle with the given top left corner, and with the given | |
532 | size. The current pen is used for the outline and the current brush | |
533 | for filling the shape. | |
534 | */ | |
f09b5681 | 535 | void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height); |
23324ae1 | 536 | |
83b4d26c VZ |
537 | /** |
538 | @overload | |
539 | */ | |
540 | void DrawRectangle(const wxPoint& pt, const wxSize& sz); | |
541 | ||
542 | /** | |
543 | @overload | |
544 | */ | |
545 | void DrawRectangle(const wxRect& rect); | |
546 | ||
23324ae1 | 547 | /** |
aff647c1 FM |
548 | Draws the text rotated by @a angle degrees |
549 | (positive angles are counterclockwise; the full angle is 360 degrees). | |
f09b5681 | 550 | |
1f1d2182 | 551 | @note Under Win9x only TrueType fonts can be drawn by this function. In |
f09b5681 BP |
552 | particular, a font different from @c wxNORMAL_FONT should be used |
553 | as the latter is not a TrueType font. @c wxSWISS_FONT is an | |
554 | example of a font which is. | |
3c4f71cc | 555 | |
4cc4bfaf | 556 | @see DrawText() |
23324ae1 FM |
557 | */ |
558 | void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, | |
559 | double angle); | |
560 | ||
83b4d26c VZ |
561 | /** |
562 | @overload | |
563 | */ | |
8ff9b17d | 564 | void DrawRotatedText(const wxString& text, const wxPoint& point, |
83b4d26c VZ |
565 | double angle); |
566 | ||
23324ae1 FM |
567 | /** |
568 | Draws a rectangle with the given top left corner, and with the given | |
f09b5681 | 569 | size. The corners are quarter-circles using the given radius. The |
23324ae1 FM |
570 | current pen is used for the outline and the current brush for filling |
571 | the shape. | |
f09b5681 BP |
572 | |
573 | If @a radius is positive, the value is assumed to be the radius of the | |
574 | rounded corner. If @a radius is negative, the absolute value is assumed | |
575 | to be the @e proportion of the smallest dimension of the rectangle. | |
576 | This means that the corner can be a sensible size relative to the size | |
577 | of the rectangle, and also avoids the strange effects X produces when | |
578 | the corners are too big for the rectangle. | |
23324ae1 FM |
579 | */ |
580 | void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, | |
f09b5681 | 581 | wxCoord height, double radius); |
23324ae1 | 582 | |
83b4d26c VZ |
583 | /** |
584 | @overload | |
585 | */ | |
586 | void DrawRoundedRectangle(const wxPoint& pt, const wxSize& sz, | |
587 | double radius); | |
588 | ||
589 | /** | |
590 | @overload | |
591 | */ | |
592 | void DrawRoundedRectangle(const wxRect& rect, double radius); | |
593 | ||
23324ae1 | 594 | /** |
f09b5681 BP |
595 | Draws a spline between all given points using the current pen. |
596 | ||
597 | @beginWxPythonOnly | |
598 | The wxPython version of this method accepts a Python list of wxPoint | |
599 | objects. | |
600 | @endWxPythonOnly | |
1058f652 MB |
601 | |
602 | @beginWxPerlOnly | |
603 | Not supported by wxPerl. | |
604 | @endWxPerlOnly | |
23324ae1 FM |
605 | */ |
606 | void DrawSpline(int n, wxPoint points[]); | |
e3995493 FM |
607 | |
608 | /** | |
609 | @overload | |
1058f652 MB |
610 | |
611 | ||
612 | @beginWxPerlOnly | |
613 | The wxPerl version of this method accepts | |
614 | as its first parameter a reference to an array | |
615 | of wxPoint objects. | |
616 | @endWxPerlOnly | |
e3995493 | 617 | */ |
4cc4bfaf | 618 | void DrawSpline(const wxPointList* points); |
e3995493 FM |
619 | |
620 | /** | |
621 | @overload | |
1058f652 MB |
622 | |
623 | ||
624 | @beginWxPerlOnly | |
625 | Not supported by wxPerl. | |
626 | @endWxPerlOnly | |
e3995493 | 627 | */ |
f09b5681 BP |
628 | void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, |
629 | wxCoord x3, wxCoord y3); | |
23324ae1 FM |
630 | |
631 | /** | |
f09b5681 BP |
632 | Draws a text string at the specified point, using the current text |
633 | font, and the current text foreground and background colours. | |
634 | ||
23324ae1 | 635 | The coordinates refer to the top-left corner of the rectangle bounding |
f09b5681 | 636 | the string. See GetTextExtent() for how to get the dimensions of a text |
a5bb4514 VZ |
637 | string, which can be used to position the text more precisely and |
638 | DrawLabel() if you need to align the string differently. | |
639 | ||
640 | Starting from wxWidgets 2.9.2 @a text parameter can be a multi-line | |
641 | string, i.e. contain new line characters, and will be rendered | |
642 | correctly. | |
f09b5681 | 643 | |
408776d0 | 644 | @note The current @ref GetLogicalFunction() "logical function" is |
e928566f | 645 | ignored by this function. |
23324ae1 FM |
646 | */ |
647 | void DrawText(const wxString& text, wxCoord x, wxCoord y); | |
648 | ||
83b4d26c VZ |
649 | /** |
650 | @overload | |
651 | */ | |
652 | void DrawText(const wxString& text, const wxPoint& pt); | |
653 | ||
23324ae1 | 654 | /** |
e3995493 FM |
655 | Fill the area specified by rect with a radial gradient, starting from |
656 | @a initialColour at the centre of the circle and fading to | |
657 | @a destColour on the circle outside. | |
658 | ||
659 | The circle is placed at the centre of @a rect. | |
660 | ||
661 | @note Currently this function is very slow, don't use it for real-time | |
662 | drawing. | |
23324ae1 | 663 | */ |
e3995493 FM |
664 | void GradientFillConcentric(const wxRect& rect, |
665 | const wxColour& initialColour, | |
666 | const wxColour& destColour); | |
23324ae1 FM |
667 | |
668 | /** | |
e3995493 FM |
669 | Fill the area specified by rect with a radial gradient, starting from |
670 | @a initialColour at the centre of the circle and fading to | |
671 | @a destColour on the circle outside. | |
672 | ||
673 | @a circleCenter are the relative coordinates of centre of the circle in | |
674 | the specified @a rect. | |
675 | ||
676 | @note Currently this function is very slow, don't use it for real-time | |
677 | drawing. | |
23324ae1 | 678 | */ |
e3995493 FM |
679 | void GradientFillConcentric(const wxRect& rect, |
680 | const wxColour& initialColour, | |
681 | const wxColour& destColour, | |
682 | const wxPoint& circleCenter); | |
683 | ||
684 | /** | |
685 | Fill the area specified by @a rect with a linear gradient, starting | |
686 | from @a initialColour and eventually fading to @e destColour. | |
687 | ||
688 | The @a nDirection specifies the direction of the colour change, default is | |
689 | to use @a initialColour on the left part of the rectangle and | |
690 | @a destColour on the right one. | |
691 | */ | |
692 | void GradientFillLinear(const wxRect& rect, const wxColour& initialColour, | |
693 | const wxColour& destColour, | |
694 | wxDirection nDirection = wxRIGHT); | |
23324ae1 FM |
695 | |
696 | /** | |
697 | Flood fills the device context starting from the given point, using | |
f09b5681 BP |
698 | the current brush colour, and using a style: |
699 | ||
700 | - wxFLOOD_SURFACE: The flooding occurs until a colour other than the | |
701 | given colour is encountered. | |
702 | - wxFLOOD_BORDER: The area to be flooded is bounded by the given | |
703 | colour. | |
704 | ||
d29a9a8a | 705 | @return @false if the operation failed. |
f09b5681 BP |
706 | |
707 | @note The present implementation for non-Windows platforms may fail to | |
708 | find colour borders if the pixels do not match the colour | |
709 | exactly. However the function will still return @true. | |
23324ae1 FM |
710 | */ |
711 | bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour, | |
89efaf2b | 712 | wxFloodFillStyle style = wxFLOOD_SURFACE); |
23324ae1 | 713 | |
83b4d26c VZ |
714 | /** |
715 | @overload | |
716 | */ | |
717 | bool FloodFill(const wxPoint& pt, const wxColour& col, | |
8ff9b17d | 718 | wxFloodFillStyle style = wxFLOOD_SURFACE); |
83b4d26c | 719 | |
23324ae1 | 720 | /** |
e3995493 FM |
721 | Displays a cross hair using the current pen. This is a vertical and |
722 | horizontal line the height and width of the window, centred on the | |
723 | given point. | |
23324ae1 | 724 | */ |
e3995493 | 725 | void CrossHair(wxCoord x, wxCoord y); |
23324ae1 | 726 | |
83b4d26c VZ |
727 | /** |
728 | @overload | |
729 | */ | |
730 | void CrossHair(const wxPoint& pt); | |
731 | ||
e3995493 | 732 | //@} |
3c4f71cc | 733 | |
23324ae1 FM |
734 | |
735 | /** | |
e3995493 | 736 | @name Clipping region functions |
23324ae1 | 737 | */ |
e3995493 | 738 | //@{ |
23324ae1 FM |
739 | |
740 | /** | |
e3995493 | 741 | Destroys the current clipping region so that none of the DC is clipped. |
23324ae1 | 742 | |
e3995493 | 743 | @see SetClippingRegion() |
23324ae1 | 744 | */ |
e3995493 | 745 | void DestroyClippingRegion(); |
23324ae1 FM |
746 | |
747 | /** | |
748 | Gets the rectangle surrounding the current clipping region. | |
f09b5681 BP |
749 | |
750 | @beginWxPythonOnly | |
751 | No arguments are required and the four values defining the rectangle | |
752 | are returned as a tuple. | |
753 | @endWxPythonOnly | |
23324ae1 | 754 | */ |
408776d0 | 755 | void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const; |
23324ae1 FM |
756 | |
757 | /** | |
e3995493 FM |
758 | Sets the clipping region for this device context to the intersection of |
759 | the given region described by the parameters of this method and the | |
3821ccfa | 760 | previously set clipping region. |
3c4f71cc | 761 | |
e3995493 FM |
762 | The clipping region is an area to which drawing is restricted. Possible |
763 | uses for the clipping region are for clipping text or for speeding up | |
764 | window redraws when only a known area of the screen is damaged. | |
23324ae1 | 765 | |
3821ccfa VZ |
766 | Notice that you need to call DestroyClippingRegion() if you want to set |
767 | the clipping region exactly to the region specified. | |
768 | ||
769 | Also note that if the clipping region is empty, any previously set | |
770 | clipping region is destroyed, i.e. it is equivalent to calling | |
771 | DestroyClippingRegion(), and not to clipping out all drawing on the DC | |
772 | as might be expected. | |
773 | ||
e3995493 | 774 | @see DestroyClippingRegion(), wxRegion |
23324ae1 | 775 | */ |
e3995493 | 776 | void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height); |
23324ae1 FM |
777 | |
778 | /** | |
e3995493 | 779 | @overload |
23324ae1 | 780 | */ |
e3995493 | 781 | void SetClippingRegion(const wxPoint& pt, const wxSize& sz); |
23324ae1 FM |
782 | |
783 | /** | |
e3995493 | 784 | @overload |
23324ae1 | 785 | */ |
e3995493 | 786 | void SetClippingRegion(const wxRect& rect); |
23324ae1 FM |
787 | |
788 | /** | |
e3995493 | 789 | Sets the clipping region for this device context. |
f09b5681 | 790 | |
e3995493 FM |
791 | Unlike SetClippingRegion(), this function works with physical |
792 | coordinates and not with the logical ones. | |
793 | */ | |
794 | void SetDeviceClippingRegion(const wxRegion& region); | |
795 | ||
796 | //@} | |
797 | ||
798 | ||
799 | /** | |
800 | @name Text/character extent functions | |
23324ae1 | 801 | */ |
e3995493 FM |
802 | //@{ |
803 | ||
804 | /** | |
805 | Gets the character height of the currently set font. | |
806 | */ | |
807 | wxCoord GetCharHeight() const; | |
808 | ||
809 | /** | |
810 | Gets the average character width of the currently set font. | |
811 | */ | |
812 | wxCoord GetCharWidth() const; | |
23324ae1 | 813 | |
e29bf4b0 VZ |
814 | /** |
815 | Returns the various font characteristics. | |
816 | ||
817 | This method allows to retrieve some of the font characteristics not | |
818 | returned by GetTextExtent(), notably internal leading and average | |
819 | character width. | |
820 | ||
821 | Currently this method returns correct results only under wxMSW, in the | |
822 | other ports the internal leading will always be 0 and the average | |
823 | character width will be computed as the width of the character 'x'. | |
824 | ||
825 | @since 2.9.2 | |
826 | */ | |
827 | wxFontMetrics GetFontMetrics() const; | |
828 | ||
23324ae1 FM |
829 | /** |
830 | Gets the dimensions of the string using the currently selected font. | |
4cc4bfaf | 831 | @a string is the text string to measure, @e heightLine, if non @NULL, |
23324ae1 | 832 | is where to store the height of a single line. |
f09b5681 BP |
833 | |
834 | The text extent is set in the given @a w and @a h pointers. | |
835 | ||
836 | If the optional parameter @a font is specified and valid, then it is | |
837 | used for the text extent calculation, otherwise the currently selected | |
838 | font is used. | |
839 | ||
840 | @note This function works with both single-line and multi-line strings. | |
3c4f71cc | 841 | |
1058f652 MB |
842 | @beginWxPerlOnly |
843 | In wxPerl this method is implemented as | |
844 | GetMultiLineTextExtent(string, font = undef) returning a | |
845 | 3-element list (width, height, line_height) | |
846 | @endWxPerlOnly | |
847 | ||
4cc4bfaf | 848 | @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() |
23324ae1 | 849 | */ |
4cc4bfaf FM |
850 | void GetMultiLineTextExtent(const wxString& string, wxCoord* w, |
851 | wxCoord* h, | |
852 | wxCoord* heightLine = NULL, | |
408776d0 | 853 | const wxFont* font = NULL) const; |
23324ae1 | 854 | /** |
f09b5681 BP |
855 | Gets the dimensions of the string using the currently selected font. |
856 | @a string is the text string to measure, @e heightLine, if non @NULL, | |
857 | is where to store the height of a single line. | |
858 | ||
d29a9a8a | 859 | @return The text extent as a wxSize object. |
f09b5681 BP |
860 | |
861 | @note This function works with both single-line and multi-line strings. | |
862 | ||
1058f652 MB |
863 | @beginWxPerlOnly |
864 | Not supported by wxPerl. | |
865 | @endWxPerlOnly | |
866 | ||
f09b5681 | 867 | @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() |
23324ae1 | 868 | */ |
408776d0 | 869 | wxSize GetMultiLineTextExtent(const wxString& string) const; |
23324ae1 FM |
870 | |
871 | /** | |
f09b5681 BP |
872 | Fills the @a widths array with the widths from the beginning of @a text |
873 | to the corresponding character of @a text. The generic version simply | |
874 | builds a running total of the widths of each character using | |
875 | GetTextExtent(), however if the various platforms have a native API | |
876 | function that is faster or more accurate than the generic | |
877 | implementation then it should be used instead. | |
878 | ||
879 | @beginWxPythonOnly | |
880 | This method only takes the @a text parameter and returns a Python list | |
881 | of integers. | |
882 | @endWxPythonOnly | |
3c4f71cc | 883 | |
1058f652 MB |
884 | @beginWxPerlOnly |
885 | In wxPerl this method only takes the @a text parameter and | |
886 | returns the widths as a list of integers. | |
887 | @endWxPerlOnly | |
888 | ||
4cc4bfaf | 889 | @see GetMultiLineTextExtent(), GetTextExtent() |
23324ae1 FM |
890 | */ |
891 | bool GetPartialTextExtents(const wxString& text, | |
328f5751 | 892 | wxArrayInt& widths) const; |
23324ae1 | 893 | |
23324ae1 FM |
894 | /** |
895 | Gets the dimensions of the string using the currently selected font. | |
f09b5681 BP |
896 | @a string is the text string to measure, @a descent is the dimension |
897 | from the baseline of the font to the bottom of the descender, and | |
898 | @a externalLeading is any extra vertical space added to the font by the | |
899 | font designer (usually is zero). | |
900 | ||
901 | The text extent is returned in @a w and @a h pointers or as a wxSize | |
902 | object depending on which version of this function is used. | |
903 | ||
904 | If the optional parameter @a font is specified and valid, then it is | |
905 | used for the text extent calculation. Otherwise the currently selected | |
906 | font is. | |
907 | ||
908 | @note This function only works with single-line strings. | |
909 | ||
910 | @beginWxPythonOnly | |
911 | The following methods are implemented in wxPython: | |
912 | - GetTextExtent(string) - Returns a 2-tuple, (width, height). | |
913 | - GetFullTextExtent(string, font=NULL) - | |
914 | Returns a 4-tuple, (width, height, descent, externalLeading). | |
915 | @endWxPythonOnly | |
3c4f71cc | 916 | |
1058f652 MB |
917 | @beginWxPerlOnly |
918 | In wxPerl this method is implemented as GetTextExtent(string, | |
919 | font = undef) returning a 4-element list (width, height, | |
920 | descent, externalLeading) | |
921 | @endWxPerlOnly | |
922 | ||
4cc4bfaf FM |
923 | @see wxFont, SetFont(), GetPartialTextExtents(), |
924 | GetMultiLineTextExtent() | |
925 | */ | |
f09b5681 | 926 | void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h, |
4cc4bfaf FM |
927 | wxCoord* descent = NULL, |
928 | wxCoord* externalLeading = NULL, | |
328f5751 | 929 | const wxFont* font = NULL) const; |
e3995493 FM |
930 | |
931 | /** | |
932 | @overload | |
1058f652 MB |
933 | |
934 | ||
935 | @beginWxPerlOnly | |
936 | Not supported by wxPerl. | |
937 | @endWxPerlOnly | |
e3995493 | 938 | */ |
382f12e4 | 939 | wxSize GetTextExtent(const wxString& string) const; |
e3995493 | 940 | |
23324ae1 FM |
941 | //@} |
942 | ||
e3995493 | 943 | |
23324ae1 | 944 | /** |
e3995493 FM |
945 | @name Text properties functions |
946 | */ | |
947 | //@{ | |
f09b5681 | 948 | |
e3995493 FM |
949 | /** |
950 | Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. | |
951 | ||
952 | @see SetBackgroundMode() | |
23324ae1 | 953 | */ |
e3995493 | 954 | int GetBackgroundMode() const; |
23324ae1 FM |
955 | |
956 | /** | |
ac55e6b0 FM |
957 | Gets the current font. |
958 | ||
959 | Notice that even although each device context object has some default font | |
960 | after creation, this method would return a ::wxNullFont initially and only | |
961 | after calling SetFont() a valid font is returned. | |
e3995493 FM |
962 | */ |
963 | const wxFont& GetFont() const; | |
f09b5681 | 964 | |
e3995493 FM |
965 | /** |
966 | Gets the current layout direction of the device context. On platforms | |
967 | where RTL layout is supported, the return value will either be | |
968 | @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is | |
969 | not supported, the return value will be @c wxLayout_Default. | |
970 | ||
971 | @see SetLayoutDirection() | |
23324ae1 | 972 | */ |
e3995493 | 973 | wxLayoutDirection GetLayoutDirection() const; |
23324ae1 | 974 | |
23324ae1 | 975 | /** |
e3995493 | 976 | Gets the current text background colour. |
f09b5681 | 977 | |
e3995493 FM |
978 | @see SetTextBackground() |
979 | */ | |
980 | const wxColour& GetTextBackground() const; | |
f09b5681 | 981 | |
e3995493 FM |
982 | /** |
983 | Gets the current text foreground colour. | |
984 | ||
985 | @see SetTextForeground() | |
23324ae1 | 986 | */ |
e3995493 | 987 | const wxColour& GetTextForeground() const; |
23324ae1 FM |
988 | |
989 | /** | |
ac55e6b0 FM |
990 | @a mode may be one of @c wxSOLID and @c wxTRANSPARENT. |
991 | ||
992 | This setting determines whether text will be drawn with a background | |
993 | colour or not. | |
23324ae1 | 994 | */ |
e3995493 | 995 | void SetBackgroundMode(int mode); |
23324ae1 FM |
996 | |
997 | /** | |
ac55e6b0 FM |
998 | Sets the current font for the DC. |
999 | ||
1000 | If the argument is ::wxNullFont (or another invalid font; see wxFont::IsOk), | |
1001 | the current font is selected out of the device context (leaving wxDC without | |
1002 | any valid font), allowing the current font to be destroyed safely. | |
e3995493 FM |
1003 | |
1004 | @see wxFont | |
23324ae1 | 1005 | */ |
e3995493 | 1006 | void SetFont(const wxFont& font); |
23324ae1 FM |
1007 | |
1008 | /** | |
e3995493 | 1009 | Sets the current text background colour for the DC. |
23324ae1 | 1010 | */ |
e3995493 | 1011 | void SetTextBackground(const wxColour& colour); |
23324ae1 FM |
1012 | |
1013 | /** | |
e3995493 FM |
1014 | Sets the current text foreground colour for the DC. |
1015 | ||
1016 | @see wxMemoryDC for the interpretation of colours when drawing into a | |
1017 | monochrome bitmap. | |
23324ae1 | 1018 | */ |
e3995493 | 1019 | void SetTextForeground(const wxColour& colour); |
23324ae1 FM |
1020 | |
1021 | /** | |
ac55e6b0 FM |
1022 | Sets the current layout direction for the device context. |
1023 | ||
1024 | @param dir | |
1025 | May be either @c wxLayout_Default, @c wxLayout_LeftToRight or | |
1026 | @c wxLayout_RightToLeft. | |
e3995493 FM |
1027 | |
1028 | @see GetLayoutDirection() | |
23324ae1 | 1029 | */ |
e3995493 FM |
1030 | void SetLayoutDirection(wxLayoutDirection dir); |
1031 | ||
1032 | //@} | |
1033 | ||
23324ae1 FM |
1034 | |
1035 | /** | |
e3995493 | 1036 | @name Bounding box functions |
23324ae1 | 1037 | */ |
e3995493 FM |
1038 | //@{ |
1039 | ||
1040 | /** | |
1041 | Adds the specified point to the bounding box which can be retrieved | |
1042 | with MinX(), MaxX() and MinY(), MaxY() functions. | |
1043 | ||
1044 | @see ResetBoundingBox() | |
1045 | */ | |
1046 | void CalcBoundingBox(wxCoord x, wxCoord y); | |
23324ae1 FM |
1047 | |
1048 | /** | |
1049 | Gets the maximum horizontal extent used in drawing commands so far. | |
1050 | */ | |
adaaa686 | 1051 | wxCoord MaxX() const; |
23324ae1 FM |
1052 | |
1053 | /** | |
1054 | Gets the maximum vertical extent used in drawing commands so far. | |
1055 | */ | |
adaaa686 | 1056 | wxCoord MaxY() const; |
23324ae1 FM |
1057 | |
1058 | /** | |
1059 | Gets the minimum horizontal extent used in drawing commands so far. | |
1060 | */ | |
adaaa686 | 1061 | wxCoord MinX() const; |
23324ae1 FM |
1062 | |
1063 | /** | |
1064 | Gets the minimum vertical extent used in drawing commands so far. | |
1065 | */ | |
adaaa686 | 1066 | wxCoord MinY() const; |
23324ae1 FM |
1067 | |
1068 | /** | |
f09b5681 BP |
1069 | Resets the bounding box: after a call to this function, the bounding |
1070 | box doesn't contain anything. | |
3c4f71cc | 1071 | |
4cc4bfaf | 1072 | @see CalcBoundingBox() |
23324ae1 FM |
1073 | */ |
1074 | void ResetBoundingBox(); | |
1075 | ||
e3995493 | 1076 | //@} |
3c4f71cc | 1077 | |
23324ae1 FM |
1078 | |
1079 | /** | |
e3995493 | 1080 | @name Page and document start/end functions |
23324ae1 | 1081 | */ |
e3995493 | 1082 | //@{ |
23324ae1 FM |
1083 | |
1084 | /** | |
e3995493 FM |
1085 | Starts a document (only relevant when outputting to a printer). |
1086 | @a message is a message to show while printing. | |
23324ae1 | 1087 | */ |
e3995493 | 1088 | bool StartDoc(const wxString& message); |
23324ae1 FM |
1089 | |
1090 | /** | |
e3995493 | 1091 | Starts a document page (only relevant when outputting to a printer). |
23324ae1 | 1092 | */ |
e3995493 | 1093 | void StartPage(); |
23324ae1 | 1094 | |
23324ae1 | 1095 | /** |
e3995493 FM |
1096 | Ends a document (only relevant when outputting to a printer). |
1097 | */ | |
1098 | void EndDoc(); | |
3c4f71cc | 1099 | |
e3995493 FM |
1100 | /** |
1101 | Ends a document page (only relevant when outputting to a printer). | |
23324ae1 | 1102 | */ |
e3995493 FM |
1103 | void EndPage(); |
1104 | ||
23324ae1 FM |
1105 | //@} |
1106 | ||
23324ae1 FM |
1107 | |
1108 | /** | |
e3995493 | 1109 | @name Bit-Block Transfer operations (blit) |
23324ae1 | 1110 | */ |
e3995493 | 1111 | //@{ |
23324ae1 FM |
1112 | |
1113 | /** | |
e3995493 FM |
1114 | Copy from a source DC to this DC, specifying the destination |
1115 | coordinates, size of area to copy, source DC, source coordinates, | |
1116 | logical function, whether to use a bitmap mask, and mask source | |
1117 | position. | |
23324ae1 | 1118 | |
e3995493 FM |
1119 | @param xdest |
1120 | Destination device context x position. | |
1121 | @param ydest | |
1122 | Destination device context y position. | |
1123 | @param width | |
1124 | Width of source area to be copied. | |
1125 | @param height | |
1126 | Height of source area to be copied. | |
1127 | @param source | |
1128 | Source device context. | |
1129 | @param xsrc | |
1130 | Source device context x position. | |
1131 | @param ysrc | |
1132 | Source device context y position. | |
1133 | @param logicalFunc | |
1134 | Logical function to use, see SetLogicalFunction(). | |
1135 | @param useMask | |
1136 | If @true, Blit does a transparent blit using the mask that is | |
1137 | associated with the bitmap selected into the source device context. | |
1138 | The Windows implementation does the following if MaskBlt cannot be | |
1139 | used: | |
1140 | <ol> | |
1141 | <li>Creates a temporary bitmap and copies the destination area into | |
1142 | it.</li> | |
1143 | <li>Copies the source area into the temporary bitmap using the | |
1144 | specified logical function.</li> | |
1145 | <li>Sets the masked area in the temporary bitmap to BLACK by ANDing | |
1146 | the mask bitmap with the temp bitmap with the foreground colour | |
1147 | set to WHITE and the bg colour set to BLACK.</li> | |
1148 | <li>Sets the unmasked area in the destination area to BLACK by | |
1149 | ANDing the mask bitmap with the destination area with the | |
1150 | foreground colour set to BLACK and the background colour set to | |
1151 | WHITE.</li> | |
1152 | <li>ORs the temporary bitmap with the destination area.</li> | |
1153 | <li>Deletes the temporary bitmap.</li> | |
1154 | </ol> | |
1155 | This sequence of operations ensures that the source's transparent | |
1156 | area need not be black, and logical functions are supported. | |
1157 | @n @b Note: on Windows, blitting with masks can be speeded up | |
519d7f23 | 1158 | considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option |
e3995493 FM |
1159 | enabled. You can also influence whether MaskBlt or the explicit |
1160 | mask blitting code above is used, by using wxSystemOptions and | |
1161 | setting the @c no-maskblt option to 1. | |
1162 | @param xsrcMask | |
1163 | Source x position on the mask. If both xsrcMask and ysrcMask are | |
1164 | @c -1, xsrc and ysrc will be assumed for the mask source position. | |
1165 | Currently only implemented on Windows. | |
1166 | @param ysrcMask | |
1167 | Source y position on the mask. If both xsrcMask and ysrcMask are | |
1168 | @c -1, xsrc and ysrc will be assumed for the mask source position. | |
1169 | Currently only implemented on Windows. | |
23324ae1 | 1170 | |
e3995493 | 1171 | @remarks There is partial support for Blit() in wxPostScriptDC, under X. |
23324ae1 | 1172 | |
e3995493 | 1173 | @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask |
23324ae1 | 1174 | */ |
e3995493 FM |
1175 | bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, |
1176 | wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc, | |
1177 | wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false, | |
1178 | wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord); | |
23324ae1 FM |
1179 | |
1180 | /** | |
1181 | Copy from a source DC to this DC, specifying the destination | |
f09b5681 BP |
1182 | coordinates, destination size, source DC, source coordinates, size of |
1183 | source area to copy, logical function, whether to use a bitmap mask, | |
23324ae1 | 1184 | and mask source position. |
3c4f71cc | 1185 | |
7c913512 | 1186 | @param xdest |
4cc4bfaf | 1187 | Destination device context x position. |
7c913512 | 1188 | @param ydest |
4cc4bfaf | 1189 | Destination device context y position. |
7c913512 | 1190 | @param dstWidth |
4cc4bfaf | 1191 | Width of destination area. |
7c913512 | 1192 | @param dstHeight |
4cc4bfaf | 1193 | Height of destination area. |
7c913512 | 1194 | @param source |
4cc4bfaf | 1195 | Source device context. |
7c913512 | 1196 | @param xsrc |
4cc4bfaf | 1197 | Source device context x position. |
7c913512 | 1198 | @param ysrc |
4cc4bfaf | 1199 | Source device context y position. |
7c913512 | 1200 | @param srcWidth |
4cc4bfaf | 1201 | Width of source area to be copied. |
7c913512 | 1202 | @param srcHeight |
4cc4bfaf | 1203 | Height of source area to be copied. |
7c913512 | 1204 | @param logicalFunc |
f09b5681 | 1205 | Logical function to use, see SetLogicalFunction(). |
7c913512 | 1206 | @param useMask |
f09b5681 BP |
1207 | If @true, Blit does a transparent blit using the mask that is |
1208 | associated with the bitmap selected into the source device context. | |
1209 | The Windows implementation does the following if MaskBlt cannot be | |
1210 | used: | |
1211 | <ol> | |
1212 | <li>Creates a temporary bitmap and copies the destination area into | |
1213 | it.</li> | |
1214 | <li>Copies the source area into the temporary bitmap using the | |
1215 | specified logical function.</li> | |
1216 | <li>Sets the masked area in the temporary bitmap to BLACK by ANDing | |
1217 | the mask bitmap with the temp bitmap with the foreground colour | |
1218 | set to WHITE and the bg colour set to BLACK.</li> | |
1219 | <li>Sets the unmasked area in the destination area to BLACK by | |
1220 | ANDing the mask bitmap with the destination area with the | |
1221 | foreground colour set to BLACK and the background colour set to | |
1222 | WHITE.</li> | |
1223 | <li>ORs the temporary bitmap with the destination area.</li> | |
1224 | <li>Deletes the temporary bitmap.</li> | |
1225 | </ol> | |
1226 | This sequence of operations ensures that the source's transparent | |
1227 | area need not be black, and logical functions are supported. | |
1228 | @n @b Note: on Windows, blitting with masks can be speeded up | |
519d7f23 | 1229 | considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option |
f09b5681 BP |
1230 | enabled. You can also influence whether MaskBlt or the explicit |
1231 | mask blitting code above is used, by using wxSystemOptions and | |
1232 | setting the @c no-maskblt option to 1. | |
7c913512 | 1233 | @param xsrcMask |
f09b5681 | 1234 | Source x position on the mask. If both xsrcMask and ysrcMask are |
408776d0 FM |
1235 | wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask |
1236 | source position. Currently only implemented on Windows. | |
7c913512 | 1237 | @param ysrcMask |
f09b5681 | 1238 | Source y position on the mask. If both xsrcMask and ysrcMask are |
408776d0 FM |
1239 | wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask |
1240 | source position. Currently only implemented on Windows. | |
f09b5681 BP |
1241 | |
1242 | There is partial support for Blit() in wxPostScriptDC, under X. | |
1243 | ||
1244 | StretchBlit() is only implemented under wxMAC and wxMSW. | |
1245 | ||
1246 | See wxMemoryDC for typical usage. | |
1247 | ||
1e24c2af | 1248 | @since 2.9.0 |
f09b5681 BP |
1249 | |
1250 | @see Blit(), wxMemoryDC, wxBitmap, wxMask | |
1251 | */ | |
1252 | bool StretchBlit(wxCoord xdest, wxCoord ydest, | |
1253 | wxCoord dstWidth, wxCoord dstHeight, | |
1254 | wxDC* source, wxCoord xsrc, wxCoord ysrc, | |
1255 | wxCoord srcWidth, wxCoord srcHeight, | |
89efaf2b | 1256 | wxRasterOperationMode logicalFunc = wxCOPY, |
4cc4bfaf | 1257 | bool useMask = false, |
408776d0 FM |
1258 | wxCoord xsrcMask = wxDefaultCoord, |
1259 | wxCoord ysrcMask = wxDefaultCoord); | |
e3995493 FM |
1260 | //@} |
1261 | ||
1262 | ||
1263 | /** | |
1264 | @name Background/foreground brush and pen | |
1265 | */ | |
1266 | //@{ | |
1267 | ||
1268 | /** | |
1269 | Gets the brush used for painting the background. | |
1270 | ||
1271 | @see wxDC::SetBackground() | |
1272 | */ | |
1273 | const wxBrush& GetBackground() const; | |
1274 | ||
1275 | /** | |
1276 | Gets the current brush. | |
1277 | ||
1278 | @see wxDC::SetBrush() | |
1279 | */ | |
1280 | const wxBrush& GetBrush() const; | |
1281 | ||
1282 | /** | |
1283 | Gets the current pen. | |
1284 | ||
1285 | @see SetPen() | |
1286 | */ | |
1287 | const wxPen& GetPen() const; | |
1288 | ||
1289 | /** | |
1290 | Sets the current background brush for the DC. | |
1291 | */ | |
1292 | void SetBackground(const wxBrush& brush); | |
1293 | ||
1294 | /** | |
1295 | Sets the current brush for the DC. | |
1296 | ||
ac55e6b0 FM |
1297 | If the argument is ::wxNullBrush (or another invalid brush; see wxBrush::IsOk), |
1298 | the current brush is selected out of the device context (leaving wxDC without | |
1299 | any valid brush), allowing the current brush to be destroyed safely. | |
e3995493 FM |
1300 | |
1301 | @see wxBrush, wxMemoryDC (for the interpretation of colours when | |
1302 | drawing into a monochrome bitmap) | |
1303 | */ | |
1304 | void SetBrush(const wxBrush& brush); | |
1305 | ||
1306 | /** | |
ac55e6b0 FM |
1307 | Sets the current pen for the DC. |
1308 | ||
1309 | If the argument is ::wxNullPen (or another invalid pen; see wxPen::IsOk), | |
1310 | the current pen is selected out of the device context (leaving wxDC without any | |
1311 | valid pen), allowing the current pen to be destroyed safely. | |
e3995493 FM |
1312 | |
1313 | @see wxMemoryDC for the interpretation of colours when drawing into a | |
1314 | monochrome bitmap. | |
1315 | */ | |
1316 | void SetPen(const wxPen& pen); | |
1317 | ||
1318 | //@} | |
1319 | ||
1320 | ||
4feecbb9 VZ |
1321 | /** |
1322 | Copy attributes from another DC. | |
1323 | ||
1324 | The copied attributes currently are: | |
1325 | - Font | |
1326 | - Text foreground and background colours | |
1327 | - Background brush | |
1328 | - Layout direction | |
1329 | ||
1330 | @param dc | |
1331 | A valid (i.e. its IsOk() must return @true) source device context. | |
1332 | */ | |
1333 | void CopyAttributes(const wxDC& dc); | |
e3995493 FM |
1334 | |
1335 | /** | |
1336 | Returns the depth (number of bits/pixel) of this DC. | |
1337 | ||
1338 | @see wxDisplayDepth() | |
1339 | */ | |
1340 | int GetDepth() const; | |
1341 | ||
1342 | /** | |
1343 | Returns the current device origin. | |
1344 | ||
1345 | @see SetDeviceOrigin() | |
1346 | */ | |
1347 | wxPoint GetDeviceOrigin() const; | |
1348 | ||
1349 | /** | |
1350 | Gets the current logical function. | |
1351 | ||
1352 | @see SetLogicalFunction() | |
1353 | */ | |
1354 | wxRasterOperationMode GetLogicalFunction() const; | |
1355 | ||
1356 | /** | |
1357 | Gets the current mapping mode for the device context. | |
1358 | ||
1359 | @see SetMapMode() | |
1360 | */ | |
1361 | wxMappingMode GetMapMode() const; | |
1362 | ||
1363 | /** | |
1364 | Gets in @a colour the colour at the specified location. Not available | |
1365 | for wxPostScriptDC or wxMetafileDC. | |
1366 | ||
1367 | @note Setting a pixel can be done using DrawPoint(). | |
1368 | ||
1369 | @beginWxPythonOnly | |
1370 | The wxColour value is returned and is not required as a parameter. | |
1371 | @endWxPythonOnly | |
1372 | */ | |
1373 | bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const; | |
1374 | ||
1375 | /** | |
1376 | Returns the resolution of the device in pixels per inch. | |
1377 | */ | |
1378 | wxSize GetPPI() const; | |
1379 | ||
1380 | /** | |
1381 | Gets the horizontal and vertical extent of this device context in @e device units. | |
1382 | It can be used to scale graphics to fit the page. | |
1383 | ||
1384 | For example, if @e maxX and @e maxY represent the maximum horizontal | |
1385 | and vertical 'pixel' values used in your application, the following | |
1386 | code will scale the graphic to fit on the printer page: | |
1387 | ||
1388 | @code | |
1389 | wxCoord w, h; | |
1390 | dc.GetSize(&w, &h); | |
1391 | double scaleX = (double)(maxX / w); | |
1392 | double scaleY = (double)(maxY / h); | |
1393 | dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY)); | |
1394 | @endcode | |
1395 | ||
1396 | @beginWxPythonOnly | |
1397 | In place of a single overloaded method name, wxPython implements the | |
1398 | following methods: | |
1399 | - GetSize() - Returns a wxSize. | |
1400 | - GetSizeWH() - Returns a 2-tuple (width, height). | |
1401 | @endWxPythonOnly | |
1058f652 MB |
1402 | |
1403 | @beginWxPerlOnly | |
1404 | In wxPerl there are two methods instead of a single overloaded | |
1405 | method: | |
1406 | - GetSize(): returns a Wx::Size object. | |
1407 | - GetSizeWH(): returns a 2-element list (width, height). | |
1408 | @endWxPerlOnly | |
e3995493 FM |
1409 | */ |
1410 | void GetSize(wxCoord* width, wxCoord* height) const; | |
1411 | ||
1412 | /** | |
1413 | @overload | |
1414 | */ | |
1415 | wxSize GetSize() const; | |
1416 | ||
1417 | /** | |
1418 | Returns the horizontal and vertical resolution in millimetres. | |
1419 | */ | |
1420 | void GetSizeMM(wxCoord* width, wxCoord* height) const; | |
1421 | ||
1422 | /** | |
1423 | @overload | |
1424 | */ | |
1425 | wxSize GetSizeMM() const; | |
1426 | ||
1427 | /** | |
1428 | Gets the current user scale factor. | |
1429 | ||
1058f652 MB |
1430 | @beginWxPerlOnly |
1431 | In wxPerl this method takes no arguments and return a two | |
1432 | element array (x, y). | |
1433 | @endWxPerlOnly | |
1434 | ||
e3995493 FM |
1435 | @see SetUserScale() |
1436 | */ | |
1437 | void GetUserScale(double* x, double* y) const; | |
1438 | ||
1439 | /** | |
1440 | Returns @true if the DC is ok to use. | |
1441 | */ | |
1442 | bool IsOk() const; | |
1443 | ||
1444 | /** | |
1445 | Sets the x and y axis orientation (i.e., the direction from lowest to | |
1446 | highest values on the axis). The default orientation is x axis from | |
1447 | left to right and y axis from top down. | |
1448 | ||
1449 | @param xLeftRight | |
1450 | True to set the x axis orientation to the natural left to right | |
1451 | orientation, @false to invert it. | |
1452 | @param yBottomUp | |
1453 | True to set the y axis orientation to the natural bottom up | |
1454 | orientation, @false to invert it. | |
1455 | */ | |
1456 | void SetAxisOrientation(bool xLeftRight, bool yBottomUp); | |
1457 | ||
1458 | /** | |
1459 | Sets the device origin (i.e., the origin in pixels after scaling has | |
1460 | been applied). This function may be useful in Windows printing | |
1461 | operations for placing a graphic on a page. | |
1462 | */ | |
1463 | void SetDeviceOrigin(wxCoord x, wxCoord y); | |
1464 | ||
1465 | /** | |
1466 | Sets the current logical function for the device context. | |
1467 | It determines how a @e source pixel (from a pen or brush colour, or source | |
1468 | device context if using Blit()) combines with a @e destination pixel in | |
1469 | the current device context. | |
1470 | Text drawing is not affected by this function. | |
1471 | ||
1472 | See ::wxRasterOperationMode enumeration values for more info. | |
1473 | ||
1474 | The default is @c wxCOPY, which simply draws with the current colour. | |
1475 | The others combine the current colour and the background using a logical | |
1476 | operation. @c wxINVERT is commonly used for drawing rubber bands or moving | |
1477 | outlines, since drawing twice reverts to the original colour. | |
1478 | */ | |
1479 | void SetLogicalFunction(wxRasterOperationMode function); | |
1480 | ||
1481 | /** | |
1482 | The mapping mode of the device context defines the unit of measurement | |
1483 | used to convert @e logical units to @e device units. | |
1484 | ||
1485 | Note that in X, text drawing isn't handled consistently with the mapping mode; | |
1486 | a font is always specified in point size. However, setting the user scale (see | |
1487 | SetUserScale()) scales the text appropriately. In Windows, scalable | |
1488 | TrueType fonts are always used; in X, results depend on availability of | |
1489 | fonts, but usually a reasonable match is found. | |
1490 | ||
1491 | The coordinate origin is always at the top left of the screen/printer. | |
1492 | ||
1493 | Drawing to a Windows printer device context uses the current mapping | |
1494 | mode, but mapping mode is currently ignored for PostScript output. | |
1495 | */ | |
1496 | void SetMapMode(wxMappingMode mode); | |
1497 | ||
1498 | /** | |
1499 | If this is a window DC or memory DC, assigns the given palette to the | |
1500 | window or bitmap associated with the DC. If the argument is | |
1501 | ::wxNullPalette, the current palette is selected out of the device | |
1502 | context, and the original palette restored. | |
1503 | ||
1504 | @see wxPalette | |
1505 | */ | |
1506 | void SetPalette(const wxPalette& palette); | |
1507 | ||
1508 | /** | |
1509 | Sets the user scaling factor, useful for applications which require | |
1510 | 'zooming'. | |
1511 | */ | |
1512 | void SetUserScale(double xScale, double yScale); | |
e71508e1 VZ |
1513 | |
1514 | ||
1515 | /** | |
1516 | @name Transformation matrix | |
1517 | ||
1518 | See the notes about the availability of these functions in the class | |
1519 | documentation. | |
1520 | */ | |
1521 | //@{ | |
1522 | ||
1523 | /** | |
1524 | Check if the use of transformation matrix is supported by the current | |
1525 | system. | |
1526 | ||
1527 | Currently this function always returns @false for non-MSW platforms and | |
1528 | may return @false for old (Windows 9x/ME) Windows systems. Normally | |
1529 | support for the transformation matrix is always available in any | |
1530 | relatively recent Windows versions. | |
1531 | ||
1532 | @since 2.9.2 | |
1533 | */ | |
1534 | bool CanUseTransformMatrix() const; | |
1535 | ||
1536 | /** | |
1537 | Set the transformation matrix. | |
1538 | ||
1539 | If transformation matrix is supported on the current system, the | |
1540 | specified @a matrix will be used to transform between wxDC and physical | |
1541 | coordinates. Otherwise the function returns @false and doesn't change | |
1542 | the coordinate mapping. | |
1543 | ||
1544 | @since 2.9.2 | |
1545 | */ | |
1546 | bool SetTransformMatrix(const wxAffineMatrix2D& matrix); | |
1547 | ||
1548 | /** | |
1549 | Return the transformation matrix used by this device context. | |
1550 | ||
1551 | By default the transformation matrix is the identity matrix. | |
1552 | ||
1553 | @since 2.9.2 | |
1554 | */ | |
1555 | wxAffineMatrix2D GetTransformMatrix() const; | |
1556 | ||
1557 | /** | |
1558 | Revert the transformation matrix to identity matrix. | |
1559 | ||
1560 | @since 2.9.2 | |
1561 | */ | |
1562 | void ResetTransformMatrix(); | |
1563 | ||
1564 | //@} | |
9a077460 RD |
1565 | |
1566 | ||
1567 | void SetLogicalScale(double x, double y); | |
1568 | void GetLogicalScale(double *x, double *y) const; | |
1569 | void SetLogicalOrigin(wxCoord x, wxCoord y); | |
1570 | void GetLogicalOrigin(wxCoord *x, wxCoord *y) const; | |
1571 | wxPoint GetLogicalOrigin() const; | |
1572 | ||
23324ae1 FM |
1573 | }; |
1574 | ||
1575 | ||
e54c96f1 | 1576 | |
23324ae1 FM |
1577 | /** |
1578 | @class wxDCClipper | |
7c913512 | 1579 | |
f09b5681 BP |
1580 | wxDCClipper is a small helper class for setting a clipping region on a wxDC |
1581 | and unsetting it automatically. An object of wxDCClipper class is typically | |
1582 | created on the stack so that it is automatically destroyed when the object | |
1583 | goes out of scope. A typical usage example: | |
7c913512 | 1584 | |
23324ae1 FM |
1585 | @code |
1586 | void MyFunction(wxDC& dc) | |
f09b5681 BP |
1587 | { |
1588 | wxDCClipper clip(dc, rect); | |
1589 | // ... drawing functions here are affected by clipping rect ... | |
1590 | } | |
1591 | ||
1592 | void OtherFunction() | |
1593 | { | |
1594 | wxDC dc; | |
1595 | MyFunction(dc); | |
1596 | // ... drawing functions here are not affected by clipping rect ... | |
1597 | } | |
23324ae1 | 1598 | @endcode |
7c913512 | 1599 | |
23324ae1 FM |
1600 | @library{wxcore} |
1601 | @category{gdi} | |
7c913512 | 1602 | |
382f12e4 FM |
1603 | @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger, |
1604 | wxDCBrushChanger | |
23324ae1 | 1605 | */ |
7c913512 | 1606 | class wxDCClipper |
23324ae1 FM |
1607 | { |
1608 | public: | |
1609 | //@{ | |
1610 | /** | |
f09b5681 BP |
1611 | Sets the clipping region to the specified region/coordinates. |
1612 | ||
23324ae1 FM |
1613 | The clipping region is automatically unset when this object is destroyed. |
1614 | */ | |
9a077460 | 1615 | wxDCClipper(wxDC& dc, const wxRegion& region); |
7c913512 | 1616 | wxDCClipper(wxDC& dc, const wxRect& rect); |
882678eb | 1617 | wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h); |
23324ae1 | 1618 | //@} |
c48d6cdf FM |
1619 | |
1620 | /** | |
1621 | Destroys the clipping region associated with the DC passed to the ctor. | |
1622 | */ | |
1623 | ~wxDCClipper(); | |
1624 | }; | |
1625 | ||
1626 | ||
1627 | /** | |
1628 | @class wxDCBrushChanger | |
1629 | ||
1630 | wxDCBrushChanger is a small helper class for setting a brush on a wxDC | |
1631 | and unsetting it automatically in the destructor, restoring the previous one. | |
1632 | ||
1633 | @library{wxcore} | |
1634 | @category{gdi} | |
1635 | ||
382f12e4 FM |
1636 | @see wxDC::SetBrush(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger, |
1637 | wxDCClipper | |
c48d6cdf FM |
1638 | */ |
1639 | class wxDCBrushChanger | |
1640 | { | |
1641 | public: | |
1642 | /** | |
1643 | Sets @a brush on the given @a dc, storing the old one. | |
1644 | ||
1645 | @param dc | |
1646 | The DC where the brush must be temporary set. | |
1647 | @param brush | |
1648 | The brush to set. | |
1649 | */ | |
1650 | wxDCBrushChanger(wxDC& dc, const wxBrush& brush); | |
1651 | ||
1652 | /** | |
1653 | Restores the brush originally selected in the DC passed to the ctor. | |
1654 | */ | |
1655 | ~wxDCBrushChanger(); | |
1656 | }; | |
1657 | ||
1658 | ||
1659 | /** | |
1660 | @class wxDCPenChanger | |
1661 | ||
1662 | wxDCPenChanger is a small helper class for setting a pen on a wxDC | |
1663 | and unsetting it automatically in the destructor, restoring the previous one. | |
1664 | ||
1665 | @library{wxcore} | |
1666 | @category{gdi} | |
1667 | ||
382f12e4 FM |
1668 | @see wxDC::SetPen(), wxDCFontChanger, wxDCTextColourChanger, wxDCBrushChanger, |
1669 | wxDCClipper | |
c48d6cdf FM |
1670 | */ |
1671 | class wxDCPenChanger | |
1672 | { | |
1673 | public: | |
1674 | /** | |
1675 | Sets @a pen on the given @a dc, storing the old one. | |
1676 | ||
1677 | @param dc | |
1678 | The DC where the pen must be temporary set. | |
1679 | @param pen | |
1680 | The pen to set. | |
1681 | */ | |
1682 | wxDCPenChanger(wxDC& dc, const wxPen& pen); | |
1683 | ||
1684 | /** | |
1685 | Restores the pen originally selected in the DC passed to the ctor. | |
1686 | */ | |
1687 | ~wxDCPenChanger(); | |
1688 | }; | |
1689 | ||
1690 | ||
1691 | ||
1692 | /** | |
1693 | @class wxDCTextColourChanger | |
1694 | ||
1695 | wxDCTextColourChanger is a small helper class for setting a foreground | |
1696 | text colour on a wxDC and unsetting it automatically in the destructor, | |
1697 | restoring the previous one. | |
1698 | ||
1699 | @library{wxcore} | |
1700 | @category{gdi} | |
1701 | ||
382f12e4 FM |
1702 | @see wxDC::SetTextForeground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger, |
1703 | wxDCClipper | |
c48d6cdf FM |
1704 | */ |
1705 | class wxDCTextColourChanger | |
1706 | { | |
1707 | public: | |
489cc69b VZ |
1708 | /** |
1709 | Trivial constructor not changing anything. | |
1710 | ||
1711 | This constructor is useful if you don't know beforehand if the colour | |
1712 | needs to be changed or not. It simply creates the object which won't do | |
1713 | anything in its destructor unless Set() is called -- in which case it | |
1714 | would reset the previous colour. | |
1715 | */ | |
1716 | wxDCTextColourChanger(wxDC& dc); | |
1717 | ||
c48d6cdf FM |
1718 | /** |
1719 | Sets @a col on the given @a dc, storing the old one. | |
1720 | ||
1721 | @param dc | |
1722 | The DC where the colour must be temporary set. | |
1723 | @param col | |
1724 | The colour to set. | |
1725 | */ | |
1726 | wxDCTextColourChanger(wxDC& dc, const wxColour& col); | |
1727 | ||
489cc69b VZ |
1728 | /** |
1729 | Set the colour to use. | |
1730 | ||
1731 | This method is meant to be called once only and only on the objects | |
1732 | created with the constructor overload not taking wxColour argument and | |
1733 | has the same effect as the other constructor, i.e. sets the colour to | |
1734 | the given @a col and ensures that the old value is restored when this | |
1735 | object is destroyed. | |
1736 | */ | |
1737 | void Set(const wxColour& col); | |
1738 | ||
c48d6cdf FM |
1739 | /** |
1740 | Restores the colour originally selected in the DC passed to the ctor. | |
1741 | */ | |
1742 | ~wxDCTextColourChanger(); | |
1743 | }; | |
1744 | ||
1745 | ||
1746 | ||
1747 | /** | |
1748 | @class wxDCFontChanger | |
1749 | ||
1750 | wxDCFontChanger is a small helper class for setting a font on a wxDC and | |
1751 | unsetting it automatically in the destructor, restoring the previous one. | |
1752 | ||
1753 | @since 2.9.0 | |
1754 | ||
1755 | @library{wxcore} | |
1756 | @category{gdi} | |
1757 | ||
382f12e4 FM |
1758 | @see wxDC::SetFont(), wxDCTextColourChanger, wxDCPenChanger, wxDCBrushChanger, |
1759 | wxDCClipper | |
c48d6cdf FM |
1760 | */ |
1761 | class wxDCFontChanger | |
1762 | { | |
1763 | public: | |
ca4adfd0 VZ |
1764 | /** |
1765 | Trivial constructor not changing anything. | |
1766 | ||
1767 | This constructor is useful if you don't know beforehand if the font | |
1768 | needs to be changed or not. It simply creates the object which won't do | |
1769 | anything in its destructor unless Set() is called -- in which case it | |
1770 | would reset the previous font. | |
1771 | ||
1772 | @since 2.9.1 | |
1773 | */ | |
1774 | wxDCFontChanger(wxDC& dc); | |
1775 | ||
c48d6cdf FM |
1776 | /** |
1777 | Sets @a font on the given @a dc, storing the old one. | |
1778 | ||
1779 | @param dc | |
1780 | The DC where the font must be temporary set. | |
1781 | @param font | |
1782 | The font to set. | |
1783 | */ | |
1784 | wxDCFontChanger(wxDC& dc, const wxFont& font); | |
1785 | ||
1786 | /** | |
ca4adfd0 VZ |
1787 | Set the font to use. |
1788 | ||
1789 | This method is meant to be called once only and only on the objects | |
1790 | created with the constructor overload not taking wxColour argument and | |
1791 | has the same effect as the other constructor, i.e. sets the font to | |
1792 | the given @a font and ensures that the old value is restored when this | |
1793 | object is destroyed. | |
1794 | */ | |
1795 | void Set(const wxFont& font); | |
1796 | ||
1797 | /** | |
1798 | Restores the font originally selected in the DC passed to the ctor. | |
c48d6cdf FM |
1799 | */ |
1800 | ~wxDCFontChanger(); | |
23324ae1 | 1801 | }; |
e54c96f1 | 1802 |