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