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 ontop 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 On Mac OS X colours with alpha channel are supported. Instances of wxPen
157 or wxBrush that are built from wxColour use the colour's alpha values
158 when stroking or filling.
164 @see @ref overview_dc, wxGraphicsContext, wxDCFontChanger, wxDCTextColourChanger,
165 wxDCPenChanger, wxDCBrushChanger, wxDCClipper
167 @todo Precise definition of default/initial state.
168 @todo Pixelwise definition of operations (e.g. last point of a line not
171 class wxDC
: public wxObject
175 @name Coordinate conversion functions
180 Convert @e device X coordinate to logical coordinate, using the current
181 mapping mode, user scale factor, device origin and axis orientation.
183 wxCoord
DeviceToLogicalX(wxCoord x
) const;
186 Convert @e device X coordinate to relative logical coordinate, using the
187 current mapping mode and user scale factor but ignoring the
188 axis orientation. Use this for converting a width, for example.
190 wxCoord
DeviceToLogicalXRel(wxCoord x
) const;
193 Converts @e device Y coordinate to logical coordinate, using the current
194 mapping mode, user scale factor, device origin and axis orientation.
196 wxCoord
DeviceToLogicalY(wxCoord y
) const;
199 Convert @e device Y coordinate to relative logical coordinate, using the
200 current mapping mode and user scale factor but ignoring the
201 axis orientation. Use this for converting a height, for example.
203 wxCoord
DeviceToLogicalYRel(wxCoord y
) const;
206 Converts logical X coordinate to device coordinate, using the current
207 mapping mode, user scale factor, device origin and axis orientation.
209 wxCoord
LogicalToDeviceX(wxCoord x
) const;
212 Converts logical X coordinate to relative device coordinate, using the
213 current mapping mode and user scale factor but ignoring the
214 axis orientation. Use this for converting a width, for example.
216 wxCoord
LogicalToDeviceXRel(wxCoord x
) const;
219 Converts logical Y coordinate to device coordinate, using the current
220 mapping mode, user scale factor, device origin and axis orientation.
222 wxCoord
LogicalToDeviceY(wxCoord y
) const;
225 Converts logical Y coordinate to relative device coordinate, using the
226 current mapping mode and user scale factor but ignoring the
227 axis orientation. Use this for converting a height, for example.
229 wxCoord
LogicalToDeviceYRel(wxCoord y
) const;
236 @name Drawing functions
241 Clears the device context using the current background brush.
246 Draws an arc of a circle, centred on (@a xc, @a yc), with starting
247 point (@a xStart, @a yStart) and ending at (@a xEnd, @a yEnd).
248 The current pen is used for the outline and the current brush for
251 The arc is drawn in a counter-clockwise direction from the start point
254 void DrawArc(wxCoord xStart
, wxCoord yStart
, wxCoord xEnd
, wxCoord yEnd
,
255 wxCoord xc
, wxCoord yc
);
260 void DrawArc(const wxPoint
& ptStart
, const wxPoint
& ptEnd
, const wxPoint
& centre
);
263 Draw a bitmap on the device context at the specified point. If
264 @a transparent is @true and the bitmap has a transparency mask, the
265 bitmap will be drawn transparently.
267 When drawing a mono-bitmap, the current text foreground colour will be
268 used to draw the foreground of the bitmap (all bits set to 1), and the
269 current text background colour to draw the background (all bits set to
272 @see SetTextForeground(), SetTextBackground(), wxMemoryDC
274 void DrawBitmap(const wxBitmap
& bitmap
, wxCoord x
, wxCoord y
,
275 bool useMask
= false);
280 void DrawBitmap(const wxBitmap
&bmp
, const wxPoint
& pt
,
281 bool useMask
= false);
284 Draws a check mark inside the given rectangle.
286 void DrawCheckMark(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
291 void DrawCheckMark(const wxRect
& rect
);
294 Draws a circle with the given centre and radius.
298 void DrawCircle(wxCoord x
, wxCoord y
, wxCoord radius
);
303 void DrawCircle(const wxPoint
& pt
, wxCoord radius
);
306 Draws an ellipse contained in the rectangle specified either with the
307 given top left corner and the given size or directly. The current pen
308 is used for the outline and the current brush for filling the shape.
312 void DrawEllipse(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
317 void DrawEllipse(const wxPoint
& pt
, const wxSize
& size
);
322 void DrawEllipse(const wxRect
& rect
);
325 Draws an arc of an ellipse. The current pen is used for drawing the arc
326 and the current brush is used for drawing the pie.
328 @a x and @a y specify the x and y coordinates of the upper-left corner
329 of the rectangle that contains the ellipse.
331 @a width and @a height specify the width and height of the rectangle
332 that contains the ellipse.
334 @a start and @a end specify the start and end of the arc relative to
335 the three-o'clock position from the center of the rectangle. Angles are
336 specified in degrees (360 is a complete circle). Positive values mean
337 counter-clockwise motion. If @a start is equal to @e end, a complete
338 ellipse will be drawn.
340 void DrawEllipticArc(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
,
341 double start
, double end
);
346 void DrawEllipticArc(const wxPoint
& pt
, const wxSize
& sz
,
347 double sa
, double ea
);
350 Draw an icon on the display (does nothing if the device context is
351 PostScript). This can be the simplest way of drawing bitmaps on a
354 void DrawIcon(const wxIcon
& icon
, wxCoord x
, wxCoord y
);
359 void DrawIcon(const wxIcon
& icon
, const wxPoint
& pt
);
362 Draw optional bitmap and the text into the given rectangle and aligns
363 it as specified by alignment parameter; it also will emphasize the
364 character with the given index if it is != -1 and return the bounding
365 rectangle if required.
367 void DrawLabel(const wxString
& text
, const wxBitmap
& image
,
369 int alignment
= wxALIGN_LEFT
| wxALIGN_TOP
,
370 int indexAccel
= -1, wxRect
* rectBounding
= NULL
);
375 void DrawLabel(const wxString
& text
, const wxRect
& rect
,
376 int alignment
= wxALIGN_LEFT
| wxALIGN_TOP
,
377 int indexAccel
= -1);
380 Draws a line from the first point to the second. The current pen is
381 used for drawing the line. Note that the point (@a x2, @a y2) is not
382 part of the line and is not drawn by this function (this is consistent
383 with the behaviour of many other toolkits).
385 void DrawLine(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
);
390 void DrawLine(const wxPoint
& pt1
, const wxPoint
& pt2
);
393 Draws lines using an array of points of size @a n adding the optional
394 offset coordinate. The current pen is used for drawing the lines.
397 The wxPython version of this method accepts a Python list of wxPoint
402 Not supported by wxPerl.
405 void DrawLines(int n
, wxPoint points
[], wxCoord xoffset
= 0,
406 wxCoord yoffset
= 0);
408 This method uses a list of wxPoints, adding the optional offset
409 coordinate. The programmer is responsible for deleting the list of
413 The wxPython version of this method accepts a Python list of wxPoint
418 The wxPerl version of this method accepts
419 as its first parameter a reference to an array
423 void DrawLines(const wxPointList
* points
,
424 wxCoord xoffset
= 0, wxCoord yoffset
= 0);
427 Draws a point using the color of the current pen. Note that the other
428 properties of the pen are not used, such as width.
430 void DrawPoint(wxCoord x
, wxCoord y
);
435 void DrawPoint(const wxPoint
& pt
);
438 Draws a filled polygon using an array of points of size @a n, adding
439 the optional offset coordinate. The first and last points are
440 automatically closed.
442 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
443 default) or @b wxWINDING_RULE.
445 The current pen is used for drawing the outline, and the current brush
446 for filling the shape. Using a transparent brush suppresses filling.
449 Not supported by wxPerl.
452 void DrawPolygon(int n
, wxPoint points
[], wxCoord xoffset
= 0,
454 wxPolygonFillMode fill_style
= wxODDEVEN_RULE
);
456 This method draws a filled polygon using a list of wxPoints, adding the
457 optional offset coordinate. The first and last points are automatically
460 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
461 default) or @b wxWINDING_RULE.
463 The current pen is used for drawing the outline, and the current brush
464 for filling the shape. Using a transparent brush suppresses filling.
466 The programmer is responsible for deleting the list of points.
469 The wxPython version of this method accepts a Python list of wxPoint
474 The wxPerl version of this method accepts
475 as its first parameter a reference to an array
479 void DrawPolygon(const wxPointList
* points
,
480 wxCoord xoffset
= 0, wxCoord yoffset
= 0,
481 wxPolygonFillMode fill_style
= wxODDEVEN_RULE
);
484 Draws two or more filled polygons using an array of @a points, adding
485 the optional offset coordinates.
487 Notice that for the platforms providing a native implementation of this
488 function (Windows and PostScript-based wxDC currently), this is more
489 efficient than using DrawPolygon() in a loop.
491 @a n specifies the number of polygons to draw, the array @e count of
492 size @a n specifies the number of points in each of the polygons in the
495 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
496 default) or @b wxWINDING_RULE.
498 The current pen is used for drawing the outline, and the current brush
499 for filling the shape. Using a transparent brush suppresses filling.
501 The polygons maybe disjoint or overlapping. Each polygon specified in a
502 call to DrawPolyPolygon() must be closed. Unlike polygons created by
503 the DrawPolygon() member function, the polygons created by this
504 method are not closed automatically.
510 void DrawPolyPolygon(int n
, int count
[], wxPoint points
[],
511 wxCoord xoffset
= 0, wxCoord yoffset
= 0,
512 wxPolygonFillMode fill_style
= wxODDEVEN_RULE
);
515 Draws a rectangle with the given top left corner, and with the given
516 size. The current pen is used for the outline and the current brush
517 for filling the shape.
519 void DrawRectangle(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
524 void DrawRectangle(const wxPoint
& pt
, const wxSize
& sz
);
529 void DrawRectangle(const wxRect
& rect
);
532 Draws the text rotated by @a angle degrees
533 (positive angles are counterclockwise; the full angle is 360 degrees).
535 @note Under Win9x only TrueType fonts can be drawn by this function. In
536 particular, a font different from @c wxNORMAL_FONT should be used
537 as the latter is not a TrueType font. @c wxSWISS_FONT is an
538 example of a font which is.
542 void DrawRotatedText(const wxString
& text
, wxCoord x
, wxCoord y
,
548 void DrawRotatedText(const wxString
& text
, const wxPoint
&,
552 Draws a rectangle with the given top left corner, and with the given
553 size. The corners are quarter-circles using the given radius. The
554 current pen is used for the outline and the current brush for filling
557 If @a radius is positive, the value is assumed to be the radius of the
558 rounded corner. If @a radius is negative, the absolute value is assumed
559 to be the @e proportion of the smallest dimension of the rectangle.
560 This means that the corner can be a sensible size relative to the size
561 of the rectangle, and also avoids the strange effects X produces when
562 the corners are too big for the rectangle.
564 void DrawRoundedRectangle(wxCoord x
, wxCoord y
, wxCoord width
,
565 wxCoord height
, double radius
);
570 void DrawRoundedRectangle(const wxPoint
& pt
, const wxSize
& sz
,
576 void DrawRoundedRectangle(const wxRect
& rect
, double radius
);
579 Draws a spline between all given points using the current pen.
582 The wxPython version of this method accepts a Python list of wxPoint
587 Not supported by wxPerl.
590 void DrawSpline(int n
, wxPoint points
[]);
597 The wxPerl version of this method accepts
598 as its first parameter a reference to an array
602 void DrawSpline(const wxPointList
* points
);
609 Not supported by wxPerl.
612 void DrawSpline(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
,
613 wxCoord x3
, wxCoord y3
);
616 Draws a text string at the specified point, using the current text
617 font, and the current text foreground and background colours.
619 The coordinates refer to the top-left corner of the rectangle bounding
620 the string. See GetTextExtent() for how to get the dimensions of a text
621 string, which can be used to position the text more precisely and
622 DrawLabel() if you need to align the string differently.
624 Starting from wxWidgets 2.9.2 @a text parameter can be a multi-line
625 string, i.e. contain new line characters, and will be rendered
628 @note The current @ref GetLogicalFunction() "logical function" is
629 ignored by this function.
631 void DrawText(const wxString
& text
, wxCoord x
, wxCoord y
);
636 void DrawText(const wxString
& text
, const wxPoint
& pt
);
639 Fill the area specified by rect with a radial gradient, starting from
640 @a initialColour at the centre of the circle and fading to
641 @a destColour on the circle outside.
643 The circle is placed at the centre of @a rect.
645 @note Currently this function is very slow, don't use it for real-time
648 void GradientFillConcentric(const wxRect
& rect
,
649 const wxColour
& initialColour
,
650 const wxColour
& destColour
);
653 Fill the area specified by rect with a radial gradient, starting from
654 @a initialColour at the centre of the circle and fading to
655 @a destColour on the circle outside.
657 @a circleCenter are the relative coordinates of centre of the circle in
658 the specified @a rect.
660 @note Currently this function is very slow, don't use it for real-time
663 void GradientFillConcentric(const wxRect
& rect
,
664 const wxColour
& initialColour
,
665 const wxColour
& destColour
,
666 const wxPoint
& circleCenter
);
669 Fill the area specified by @a rect with a linear gradient, starting
670 from @a initialColour and eventually fading to @e destColour.
672 The @a nDirection specifies the direction of the colour change, default is
673 to use @a initialColour on the left part of the rectangle and
674 @a destColour on the right one.
676 void GradientFillLinear(const wxRect
& rect
, const wxColour
& initialColour
,
677 const wxColour
& destColour
,
678 wxDirection nDirection
= wxRIGHT
);
681 Flood fills the device context starting from the given point, using
682 the current brush colour, and using a style:
684 - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
685 given colour is encountered.
686 - wxFLOOD_BORDER: The area to be flooded is bounded by the given
689 @return @false if the operation failed.
691 @note The present implementation for non-Windows platforms may fail to
692 find colour borders if the pixels do not match the colour
693 exactly. However the function will still return @true.
695 bool FloodFill(wxCoord x
, wxCoord y
, const wxColour
& colour
,
696 wxFloodFillStyle style
= wxFLOOD_SURFACE
);
701 bool FloodFill(const wxPoint
& pt
, const wxColour
& col
,
702 int style
= wxFLOOD_SURFACE
);
705 Displays a cross hair using the current pen. This is a vertical and
706 horizontal line the height and width of the window, centred on the
709 void CrossHair(wxCoord x
, wxCoord y
);
714 void CrossHair(const wxPoint
& pt
);
720 @name Clipping region functions
725 Destroys the current clipping region so that none of the DC is clipped.
727 @see SetClippingRegion()
729 void DestroyClippingRegion();
732 Gets the rectangle surrounding the current clipping region.
735 No arguments are required and the four values defining the rectangle
736 are returned as a tuple.
739 void GetClippingBox(wxCoord
*x
, wxCoord
*y
, wxCoord
*width
, wxCoord
*height
) const;
742 Sets the clipping region for this device context to the intersection of
743 the given region described by the parameters of this method and the
744 previously set clipping region.
746 The clipping region is an area to which drawing is restricted. Possible
747 uses for the clipping region are for clipping text or for speeding up
748 window redraws when only a known area of the screen is damaged.
750 Notice that you need to call DestroyClippingRegion() if you want to set
751 the clipping region exactly to the region specified.
753 Also note that if the clipping region is empty, any previously set
754 clipping region is destroyed, i.e. it is equivalent to calling
755 DestroyClippingRegion(), and not to clipping out all drawing on the DC
756 as might be expected.
758 @see DestroyClippingRegion(), wxRegion
760 void SetClippingRegion(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
765 void SetClippingRegion(const wxPoint
& pt
, const wxSize
& sz
);
770 void SetClippingRegion(const wxRect
& rect
);
773 Sets the clipping region for this device context.
775 Unlike SetClippingRegion(), this function works with physical
776 coordinates and not with the logical ones.
778 void SetDeviceClippingRegion(const wxRegion
& region
);
784 @name Text/character extent functions
789 Gets the character height of the currently set font.
791 wxCoord
GetCharHeight() const;
794 Gets the average character width of the currently set font.
796 wxCoord
GetCharWidth() const;
799 Returns the various font characteristics.
801 This method allows to retrieve some of the font characteristics not
802 returned by GetTextExtent(), notably internal leading and average
805 Currently this method returns correct results only under wxMSW, in the
806 other ports the internal leading will always be 0 and the average
807 character width will be computed as the width of the character 'x'.
811 wxFontMetrics
GetFontMetrics() const;
814 Gets the dimensions of the string using the currently selected font.
815 @a string is the text string to measure, @e heightLine, if non @NULL,
816 is where to store the height of a single line.
818 The text extent is set in the given @a w and @a h pointers.
820 If the optional parameter @a font is specified and valid, then it is
821 used for the text extent calculation, otherwise the currently selected
824 @note This function works with both single-line and multi-line strings.
827 In wxPerl this method is implemented as
828 GetMultiLineTextExtent(string, font = undef) returning a
829 3-element list (width, height, line_height)
832 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
834 void GetMultiLineTextExtent(const wxString
& string
, wxCoord
* w
,
836 wxCoord
* heightLine
= NULL
,
837 const wxFont
* font
= NULL
) const;
839 Gets the dimensions of the string using the currently selected font.
840 @a string is the text string to measure, @e heightLine, if non @NULL,
841 is where to store the height of a single line.
843 @return The text extent as a wxSize object.
845 @note This function works with both single-line and multi-line strings.
848 Not supported by wxPerl.
851 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
853 wxSize
GetMultiLineTextExtent(const wxString
& string
) const;
856 Fills the @a widths array with the widths from the beginning of @a text
857 to the corresponding character of @a text. The generic version simply
858 builds a running total of the widths of each character using
859 GetTextExtent(), however if the various platforms have a native API
860 function that is faster or more accurate than the generic
861 implementation then it should be used instead.
864 This method only takes the @a text parameter and returns a Python list
869 In wxPerl this method only takes the @a text parameter and
870 returns the widths as a list of integers.
873 @see GetMultiLineTextExtent(), GetTextExtent()
875 bool GetPartialTextExtents(const wxString
& text
,
876 wxArrayInt
& widths
) const;
879 Gets the dimensions of the string using the currently selected font.
880 @a string is the text string to measure, @a descent is the dimension
881 from the baseline of the font to the bottom of the descender, and
882 @a externalLeading is any extra vertical space added to the font by the
883 font designer (usually is zero).
885 The text extent is returned in @a w and @a h pointers or as a wxSize
886 object depending on which version of this function is used.
888 If the optional parameter @a font is specified and valid, then it is
889 used for the text extent calculation. Otherwise the currently selected
892 @note This function only works with single-line strings.
895 The following methods are implemented in wxPython:
896 - GetTextExtent(string) - Returns a 2-tuple, (width, height).
897 - GetFullTextExtent(string, font=NULL) -
898 Returns a 4-tuple, (width, height, descent, externalLeading).
902 In wxPerl this method is implemented as GetTextExtent(string,
903 font = undef) returning a 4-element list (width, height,
904 descent, externalLeading)
907 @see wxFont, SetFont(), GetPartialTextExtents(),
908 GetMultiLineTextExtent()
910 void GetTextExtent(const wxString
& string
, wxCoord
* w
, wxCoord
* h
,
911 wxCoord
* descent
= NULL
,
912 wxCoord
* externalLeading
= NULL
,
913 const wxFont
* font
= NULL
) const;
920 Not supported by wxPerl.
923 wxSize
GetTextExtent(const wxString
& string
) const;
929 @name Text properties functions
934 Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
936 @see SetBackgroundMode()
938 int GetBackgroundMode() const;
941 Gets the current font.
943 Notice that even although each device context object has some default font
944 after creation, this method would return a ::wxNullFont initially and only
945 after calling SetFont() a valid font is returned.
947 const wxFont
& GetFont() const;
950 Gets the current layout direction of the device context. On platforms
951 where RTL layout is supported, the return value will either be
952 @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
953 not supported, the return value will be @c wxLayout_Default.
955 @see SetLayoutDirection()
957 wxLayoutDirection
GetLayoutDirection() const;
960 Gets the current text background colour.
962 @see SetTextBackground()
964 const wxColour
& GetTextBackground() const;
967 Gets the current text foreground colour.
969 @see SetTextForeground()
971 const wxColour
& GetTextForeground() const;
974 @a mode may be one of @c wxSOLID and @c wxTRANSPARENT.
976 This setting determines whether text will be drawn with a background
979 void SetBackgroundMode(int mode
);
982 Sets the current font for the DC.
984 If the argument is ::wxNullFont (or another invalid font; see wxFont::IsOk),
985 the current font is selected out of the device context (leaving wxDC without
986 any valid font), allowing the current font to be destroyed safely.
990 void SetFont(const wxFont
& font
);
993 Sets the current text background colour for the DC.
995 void SetTextBackground(const wxColour
& colour
);
998 Sets the current text foreground colour for the DC.
1000 @see wxMemoryDC for the interpretation of colours when drawing into a
1003 void SetTextForeground(const wxColour
& colour
);
1006 Sets the current layout direction for the device context.
1009 May be either @c wxLayout_Default, @c wxLayout_LeftToRight or
1010 @c wxLayout_RightToLeft.
1012 @see GetLayoutDirection()
1014 void SetLayoutDirection(wxLayoutDirection dir
);
1020 @name Bounding box functions
1025 Adds the specified point to the bounding box which can be retrieved
1026 with MinX(), MaxX() and MinY(), MaxY() functions.
1028 @see ResetBoundingBox()
1030 void CalcBoundingBox(wxCoord x
, wxCoord y
);
1033 Gets the maximum horizontal extent used in drawing commands so far.
1035 wxCoord
MaxX() const;
1038 Gets the maximum vertical extent used in drawing commands so far.
1040 wxCoord
MaxY() const;
1043 Gets the minimum horizontal extent used in drawing commands so far.
1045 wxCoord
MinX() const;
1048 Gets the minimum vertical extent used in drawing commands so far.
1050 wxCoord
MinY() const;
1053 Resets the bounding box: after a call to this function, the bounding
1054 box doesn't contain anything.
1056 @see CalcBoundingBox()
1058 void ResetBoundingBox();
1064 @name Page and document start/end functions
1069 Starts a document (only relevant when outputting to a printer).
1070 @a message is a message to show while printing.
1072 bool StartDoc(const wxString
& message
);
1075 Starts a document page (only relevant when outputting to a printer).
1080 Ends a document (only relevant when outputting to a printer).
1085 Ends a document page (only relevant when outputting to a printer).
1093 @name Bit-Block Transfer operations (blit)
1098 Copy from a source DC to this DC, specifying the destination
1099 coordinates, size of area to copy, source DC, source coordinates,
1100 logical function, whether to use a bitmap mask, and mask source
1104 Destination device context x position.
1106 Destination device context y position.
1108 Width of source area to be copied.
1110 Height of source area to be copied.
1112 Source device context.
1114 Source device context x position.
1116 Source device context y position.
1118 Logical function to use, see SetLogicalFunction().
1120 If @true, Blit does a transparent blit using the mask that is
1121 associated with the bitmap selected into the source device context.
1122 The Windows implementation does the following if MaskBlt cannot be
1125 <li>Creates a temporary bitmap and copies the destination area into
1127 <li>Copies the source area into the temporary bitmap using the
1128 specified logical function.</li>
1129 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1130 the mask bitmap with the temp bitmap with the foreground colour
1131 set to WHITE and the bg colour set to BLACK.</li>
1132 <li>Sets the unmasked area in the destination area to BLACK by
1133 ANDing the mask bitmap with the destination area with the
1134 foreground colour set to BLACK and the background colour set to
1136 <li>ORs the temporary bitmap with the destination area.</li>
1137 <li>Deletes the temporary bitmap.</li>
1139 This sequence of operations ensures that the source's transparent
1140 area need not be black, and logical functions are supported.
1141 @n @b Note: on Windows, blitting with masks can be speeded up
1142 considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
1143 enabled. You can also influence whether MaskBlt or the explicit
1144 mask blitting code above is used, by using wxSystemOptions and
1145 setting the @c no-maskblt option to 1.
1147 Source x position on the mask. If both xsrcMask and ysrcMask are
1148 @c -1, xsrc and ysrc will be assumed for the mask source position.
1149 Currently only implemented on Windows.
1151 Source y position on the mask. If both xsrcMask and ysrcMask are
1152 @c -1, xsrc and ysrc will be assumed for the mask source position.
1153 Currently only implemented on Windows.
1155 @remarks There is partial support for Blit() in wxPostScriptDC, under X.
1157 @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
1159 bool Blit(wxCoord xdest
, wxCoord ydest
, wxCoord width
,
1160 wxCoord height
, wxDC
* source
, wxCoord xsrc
, wxCoord ysrc
,
1161 wxRasterOperationMode logicalFunc
= wxCOPY
, bool useMask
= false,
1162 wxCoord xsrcMask
= wxDefaultCoord
, wxCoord ysrcMask
= wxDefaultCoord
);
1165 Copy from a source DC to this DC, specifying the destination
1166 coordinates, destination size, source DC, source coordinates, size of
1167 source area to copy, logical function, whether to use a bitmap mask,
1168 and mask source position.
1171 Destination device context x position.
1173 Destination device context y position.
1175 Width of destination area.
1177 Height of destination area.
1179 Source device context.
1181 Source device context x position.
1183 Source device context y position.
1185 Width of source area to be copied.
1187 Height of source area to be copied.
1189 Logical function to use, see SetLogicalFunction().
1191 If @true, Blit does a transparent blit using the mask that is
1192 associated with the bitmap selected into the source device context.
1193 The Windows implementation does the following if MaskBlt cannot be
1196 <li>Creates a temporary bitmap and copies the destination area into
1198 <li>Copies the source area into the temporary bitmap using the
1199 specified logical function.</li>
1200 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1201 the mask bitmap with the temp bitmap with the foreground colour
1202 set to WHITE and the bg colour set to BLACK.</li>
1203 <li>Sets the unmasked area in the destination area to BLACK by
1204 ANDing the mask bitmap with the destination area with the
1205 foreground colour set to BLACK and the background colour set to
1207 <li>ORs the temporary bitmap with the destination area.</li>
1208 <li>Deletes the temporary bitmap.</li>
1210 This sequence of operations ensures that the source's transparent
1211 area need not be black, and logical functions are supported.
1212 @n @b Note: on Windows, blitting with masks can be speeded up
1213 considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
1214 enabled. You can also influence whether MaskBlt or the explicit
1215 mask blitting code above is used, by using wxSystemOptions and
1216 setting the @c no-maskblt option to 1.
1218 Source x position on the mask. If both xsrcMask and ysrcMask are
1219 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1220 source position. Currently only implemented on Windows.
1222 Source y position on the mask. If both xsrcMask and ysrcMask are
1223 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1224 source position. Currently only implemented on Windows.
1226 There is partial support for Blit() in wxPostScriptDC, under X.
1228 StretchBlit() is only implemented under wxMAC and wxMSW.
1230 See wxMemoryDC for typical usage.
1234 @see Blit(), wxMemoryDC, wxBitmap, wxMask
1236 bool StretchBlit(wxCoord xdest
, wxCoord ydest
,
1237 wxCoord dstWidth
, wxCoord dstHeight
,
1238 wxDC
* source
, wxCoord xsrc
, wxCoord ysrc
,
1239 wxCoord srcWidth
, wxCoord srcHeight
,
1240 wxRasterOperationMode logicalFunc
= wxCOPY
,
1241 bool useMask
= false,
1242 wxCoord xsrcMask
= wxDefaultCoord
,
1243 wxCoord ysrcMask
= wxDefaultCoord
);
1248 @name Background/foreground brush and pen
1253 Gets the brush used for painting the background.
1255 @see wxDC::SetBackground()
1257 const wxBrush
& GetBackground() const;
1260 Gets the current brush.
1262 @see wxDC::SetBrush()
1264 const wxBrush
& GetBrush() const;
1267 Gets the current pen.
1271 const wxPen
& GetPen() const;
1274 Sets the current background brush for the DC.
1276 void SetBackground(const wxBrush
& brush
);
1279 Sets the current brush for the DC.
1281 If the argument is ::wxNullBrush (or another invalid brush; see wxBrush::IsOk),
1282 the current brush is selected out of the device context (leaving wxDC without
1283 any valid brush), allowing the current brush to be destroyed safely.
1285 @see wxBrush, wxMemoryDC (for the interpretation of colours when
1286 drawing into a monochrome bitmap)
1288 void SetBrush(const wxBrush
& brush
);
1291 Sets the current pen for the DC.
1293 If the argument is ::wxNullPen (or another invalid pen; see wxPen::IsOk),
1294 the current pen is selected out of the device context (leaving wxDC without any
1295 valid pen), allowing the current pen to be destroyed safely.
1297 @see wxMemoryDC for the interpretation of colours when drawing into a
1300 void SetPen(const wxPen
& pen
);
1306 Copy attributes from another DC.
1308 The copied attributes currently are:
1310 - Text foreground and background colours
1315 A valid (i.e. its IsOk() must return @true) source device context.
1317 void CopyAttributes(const wxDC
& dc
);
1320 Returns the depth (number of bits/pixel) of this DC.
1322 @see wxDisplayDepth()
1324 int GetDepth() const;
1327 Returns the current device origin.
1329 @see SetDeviceOrigin()
1331 wxPoint
GetDeviceOrigin() const;
1334 Gets the current logical function.
1336 @see SetLogicalFunction()
1338 wxRasterOperationMode
GetLogicalFunction() const;
1341 Gets the current mapping mode for the device context.
1345 wxMappingMode
GetMapMode() const;
1348 Gets in @a colour the colour at the specified location. Not available
1349 for wxPostScriptDC or wxMetafileDC.
1351 @note Setting a pixel can be done using DrawPoint().
1354 The wxColour value is returned and is not required as a parameter.
1357 bool GetPixel(wxCoord x
, wxCoord y
, wxColour
* colour
) const;
1360 Returns the resolution of the device in pixels per inch.
1362 wxSize
GetPPI() const;
1365 Gets the horizontal and vertical extent of this device context in @e device units.
1366 It can be used to scale graphics to fit the page.
1368 For example, if @e maxX and @e maxY represent the maximum horizontal
1369 and vertical 'pixel' values used in your application, the following
1370 code will scale the graphic to fit on the printer page:
1375 double scaleX = (double)(maxX / w);
1376 double scaleY = (double)(maxY / h);
1377 dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
1381 In place of a single overloaded method name, wxPython implements the
1383 - GetSize() - Returns a wxSize.
1384 - GetSizeWH() - Returns a 2-tuple (width, height).
1388 In wxPerl there are two methods instead of a single overloaded
1390 - GetSize(): returns a Wx::Size object.
1391 - GetSizeWH(): returns a 2-element list (width, height).
1394 void GetSize(wxCoord
* width
, wxCoord
* height
) const;
1399 wxSize
GetSize() const;
1402 Returns the horizontal and vertical resolution in millimetres.
1404 void GetSizeMM(wxCoord
* width
, wxCoord
* height
) const;
1409 wxSize
GetSizeMM() const;
1412 Gets the current user scale factor.
1415 In wxPerl this method takes no arguments and return a two
1416 element array (x, y).
1421 void GetUserScale(double* x
, double* y
) const;
1424 Returns @true if the DC is ok to use.
1429 Sets the x and y axis orientation (i.e., the direction from lowest to
1430 highest values on the axis). The default orientation is x axis from
1431 left to right and y axis from top down.
1434 True to set the x axis orientation to the natural left to right
1435 orientation, @false to invert it.
1437 True to set the y axis orientation to the natural bottom up
1438 orientation, @false to invert it.
1440 void SetAxisOrientation(bool xLeftRight
, bool yBottomUp
);
1443 Sets the device origin (i.e., the origin in pixels after scaling has
1444 been applied). This function may be useful in Windows printing
1445 operations for placing a graphic on a page.
1447 void SetDeviceOrigin(wxCoord x
, wxCoord y
);
1450 Sets the current logical function for the device context.
1451 It determines how a @e source pixel (from a pen or brush colour, or source
1452 device context if using Blit()) combines with a @e destination pixel in
1453 the current device context.
1454 Text drawing is not affected by this function.
1456 See ::wxRasterOperationMode enumeration values for more info.
1458 The default is @c wxCOPY, which simply draws with the current colour.
1459 The others combine the current colour and the background using a logical
1460 operation. @c wxINVERT is commonly used for drawing rubber bands or moving
1461 outlines, since drawing twice reverts to the original colour.
1463 void SetLogicalFunction(wxRasterOperationMode function
);
1466 The mapping mode of the device context defines the unit of measurement
1467 used to convert @e logical units to @e device units.
1469 Note that in X, text drawing isn't handled consistently with the mapping mode;
1470 a font is always specified in point size. However, setting the user scale (see
1471 SetUserScale()) scales the text appropriately. In Windows, scalable
1472 TrueType fonts are always used; in X, results depend on availability of
1473 fonts, but usually a reasonable match is found.
1475 The coordinate origin is always at the top left of the screen/printer.
1477 Drawing to a Windows printer device context uses the current mapping
1478 mode, but mapping mode is currently ignored for PostScript output.
1480 void SetMapMode(wxMappingMode mode
);
1483 If this is a window DC or memory DC, assigns the given palette to the
1484 window or bitmap associated with the DC. If the argument is
1485 ::wxNullPalette, the current palette is selected out of the device
1486 context, and the original palette restored.
1490 void SetPalette(const wxPalette
& palette
);
1493 Sets the user scaling factor, useful for applications which require
1496 void SetUserScale(double xScale
, double yScale
);
1504 wxDCClipper is a small helper class for setting a clipping region on a wxDC
1505 and unsetting it automatically. An object of wxDCClipper class is typically
1506 created on the stack so that it is automatically destroyed when the object
1507 goes out of scope. A typical usage example:
1510 void MyFunction(wxDC& dc)
1512 wxDCClipper clip(dc, rect);
1513 // ... drawing functions here are affected by clipping rect ...
1516 void OtherFunction()
1520 // ... drawing functions here are not affected by clipping rect ...
1527 @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1535 Sets the clipping region to the specified region/coordinates.
1537 The clipping region is automatically unset when this object is destroyed.
1539 wxDCClipper(wxDC
& dc
, const wxRegion
& r
);
1540 wxDCClipper(wxDC
& dc
, const wxRect
& rect
);
1541 wxDCClipper(wxDC
& dc
, wxCoord x
, wxCoord y
, wxCoord w
, wxCoord h
);
1545 Destroys the clipping region associated with the DC passed to the ctor.
1552 @class wxDCBrushChanger
1554 wxDCBrushChanger is a small helper class for setting a brush on a wxDC
1555 and unsetting it automatically in the destructor, restoring the previous one.
1560 @see wxDC::SetBrush(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1563 class wxDCBrushChanger
1567 Sets @a brush on the given @a dc, storing the old one.
1570 The DC where the brush must be temporary set.
1574 wxDCBrushChanger(wxDC
& dc
, const wxBrush
& brush
);
1577 Restores the brush originally selected in the DC passed to the ctor.
1579 ~wxDCBrushChanger();
1584 @class wxDCPenChanger
1586 wxDCPenChanger is a small helper class for setting a pen on a wxDC
1587 and unsetting it automatically in the destructor, restoring the previous one.
1592 @see wxDC::SetPen(), wxDCFontChanger, wxDCTextColourChanger, wxDCBrushChanger,
1595 class wxDCPenChanger
1599 Sets @a pen on the given @a dc, storing the old one.
1602 The DC where the pen must be temporary set.
1606 wxDCPenChanger(wxDC
& dc
, const wxPen
& pen
);
1609 Restores the pen originally selected in the DC passed to the ctor.
1617 @class wxDCTextColourChanger
1619 wxDCTextColourChanger is a small helper class for setting a foreground
1620 text colour on a wxDC and unsetting it automatically in the destructor,
1621 restoring the previous one.
1626 @see wxDC::SetTextForeground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger,
1629 class wxDCTextColourChanger
1633 Trivial constructor not changing anything.
1635 This constructor is useful if you don't know beforehand if the colour
1636 needs to be changed or not. It simply creates the object which won't do
1637 anything in its destructor unless Set() is called -- in which case it
1638 would reset the previous colour.
1640 wxDCTextColourChanger(wxDC
& dc
);
1643 Sets @a col on the given @a dc, storing the old one.
1646 The DC where the colour must be temporary set.
1650 wxDCTextColourChanger(wxDC
& dc
, const wxColour
& col
);
1653 Set the colour to use.
1655 This method is meant to be called once only and only on the objects
1656 created with the constructor overload not taking wxColour argument and
1657 has the same effect as the other constructor, i.e. sets the colour to
1658 the given @a col and ensures that the old value is restored when this
1659 object is destroyed.
1661 void Set(const wxColour
& col
);
1664 Restores the colour originally selected in the DC passed to the ctor.
1666 ~wxDCTextColourChanger();
1672 @class wxDCFontChanger
1674 wxDCFontChanger is a small helper class for setting a font on a wxDC and
1675 unsetting it automatically in the destructor, restoring the previous one.
1682 @see wxDC::SetFont(), wxDCTextColourChanger, wxDCPenChanger, wxDCBrushChanger,
1685 class wxDCFontChanger
1689 Trivial constructor not changing anything.
1691 This constructor is useful if you don't know beforehand if the font
1692 needs to be changed or not. It simply creates the object which won't do
1693 anything in its destructor unless Set() is called -- in which case it
1694 would reset the previous font.
1698 wxDCFontChanger(wxDC
& dc
);
1701 Sets @a font on the given @a dc, storing the old one.
1704 The DC where the font must be temporary set.
1708 wxDCFontChanger(wxDC
& dc
, const wxFont
& font
);
1711 Set the font to use.
1713 This method is meant to be called once only and only on the objects
1714 created with the constructor overload not taking wxColour argument and
1715 has the same effect as the other constructor, i.e. sets the font to
1716 the given @a font and ensures that the old value is restored when this
1717 object is destroyed.
1719 void Set(const wxFont
& font
);
1722 Restores the font originally selected in the DC passed to the ctor.