]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/dc.h
Updates to Indonesian translations by Rahmat Bambang.
[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 licence
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 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 };
104
105
106 /**
107 @class wxDC
108
109 A wxDC is a @e "device context" onto which graphics and text can be drawn.
110 It is intended to represent different output devices and offers a common
111 abstract API for drawing on any of them.
112
113 wxWidgets offers an alternative drawing API based on the modern drawing
114 backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer
115 and related classes. There is also a wxGCDC linking the APIs by offering
116 the wxDC API on top of a wxGraphicsContext.
117
118 wxDC is an abstract base class and cannot be created directly.
119 Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or
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.
125
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.
130
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.
136
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
146 All wxDC functions use instead @b logical units, unless where explicitly
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
154 @section dc_alpha_support Support for Transparency / Alpha Channel
155
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.
164
165
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
177 @library{wxcore}
178 @category{dc,gdi}
179
180 @see @ref overview_dc, wxGraphicsContext, wxDCFontChanger, wxDCTextColourChanger,
181 wxDCPenChanger, wxDCBrushChanger, wxDCClipper
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).
186 */
187 class wxDC : public wxObject
188 {
189 public:
190 /**
191 @name Coordinate conversion functions
192 */
193 //@{
194
195 /**
196 Convert @e device X coordinate to logical coordinate, using the current
197 mapping mode, user scale factor, device origin and axis orientation.
198 */
199 wxCoord DeviceToLogicalX(wxCoord x) const;
200
201 /**
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.
205 */
206 wxCoord DeviceToLogicalXRel(wxCoord x) const;
207
208 /**
209 Converts @e device Y coordinate to logical coordinate, using the current
210 mapping mode, user scale factor, device origin and axis orientation.
211 */
212 wxCoord DeviceToLogicalY(wxCoord y) const;
213
214 /**
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.
218 */
219 wxCoord DeviceToLogicalYRel(wxCoord y) const;
220
221 /**
222 Converts logical X coordinate to device coordinate, using the current
223 mapping mode, user scale factor, device origin and axis orientation.
224 */
225 wxCoord LogicalToDeviceX(wxCoord x) const;
226
227 /**
228 Converts logical X coordinate to relative device coordinate, using the
229 current mapping mode and user scale factor but ignoring the
230 axis orientation. Use this for converting a width, for example.
231 */
232 wxCoord LogicalToDeviceXRel(wxCoord x) const;
233
234 /**
235 Converts logical Y coordinate to device coordinate, using the current
236 mapping mode, user scale factor, device origin and axis orientation.
237 */
238 wxCoord LogicalToDeviceY(wxCoord y) const;
239
240 /**
241 Converts logical Y coordinate to relative device coordinate, using the
242 current mapping mode and user scale factor but ignoring the
243 axis orientation. Use this for converting a height, for example.
244 */
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();
260
261 /**
262 Draws an arc of a circle, centred on (@a xc, @a yc), with starting
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.
266
267 The arc is drawn in a counter-clockwise direction from the start point
268 to the end point.
269 */
270 void DrawArc(wxCoord xStart, wxCoord yStart, wxCoord xEnd, wxCoord yEnd,
271 wxCoord xc, wxCoord yc);
272
273 /**
274 @overload
275 */
276 void DrawArc(const wxPoint& ptStart, const wxPoint& ptEnd, const wxPoint& centre);
277
278 /**
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
289 */
290 void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y,
291 bool useMask = false);
292
293 /**
294 @overload
295 */
296 void DrawBitmap(const wxBitmap &bmp, const wxPoint& pt,
297 bool useMask = false);
298
299 /**
300 Draws a check mark inside the given rectangle.
301 */
302 void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
303
304 /**
305 @overload
306 */
307 void DrawCheckMark(const wxRect& rect);
308
309 /**
310 Draws a circle with the given centre and radius.
311
312 @see DrawEllipse()
313 */
314 void DrawCircle(wxCoord x, wxCoord y, wxCoord radius);
315
316 /**
317 @overload
318 */
319 void DrawCircle(const wxPoint& pt, wxCoord radius);
320
321 /**
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.
325
326 @see DrawCircle()
327 */
328 void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
329
330 /**
331 @overload
332 */
333 void DrawEllipse(const wxPoint& pt, const wxSize& size);
334
335 /**
336 @overload
337 */
338 void DrawEllipse(const wxRect& rect);
339
340 /**
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.
355 */
356 void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height,
357 double start, double end);
358
359 /**
360 @overload
361 */
362 void DrawEllipticArc(const wxPoint& pt, const wxSize& sz,
363 double sa, double ea);
364
365 /**
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.
369 */
370 void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);
371
372 /**
373 @overload
374 */
375 void DrawIcon(const wxIcon& icon, const wxPoint& pt);
376
377 /**
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.
382 */
383 void DrawLabel(const wxString& text, const wxBitmap& bitmap,
384 const wxRect& rect,
385 int alignment = wxALIGN_LEFT | wxALIGN_TOP,
386 int indexAccel = -1, wxRect* rectBounding = NULL);
387
388 /**
389 @overload
390 */
391 void DrawLabel(const wxString& text, const wxRect& rect,
392 int alignment = wxALIGN_LEFT | wxALIGN_TOP,
393 int indexAccel = -1);
394
395 /**
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).
400 */
401 void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
402
403 /**
404 @overload
405 */
406 void DrawLine(const wxPoint& pt1, const wxPoint& pt2);
407
408 /**
409 Draws lines using an array of points of size @a n adding the optional
410 offset coordinate. The current pen is used for drawing the lines.
411
412 @beginWxPerlOnly
413 Not supported by wxPerl.
414 @endWxPerlOnly
415 */
416 void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0,
417 wxCoord yoffset = 0);
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
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
428 */
429 void DrawLines(const wxPointList* points,
430 wxCoord xoffset = 0, wxCoord yoffset = 0);
431
432 /**
433 Draws a point using the color of the current pen. Note that the other
434 properties of the pen are not used, such as width.
435 */
436 void DrawPoint(wxCoord x, wxCoord y);
437
438 /**
439 @overload
440 */
441 void DrawPoint(const wxPoint& pt);
442
443 /**
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.
447
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.
453
454 @beginWxPerlOnly
455 Not supported by wxPerl.
456 @endWxPerlOnly
457 */
458 void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0,
459 wxCoord yoffset = 0,
460 wxPolygonFillMode fill_style = wxODDEVEN_RULE);
461 /**
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
466 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
467 default) or @b wxWINDING_RULE.
468
469 The current pen is used for drawing the outline, and the current brush
470 for filling the shape. Using a transparent brush suppresses filling.
471
472 The programmer is responsible for deleting the list of points.
473
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
479 */
480 void DrawPolygon(const wxPointList* points,
481 wxCoord xoffset = 0, wxCoord yoffset = 0,
482 wxPolygonFillMode fill_style = wxODDEVEN_RULE);
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.
506 */
507 void DrawPolyPolygon(int n, int count[], wxPoint points[],
508 wxCoord xoffset = 0, wxCoord yoffset = 0,
509 wxPolygonFillMode fill_style = wxODDEVEN_RULE);
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 */
516 void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
517
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
528 /**
529 Draws the text rotated by @a angle degrees
530 (positive angles are counterclockwise; the full angle is 360 degrees).
531
532 @note Under Win9x only TrueType fonts can be drawn by this function. In
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.
536
537 @see DrawText()
538 */
539 void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y,
540 double angle);
541
542 /**
543 @overload
544 */
545 void DrawRotatedText(const wxString& text, const wxPoint& point,
546 double angle);
547
548 /**
549 Draws a rectangle with the given top left corner, and with the given
550 size. The corners are quarter-circles using the given radius. The
551 current pen is used for the outline and the current brush for filling
552 the shape.
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.
560 */
561 void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width,
562 wxCoord height, double radius);
563
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
575 /**
576 Draws a spline between all given points using the current pen.
577
578 @beginWxPerlOnly
579 Not supported by wxPerl.
580 @endWxPerlOnly
581 */
582 void DrawSpline(int n, wxPoint points[]);
583
584 /**
585 @overload
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
593 */
594 void DrawSpline(const wxPointList* points);
595
596 /**
597 @overload
598
599
600 @beginWxPerlOnly
601 Not supported by wxPerl.
602 @endWxPerlOnly
603 */
604 void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
605 wxCoord x3, wxCoord y3);
606
607 /**
608 Draws a text string at the specified point, using the current text
609 font, and the current text foreground and background colours.
610
611 The coordinates refer to the top-left corner of the rectangle bounding
612 the string. See GetTextExtent() for how to get the dimensions of a text
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.
619
620 @note The current @ref GetLogicalFunction() "logical function" is
621 ignored by this function.
622 */
623 void DrawText(const wxString& text, wxCoord x, wxCoord y);
624
625 /**
626 @overload
627 */
628 void DrawText(const wxString& text, const wxPoint& pt);
629
630 /**
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.
639 */
640 void GradientFillConcentric(const wxRect& rect,
641 const wxColour& initialColour,
642 const wxColour& destColour);
643
644 /**
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.
654 */
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);
671
672 /**
673 Flood fills the device context starting from the given point, using
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
681 @return @false if the operation failed.
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.
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.
693 */
694 bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
695 wxFloodFillStyle style = wxFLOOD_SURFACE);
696
697 /**
698 @overload
699 */
700 bool FloodFill(const wxPoint& pt, const wxColour& col,
701 wxFloodFillStyle style = wxFLOOD_SURFACE);
702
703 /**
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.
707 */
708 void CrossHair(wxCoord x, wxCoord y);
709
710 /**
711 @overload
712 */
713 void CrossHair(const wxPoint& pt);
714
715 //@}
716
717
718 /**
719 @name Clipping region functions
720 */
721 //@{
722
723 /**
724 Destroys the current clipping region so that none of the DC is clipped.
725
726 @see SetClippingRegion()
727 */
728 void DestroyClippingRegion();
729
730 /**
731 Gets the rectangle surrounding the current clipping region.
732 */
733 void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const;
734
735 /**
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
738 previously set clipping region.
739
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.
743
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
752 @see DestroyClippingRegion(), wxRegion
753 */
754 void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
755
756 /**
757 @overload
758 */
759 void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
760
761 /**
762 @overload
763 */
764 void SetClippingRegion(const wxRect& rect);
765
766 /**
767 Sets the clipping region for this device context.
768
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
779 */
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;
791
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
807 /**
808 Gets the dimensions of the string using the currently selected font.
809 @a string is the text string to measure, @e heightLine, if non @NULL,
810 is where to store the height of a single line.
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.
819
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
826 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
827 */
828 void GetMultiLineTextExtent(const wxString& string, wxCoord* w,
829 wxCoord* h,
830 wxCoord* heightLine = NULL,
831 const wxFont* font = NULL) const;
832 /**
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
837 @return The text extent as a wxSize object.
838
839 @note This function works with both single-line and multi-line strings.
840
841 @beginWxPerlOnly
842 Not supported by wxPerl.
843 @endWxPerlOnly
844
845 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
846 */
847 wxSize GetMultiLineTextExtent(const wxString& string) const;
848
849 /**
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
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
862 @see GetMultiLineTextExtent(), GetTextExtent()
863 */
864 bool GetPartialTextExtents(const wxString& text,
865 wxArrayInt& widths) const;
866
867 /**
868 Gets the dimensions of the string using the currently selected font.
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
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
889 @see wxFont, SetFont(), GetPartialTextExtents(),
890 GetMultiLineTextExtent()
891 */
892 void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
893 wxCoord* descent = NULL,
894 wxCoord* externalLeading = NULL,
895 const wxFont* font = NULL) const;
896
897 /**
898 @overload
899
900
901 @beginWxPerlOnly
902 Not supported by wxPerl.
903 @endWxPerlOnly
904 */
905 wxSize GetTextExtent(const wxString& string) const;
906
907 //@}
908
909
910 /**
911 @name Text properties functions
912 */
913 //@{
914
915 /**
916 Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
917
918 @see SetBackgroundMode()
919 */
920 int GetBackgroundMode() const;
921
922 /**
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.
928 */
929 const wxFont& GetFont() const;
930
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()
938 */
939 wxLayoutDirection GetLayoutDirection() const;
940
941 /**
942 Gets the current text background colour.
943
944 @see SetTextBackground()
945 */
946 const wxColour& GetTextBackground() const;
947
948 /**
949 Gets the current text foreground colour.
950
951 @see SetTextForeground()
952 */
953 const wxColour& GetTextForeground() const;
954
955 /**
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.
960 */
961 void SetBackgroundMode(int mode);
962
963 /**
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.
969
970 @see wxFont
971 */
972 void SetFont(const wxFont& font);
973
974 /**
975 Sets the current text background colour for the DC.
976 */
977 void SetTextBackground(const wxColour& colour);
978
979 /**
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.
984 */
985 void SetTextForeground(const wxColour& colour);
986
987 /**
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.
993
994 @see GetLayoutDirection()
995 */
996 void SetLayoutDirection(wxLayoutDirection dir);
997
998 //@}
999
1000
1001 /**
1002 @name Bounding box functions
1003 */
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);
1013
1014 /**
1015 Gets the maximum horizontal extent used in drawing commands so far.
1016 */
1017 wxCoord MaxX() const;
1018
1019 /**
1020 Gets the maximum vertical extent used in drawing commands so far.
1021 */
1022 wxCoord MaxY() const;
1023
1024 /**
1025 Gets the minimum horizontal extent used in drawing commands so far.
1026 */
1027 wxCoord MinX() const;
1028
1029 /**
1030 Gets the minimum vertical extent used in drawing commands so far.
1031 */
1032 wxCoord MinY() const;
1033
1034 /**
1035 Resets the bounding box: after a call to this function, the bounding
1036 box doesn't contain anything.
1037
1038 @see CalcBoundingBox()
1039 */
1040 void ResetBoundingBox();
1041
1042 //@}
1043
1044
1045 /**
1046 @name Page and document start/end functions
1047 */
1048 //@{
1049
1050 /**
1051 Starts a document (only relevant when outputting to a printer).
1052 @a message is a message to show while printing.
1053 */
1054 bool StartDoc(const wxString& message);
1055
1056 /**
1057 Starts a document page (only relevant when outputting to a printer).
1058 */
1059 void StartPage();
1060
1061 /**
1062 Ends a document (only relevant when outputting to a printer).
1063 */
1064 void EndDoc();
1065
1066 /**
1067 Ends a document page (only relevant when outputting to a printer).
1068 */
1069 void EndPage();
1070
1071 //@}
1072
1073
1074 /**
1075 @name Bit-Block Transfer operations (blit)
1076 */
1077 //@{
1078
1079 /**
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().
1086
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
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
1131 considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
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.
1143
1144 @remarks There is partial support for Blit() in wxPostScriptDC, under X.
1145
1146 @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
1147 */
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);
1152
1153 /**
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
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.
1166
1167 @param xdest
1168 Destination device context x position.
1169 @param ydest
1170 Destination device context y position.
1171 @param dstWidth
1172 Width of destination area.
1173 @param dstHeight
1174 Height of destination area.
1175 @param source
1176 Source device context.
1177 @param xsrc
1178 Source device context x position.
1179 @param ysrc
1180 Source device context y position.
1181 @param srcWidth
1182 Width of source area to be copied.
1183 @param srcHeight
1184 Height of source area to be copied.
1185 @param logicalFunc
1186 Logical function to use, see SetLogicalFunction().
1187 @param useMask
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
1210 considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
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.
1214 @param xsrcMask
1215 Source x position on the mask. If both xsrcMask and ysrcMask are
1216 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1217 source position. Currently only implemented on Windows.
1218 @param ysrcMask
1219 Source y position on the mask. If both xsrcMask and ysrcMask are
1220 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1221 source position. Currently only implemented on Windows.
1222
1223 There is partial support for Blit() in wxPostScriptDC, under X.
1224
1225 See wxMemoryDC for typical usage.
1226
1227 @since 2.9.0
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,
1235 wxRasterOperationMode logicalFunc = wxCOPY,
1236 bool useMask = false,
1237 wxCoord xsrcMask = wxDefaultCoord,
1238 wxCoord ysrcMask = wxDefaultCoord);
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
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.
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 /**
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.
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
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);
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
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.
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
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
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
1401 @beginWxPerlOnly
1402 In wxPerl this method takes no arguments and return a two
1403 element array (x, y).
1404 @endWxPerlOnly
1405
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 /**
1416 Sets the x and y axis orientation (i.e., the direction from lowest to
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 /**
1430 Sets the device origin (i.e., the origin in pixels after scaling has
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);
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 //@}
1536
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 //@}
1554
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;
1569
1570
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
1576
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
1583 };
1584
1585
1586
1587 /**
1588 @class wxDCClipper
1589
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:
1596
1597 @code
1598 void MyFunction(wxDC& dc)
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 }
1610 @endcode
1611
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
1618 @library{wxcore}
1619 @category{gdi}
1620
1621 @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1622 wxDCBrushChanger
1623 */
1624 class wxDCClipper
1625 {
1626 public:
1627 //@{
1628 /**
1629 Sets the clipping region to the specified region/coordinates.
1630
1631 The clipping region is automatically unset when this object is destroyed.
1632 */
1633 wxDCClipper(wxDC& dc, const wxRegion& region);
1634 wxDCClipper(wxDC& dc, const wxRect& rect);
1635 wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h);
1636 //@}
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
1654 @see wxDC::SetBrush(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1655 wxDCClipper
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
1686 @see wxDC::SetPen(), wxDCFontChanger, wxDCTextColourChanger, wxDCBrushChanger,
1687 wxDCClipper
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
1720 @see wxDC::SetTextForeground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger,
1721 wxDCClipper
1722 */
1723 class wxDCTextColourChanger
1724 {
1725 public:
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
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
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
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
1776 @see wxDC::SetFont(), wxDCTextColourChanger, wxDCPenChanger, wxDCBrushChanger,
1777 wxDCClipper
1778 */
1779 class wxDCFontChanger
1780 {
1781 public:
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
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 /**
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.
1817 */
1818 ~wxDCFontChanger();
1819 };
1820