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 | 75 | /** |
0824e369 | 76 | Each logical unit is a @e "printer point" i.e.\ 1/72 of an inch. |
e65a6cc1 FM |
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 | ||
1058f652 MB |
412 | @beginWxPerlOnly |
413 | Not supported by wxPerl. | |
414 | @endWxPerlOnly | |
23324ae1 | 415 | */ |
4787c92d | 416 | void DrawLines(int n, const wxPoint points[], wxCoord xoffset = 0, |
23324ae1 | 417 | wxCoord yoffset = 0); |
f09b5681 BP |
418 | /** |
419 | This method uses a list of wxPoints, adding the optional offset | |
420 | coordinate. The programmer is responsible for deleting the list of | |
421 | points. | |
422 | ||
1058f652 MB |
423 | @beginWxPerlOnly |
424 | The wxPerl version of this method accepts | |
425 | as its first parameter a reference to an array | |
426 | of wxPoint objects. | |
427 | @endWxPerlOnly | |
f09b5681 | 428 | */ |
4cc4bfaf | 429 | void DrawLines(const wxPointList* points, |
f09b5681 | 430 | wxCoord xoffset = 0, wxCoord yoffset = 0); |
23324ae1 FM |
431 | |
432 | /** | |
433 | Draws a point using the color of the current pen. Note that the other | |
f09b5681 | 434 | properties of the pen are not used, such as width. |
23324ae1 FM |
435 | */ |
436 | void DrawPoint(wxCoord x, wxCoord y); | |
437 | ||
83b4d26c VZ |
438 | /** |
439 | @overload | |
440 | */ | |
441 | void DrawPoint(const wxPoint& pt); | |
442 | ||
23324ae1 | 443 | /** |
f09b5681 BP |
444 | Draws a filled polygon using an array of points of size @a n, adding |
445 | the optional offset coordinate. The first and last points are | |
446 | automatically closed. | |
23324ae1 | 447 | |
f09b5681 BP |
448 | The last argument specifies the fill rule: @b wxODDEVEN_RULE (the |
449 | default) or @b wxWINDING_RULE. | |
450 | ||
451 | The current pen is used for drawing the outline, and the current brush | |
452 | for filling the shape. Using a transparent brush suppresses filling. | |
1058f652 MB |
453 | |
454 | @beginWxPerlOnly | |
455 | Not supported by wxPerl. | |
456 | @endWxPerlOnly | |
f09b5681 | 457 | */ |
4787c92d | 458 | void DrawPolygon(int n, const wxPoint points[], wxCoord xoffset = 0, |
89efaf2b FM |
459 | wxCoord yoffset = 0, |
460 | wxPolygonFillMode fill_style = wxODDEVEN_RULE); | |
23324ae1 | 461 | /** |
f09b5681 BP |
462 | This method draws a filled polygon using a list of wxPoints, adding the |
463 | optional offset coordinate. The first and last points are automatically | |
464 | closed. | |
465 | ||
23324ae1 FM |
466 | The last argument specifies the fill rule: @b wxODDEVEN_RULE (the |
467 | default) or @b wxWINDING_RULE. | |
f09b5681 | 468 | |
23324ae1 | 469 | The current pen is used for drawing the outline, and the current brush |
f09b5681 BP |
470 | for filling the shape. Using a transparent brush suppresses filling. |
471 | ||
23324ae1 | 472 | The programmer is responsible for deleting the list of points. |
f09b5681 | 473 | |
1058f652 MB |
474 | @beginWxPerlOnly |
475 | The wxPerl version of this method accepts | |
476 | as its first parameter a reference to an array | |
477 | of wxPoint objects. | |
478 | @endWxPerlOnly | |
23324ae1 | 479 | */ |
4cc4bfaf | 480 | void DrawPolygon(const wxPointList* points, |
f09b5681 | 481 | wxCoord xoffset = 0, wxCoord yoffset = 0, |
89efaf2b | 482 | wxPolygonFillMode fill_style = wxODDEVEN_RULE); |
f09b5681 BP |
483 | |
484 | /** | |
485 | Draws two or more filled polygons using an array of @a points, adding | |
486 | the optional offset coordinates. | |
487 | ||
488 | Notice that for the platforms providing a native implementation of this | |
489 | function (Windows and PostScript-based wxDC currently), this is more | |
490 | efficient than using DrawPolygon() in a loop. | |
491 | ||
492 | @a n specifies the number of polygons to draw, the array @e count of | |
493 | size @a n specifies the number of points in each of the polygons in the | |
494 | @a points array. | |
495 | ||
496 | The last argument specifies the fill rule: @b wxODDEVEN_RULE (the | |
497 | default) or @b wxWINDING_RULE. | |
498 | ||
499 | The current pen is used for drawing the outline, and the current brush | |
500 | for filling the shape. Using a transparent brush suppresses filling. | |
501 | ||
502 | The polygons maybe disjoint or overlapping. Each polygon specified in a | |
503 | call to DrawPolyPolygon() must be closed. Unlike polygons created by | |
504 | the DrawPolygon() member function, the polygons created by this | |
505 | method are not closed automatically. | |
f09b5681 | 506 | */ |
4787c92d | 507 | void DrawPolyPolygon(int n, const int count[], const wxPoint points[], |
f09b5681 | 508 | wxCoord xoffset = 0, wxCoord yoffset = 0, |
89efaf2b | 509 | wxPolygonFillMode fill_style = wxODDEVEN_RULE); |
23324ae1 FM |
510 | |
511 | /** | |
512 | Draws a rectangle with the given top left corner, and with the given | |
513 | size. The current pen is used for the outline and the current brush | |
514 | for filling the shape. | |
515 | */ | |
f09b5681 | 516 | void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height); |
23324ae1 | 517 | |
83b4d26c VZ |
518 | /** |
519 | @overload | |
520 | */ | |
521 | void DrawRectangle(const wxPoint& pt, const wxSize& sz); | |
522 | ||
523 | /** | |
524 | @overload | |
525 | */ | |
526 | void DrawRectangle(const wxRect& rect); | |
527 | ||
23324ae1 | 528 | /** |
aff647c1 FM |
529 | Draws the text rotated by @a angle degrees |
530 | (positive angles are counterclockwise; the full angle is 360 degrees). | |
f09b5681 | 531 | |
1f1d2182 | 532 | @note Under Win9x only TrueType fonts can be drawn by this function. In |
f09b5681 BP |
533 | particular, a font different from @c wxNORMAL_FONT should be used |
534 | as the latter is not a TrueType font. @c wxSWISS_FONT is an | |
535 | example of a font which is. | |
3c4f71cc | 536 | |
4cc4bfaf | 537 | @see DrawText() |
23324ae1 FM |
538 | */ |
539 | void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, | |
540 | double angle); | |
541 | ||
83b4d26c VZ |
542 | /** |
543 | @overload | |
544 | */ | |
8ff9b17d | 545 | void DrawRotatedText(const wxString& text, const wxPoint& point, |
83b4d26c VZ |
546 | double angle); |
547 | ||
23324ae1 FM |
548 | /** |
549 | Draws a rectangle with the given top left corner, and with the given | |
f09b5681 | 550 | size. The corners are quarter-circles using the given radius. The |
23324ae1 FM |
551 | current pen is used for the outline and the current brush for filling |
552 | the shape. | |
f09b5681 BP |
553 | |
554 | If @a radius is positive, the value is assumed to be the radius of the | |
555 | rounded corner. If @a radius is negative, the absolute value is assumed | |
556 | to be the @e proportion of the smallest dimension of the rectangle. | |
557 | This means that the corner can be a sensible size relative to the size | |
558 | of the rectangle, and also avoids the strange effects X produces when | |
559 | the corners are too big for the rectangle. | |
23324ae1 FM |
560 | */ |
561 | void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, | |
f09b5681 | 562 | wxCoord height, double radius); |
23324ae1 | 563 | |
83b4d26c VZ |
564 | /** |
565 | @overload | |
566 | */ | |
567 | void DrawRoundedRectangle(const wxPoint& pt, const wxSize& sz, | |
568 | double radius); | |
569 | ||
570 | /** | |
571 | @overload | |
572 | */ | |
573 | void DrawRoundedRectangle(const wxRect& rect, double radius); | |
574 | ||
23324ae1 | 575 | /** |
f09b5681 BP |
576 | Draws a spline between all given points using the current pen. |
577 | ||
1058f652 MB |
578 | @beginWxPerlOnly |
579 | Not supported by wxPerl. | |
580 | @endWxPerlOnly | |
23324ae1 | 581 | */ |
4787c92d | 582 | void DrawSpline(int n, const wxPoint points[]); |
e3995493 FM |
583 | |
584 | /** | |
585 | @overload | |
1058f652 MB |
586 | |
587 | ||
588 | @beginWxPerlOnly | |
589 | The wxPerl version of this method accepts | |
590 | as its first parameter a reference to an array | |
591 | of wxPoint objects. | |
592 | @endWxPerlOnly | |
e3995493 | 593 | */ |
4cc4bfaf | 594 | void DrawSpline(const wxPointList* points); |
e3995493 FM |
595 | |
596 | /** | |
597 | @overload | |
1058f652 MB |
598 | |
599 | ||
600 | @beginWxPerlOnly | |
601 | Not supported by wxPerl. | |
602 | @endWxPerlOnly | |
e3995493 | 603 | */ |
f09b5681 BP |
604 | void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, |
605 | wxCoord x3, wxCoord y3); | |
23324ae1 FM |
606 | |
607 | /** | |
f09b5681 BP |
608 | Draws a text string at the specified point, using the current text |
609 | font, and the current text foreground and background colours. | |
610 | ||
23324ae1 | 611 | The coordinates refer to the top-left corner of the rectangle bounding |
f09b5681 | 612 | the string. See GetTextExtent() for how to get the dimensions of a text |
a5bb4514 VZ |
613 | string, which can be used to position the text more precisely and |
614 | DrawLabel() if you need to align the string differently. | |
615 | ||
616 | Starting from wxWidgets 2.9.2 @a text parameter can be a multi-line | |
617 | string, i.e. contain new line characters, and will be rendered | |
618 | correctly. | |
f09b5681 | 619 | |
408776d0 | 620 | @note The current @ref GetLogicalFunction() "logical function" is |
e928566f | 621 | ignored by this function. |
23324ae1 FM |
622 | */ |
623 | void DrawText(const wxString& text, wxCoord x, wxCoord y); | |
624 | ||
83b4d26c VZ |
625 | /** |
626 | @overload | |
627 | */ | |
628 | void DrawText(const wxString& text, const wxPoint& pt); | |
629 | ||
23324ae1 | 630 | /** |
e3995493 FM |
631 | Fill the area specified by rect with a radial gradient, starting from |
632 | @a initialColour at the centre of the circle and fading to | |
633 | @a destColour on the circle outside. | |
634 | ||
635 | The circle is placed at the centre of @a rect. | |
636 | ||
637 | @note Currently this function is very slow, don't use it for real-time | |
638 | drawing. | |
23324ae1 | 639 | */ |
e3995493 FM |
640 | void GradientFillConcentric(const wxRect& rect, |
641 | const wxColour& initialColour, | |
642 | const wxColour& destColour); | |
23324ae1 FM |
643 | |
644 | /** | |
e3995493 FM |
645 | Fill the area specified by rect with a radial gradient, starting from |
646 | @a initialColour at the centre of the circle and fading to | |
647 | @a destColour on the circle outside. | |
648 | ||
649 | @a circleCenter are the relative coordinates of centre of the circle in | |
650 | the specified @a rect. | |
651 | ||
652 | @note Currently this function is very slow, don't use it for real-time | |
653 | drawing. | |
23324ae1 | 654 | */ |
e3995493 FM |
655 | void GradientFillConcentric(const wxRect& rect, |
656 | const wxColour& initialColour, | |
657 | const wxColour& destColour, | |
658 | const wxPoint& circleCenter); | |
659 | ||
660 | /** | |
661 | Fill the area specified by @a rect with a linear gradient, starting | |
662 | from @a initialColour and eventually fading to @e destColour. | |
663 | ||
664 | The @a nDirection specifies the direction of the colour change, default is | |
665 | to use @a initialColour on the left part of the rectangle and | |
666 | @a destColour on the right one. | |
667 | */ | |
668 | void GradientFillLinear(const wxRect& rect, const wxColour& initialColour, | |
669 | const wxColour& destColour, | |
670 | wxDirection nDirection = wxRIGHT); | |
23324ae1 FM |
671 | |
672 | /** | |
673 | Flood fills the device context starting from the given point, using | |
f09b5681 BP |
674 | the current brush colour, and using a style: |
675 | ||
676 | - wxFLOOD_SURFACE: The flooding occurs until a colour other than the | |
677 | given colour is encountered. | |
678 | - wxFLOOD_BORDER: The area to be flooded is bounded by the given | |
679 | colour. | |
680 | ||
d29a9a8a | 681 | @return @false if the operation failed. |
f09b5681 BP |
682 | |
683 | @note The present implementation for non-Windows platforms may fail to | |
684 | find colour borders if the pixels do not match the colour | |
685 | exactly. However the function will still return @true. | |
72dc7302 VZ |
686 | |
687 | @note This method shouldn't be used with wxPaintDC under non-Windows | |
688 | platforms as it uses GetPixel() internally and this may give | |
689 | wrong results, notably in wxGTK. If you need to flood fill | |
690 | wxPaintDC, create a temporary wxMemoryDC, flood fill it and then | |
691 | blit it to, or draw as a bitmap on, wxPaintDC. See the example of | |
692 | doing this in the drawing sample and wxBufferedPaintDC class. | |
23324ae1 FM |
693 | */ |
694 | bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour, | |
89efaf2b | 695 | wxFloodFillStyle style = wxFLOOD_SURFACE); |
23324ae1 | 696 | |
83b4d26c VZ |
697 | /** |
698 | @overload | |
699 | */ | |
700 | bool FloodFill(const wxPoint& pt, const wxColour& col, | |
8ff9b17d | 701 | wxFloodFillStyle style = wxFLOOD_SURFACE); |
83b4d26c | 702 | |
23324ae1 | 703 | /** |
e3995493 FM |
704 | Displays a cross hair using the current pen. This is a vertical and |
705 | horizontal line the height and width of the window, centred on the | |
706 | given point. | |
23324ae1 | 707 | */ |
e3995493 | 708 | void CrossHair(wxCoord x, wxCoord y); |
23324ae1 | 709 | |
83b4d26c VZ |
710 | /** |
711 | @overload | |
712 | */ | |
713 | void CrossHair(const wxPoint& pt); | |
714 | ||
e3995493 | 715 | //@} |
3c4f71cc | 716 | |
23324ae1 FM |
717 | |
718 | /** | |
e3995493 | 719 | @name Clipping region functions |
23324ae1 | 720 | */ |
e3995493 | 721 | //@{ |
23324ae1 FM |
722 | |
723 | /** | |
e3995493 | 724 | Destroys the current clipping region so that none of the DC is clipped. |
23324ae1 | 725 | |
e3995493 | 726 | @see SetClippingRegion() |
23324ae1 | 727 | */ |
e3995493 | 728 | void DestroyClippingRegion(); |
23324ae1 FM |
729 | |
730 | /** | |
731 | Gets the rectangle surrounding the current clipping region. | |
732 | */ | |
408776d0 | 733 | void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const; |
23324ae1 FM |
734 | |
735 | /** | |
e3995493 FM |
736 | Sets the clipping region for this device context to the intersection of |
737 | the given region described by the parameters of this method and the | |
3821ccfa | 738 | previously set clipping region. |
3c4f71cc | 739 | |
e3995493 FM |
740 | The clipping region is an area to which drawing is restricted. Possible |
741 | uses for the clipping region are for clipping text or for speeding up | |
742 | window redraws when only a known area of the screen is damaged. | |
23324ae1 | 743 | |
3821ccfa VZ |
744 | Notice that you need to call DestroyClippingRegion() if you want to set |
745 | the clipping region exactly to the region specified. | |
746 | ||
747 | Also note that if the clipping region is empty, any previously set | |
748 | clipping region is destroyed, i.e. it is equivalent to calling | |
749 | DestroyClippingRegion(), and not to clipping out all drawing on the DC | |
750 | as might be expected. | |
751 | ||
e3995493 | 752 | @see DestroyClippingRegion(), wxRegion |
23324ae1 | 753 | */ |
e3995493 | 754 | void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height); |
23324ae1 FM |
755 | |
756 | /** | |
e3995493 | 757 | @overload |
23324ae1 | 758 | */ |
e3995493 | 759 | void SetClippingRegion(const wxPoint& pt, const wxSize& sz); |
23324ae1 FM |
760 | |
761 | /** | |
e3995493 | 762 | @overload |
23324ae1 | 763 | */ |
e3995493 | 764 | void SetClippingRegion(const wxRect& rect); |
23324ae1 FM |
765 | |
766 | /** | |
e3995493 | 767 | Sets the clipping region for this device context. |
f09b5681 | 768 | |
e3995493 FM |
769 | Unlike SetClippingRegion(), this function works with physical |
770 | coordinates and not with the logical ones. | |
771 | */ | |
772 | void SetDeviceClippingRegion(const wxRegion& region); | |
773 | ||
774 | //@} | |
775 | ||
776 | ||
777 | /** | |
778 | @name Text/character extent functions | |
23324ae1 | 779 | */ |
e3995493 FM |
780 | //@{ |
781 | ||
782 | /** | |
783 | Gets the character height of the currently set font. | |
784 | */ | |
785 | wxCoord GetCharHeight() const; | |
786 | ||
787 | /** | |
788 | Gets the average character width of the currently set font. | |
789 | */ | |
790 | wxCoord GetCharWidth() const; | |
23324ae1 | 791 | |
e29bf4b0 VZ |
792 | /** |
793 | Returns the various font characteristics. | |
794 | ||
795 | This method allows to retrieve some of the font characteristics not | |
796 | returned by GetTextExtent(), notably internal leading and average | |
797 | character width. | |
798 | ||
799 | Currently this method returns correct results only under wxMSW, in the | |
800 | other ports the internal leading will always be 0 and the average | |
801 | character width will be computed as the width of the character 'x'. | |
802 | ||
803 | @since 2.9.2 | |
804 | */ | |
805 | wxFontMetrics GetFontMetrics() const; | |
806 | ||
23324ae1 FM |
807 | /** |
808 | Gets the dimensions of the string using the currently selected font. | |
4cc4bfaf | 809 | @a string is the text string to measure, @e heightLine, if non @NULL, |
23324ae1 | 810 | is where to store the height of a single line. |
f09b5681 BP |
811 | |
812 | The text extent is set in the given @a w and @a h pointers. | |
813 | ||
814 | If the optional parameter @a font is specified and valid, then it is | |
815 | used for the text extent calculation, otherwise the currently selected | |
816 | font is used. | |
817 | ||
818 | @note This function works with both single-line and multi-line strings. | |
3c4f71cc | 819 | |
1058f652 MB |
820 | @beginWxPerlOnly |
821 | In wxPerl this method is implemented as | |
822 | GetMultiLineTextExtent(string, font = undef) returning a | |
823 | 3-element list (width, height, line_height) | |
824 | @endWxPerlOnly | |
825 | ||
4cc4bfaf | 826 | @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() |
23324ae1 | 827 | */ |
4cc4bfaf FM |
828 | void GetMultiLineTextExtent(const wxString& string, wxCoord* w, |
829 | wxCoord* h, | |
830 | wxCoord* heightLine = NULL, | |
408776d0 | 831 | const wxFont* font = NULL) const; |
23324ae1 | 832 | /** |
f09b5681 BP |
833 | Gets the dimensions of the string using the currently selected font. |
834 | @a string is the text string to measure, @e heightLine, if non @NULL, | |
835 | is where to store the height of a single line. | |
836 | ||
d29a9a8a | 837 | @return The text extent as a wxSize object. |
f09b5681 BP |
838 | |
839 | @note This function works with both single-line and multi-line strings. | |
840 | ||
1058f652 MB |
841 | @beginWxPerlOnly |
842 | Not supported by wxPerl. | |
843 | @endWxPerlOnly | |
844 | ||
f09b5681 | 845 | @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent() |
23324ae1 | 846 | */ |
408776d0 | 847 | wxSize GetMultiLineTextExtent(const wxString& string) const; |
23324ae1 FM |
848 | |
849 | /** | |
f09b5681 BP |
850 | Fills the @a widths array with the widths from the beginning of @a text |
851 | to the corresponding character of @a text. The generic version simply | |
852 | builds a running total of the widths of each character using | |
853 | GetTextExtent(), however if the various platforms have a native API | |
854 | function that is faster or more accurate than the generic | |
855 | implementation then it should be used instead. | |
856 | ||
1058f652 MB |
857 | @beginWxPerlOnly |
858 | In wxPerl this method only takes the @a text parameter and | |
859 | returns the widths as a list of integers. | |
860 | @endWxPerlOnly | |
861 | ||
4cc4bfaf | 862 | @see GetMultiLineTextExtent(), GetTextExtent() |
23324ae1 FM |
863 | */ |
864 | bool GetPartialTextExtents(const wxString& text, | |
328f5751 | 865 | wxArrayInt& widths) const; |
23324ae1 | 866 | |
23324ae1 FM |
867 | /** |
868 | Gets the dimensions of the string using the currently selected font. | |
f09b5681 BP |
869 | @a string is the text string to measure, @a descent is the dimension |
870 | from the baseline of the font to the bottom of the descender, and | |
871 | @a externalLeading is any extra vertical space added to the font by the | |
872 | font designer (usually is zero). | |
873 | ||
874 | The text extent is returned in @a w and @a h pointers or as a wxSize | |
875 | object depending on which version of this function is used. | |
876 | ||
877 | If the optional parameter @a font is specified and valid, then it is | |
878 | used for the text extent calculation. Otherwise the currently selected | |
879 | font is. | |
880 | ||
881 | @note This function only works with single-line strings. | |
882 | ||
1058f652 MB |
883 | @beginWxPerlOnly |
884 | In wxPerl this method is implemented as GetTextExtent(string, | |
885 | font = undef) returning a 4-element list (width, height, | |
886 | descent, externalLeading) | |
887 | @endWxPerlOnly | |
888 | ||
4cc4bfaf FM |
889 | @see wxFont, SetFont(), GetPartialTextExtents(), |
890 | GetMultiLineTextExtent() | |
891 | */ | |
f09b5681 | 892 | void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h, |
4cc4bfaf FM |
893 | wxCoord* descent = NULL, |
894 | wxCoord* externalLeading = NULL, | |
328f5751 | 895 | const wxFont* font = NULL) const; |
e3995493 FM |
896 | |
897 | /** | |
898 | @overload | |
1058f652 MB |
899 | |
900 | ||
901 | @beginWxPerlOnly | |
902 | Not supported by wxPerl. | |
903 | @endWxPerlOnly | |
e3995493 | 904 | */ |
382f12e4 | 905 | wxSize GetTextExtent(const wxString& string) const; |
e3995493 | 906 | |
23324ae1 FM |
907 | //@} |
908 | ||
e3995493 | 909 | |
23324ae1 | 910 | /** |
e3995493 FM |
911 | @name Text properties functions |
912 | */ | |
913 | //@{ | |
f09b5681 | 914 | |
e3995493 FM |
915 | /** |
916 | Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT. | |
917 | ||
918 | @see SetBackgroundMode() | |
23324ae1 | 919 | */ |
e3995493 | 920 | int GetBackgroundMode() const; |
23324ae1 FM |
921 | |
922 | /** | |
ac55e6b0 FM |
923 | Gets the current font. |
924 | ||
925 | Notice that even although each device context object has some default font | |
926 | after creation, this method would return a ::wxNullFont initially and only | |
927 | after calling SetFont() a valid font is returned. | |
e3995493 FM |
928 | */ |
929 | const wxFont& GetFont() const; | |
f09b5681 | 930 | |
e3995493 FM |
931 | /** |
932 | Gets the current layout direction of the device context. On platforms | |
933 | where RTL layout is supported, the return value will either be | |
934 | @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is | |
935 | not supported, the return value will be @c wxLayout_Default. | |
936 | ||
937 | @see SetLayoutDirection() | |
23324ae1 | 938 | */ |
e3995493 | 939 | wxLayoutDirection GetLayoutDirection() const; |
23324ae1 | 940 | |
23324ae1 | 941 | /** |
e3995493 | 942 | Gets the current text background colour. |
f09b5681 | 943 | |
e3995493 FM |
944 | @see SetTextBackground() |
945 | */ | |
946 | const wxColour& GetTextBackground() const; | |
f09b5681 | 947 | |
e3995493 FM |
948 | /** |
949 | Gets the current text foreground colour. | |
950 | ||
951 | @see SetTextForeground() | |
23324ae1 | 952 | */ |
e3995493 | 953 | const wxColour& GetTextForeground() const; |
23324ae1 FM |
954 | |
955 | /** | |
ac55e6b0 FM |
956 | @a mode may be one of @c wxSOLID and @c wxTRANSPARENT. |
957 | ||
958 | This setting determines whether text will be drawn with a background | |
959 | colour or not. | |
23324ae1 | 960 | */ |
e3995493 | 961 | void SetBackgroundMode(int mode); |
23324ae1 FM |
962 | |
963 | /** | |
ac55e6b0 FM |
964 | Sets the current font for the DC. |
965 | ||
966 | If the argument is ::wxNullFont (or another invalid font; see wxFont::IsOk), | |
967 | the current font is selected out of the device context (leaving wxDC without | |
968 | any valid font), allowing the current font to be destroyed safely. | |
e3995493 FM |
969 | |
970 | @see wxFont | |
23324ae1 | 971 | */ |
e3995493 | 972 | void SetFont(const wxFont& font); |
23324ae1 FM |
973 | |
974 | /** | |
e3995493 | 975 | Sets the current text background colour for the DC. |
23324ae1 | 976 | */ |
e3995493 | 977 | void SetTextBackground(const wxColour& colour); |
23324ae1 FM |
978 | |
979 | /** | |
e3995493 FM |
980 | Sets the current text foreground colour for the DC. |
981 | ||
982 | @see wxMemoryDC for the interpretation of colours when drawing into a | |
983 | monochrome bitmap. | |
23324ae1 | 984 | */ |
e3995493 | 985 | void SetTextForeground(const wxColour& colour); |
23324ae1 FM |
986 | |
987 | /** | |
ac55e6b0 FM |
988 | Sets the current layout direction for the device context. |
989 | ||
990 | @param dir | |
991 | May be either @c wxLayout_Default, @c wxLayout_LeftToRight or | |
992 | @c wxLayout_RightToLeft. | |
e3995493 FM |
993 | |
994 | @see GetLayoutDirection() | |
23324ae1 | 995 | */ |
e3995493 FM |
996 | void SetLayoutDirection(wxLayoutDirection dir); |
997 | ||
998 | //@} | |
999 | ||
23324ae1 FM |
1000 | |
1001 | /** | |
e3995493 | 1002 | @name Bounding box functions |
23324ae1 | 1003 | */ |
e3995493 FM |
1004 | //@{ |
1005 | ||
1006 | /** | |
1007 | Adds the specified point to the bounding box which can be retrieved | |
1008 | with MinX(), MaxX() and MinY(), MaxY() functions. | |
1009 | ||
1010 | @see ResetBoundingBox() | |
1011 | */ | |
1012 | void CalcBoundingBox(wxCoord x, wxCoord y); | |
23324ae1 FM |
1013 | |
1014 | /** | |
1015 | Gets the maximum horizontal extent used in drawing commands so far. | |
1016 | */ | |
adaaa686 | 1017 | wxCoord MaxX() const; |
23324ae1 FM |
1018 | |
1019 | /** | |
1020 | Gets the maximum vertical extent used in drawing commands so far. | |
1021 | */ | |
adaaa686 | 1022 | wxCoord MaxY() const; |
23324ae1 FM |
1023 | |
1024 | /** | |
1025 | Gets the minimum horizontal extent used in drawing commands so far. | |
1026 | */ | |
adaaa686 | 1027 | wxCoord MinX() const; |
23324ae1 FM |
1028 | |
1029 | /** | |
1030 | Gets the minimum vertical extent used in drawing commands so far. | |
1031 | */ | |
adaaa686 | 1032 | wxCoord MinY() const; |
23324ae1 FM |
1033 | |
1034 | /** | |
f09b5681 BP |
1035 | Resets the bounding box: after a call to this function, the bounding |
1036 | box doesn't contain anything. | |
3c4f71cc | 1037 | |
4cc4bfaf | 1038 | @see CalcBoundingBox() |
23324ae1 FM |
1039 | */ |
1040 | void ResetBoundingBox(); | |
1041 | ||
e3995493 | 1042 | //@} |
3c4f71cc | 1043 | |
23324ae1 FM |
1044 | |
1045 | /** | |
e3995493 | 1046 | @name Page and document start/end functions |
23324ae1 | 1047 | */ |
e3995493 | 1048 | //@{ |
23324ae1 FM |
1049 | |
1050 | /** | |
e3995493 FM |
1051 | Starts a document (only relevant when outputting to a printer). |
1052 | @a message is a message to show while printing. | |
23324ae1 | 1053 | */ |
e3995493 | 1054 | bool StartDoc(const wxString& message); |
23324ae1 FM |
1055 | |
1056 | /** | |
e3995493 | 1057 | Starts a document page (only relevant when outputting to a printer). |
23324ae1 | 1058 | */ |
e3995493 | 1059 | void StartPage(); |
23324ae1 | 1060 | |
23324ae1 | 1061 | /** |
e3995493 FM |
1062 | Ends a document (only relevant when outputting to a printer). |
1063 | */ | |
1064 | void EndDoc(); | |
3c4f71cc | 1065 | |
e3995493 FM |
1066 | /** |
1067 | Ends a document page (only relevant when outputting to a printer). | |
23324ae1 | 1068 | */ |
e3995493 FM |
1069 | void EndPage(); |
1070 | ||
23324ae1 FM |
1071 | //@} |
1072 | ||
23324ae1 FM |
1073 | |
1074 | /** | |
e3995493 | 1075 | @name Bit-Block Transfer operations (blit) |
23324ae1 | 1076 | */ |
e3995493 | 1077 | //@{ |
23324ae1 FM |
1078 | |
1079 | /** | |
825842b4 VZ |
1080 | Copy from a source DC to this DC. |
1081 | ||
1082 | With this method you can specify the destination coordinates and the | |
1083 | size of area to copy which will be the same for both the source and | |
1084 | target DCs. If you need to apply scaling while copying, use | |
1085 | StretchBlit(). | |
23324ae1 | 1086 | |
6f26e880 VZ |
1087 | Notice that source DC coordinates @a xsrc and @a ysrc are interpreted |
1088 | using the current source DC coordinate system, i.e. the scale, origin | |
1089 | position and axis directions are taken into account when transforming | |
1090 | them to physical (pixel) coordinates. | |
1091 | ||
e3995493 FM |
1092 | @param xdest |
1093 | Destination device context x position. | |
1094 | @param ydest | |
1095 | Destination device context y position. | |
1096 | @param width | |
1097 | Width of source area to be copied. | |
1098 | @param height | |
1099 | Height of source area to be copied. | |
1100 | @param source | |
1101 | Source device context. | |
1102 | @param xsrc | |
1103 | Source device context x position. | |
1104 | @param ysrc | |
1105 | Source device context y position. | |
1106 | @param logicalFunc | |
1107 | Logical function to use, see SetLogicalFunction(). | |
1108 | @param useMask | |
1109 | If @true, Blit does a transparent blit using the mask that is | |
1110 | associated with the bitmap selected into the source device context. | |
1111 | The Windows implementation does the following if MaskBlt cannot be | |
1112 | used: | |
1113 | <ol> | |
1114 | <li>Creates a temporary bitmap and copies the destination area into | |
1115 | it.</li> | |
1116 | <li>Copies the source area into the temporary bitmap using the | |
1117 | specified logical function.</li> | |
1118 | <li>Sets the masked area in the temporary bitmap to BLACK by ANDing | |
1119 | the mask bitmap with the temp bitmap with the foreground colour | |
1120 | set to WHITE and the bg colour set to BLACK.</li> | |
1121 | <li>Sets the unmasked area in the destination area to BLACK by | |
1122 | ANDing the mask bitmap with the destination area with the | |
1123 | foreground colour set to BLACK and the background colour set to | |
1124 | WHITE.</li> | |
1125 | <li>ORs the temporary bitmap with the destination area.</li> | |
1126 | <li>Deletes the temporary bitmap.</li> | |
1127 | </ol> | |
1128 | This sequence of operations ensures that the source's transparent | |
1129 | area need not be black, and logical functions are supported. | |
1130 | @n @b Note: on Windows, blitting with masks can be speeded up | |
519d7f23 | 1131 | considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option |
e3995493 FM |
1132 | enabled. You can also influence whether MaskBlt or the explicit |
1133 | mask blitting code above is used, by using wxSystemOptions and | |
1134 | setting the @c no-maskblt option to 1. | |
1135 | @param xsrcMask | |
1136 | Source x position on the mask. If both xsrcMask and ysrcMask are | |
1137 | @c -1, xsrc and ysrc will be assumed for the mask source position. | |
1138 | Currently only implemented on Windows. | |
1139 | @param ysrcMask | |
1140 | Source y position on the mask. If both xsrcMask and ysrcMask are | |
1141 | @c -1, xsrc and ysrc will be assumed for the mask source position. | |
1142 | Currently only implemented on Windows. | |
23324ae1 | 1143 | |
e3995493 | 1144 | @remarks There is partial support for Blit() in wxPostScriptDC, under X. |
23324ae1 | 1145 | |
e3995493 | 1146 | @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask |
23324ae1 | 1147 | */ |
e3995493 FM |
1148 | bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width, |
1149 | wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc, | |
1150 | wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false, | |
1151 | wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord); | |
23324ae1 FM |
1152 | |
1153 | /** | |
825842b4 VZ |
1154 | Copy from a source DC to this DC possibly changing the scale. |
1155 | ||
1156 | Unlike Blit(), this method allows to specify different source and | |
1157 | destination region sizes, meaning that it can stretch or shrink it | |
1158 | while copying. The same can be achieved by changing the scale of the | |
1159 | source or target DC but calling this method is simpler and can also be | |
1160 | more efficient if the platform provides a native implementation of it. | |
1161 | ||
6f26e880 VZ |
1162 | The meaning of its other parameters is the same as with Blit(), in |
1163 | particular all source coordinates are interpreted using the source DC | |
1164 | coordinate system, i.e. are affected by its scale, origin translation | |
1165 | and axis direction. | |
3c4f71cc | 1166 | |
7c913512 | 1167 | @param xdest |
4cc4bfaf | 1168 | Destination device context x position. |
7c913512 | 1169 | @param ydest |
4cc4bfaf | 1170 | Destination device context y position. |
7c913512 | 1171 | @param dstWidth |
4cc4bfaf | 1172 | Width of destination area. |
7c913512 | 1173 | @param dstHeight |
4cc4bfaf | 1174 | Height of destination area. |
7c913512 | 1175 | @param source |
4cc4bfaf | 1176 | Source device context. |
7c913512 | 1177 | @param xsrc |
4cc4bfaf | 1178 | Source device context x position. |
7c913512 | 1179 | @param ysrc |
4cc4bfaf | 1180 | Source device context y position. |
7c913512 | 1181 | @param srcWidth |
4cc4bfaf | 1182 | Width of source area to be copied. |
7c913512 | 1183 | @param srcHeight |
4cc4bfaf | 1184 | Height of source area to be copied. |
7c913512 | 1185 | @param logicalFunc |
f09b5681 | 1186 | Logical function to use, see SetLogicalFunction(). |
7c913512 | 1187 | @param useMask |
f09b5681 BP |
1188 | If @true, Blit does a transparent blit using the mask that is |
1189 | associated with the bitmap selected into the source device context. | |
1190 | The Windows implementation does the following if MaskBlt cannot be | |
1191 | used: | |
1192 | <ol> | |
1193 | <li>Creates a temporary bitmap and copies the destination area into | |
1194 | it.</li> | |
1195 | <li>Copies the source area into the temporary bitmap using the | |
1196 | specified logical function.</li> | |
1197 | <li>Sets the masked area in the temporary bitmap to BLACK by ANDing | |
1198 | the mask bitmap with the temp bitmap with the foreground colour | |
1199 | set to WHITE and the bg colour set to BLACK.</li> | |
1200 | <li>Sets the unmasked area in the destination area to BLACK by | |
1201 | ANDing the mask bitmap with the destination area with the | |
1202 | foreground colour set to BLACK and the background colour set to | |
1203 | WHITE.</li> | |
1204 | <li>ORs the temporary bitmap with the destination area.</li> | |
1205 | <li>Deletes the temporary bitmap.</li> | |
1206 | </ol> | |
1207 | This sequence of operations ensures that the source's transparent | |
1208 | area need not be black, and logical functions are supported. | |
1209 | @n @b Note: on Windows, blitting with masks can be speeded up | |
519d7f23 | 1210 | considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option |
f09b5681 BP |
1211 | enabled. You can also influence whether MaskBlt or the explicit |
1212 | mask blitting code above is used, by using wxSystemOptions and | |
1213 | setting the @c no-maskblt option to 1. | |
7c913512 | 1214 | @param xsrcMask |
f09b5681 | 1215 | Source x position on the mask. If both xsrcMask and ysrcMask are |
408776d0 FM |
1216 | wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask |
1217 | source position. Currently only implemented on Windows. | |
7c913512 | 1218 | @param ysrcMask |
f09b5681 | 1219 | Source y position on the mask. If both xsrcMask and ysrcMask are |
408776d0 FM |
1220 | wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask |
1221 | source position. Currently only implemented on Windows. | |
f09b5681 BP |
1222 | |
1223 | There is partial support for Blit() in wxPostScriptDC, under X. | |
1224 | ||
f09b5681 BP |
1225 | See wxMemoryDC for typical usage. |
1226 | ||
1e24c2af | 1227 | @since 2.9.0 |
f09b5681 BP |
1228 | |
1229 | @see Blit(), wxMemoryDC, wxBitmap, wxMask | |
1230 | */ | |
1231 | bool StretchBlit(wxCoord xdest, wxCoord ydest, | |
1232 | wxCoord dstWidth, wxCoord dstHeight, | |
1233 | wxDC* source, wxCoord xsrc, wxCoord ysrc, | |
1234 | wxCoord srcWidth, wxCoord srcHeight, | |
89efaf2b | 1235 | wxRasterOperationMode logicalFunc = wxCOPY, |
4cc4bfaf | 1236 | bool useMask = false, |
408776d0 FM |
1237 | wxCoord xsrcMask = wxDefaultCoord, |
1238 | wxCoord ysrcMask = wxDefaultCoord); | |
e3995493 FM |
1239 | //@} |
1240 | ||
1241 | ||
1242 | /** | |
1243 | @name Background/foreground brush and pen | |
1244 | */ | |
1245 | //@{ | |
1246 | ||
1247 | /** | |
1248 | Gets the brush used for painting the background. | |
1249 | ||
1250 | @see wxDC::SetBackground() | |
1251 | */ | |
1252 | const wxBrush& GetBackground() const; | |
1253 | ||
1254 | /** | |
1255 | Gets the current brush. | |
1256 | ||
1257 | @see wxDC::SetBrush() | |
1258 | */ | |
1259 | const wxBrush& GetBrush() const; | |
1260 | ||
1261 | /** | |
1262 | Gets the current pen. | |
1263 | ||
1264 | @see SetPen() | |
1265 | */ | |
1266 | const wxPen& GetPen() const; | |
1267 | ||
1268 | /** | |
1269 | Sets the current background brush for the DC. | |
1270 | */ | |
1271 | void SetBackground(const wxBrush& brush); | |
1272 | ||
1273 | /** | |
1274 | Sets the current brush for the DC. | |
1275 | ||
ac55e6b0 FM |
1276 | If the argument is ::wxNullBrush (or another invalid brush; see wxBrush::IsOk), |
1277 | the current brush is selected out of the device context (leaving wxDC without | |
1278 | any valid brush), allowing the current brush to be destroyed safely. | |
e3995493 FM |
1279 | |
1280 | @see wxBrush, wxMemoryDC (for the interpretation of colours when | |
1281 | drawing into a monochrome bitmap) | |
1282 | */ | |
1283 | void SetBrush(const wxBrush& brush); | |
1284 | ||
1285 | /** | |
ac55e6b0 FM |
1286 | Sets the current pen for the DC. |
1287 | ||
1288 | If the argument is ::wxNullPen (or another invalid pen; see wxPen::IsOk), | |
1289 | the current pen is selected out of the device context (leaving wxDC without any | |
1290 | valid pen), allowing the current pen to be destroyed safely. | |
e3995493 FM |
1291 | |
1292 | @see wxMemoryDC for the interpretation of colours when drawing into a | |
1293 | monochrome bitmap. | |
1294 | */ | |
1295 | void SetPen(const wxPen& pen); | |
1296 | ||
1297 | //@} | |
1298 | ||
1299 | ||
4feecbb9 VZ |
1300 | /** |
1301 | Copy attributes from another DC. | |
1302 | ||
1303 | The copied attributes currently are: | |
1304 | - Font | |
1305 | - Text foreground and background colours | |
1306 | - Background brush | |
1307 | - Layout direction | |
1308 | ||
1309 | @param dc | |
1310 | A valid (i.e. its IsOk() must return @true) source device context. | |
1311 | */ | |
1312 | void CopyAttributes(const wxDC& dc); | |
e3995493 FM |
1313 | |
1314 | /** | |
1315 | Returns the depth (number of bits/pixel) of this DC. | |
1316 | ||
1317 | @see wxDisplayDepth() | |
1318 | */ | |
1319 | int GetDepth() const; | |
1320 | ||
1321 | /** | |
1322 | Returns the current device origin. | |
1323 | ||
1324 | @see SetDeviceOrigin() | |
1325 | */ | |
1326 | wxPoint GetDeviceOrigin() const; | |
1327 | ||
1328 | /** | |
1329 | Gets the current logical function. | |
1330 | ||
1331 | @see SetLogicalFunction() | |
1332 | */ | |
1333 | wxRasterOperationMode GetLogicalFunction() const; | |
1334 | ||
1335 | /** | |
1336 | Gets the current mapping mode for the device context. | |
1337 | ||
1338 | @see SetMapMode() | |
1339 | */ | |
1340 | wxMappingMode GetMapMode() const; | |
1341 | ||
1342 | /** | |
1343 | Gets in @a colour the colour at the specified location. Not available | |
1344 | for wxPostScriptDC or wxMetafileDC. | |
1345 | ||
1346 | @note Setting a pixel can be done using DrawPoint(). | |
1347 | ||
72dc7302 VZ |
1348 | @note This method shouldn't be used with wxPaintDC as accessing the DC |
1349 | while drawing can result in unexpected results, notably in wxGTK. | |
e3995493 FM |
1350 | */ |
1351 | bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const; | |
1352 | ||
1353 | /** | |
1354 | Returns the resolution of the device in pixels per inch. | |
1355 | */ | |
1356 | wxSize GetPPI() const; | |
1357 | ||
1358 | /** | |
1359 | Gets the horizontal and vertical extent of this device context in @e device units. | |
1360 | It can be used to scale graphics to fit the page. | |
1361 | ||
1362 | For example, if @e maxX and @e maxY represent the maximum horizontal | |
1363 | and vertical 'pixel' values used in your application, the following | |
1364 | code will scale the graphic to fit on the printer page: | |
1365 | ||
1366 | @code | |
1367 | wxCoord w, h; | |
1368 | dc.GetSize(&w, &h); | |
1369 | double scaleX = (double)(maxX / w); | |
1370 | double scaleY = (double)(maxY / h); | |
1371 | dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY)); | |
1372 | @endcode | |
1373 | ||
1058f652 MB |
1374 | @beginWxPerlOnly |
1375 | In wxPerl there are two methods instead of a single overloaded | |
1376 | method: | |
1377 | - GetSize(): returns a Wx::Size object. | |
1378 | - GetSizeWH(): returns a 2-element list (width, height). | |
1379 | @endWxPerlOnly | |
e3995493 FM |
1380 | */ |
1381 | void GetSize(wxCoord* width, wxCoord* height) const; | |
1382 | ||
1383 | /** | |
1384 | @overload | |
1385 | */ | |
1386 | wxSize GetSize() const; | |
1387 | ||
1388 | /** | |
1389 | Returns the horizontal and vertical resolution in millimetres. | |
1390 | */ | |
1391 | void GetSizeMM(wxCoord* width, wxCoord* height) const; | |
1392 | ||
1393 | /** | |
1394 | @overload | |
1395 | */ | |
1396 | wxSize GetSizeMM() const; | |
1397 | ||
1398 | /** | |
1399 | Gets the current user scale factor. | |
1400 | ||
1058f652 MB |
1401 | @beginWxPerlOnly |
1402 | In wxPerl this method takes no arguments and return a two | |
1403 | element array (x, y). | |
1404 | @endWxPerlOnly | |
1405 | ||
e3995493 FM |
1406 | @see SetUserScale() |
1407 | */ | |
1408 | void GetUserScale(double* x, double* y) const; | |
1409 | ||
1410 | /** | |
1411 | Returns @true if the DC is ok to use. | |
1412 | */ | |
1413 | bool IsOk() const; | |
1414 | ||
1415 | /** | |
0824e369 | 1416 | Sets the x and y axis orientation (i.e.\ the direction from lowest to |
e3995493 FM |
1417 | highest values on the axis). The default orientation is x axis from |
1418 | left to right and y axis from top down. | |
1419 | ||
1420 | @param xLeftRight | |
1421 | True to set the x axis orientation to the natural left to right | |
1422 | orientation, @false to invert it. | |
1423 | @param yBottomUp | |
1424 | True to set the y axis orientation to the natural bottom up | |
1425 | orientation, @false to invert it. | |
1426 | */ | |
1427 | void SetAxisOrientation(bool xLeftRight, bool yBottomUp); | |
1428 | ||
1429 | /** | |
0824e369 | 1430 | Sets the device origin (i.e.\ the origin in pixels after scaling has |
e3995493 FM |
1431 | been applied). This function may be useful in Windows printing |
1432 | operations for placing a graphic on a page. | |
1433 | */ | |
1434 | void SetDeviceOrigin(wxCoord x, wxCoord y); | |
1435 | ||
1436 | /** | |
1437 | Sets the current logical function for the device context. | |
1438 | It determines how a @e source pixel (from a pen or brush colour, or source | |
1439 | device context if using Blit()) combines with a @e destination pixel in | |
1440 | the current device context. | |
1441 | Text drawing is not affected by this function. | |
1442 | ||
1443 | See ::wxRasterOperationMode enumeration values for more info. | |
1444 | ||
1445 | The default is @c wxCOPY, which simply draws with the current colour. | |
1446 | The others combine the current colour and the background using a logical | |
1447 | operation. @c wxINVERT is commonly used for drawing rubber bands or moving | |
1448 | outlines, since drawing twice reverts to the original colour. | |
1449 | */ | |
1450 | void SetLogicalFunction(wxRasterOperationMode function); | |
1451 | ||
1452 | /** | |
1453 | The mapping mode of the device context defines the unit of measurement | |
1454 | used to convert @e logical units to @e device units. | |
1455 | ||
1456 | Note that in X, text drawing isn't handled consistently with the mapping mode; | |
1457 | a font is always specified in point size. However, setting the user scale (see | |
1458 | SetUserScale()) scales the text appropriately. In Windows, scalable | |
1459 | TrueType fonts are always used; in X, results depend on availability of | |
1460 | fonts, but usually a reasonable match is found. | |
1461 | ||
1462 | The coordinate origin is always at the top left of the screen/printer. | |
1463 | ||
1464 | Drawing to a Windows printer device context uses the current mapping | |
1465 | mode, but mapping mode is currently ignored for PostScript output. | |
1466 | */ | |
1467 | void SetMapMode(wxMappingMode mode); | |
1468 | ||
1469 | /** | |
1470 | If this is a window DC or memory DC, assigns the given palette to the | |
1471 | window or bitmap associated with the DC. If the argument is | |
1472 | ::wxNullPalette, the current palette is selected out of the device | |
1473 | context, and the original palette restored. | |
1474 | ||
1475 | @see wxPalette | |
1476 | */ | |
1477 | void SetPalette(const wxPalette& palette); | |
1478 | ||
1479 | /** | |
1480 | Sets the user scaling factor, useful for applications which require | |
1481 | 'zooming'. | |
1482 | */ | |
1483 | void SetUserScale(double xScale, double yScale); | |
e71508e1 VZ |
1484 | |
1485 | ||
1486 | /** | |
1487 | @name Transformation matrix | |
1488 | ||
1489 | See the notes about the availability of these functions in the class | |
1490 | documentation. | |
1491 | */ | |
1492 | //@{ | |
1493 | ||
1494 | /** | |
1495 | Check if the use of transformation matrix is supported by the current | |
1496 | system. | |
1497 | ||
1498 | Currently this function always returns @false for non-MSW platforms and | |
1499 | may return @false for old (Windows 9x/ME) Windows systems. Normally | |
1500 | support for the transformation matrix is always available in any | |
1501 | relatively recent Windows versions. | |
1502 | ||
1503 | @since 2.9.2 | |
1504 | */ | |
1505 | bool CanUseTransformMatrix() const; | |
1506 | ||
1507 | /** | |
1508 | Set the transformation matrix. | |
1509 | ||
1510 | If transformation matrix is supported on the current system, the | |
1511 | specified @a matrix will be used to transform between wxDC and physical | |
1512 | coordinates. Otherwise the function returns @false and doesn't change | |
1513 | the coordinate mapping. | |
1514 | ||
1515 | @since 2.9.2 | |
1516 | */ | |
1517 | bool SetTransformMatrix(const wxAffineMatrix2D& matrix); | |
1518 | ||
1519 | /** | |
1520 | Return the transformation matrix used by this device context. | |
1521 | ||
1522 | By default the transformation matrix is the identity matrix. | |
1523 | ||
1524 | @since 2.9.2 | |
1525 | */ | |
1526 | wxAffineMatrix2D GetTransformMatrix() const; | |
1527 | ||
1528 | /** | |
1529 | Revert the transformation matrix to identity matrix. | |
1530 | ||
1531 | @since 2.9.2 | |
1532 | */ | |
1533 | void ResetTransformMatrix(); | |
1534 | ||
1535 | //@} | |
9a077460 | 1536 | |
0c3140ca RD |
1537 | |
1538 | /** | |
1539 | @name query capabilities | |
1540 | */ | |
1541 | //@{ | |
1542 | ||
1543 | /** | |
1544 | Does the DC support drawing bitmaps? | |
1545 | */ | |
1546 | bool CanDrawBitmap() const; | |
1547 | ||
1548 | /** | |
1549 | Does the DC supoprt calculating the size required to draw text? | |
1550 | */ | |
1551 | bool CanGetTextExtent() const; | |
1552 | ||
1553 | //@} | |
9a077460 | 1554 | |
9eefb5c1 RD |
1555 | /** |
1556 | Returns a value that can be used as a handle to the native drawing | |
1557 | context, if this wxDC has something that could be thought of in that | |
1558 | way. (Not all of them do.) | |
1559 | ||
1560 | For example, on Windows the return value is an HDC, on OSX it is a | |
1561 | CGContextRef and on wxGTK it will be a GdkDrawable. If the DC is a | |
1562 | wxGCDC then the return value will be the value returned from | |
1563 | wxGraphicsContext::GetNativeContext. A value of NULL is returned if | |
1564 | the DC does not have anything that fits the handle concept. | |
1565 | ||
1566 | @since 2.9.5 | |
1567 | */ | |
1568 | void* GetHandle() const; | |
0c3140ca | 1569 | |
9eefb5c1 | 1570 | |
0c3140ca RD |
1571 | /** |
1572 | If supported by the platform and the type of DC, fetch the contents of the DC, or a subset of it, as a bitmap. | |
1573 | */ | |
1574 | wxBitmap GetAsBitmap(const wxRect *subrect = NULL) const; | |
1575 | ||
9eefb5c1 | 1576 | |
9a077460 RD |
1577 | void SetLogicalScale(double x, double y); |
1578 | void GetLogicalScale(double *x, double *y) const; | |
1579 | void SetLogicalOrigin(wxCoord x, wxCoord y); | |
1580 | void GetLogicalOrigin(wxCoord *x, wxCoord *y) const; | |
1581 | wxPoint GetLogicalOrigin() const; | |
1582 | ||
23324ae1 FM |
1583 | }; |
1584 | ||
1585 | ||
e54c96f1 | 1586 | |
23324ae1 FM |
1587 | /** |
1588 | @class wxDCClipper | |
7c913512 | 1589 | |
586f4023 VZ |
1590 | wxDCClipper is a helper class for setting a clipping region on a wxDC |
1591 | during its lifetime. | |
1592 | ||
1593 | An object of wxDCClipper class is typically created on the stack so that it | |
1594 | is automatically destroyed when the object goes out of scope. A typical | |
1595 | usage example: | |
7c913512 | 1596 | |
23324ae1 FM |
1597 | @code |
1598 | void MyFunction(wxDC& dc) | |
f09b5681 BP |
1599 | { |
1600 | wxDCClipper clip(dc, rect); | |
1601 | // ... drawing functions here are affected by clipping rect ... | |
1602 | } | |
1603 | ||
1604 | void OtherFunction() | |
1605 | { | |
1606 | wxDC dc; | |
1607 | MyFunction(dc); | |
1608 | // ... drawing functions here are not affected by clipping rect ... | |
1609 | } | |
23324ae1 | 1610 | @endcode |
7c913512 | 1611 | |
586f4023 VZ |
1612 | @note Unlike other similar classes such as wxDCFontChanger, wxDCClipper |
1613 | currently doesn't restore the previously active clipping region when it | |
1614 | is destroyed but simply resets clipping on the associated wxDC. This | |
1615 | may be changed in the future wxWidgets versions but has to be taken | |
1616 | into account explicitly in the current one. | |
1617 | ||
23324ae1 FM |
1618 | @library{wxcore} |
1619 | @category{gdi} | |
7c913512 | 1620 | |
382f12e4 FM |
1621 | @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger, |
1622 | wxDCBrushChanger | |
23324ae1 | 1623 | */ |
7c913512 | 1624 | class wxDCClipper |
23324ae1 FM |
1625 | { |
1626 | public: | |
1627 | //@{ | |
1628 | /** | |
f09b5681 BP |
1629 | Sets the clipping region to the specified region/coordinates. |
1630 | ||
23324ae1 FM |
1631 | The clipping region is automatically unset when this object is destroyed. |
1632 | */ | |
9a077460 | 1633 | wxDCClipper(wxDC& dc, const wxRegion& region); |
7c913512 | 1634 | wxDCClipper(wxDC& dc, const wxRect& rect); |
882678eb | 1635 | wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h); |
23324ae1 | 1636 | //@} |
c48d6cdf FM |
1637 | |
1638 | /** | |
1639 | Destroys the clipping region associated with the DC passed to the ctor. | |
1640 | */ | |
1641 | ~wxDCClipper(); | |
1642 | }; | |
1643 | ||
1644 | ||
1645 | /** | |
1646 | @class wxDCBrushChanger | |
1647 | ||
1648 | wxDCBrushChanger is a small helper class for setting a brush on a wxDC | |
1649 | and unsetting it automatically in the destructor, restoring the previous one. | |
1650 | ||
1651 | @library{wxcore} | |
1652 | @category{gdi} | |
1653 | ||
382f12e4 FM |
1654 | @see wxDC::SetBrush(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger, |
1655 | wxDCClipper | |
c48d6cdf FM |
1656 | */ |
1657 | class wxDCBrushChanger | |
1658 | { | |
1659 | public: | |
1660 | /** | |
1661 | Sets @a brush on the given @a dc, storing the old one. | |
1662 | ||
1663 | @param dc | |
1664 | The DC where the brush must be temporary set. | |
1665 | @param brush | |
1666 | The brush to set. | |
1667 | */ | |
1668 | wxDCBrushChanger(wxDC& dc, const wxBrush& brush); | |
1669 | ||
1670 | /** | |
1671 | Restores the brush originally selected in the DC passed to the ctor. | |
1672 | */ | |
1673 | ~wxDCBrushChanger(); | |
1674 | }; | |
1675 | ||
1676 | ||
1677 | /** | |
1678 | @class wxDCPenChanger | |
1679 | ||
1680 | wxDCPenChanger is a small helper class for setting a pen on a wxDC | |
1681 | and unsetting it automatically in the destructor, restoring the previous one. | |
1682 | ||
1683 | @library{wxcore} | |
1684 | @category{gdi} | |
1685 | ||
382f12e4 FM |
1686 | @see wxDC::SetPen(), wxDCFontChanger, wxDCTextColourChanger, wxDCBrushChanger, |
1687 | wxDCClipper | |
c48d6cdf FM |
1688 | */ |
1689 | class wxDCPenChanger | |
1690 | { | |
1691 | public: | |
1692 | /** | |
1693 | Sets @a pen on the given @a dc, storing the old one. | |
1694 | ||
1695 | @param dc | |
1696 | The DC where the pen must be temporary set. | |
1697 | @param pen | |
1698 | The pen to set. | |
1699 | */ | |
1700 | wxDCPenChanger(wxDC& dc, const wxPen& pen); | |
1701 | ||
1702 | /** | |
1703 | Restores the pen originally selected in the DC passed to the ctor. | |
1704 | */ | |
1705 | ~wxDCPenChanger(); | |
1706 | }; | |
1707 | ||
1708 | ||
1709 | ||
1710 | /** | |
1711 | @class wxDCTextColourChanger | |
1712 | ||
1713 | wxDCTextColourChanger is a small helper class for setting a foreground | |
1714 | text colour on a wxDC and unsetting it automatically in the destructor, | |
1715 | restoring the previous one. | |
1716 | ||
1717 | @library{wxcore} | |
1718 | @category{gdi} | |
1719 | ||
382f12e4 FM |
1720 | @see wxDC::SetTextForeground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger, |
1721 | wxDCClipper | |
c48d6cdf FM |
1722 | */ |
1723 | class wxDCTextColourChanger | |
1724 | { | |
1725 | public: | |
489cc69b VZ |
1726 | /** |
1727 | Trivial constructor not changing anything. | |
1728 | ||
1729 | This constructor is useful if you don't know beforehand if the colour | |
1730 | needs to be changed or not. It simply creates the object which won't do | |
1731 | anything in its destructor unless Set() is called -- in which case it | |
1732 | would reset the previous colour. | |
1733 | */ | |
1734 | wxDCTextColourChanger(wxDC& dc); | |
1735 | ||
c48d6cdf FM |
1736 | /** |
1737 | Sets @a col on the given @a dc, storing the old one. | |
1738 | ||
1739 | @param dc | |
1740 | The DC where the colour must be temporary set. | |
1741 | @param col | |
1742 | The colour to set. | |
1743 | */ | |
1744 | wxDCTextColourChanger(wxDC& dc, const wxColour& col); | |
1745 | ||
489cc69b VZ |
1746 | /** |
1747 | Set the colour to use. | |
1748 | ||
1749 | This method is meant to be called once only and only on the objects | |
1750 | created with the constructor overload not taking wxColour argument and | |
1751 | has the same effect as the other constructor, i.e. sets the colour to | |
1752 | the given @a col and ensures that the old value is restored when this | |
1753 | object is destroyed. | |
1754 | */ | |
1755 | void Set(const wxColour& col); | |
1756 | ||
c48d6cdf FM |
1757 | /** |
1758 | Restores the colour originally selected in the DC passed to the ctor. | |
1759 | */ | |
1760 | ~wxDCTextColourChanger(); | |
1761 | }; | |
1762 | ||
1763 | ||
1764 | ||
1765 | /** | |
1766 | @class wxDCFontChanger | |
1767 | ||
1768 | wxDCFontChanger is a small helper class for setting a font on a wxDC and | |
1769 | unsetting it automatically in the destructor, restoring the previous one. | |
1770 | ||
1771 | @since 2.9.0 | |
1772 | ||
1773 | @library{wxcore} | |
1774 | @category{gdi} | |
1775 | ||
382f12e4 FM |
1776 | @see wxDC::SetFont(), wxDCTextColourChanger, wxDCPenChanger, wxDCBrushChanger, |
1777 | wxDCClipper | |
c48d6cdf FM |
1778 | */ |
1779 | class wxDCFontChanger | |
1780 | { | |
1781 | public: | |
ca4adfd0 VZ |
1782 | /** |
1783 | Trivial constructor not changing anything. | |
1784 | ||
1785 | This constructor is useful if you don't know beforehand if the font | |
1786 | needs to be changed or not. It simply creates the object which won't do | |
1787 | anything in its destructor unless Set() is called -- in which case it | |
1788 | would reset the previous font. | |
1789 | ||
1790 | @since 2.9.1 | |
1791 | */ | |
1792 | wxDCFontChanger(wxDC& dc); | |
1793 | ||
c48d6cdf FM |
1794 | /** |
1795 | Sets @a font on the given @a dc, storing the old one. | |
1796 | ||
1797 | @param dc | |
1798 | The DC where the font must be temporary set. | |
1799 | @param font | |
1800 | The font to set. | |
1801 | */ | |
1802 | wxDCFontChanger(wxDC& dc, const wxFont& font); | |
1803 | ||
1804 | /** | |
ca4adfd0 VZ |
1805 | Set the font to use. |
1806 | ||
1807 | This method is meant to be called once only and only on the objects | |
1808 | created with the constructor overload not taking wxColour argument and | |
1809 | has the same effect as the other constructor, i.e. sets the font to | |
1810 | the given @a font and ensures that the old value is restored when this | |
1811 | object is destroyed. | |
1812 | */ | |
1813 | void Set(const wxFont& font); | |
1814 | ||
1815 | /** | |
1816 | Restores the font originally selected in the DC passed to the ctor. | |
c48d6cdf FM |
1817 | */ |
1818 | ~wxDCFontChanger(); | |
23324ae1 | 1819 | }; |
e54c96f1 | 1820 |