1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDC
4 // Author: wxWidgets team
6 // Licence: wxWindows licence
7 /////////////////////////////////////////////////////////////////////////////
11 Logical raster operations which can be used with wxDC::SetLogicalFunction
12 and some other wxDC functions (e.g. wxDC::Blit and wxDC::StretchBlit).
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.
19 enum wxRasterOperationMode
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)
27 wxAND
, //!< @e src AND @e dst
28 wxAND_INVERT
, //!< (NOT @e src) AND @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
40 Flood styles used by wxDC::FloodFill.
44 /** The flooding occurs until a colour other than the given colour is encountered. */
47 /** The area to be flooded is bounded by the given colour. */
52 The mapping used to transform @e logical units to @e device units.
58 Each logical unit is 1 device pixel.
59 This is the default mapping mode for all wxDC-derived classes.
63 /** Each logical unit is 1 millimeter. */
66 /** Each logical unit is 1/10 of a millimeter. */
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.
76 Each logical unit is a @e "printer point" i.e. 1/72 of an inch.
77 Equivalent to about 353 micrometers.
83 Simple collection of various font metrics.
85 This object is returned by wxDC::GetFontMetrics().
94 /// Constructor initializes all fields to 0.
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".
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.
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.
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.
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
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.
138 @section dc_units Device and logical units
140 In the wxDC context there is a distinction between @e logical units and @e device units.
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).
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).
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.
154 @section dc_alpha_support Support for Transparency / Alpha Channel
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.
166 @section Support for Transformation Matrix
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
180 @see @ref overview_dc, wxGraphicsContext, wxDCFontChanger, wxDCTextColourChanger,
181 wxDCPenChanger, wxDCBrushChanger, wxDCClipper
183 @todo Precise definition of default/initial state.
184 @todo Pixelwise definition of operations (e.g. last point of a line not
187 class wxDC
: public wxObject
191 @name Coordinate conversion functions
196 Convert @e device X coordinate to logical coordinate, using the current
197 mapping mode, user scale factor, device origin and axis orientation.
199 wxCoord
DeviceToLogicalX(wxCoord x
) const;
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.
206 wxCoord
DeviceToLogicalXRel(wxCoord x
) const;
209 Converts @e device Y coordinate to logical coordinate, using the current
210 mapping mode, user scale factor, device origin and axis orientation.
212 wxCoord
DeviceToLogicalY(wxCoord y
) const;
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.
219 wxCoord
DeviceToLogicalYRel(wxCoord y
) const;
222 Converts logical X coordinate to device coordinate, using the current
223 mapping mode, user scale factor, device origin and axis orientation.
225 wxCoord
LogicalToDeviceX(wxCoord x
) const;
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.
232 wxCoord
LogicalToDeviceXRel(wxCoord x
) const;
235 Converts logical Y coordinate to device coordinate, using the current
236 mapping mode, user scale factor, device origin and axis orientation.
238 wxCoord
LogicalToDeviceY(wxCoord y
) const;
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.
245 wxCoord
LogicalToDeviceYRel(wxCoord y
) const;
252 @name Drawing functions
257 Clears the device context using the current background brush.
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
267 The arc is drawn in a counter-clockwise direction from the start point
270 void DrawArc(wxCoord xStart
, wxCoord yStart
, wxCoord xEnd
, wxCoord yEnd
,
271 wxCoord xc
, wxCoord yc
);
276 void DrawArc(const wxPoint
& ptStart
, const wxPoint
& ptEnd
, const wxPoint
& centre
);
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.
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
288 @see SetTextForeground(), SetTextBackground(), wxMemoryDC
290 void DrawBitmap(const wxBitmap
& bitmap
, wxCoord x
, wxCoord y
,
291 bool useMask
= false);
296 void DrawBitmap(const wxBitmap
&bmp
, const wxPoint
& pt
,
297 bool useMask
= false);
300 Draws a check mark inside the given rectangle.
302 void DrawCheckMark(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
307 void DrawCheckMark(const wxRect
& rect
);
310 Draws a circle with the given centre and radius.
314 void DrawCircle(wxCoord x
, wxCoord y
, wxCoord radius
);
319 void DrawCircle(const wxPoint
& pt
, wxCoord radius
);
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.
328 void DrawEllipse(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
333 void DrawEllipse(const wxPoint
& pt
, const wxSize
& size
);
338 void DrawEllipse(const wxRect
& rect
);
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.
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.
347 @a width and @a height specify the width and height of the rectangle
348 that contains the ellipse.
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.
356 void DrawEllipticArc(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
,
357 double start
, double end
);
362 void DrawEllipticArc(const wxPoint
& pt
, const wxSize
& sz
,
363 double sa
, double ea
);
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
370 void DrawIcon(const wxIcon
& icon
, wxCoord x
, wxCoord y
);
375 void DrawIcon(const wxIcon
& icon
, const wxPoint
& pt
);
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.
383 void DrawLabel(const wxString
& text
, const wxBitmap
& bitmap
,
385 int alignment
= wxALIGN_LEFT
| wxALIGN_TOP
,
386 int indexAccel
= -1, wxRect
* rectBounding
= NULL
);
391 void DrawLabel(const wxString
& text
, const wxRect
& rect
,
392 int alignment
= wxALIGN_LEFT
| wxALIGN_TOP
,
393 int indexAccel
= -1);
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).
401 void DrawLine(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
);
406 void DrawLine(const wxPoint
& pt1
, const wxPoint
& pt2
);
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.
413 The wxPython version of this method accepts a Python list of wxPoint
418 Not supported by wxPerl.
421 void DrawLines(int n
, wxPoint points
[], wxCoord xoffset
= 0,
422 wxCoord yoffset
= 0);
424 This method uses a list of wxPoints, adding the optional offset
425 coordinate. The programmer is responsible for deleting the list of
429 The wxPython version of this method accepts a Python list of wxPoint
434 The wxPerl version of this method accepts
435 as its first parameter a reference to an array
439 void DrawLines(const wxPointList
* points
,
440 wxCoord xoffset
= 0, wxCoord yoffset
= 0);
443 Draws a point using the color of the current pen. Note that the other
444 properties of the pen are not used, such as width.
446 void DrawPoint(wxCoord x
, wxCoord y
);
451 void DrawPoint(const wxPoint
& pt
);
454 Draws a filled polygon using an array of points of size @a n, adding
455 the optional offset coordinate. The first and last points are
456 automatically closed.
458 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
459 default) or @b wxWINDING_RULE.
461 The current pen is used for drawing the outline, and the current brush
462 for filling the shape. Using a transparent brush suppresses filling.
465 Not supported by wxPerl.
468 void DrawPolygon(int n
, wxPoint points
[], wxCoord xoffset
= 0,
470 wxPolygonFillMode fill_style
= wxODDEVEN_RULE
);
472 This method draws a filled polygon using a list of wxPoints, adding the
473 optional offset coordinate. The first and last points are automatically
476 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
477 default) or @b wxWINDING_RULE.
479 The current pen is used for drawing the outline, and the current brush
480 for filling the shape. Using a transparent brush suppresses filling.
482 The programmer is responsible for deleting the list of points.
485 The wxPython version of this method accepts a Python list of wxPoint
490 The wxPerl version of this method accepts
491 as its first parameter a reference to an array
495 void DrawPolygon(const wxPointList
* points
,
496 wxCoord xoffset
= 0, wxCoord yoffset
= 0,
497 wxPolygonFillMode fill_style
= wxODDEVEN_RULE
);
500 Draws two or more filled polygons using an array of @a points, adding
501 the optional offset coordinates.
503 Notice that for the platforms providing a native implementation of this
504 function (Windows and PostScript-based wxDC currently), this is more
505 efficient than using DrawPolygon() in a loop.
507 @a n specifies the number of polygons to draw, the array @e count of
508 size @a n specifies the number of points in each of the polygons in the
511 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
512 default) or @b wxWINDING_RULE.
514 The current pen is used for drawing the outline, and the current brush
515 for filling the shape. Using a transparent brush suppresses filling.
517 The polygons maybe disjoint or overlapping. Each polygon specified in a
518 call to DrawPolyPolygon() must be closed. Unlike polygons created by
519 the DrawPolygon() member function, the polygons created by this
520 method are not closed automatically.
526 void DrawPolyPolygon(int n
, int count
[], wxPoint points
[],
527 wxCoord xoffset
= 0, wxCoord yoffset
= 0,
528 wxPolygonFillMode fill_style
= wxODDEVEN_RULE
);
531 Draws a rectangle with the given top left corner, and with the given
532 size. The current pen is used for the outline and the current brush
533 for filling the shape.
535 void DrawRectangle(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
540 void DrawRectangle(const wxPoint
& pt
, const wxSize
& sz
);
545 void DrawRectangle(const wxRect
& rect
);
548 Draws the text rotated by @a angle degrees
549 (positive angles are counterclockwise; the full angle is 360 degrees).
551 @note Under Win9x only TrueType fonts can be drawn by this function. In
552 particular, a font different from @c wxNORMAL_FONT should be used
553 as the latter is not a TrueType font. @c wxSWISS_FONT is an
554 example of a font which is.
558 void DrawRotatedText(const wxString
& text
, wxCoord x
, wxCoord y
,
564 void DrawRotatedText(const wxString
& text
, const wxPoint
& point
,
568 Draws a rectangle with the given top left corner, and with the given
569 size. The corners are quarter-circles using the given radius. The
570 current pen is used for the outline and the current brush for filling
573 If @a radius is positive, the value is assumed to be the radius of the
574 rounded corner. If @a radius is negative, the absolute value is assumed
575 to be the @e proportion of the smallest dimension of the rectangle.
576 This means that the corner can be a sensible size relative to the size
577 of the rectangle, and also avoids the strange effects X produces when
578 the corners are too big for the rectangle.
580 void DrawRoundedRectangle(wxCoord x
, wxCoord y
, wxCoord width
,
581 wxCoord height
, double radius
);
586 void DrawRoundedRectangle(const wxPoint
& pt
, const wxSize
& sz
,
592 void DrawRoundedRectangle(const wxRect
& rect
, double radius
);
595 Draws a spline between all given points using the current pen.
598 The wxPython version of this method accepts a Python list of wxPoint
603 Not supported by wxPerl.
606 void DrawSpline(int n
, wxPoint points
[]);
613 The wxPerl version of this method accepts
614 as its first parameter a reference to an array
618 void DrawSpline(const wxPointList
* points
);
625 Not supported by wxPerl.
628 void DrawSpline(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
,
629 wxCoord x3
, wxCoord y3
);
632 Draws a text string at the specified point, using the current text
633 font, and the current text foreground and background colours.
635 The coordinates refer to the top-left corner of the rectangle bounding
636 the string. See GetTextExtent() for how to get the dimensions of a text
637 string, which can be used to position the text more precisely and
638 DrawLabel() if you need to align the string differently.
640 Starting from wxWidgets 2.9.2 @a text parameter can be a multi-line
641 string, i.e. contain new line characters, and will be rendered
644 @note The current @ref GetLogicalFunction() "logical function" is
645 ignored by this function.
647 void DrawText(const wxString
& text
, wxCoord x
, wxCoord y
);
652 void DrawText(const wxString
& text
, const wxPoint
& pt
);
655 Fill the area specified by rect with a radial gradient, starting from
656 @a initialColour at the centre of the circle and fading to
657 @a destColour on the circle outside.
659 The circle is placed at the centre of @a rect.
661 @note Currently this function is very slow, don't use it for real-time
664 void GradientFillConcentric(const wxRect
& rect
,
665 const wxColour
& initialColour
,
666 const wxColour
& destColour
);
669 Fill the area specified by rect with a radial gradient, starting from
670 @a initialColour at the centre of the circle and fading to
671 @a destColour on the circle outside.
673 @a circleCenter are the relative coordinates of centre of the circle in
674 the specified @a rect.
676 @note Currently this function is very slow, don't use it for real-time
679 void GradientFillConcentric(const wxRect
& rect
,
680 const wxColour
& initialColour
,
681 const wxColour
& destColour
,
682 const wxPoint
& circleCenter
);
685 Fill the area specified by @a rect with a linear gradient, starting
686 from @a initialColour and eventually fading to @e destColour.
688 The @a nDirection specifies the direction of the colour change, default is
689 to use @a initialColour on the left part of the rectangle and
690 @a destColour on the right one.
692 void GradientFillLinear(const wxRect
& rect
, const wxColour
& initialColour
,
693 const wxColour
& destColour
,
694 wxDirection nDirection
= wxRIGHT
);
697 Flood fills the device context starting from the given point, using
698 the current brush colour, and using a style:
700 - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
701 given colour is encountered.
702 - wxFLOOD_BORDER: The area to be flooded is bounded by the given
705 @return @false if the operation failed.
707 @note The present implementation for non-Windows platforms may fail to
708 find colour borders if the pixels do not match the colour
709 exactly. However the function will still return @true.
711 @note This method shouldn't be used with wxPaintDC under non-Windows
712 platforms as it uses GetPixel() internally and this may give
713 wrong results, notably in wxGTK. If you need to flood fill
714 wxPaintDC, create a temporary wxMemoryDC, flood fill it and then
715 blit it to, or draw as a bitmap on, wxPaintDC. See the example of
716 doing this in the drawing sample and wxBufferedPaintDC class.
718 bool FloodFill(wxCoord x
, wxCoord y
, const wxColour
& colour
,
719 wxFloodFillStyle style
= wxFLOOD_SURFACE
);
724 bool FloodFill(const wxPoint
& pt
, const wxColour
& col
,
725 wxFloodFillStyle style
= wxFLOOD_SURFACE
);
728 Displays a cross hair using the current pen. This is a vertical and
729 horizontal line the height and width of the window, centred on the
732 void CrossHair(wxCoord x
, wxCoord y
);
737 void CrossHair(const wxPoint
& pt
);
743 @name Clipping region functions
748 Destroys the current clipping region so that none of the DC is clipped.
750 @see SetClippingRegion()
752 void DestroyClippingRegion();
755 Gets the rectangle surrounding the current clipping region.
758 No arguments are required and the four values defining the rectangle
759 are returned as a tuple.
762 void GetClippingBox(wxCoord
*x
, wxCoord
*y
, wxCoord
*width
, wxCoord
*height
) const;
765 Sets the clipping region for this device context to the intersection of
766 the given region described by the parameters of this method and the
767 previously set clipping region.
769 The clipping region is an area to which drawing is restricted. Possible
770 uses for the clipping region are for clipping text or for speeding up
771 window redraws when only a known area of the screen is damaged.
773 Notice that you need to call DestroyClippingRegion() if you want to set
774 the clipping region exactly to the region specified.
776 Also note that if the clipping region is empty, any previously set
777 clipping region is destroyed, i.e. it is equivalent to calling
778 DestroyClippingRegion(), and not to clipping out all drawing on the DC
779 as might be expected.
781 @see DestroyClippingRegion(), wxRegion
783 void SetClippingRegion(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
788 void SetClippingRegion(const wxPoint
& pt
, const wxSize
& sz
);
793 void SetClippingRegion(const wxRect
& rect
);
796 Sets the clipping region for this device context.
798 Unlike SetClippingRegion(), this function works with physical
799 coordinates and not with the logical ones.
801 void SetDeviceClippingRegion(const wxRegion
& region
);
807 @name Text/character extent functions
812 Gets the character height of the currently set font.
814 wxCoord
GetCharHeight() const;
817 Gets the average character width of the currently set font.
819 wxCoord
GetCharWidth() const;
822 Returns the various font characteristics.
824 This method allows to retrieve some of the font characteristics not
825 returned by GetTextExtent(), notably internal leading and average
828 Currently this method returns correct results only under wxMSW, in the
829 other ports the internal leading will always be 0 and the average
830 character width will be computed as the width of the character 'x'.
834 wxFontMetrics
GetFontMetrics() const;
837 Gets the dimensions of the string using the currently selected font.
838 @a string is the text string to measure, @e heightLine, if non @NULL,
839 is where to store the height of a single line.
841 The text extent is set in the given @a w and @a h pointers.
843 If the optional parameter @a font is specified and valid, then it is
844 used for the text extent calculation, otherwise the currently selected
847 @note This function works with both single-line and multi-line strings.
850 In wxPerl this method is implemented as
851 GetMultiLineTextExtent(string, font = undef) returning a
852 3-element list (width, height, line_height)
855 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
857 void GetMultiLineTextExtent(const wxString
& string
, wxCoord
* w
,
859 wxCoord
* heightLine
= NULL
,
860 const wxFont
* font
= NULL
) const;
862 Gets the dimensions of the string using the currently selected font.
863 @a string is the text string to measure, @e heightLine, if non @NULL,
864 is where to store the height of a single line.
866 @return The text extent as a wxSize object.
868 @note This function works with both single-line and multi-line strings.
871 Not supported by wxPerl.
874 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
876 wxSize
GetMultiLineTextExtent(const wxString
& string
) const;
879 Fills the @a widths array with the widths from the beginning of @a text
880 to the corresponding character of @a text. The generic version simply
881 builds a running total of the widths of each character using
882 GetTextExtent(), however if the various platforms have a native API
883 function that is faster or more accurate than the generic
884 implementation then it should be used instead.
887 This method only takes the @a text parameter and returns a Python list
892 In wxPerl this method only takes the @a text parameter and
893 returns the widths as a list of integers.
896 @see GetMultiLineTextExtent(), GetTextExtent()
898 bool GetPartialTextExtents(const wxString
& text
,
899 wxArrayInt
& widths
) const;
902 Gets the dimensions of the string using the currently selected font.
903 @a string is the text string to measure, @a descent is the dimension
904 from the baseline of the font to the bottom of the descender, and
905 @a externalLeading is any extra vertical space added to the font by the
906 font designer (usually is zero).
908 The text extent is returned in @a w and @a h pointers or as a wxSize
909 object depending on which version of this function is used.
911 If the optional parameter @a font is specified and valid, then it is
912 used for the text extent calculation. Otherwise the currently selected
915 @note This function only works with single-line strings.
918 The following methods are implemented in wxPython:
919 - GetTextExtent(string) - Returns a 2-tuple, (width, height).
920 - GetFullTextExtent(string, font=NULL) -
921 Returns a 4-tuple, (width, height, descent, externalLeading).
925 In wxPerl this method is implemented as GetTextExtent(string,
926 font = undef) returning a 4-element list (width, height,
927 descent, externalLeading)
930 @see wxFont, SetFont(), GetPartialTextExtents(),
931 GetMultiLineTextExtent()
933 void GetTextExtent(const wxString
& string
, wxCoord
* w
, wxCoord
* h
,
934 wxCoord
* descent
= NULL
,
935 wxCoord
* externalLeading
= NULL
,
936 const wxFont
* font
= NULL
) const;
943 Not supported by wxPerl.
946 wxSize
GetTextExtent(const wxString
& string
) const;
952 @name Text properties functions
957 Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
959 @see SetBackgroundMode()
961 int GetBackgroundMode() const;
964 Gets the current font.
966 Notice that even although each device context object has some default font
967 after creation, this method would return a ::wxNullFont initially and only
968 after calling SetFont() a valid font is returned.
970 const wxFont
& GetFont() const;
973 Gets the current layout direction of the device context. On platforms
974 where RTL layout is supported, the return value will either be
975 @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
976 not supported, the return value will be @c wxLayout_Default.
978 @see SetLayoutDirection()
980 wxLayoutDirection
GetLayoutDirection() const;
983 Gets the current text background colour.
985 @see SetTextBackground()
987 const wxColour
& GetTextBackground() const;
990 Gets the current text foreground colour.
992 @see SetTextForeground()
994 const wxColour
& GetTextForeground() const;
997 @a mode may be one of @c wxSOLID and @c wxTRANSPARENT.
999 This setting determines whether text will be drawn with a background
1002 void SetBackgroundMode(int mode
);
1005 Sets the current font for the DC.
1007 If the argument is ::wxNullFont (or another invalid font; see wxFont::IsOk),
1008 the current font is selected out of the device context (leaving wxDC without
1009 any valid font), allowing the current font to be destroyed safely.
1013 void SetFont(const wxFont
& font
);
1016 Sets the current text background colour for the DC.
1018 void SetTextBackground(const wxColour
& colour
);
1021 Sets the current text foreground colour for the DC.
1023 @see wxMemoryDC for the interpretation of colours when drawing into a
1026 void SetTextForeground(const wxColour
& colour
);
1029 Sets the current layout direction for the device context.
1032 May be either @c wxLayout_Default, @c wxLayout_LeftToRight or
1033 @c wxLayout_RightToLeft.
1035 @see GetLayoutDirection()
1037 void SetLayoutDirection(wxLayoutDirection dir
);
1043 @name Bounding box functions
1048 Adds the specified point to the bounding box which can be retrieved
1049 with MinX(), MaxX() and MinY(), MaxY() functions.
1051 @see ResetBoundingBox()
1053 void CalcBoundingBox(wxCoord x
, wxCoord y
);
1056 Gets the maximum horizontal extent used in drawing commands so far.
1058 wxCoord
MaxX() const;
1061 Gets the maximum vertical extent used in drawing commands so far.
1063 wxCoord
MaxY() const;
1066 Gets the minimum horizontal extent used in drawing commands so far.
1068 wxCoord
MinX() const;
1071 Gets the minimum vertical extent used in drawing commands so far.
1073 wxCoord
MinY() const;
1076 Resets the bounding box: after a call to this function, the bounding
1077 box doesn't contain anything.
1079 @see CalcBoundingBox()
1081 void ResetBoundingBox();
1087 @name Page and document start/end functions
1092 Starts a document (only relevant when outputting to a printer).
1093 @a message is a message to show while printing.
1095 bool StartDoc(const wxString
& message
);
1098 Starts a document page (only relevant when outputting to a printer).
1103 Ends a document (only relevant when outputting to a printer).
1108 Ends a document page (only relevant when outputting to a printer).
1116 @name Bit-Block Transfer operations (blit)
1121 Copy from a source DC to this DC.
1123 With this method you can specify the destination coordinates and the
1124 size of area to copy which will be the same for both the source and
1125 target DCs. If you need to apply scaling while copying, use
1129 Destination device context x position.
1131 Destination device context y position.
1133 Width of source area to be copied.
1135 Height of source area to be copied.
1137 Source device context.
1139 Source device context x position.
1141 Source device context y position.
1143 Logical function to use, see SetLogicalFunction().
1145 If @true, Blit does a transparent blit using the mask that is
1146 associated with the bitmap selected into the source device context.
1147 The Windows implementation does the following if MaskBlt cannot be
1150 <li>Creates a temporary bitmap and copies the destination area into
1152 <li>Copies the source area into the temporary bitmap using the
1153 specified logical function.</li>
1154 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1155 the mask bitmap with the temp bitmap with the foreground colour
1156 set to WHITE and the bg colour set to BLACK.</li>
1157 <li>Sets the unmasked area in the destination area to BLACK by
1158 ANDing the mask bitmap with the destination area with the
1159 foreground colour set to BLACK and the background colour set to
1161 <li>ORs the temporary bitmap with the destination area.</li>
1162 <li>Deletes the temporary bitmap.</li>
1164 This sequence of operations ensures that the source's transparent
1165 area need not be black, and logical functions are supported.
1166 @n @b Note: on Windows, blitting with masks can be speeded up
1167 considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
1168 enabled. You can also influence whether MaskBlt or the explicit
1169 mask blitting code above is used, by using wxSystemOptions and
1170 setting the @c no-maskblt option to 1.
1172 Source x position on the mask. If both xsrcMask and ysrcMask are
1173 @c -1, xsrc and ysrc will be assumed for the mask source position.
1174 Currently only implemented on Windows.
1176 Source y position on the mask. If both xsrcMask and ysrcMask are
1177 @c -1, xsrc and ysrc will be assumed for the mask source position.
1178 Currently only implemented on Windows.
1180 @remarks There is partial support for Blit() in wxPostScriptDC, under X.
1182 @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
1184 bool Blit(wxCoord xdest
, wxCoord ydest
, wxCoord width
,
1185 wxCoord height
, wxDC
* source
, wxCoord xsrc
, wxCoord ysrc
,
1186 wxRasterOperationMode logicalFunc
= wxCOPY
, bool useMask
= false,
1187 wxCoord xsrcMask
= wxDefaultCoord
, wxCoord ysrcMask
= wxDefaultCoord
);
1190 Copy from a source DC to this DC possibly changing the scale.
1192 Unlike Blit(), this method allows to specify different source and
1193 destination region sizes, meaning that it can stretch or shrink it
1194 while copying. The same can be achieved by changing the scale of the
1195 source or target DC but calling this method is simpler and can also be
1196 more efficient if the platform provides a native implementation of it.
1198 The meaning of its other parameters is the same as with Blit().
1201 Destination device context x position.
1203 Destination device context y position.
1205 Width of destination area.
1207 Height of destination area.
1209 Source device context.
1211 Source device context x position.
1213 Source device context y position.
1215 Width of source area to be copied.
1217 Height of source area to be copied.
1219 Logical function to use, see SetLogicalFunction().
1221 If @true, Blit does a transparent blit using the mask that is
1222 associated with the bitmap selected into the source device context.
1223 The Windows implementation does the following if MaskBlt cannot be
1226 <li>Creates a temporary bitmap and copies the destination area into
1228 <li>Copies the source area into the temporary bitmap using the
1229 specified logical function.</li>
1230 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1231 the mask bitmap with the temp bitmap with the foreground colour
1232 set to WHITE and the bg colour set to BLACK.</li>
1233 <li>Sets the unmasked area in the destination area to BLACK by
1234 ANDing the mask bitmap with the destination area with the
1235 foreground colour set to BLACK and the background colour set to
1237 <li>ORs the temporary bitmap with the destination area.</li>
1238 <li>Deletes the temporary bitmap.</li>
1240 This sequence of operations ensures that the source's transparent
1241 area need not be black, and logical functions are supported.
1242 @n @b Note: on Windows, blitting with masks can be speeded up
1243 considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
1244 enabled. You can also influence whether MaskBlt or the explicit
1245 mask blitting code above is used, by using wxSystemOptions and
1246 setting the @c no-maskblt option to 1.
1248 Source x position on the mask. If both xsrcMask and ysrcMask are
1249 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1250 source position. Currently only implemented on Windows.
1252 Source y position on the mask. If both xsrcMask and ysrcMask are
1253 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1254 source position. Currently only implemented on Windows.
1256 There is partial support for Blit() in wxPostScriptDC, under X.
1258 See wxMemoryDC for typical usage.
1262 @see Blit(), wxMemoryDC, wxBitmap, wxMask
1264 bool StretchBlit(wxCoord xdest
, wxCoord ydest
,
1265 wxCoord dstWidth
, wxCoord dstHeight
,
1266 wxDC
* source
, wxCoord xsrc
, wxCoord ysrc
,
1267 wxCoord srcWidth
, wxCoord srcHeight
,
1268 wxRasterOperationMode logicalFunc
= wxCOPY
,
1269 bool useMask
= false,
1270 wxCoord xsrcMask
= wxDefaultCoord
,
1271 wxCoord ysrcMask
= wxDefaultCoord
);
1276 @name Background/foreground brush and pen
1281 Gets the brush used for painting the background.
1283 @see wxDC::SetBackground()
1285 const wxBrush
& GetBackground() const;
1288 Gets the current brush.
1290 @see wxDC::SetBrush()
1292 const wxBrush
& GetBrush() const;
1295 Gets the current pen.
1299 const wxPen
& GetPen() const;
1302 Sets the current background brush for the DC.
1304 void SetBackground(const wxBrush
& brush
);
1307 Sets the current brush for the DC.
1309 If the argument is ::wxNullBrush (or another invalid brush; see wxBrush::IsOk),
1310 the current brush is selected out of the device context (leaving wxDC without
1311 any valid brush), allowing the current brush to be destroyed safely.
1313 @see wxBrush, wxMemoryDC (for the interpretation of colours when
1314 drawing into a monochrome bitmap)
1316 void SetBrush(const wxBrush
& brush
);
1319 Sets the current pen for the DC.
1321 If the argument is ::wxNullPen (or another invalid pen; see wxPen::IsOk),
1322 the current pen is selected out of the device context (leaving wxDC without any
1323 valid pen), allowing the current pen to be destroyed safely.
1325 @see wxMemoryDC for the interpretation of colours when drawing into a
1328 void SetPen(const wxPen
& pen
);
1334 Copy attributes from another DC.
1336 The copied attributes currently are:
1338 - Text foreground and background colours
1343 A valid (i.e. its IsOk() must return @true) source device context.
1345 void CopyAttributes(const wxDC
& dc
);
1348 Returns the depth (number of bits/pixel) of this DC.
1350 @see wxDisplayDepth()
1352 int GetDepth() const;
1355 Returns the current device origin.
1357 @see SetDeviceOrigin()
1359 wxPoint
GetDeviceOrigin() const;
1362 Gets the current logical function.
1364 @see SetLogicalFunction()
1366 wxRasterOperationMode
GetLogicalFunction() const;
1369 Gets the current mapping mode for the device context.
1373 wxMappingMode
GetMapMode() const;
1376 Gets in @a colour the colour at the specified location. Not available
1377 for wxPostScriptDC or wxMetafileDC.
1379 @note Setting a pixel can be done using DrawPoint().
1381 @note This method shouldn't be used with wxPaintDC as accessing the DC
1382 while drawing can result in unexpected results, notably in wxGTK.
1385 The wxColour value is returned and is not required as a parameter.
1388 bool GetPixel(wxCoord x
, wxCoord y
, wxColour
* colour
) const;
1391 Returns the resolution of the device in pixels per inch.
1393 wxSize
GetPPI() const;
1396 Gets the horizontal and vertical extent of this device context in @e device units.
1397 It can be used to scale graphics to fit the page.
1399 For example, if @e maxX and @e maxY represent the maximum horizontal
1400 and vertical 'pixel' values used in your application, the following
1401 code will scale the graphic to fit on the printer page:
1406 double scaleX = (double)(maxX / w);
1407 double scaleY = (double)(maxY / h);
1408 dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
1412 In place of a single overloaded method name, wxPython implements the
1414 - GetSize() - Returns a wxSize.
1415 - GetSizeWH() - Returns a 2-tuple (width, height).
1419 In wxPerl there are two methods instead of a single overloaded
1421 - GetSize(): returns a Wx::Size object.
1422 - GetSizeWH(): returns a 2-element list (width, height).
1425 void GetSize(wxCoord
* width
, wxCoord
* height
) const;
1430 wxSize
GetSize() const;
1433 Returns the horizontal and vertical resolution in millimetres.
1435 void GetSizeMM(wxCoord
* width
, wxCoord
* height
) const;
1440 wxSize
GetSizeMM() const;
1443 Gets the current user scale factor.
1446 In wxPerl this method takes no arguments and return a two
1447 element array (x, y).
1452 void GetUserScale(double* x
, double* y
) const;
1455 Returns @true if the DC is ok to use.
1460 Sets the x and y axis orientation (i.e., the direction from lowest to
1461 highest values on the axis). The default orientation is x axis from
1462 left to right and y axis from top down.
1465 True to set the x axis orientation to the natural left to right
1466 orientation, @false to invert it.
1468 True to set the y axis orientation to the natural bottom up
1469 orientation, @false to invert it.
1471 void SetAxisOrientation(bool xLeftRight
, bool yBottomUp
);
1474 Sets the device origin (i.e., the origin in pixels after scaling has
1475 been applied). This function may be useful in Windows printing
1476 operations for placing a graphic on a page.
1478 void SetDeviceOrigin(wxCoord x
, wxCoord y
);
1481 Sets the current logical function for the device context.
1482 It determines how a @e source pixel (from a pen or brush colour, or source
1483 device context if using Blit()) combines with a @e destination pixel in
1484 the current device context.
1485 Text drawing is not affected by this function.
1487 See ::wxRasterOperationMode enumeration values for more info.
1489 The default is @c wxCOPY, which simply draws with the current colour.
1490 The others combine the current colour and the background using a logical
1491 operation. @c wxINVERT is commonly used for drawing rubber bands or moving
1492 outlines, since drawing twice reverts to the original colour.
1494 void SetLogicalFunction(wxRasterOperationMode function
);
1497 The mapping mode of the device context defines the unit of measurement
1498 used to convert @e logical units to @e device units.
1500 Note that in X, text drawing isn't handled consistently with the mapping mode;
1501 a font is always specified in point size. However, setting the user scale (see
1502 SetUserScale()) scales the text appropriately. In Windows, scalable
1503 TrueType fonts are always used; in X, results depend on availability of
1504 fonts, but usually a reasonable match is found.
1506 The coordinate origin is always at the top left of the screen/printer.
1508 Drawing to a Windows printer device context uses the current mapping
1509 mode, but mapping mode is currently ignored for PostScript output.
1511 void SetMapMode(wxMappingMode mode
);
1514 If this is a window DC or memory DC, assigns the given palette to the
1515 window or bitmap associated with the DC. If the argument is
1516 ::wxNullPalette, the current palette is selected out of the device
1517 context, and the original palette restored.
1521 void SetPalette(const wxPalette
& palette
);
1524 Sets the user scaling factor, useful for applications which require
1527 void SetUserScale(double xScale
, double yScale
);
1531 @name Transformation matrix
1533 See the notes about the availability of these functions in the class
1539 Check if the use of transformation matrix is supported by the current
1542 Currently this function always returns @false for non-MSW platforms and
1543 may return @false for old (Windows 9x/ME) Windows systems. Normally
1544 support for the transformation matrix is always available in any
1545 relatively recent Windows versions.
1549 bool CanUseTransformMatrix() const;
1552 Set the transformation matrix.
1554 If transformation matrix is supported on the current system, the
1555 specified @a matrix will be used to transform between wxDC and physical
1556 coordinates. Otherwise the function returns @false and doesn't change
1557 the coordinate mapping.
1561 bool SetTransformMatrix(const wxAffineMatrix2D
& matrix
);
1564 Return the transformation matrix used by this device context.
1566 By default the transformation matrix is the identity matrix.
1570 wxAffineMatrix2D
GetTransformMatrix() const;
1573 Revert the transformation matrix to identity matrix.
1577 void ResetTransformMatrix();
1582 void SetLogicalScale(double x
, double y
);
1583 void GetLogicalScale(double *x
, double *y
) const;
1584 void SetLogicalOrigin(wxCoord x
, wxCoord y
);
1585 void GetLogicalOrigin(wxCoord
*x
, wxCoord
*y
) const;
1586 wxPoint
GetLogicalOrigin() const;
1595 wxDCClipper is a small helper class for setting a clipping region on a wxDC
1596 and unsetting it automatically. An object of wxDCClipper class is typically
1597 created on the stack so that it is automatically destroyed when the object
1598 goes out of scope. A typical usage example:
1601 void MyFunction(wxDC& dc)
1603 wxDCClipper clip(dc, rect);
1604 // ... drawing functions here are affected by clipping rect ...
1607 void OtherFunction()
1611 // ... drawing functions here are not affected by clipping rect ...
1618 @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1626 Sets the clipping region to the specified region/coordinates.
1628 The clipping region is automatically unset when this object is destroyed.
1630 wxDCClipper(wxDC
& dc
, const wxRegion
& region
);
1631 wxDCClipper(wxDC
& dc
, const wxRect
& rect
);
1632 wxDCClipper(wxDC
& dc
, wxCoord x
, wxCoord y
, wxCoord w
, wxCoord h
);
1636 Destroys the clipping region associated with the DC passed to the ctor.
1643 @class wxDCBrushChanger
1645 wxDCBrushChanger is a small helper class for setting a brush on a wxDC
1646 and unsetting it automatically in the destructor, restoring the previous one.
1651 @see wxDC::SetBrush(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1654 class wxDCBrushChanger
1658 Sets @a brush on the given @a dc, storing the old one.
1661 The DC where the brush must be temporary set.
1665 wxDCBrushChanger(wxDC
& dc
, const wxBrush
& brush
);
1668 Restores the brush originally selected in the DC passed to the ctor.
1670 ~wxDCBrushChanger();
1675 @class wxDCPenChanger
1677 wxDCPenChanger is a small helper class for setting a pen on a wxDC
1678 and unsetting it automatically in the destructor, restoring the previous one.
1683 @see wxDC::SetPen(), wxDCFontChanger, wxDCTextColourChanger, wxDCBrushChanger,
1686 class wxDCPenChanger
1690 Sets @a pen on the given @a dc, storing the old one.
1693 The DC where the pen must be temporary set.
1697 wxDCPenChanger(wxDC
& dc
, const wxPen
& pen
);
1700 Restores the pen originally selected in the DC passed to the ctor.
1708 @class wxDCTextColourChanger
1710 wxDCTextColourChanger is a small helper class for setting a foreground
1711 text colour on a wxDC and unsetting it automatically in the destructor,
1712 restoring the previous one.
1717 @see wxDC::SetTextForeground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger,
1720 class wxDCTextColourChanger
1724 Trivial constructor not changing anything.
1726 This constructor is useful if you don't know beforehand if the colour
1727 needs to be changed or not. It simply creates the object which won't do
1728 anything in its destructor unless Set() is called -- in which case it
1729 would reset the previous colour.
1731 wxDCTextColourChanger(wxDC
& dc
);
1734 Sets @a col on the given @a dc, storing the old one.
1737 The DC where the colour must be temporary set.
1741 wxDCTextColourChanger(wxDC
& dc
, const wxColour
& col
);
1744 Set the colour to use.
1746 This method is meant to be called once only and only on the objects
1747 created with the constructor overload not taking wxColour argument and
1748 has the same effect as the other constructor, i.e. sets the colour to
1749 the given @a col and ensures that the old value is restored when this
1750 object is destroyed.
1752 void Set(const wxColour
& col
);
1755 Restores the colour originally selected in the DC passed to the ctor.
1757 ~wxDCTextColourChanger();
1763 @class wxDCFontChanger
1765 wxDCFontChanger is a small helper class for setting a font on a wxDC and
1766 unsetting it automatically in the destructor, restoring the previous one.
1773 @see wxDC::SetFont(), wxDCTextColourChanger, wxDCPenChanger, wxDCBrushChanger,
1776 class wxDCFontChanger
1780 Trivial constructor not changing anything.
1782 This constructor is useful if you don't know beforehand if the font
1783 needs to be changed or not. It simply creates the object which won't do
1784 anything in its destructor unless Set() is called -- in which case it
1785 would reset the previous font.
1789 wxDCFontChanger(wxDC
& dc
);
1792 Sets @a font on the given @a dc, storing the old one.
1795 The DC where the font must be temporary set.
1799 wxDCFontChanger(wxDC
& dc
, const wxFont
& font
);
1802 Set the font to use.
1804 This method is meant to be called once only and only on the objects
1805 created with the constructor overload not taking wxColour argument and
1806 has the same effect as the other constructor, i.e. sets the font to
1807 the given @a font and ensures that the old value is restored when this
1808 object is destroyed.
1810 void Set(const wxFont
& font
);
1813 Restores the font originally selected in the DC passed to the ctor.