1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDC
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
12 A wxDC is a @e "device context" onto which graphics and text can be drawn.
13 It is intended to represent different output devices and offers a common
14 abstract API for drawing on any of them.
16 wxWidgets offers an alternative drawing API based on the modern drawing
17 backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer
18 and related classes. There is also a wxGCDC linking the APIs by offering
19 the wxDC API ontop of a wxGraphicsContext.
21 wxDC is an abstract base class and cannot be created directly.
22 Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or
23 wxPrinterDC. Notice that device contexts which are associated with windows
24 (i.e. wxClientDC, wxWindowDC and wxPaintDC) use the window font and colours
25 by default (starting with wxWidgets 2.9.0) but the other device context
26 classes use system-default values so you always must set the appropriate
27 fonts and colours before using them.
29 In addition to the versions of the methods documented below, there
30 are also versions which accept single wxPoint parameter instead
31 of the two wxCoord ones or wxPoint and wxSize instead of the four
34 Beginning with wxWidgets 2.9.0 the entire wxDC code has been
35 reorganized. All platform dependent code (actually all drawing code)
36 has been moved into backend classes which derive from a common
37 wxDCImpl class. The user-visible classes such as wxClientDC and
38 wxPaintDC merely forward all calls to the backend implementation.
40 On Mac OS X colours with alpha channel are supported. Instances wxPen
41 or wxBrush that are built from wxColour use the colour's alpha values
42 when stroking or filling.
47 @see @ref overview_dc, wxGraphicsContext
49 @todo Precise definition of default/initial state.
50 @todo Pixelwise definition of operations (e.g. last point of a line not
52 @todo Coordinates: state clearly which type of coordinates are returned by
53 the various Get*Point() or similar functions - often they are client
54 coordinates but not always.
56 class wxDC
: public wxObject
60 Copy from a source DC to this DC, specifying the destination
61 coordinates, size of area to copy, source DC, source coordinates,
62 logical function, whether to use a bitmap mask, and mask source
66 Destination device context x position.
68 Destination device context y position.
70 Width of source area to be copied.
72 Height of source area to be copied.
74 Source device context.
76 Source device context x position.
78 Source device context y position.
80 Logical function to use, see SetLogicalFunction().
82 If @true, Blit does a transparent blit using the mask that is
83 associated with the bitmap selected into the source device context.
84 The Windows implementation does the following if MaskBlt cannot be
87 <li>Creates a temporary bitmap and copies the destination area into
89 <li>Copies the source area into the temporary bitmap using the
90 specified logical function.</li>
91 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
92 the mask bitmap with the temp bitmap with the foreground colour
93 set to WHITE and the bg colour set to BLACK.</li>
94 <li>Sets the unmasked area in the destination area to BLACK by
95 ANDing the mask bitmap with the destination area with the
96 foreground colour set to BLACK and the background colour set to
98 <li>ORs the temporary bitmap with the destination area.</li>
99 <li>Deletes the temporary bitmap.</li>
101 This sequence of operations ensures that the source's transparent
102 area need not be black, and logical functions are supported.
103 @n @b Note: on Windows, blitting with masks can be speeded up
104 considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
105 enabled. You can also influence whether MaskBlt or the explicit
106 mask blitting code above is used, by using wxSystemOptions and
107 setting the @c no-maskblt option to 1.
109 Source x position on the mask. If both xsrcMask and ysrcMask are
110 @c -1, xsrc and ysrc will be assumed for the mask source position.
111 Currently only implemented on Windows.
113 Source y position on the mask. If both xsrcMask and ysrcMask are
114 @c -1, xsrc and ysrc will be assumed for the mask source position.
115 Currently only implemented on Windows.
117 @remarks There is partial support for Blit() in wxPostScriptDC, under X.
119 @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
121 bool Blit(wxCoord xdest
, wxCoord ydest
, wxCoord width
,
122 wxCoord height
, wxDC
* source
, wxCoord xsrc
, wxCoord ysrc
,
123 wxRasterOperationMode logicalFunc
= wxCOPY
, bool useMask
= false,
124 wxCoord xsrcMask
= wxDefaultCoord
, wxCoord ysrcMask
= wxDefaultCoord
);
127 Adds the specified point to the bounding box which can be retrieved
128 with MinX(), MaxX() and MinY(), MaxY() functions.
130 @see ResetBoundingBox()
132 void CalcBoundingBox(wxCoord x
, wxCoord y
);
135 Clears the device context using the current background brush.
140 Displays a cross hair using the current pen. This is a vertical and
141 horizontal line the height and width of the window, centred on the
144 void CrossHair(wxCoord x
, wxCoord y
);
147 Destroys the current clipping region so that none of the DC is clipped.
149 @see SetClippingRegion()
151 void DestroyClippingRegion();
154 Convert device X coordinate to logical coordinate, using the current
155 mapping mode, user scale factor, device origin and axis orientation.
157 wxCoord
DeviceToLogicalX(wxCoord x
) const;
160 Convert device X coordinate to relative logical coordinate, using the
161 current mapping mode and user scale factor but ignoring the
162 axis orientation. Use this for converting a width, for example.
164 wxCoord
DeviceToLogicalXRel(wxCoord x
) const;
167 Converts device Y coordinate to logical coordinate, using the current
168 mapping mode, user scale factor, device origin and axis orientation.
170 wxCoord
DeviceToLogicalY(wxCoord y
) const;
173 Convert device Y coordinate to relative logical coordinate, using the
174 current mapping mode and user scale factor but ignoring the
175 axis orientation. Use this for converting a height, for example.
177 wxCoord
DeviceToLogicalYRel(wxCoord y
) const;
180 Draws an arc of a circle, centred on (@a xc, @a yc), with starting
181 point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is
182 used for the outline and the current brush for filling the shape.
184 The arc is drawn in a counter-clockwise direction from the start point
187 void DrawArc(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
,
188 wxCoord xc
, wxCoord yc
);
191 Draw a bitmap on the device context at the specified point. If
192 @a transparent is @true and the bitmap has a transparency mask, the
193 bitmap will be drawn transparently.
195 When drawing a mono-bitmap, the current text foreground colour will be
196 used to draw the foreground of the bitmap (all bits set to 1), and the
197 current text background colour to draw the background (all bits set to
200 @see SetTextForeground(), SetTextBackground(), wxMemoryDC
202 void DrawBitmap(const wxBitmap
& bitmap
, wxCoord x
, wxCoord y
,
203 bool useMask
= false);
207 Draws a check mark inside the given rectangle.
209 void DrawCheckMark(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
210 void DrawCheckMark(const wxRect
& rect
);
215 Draws a circle with the given centre and radius.
219 void DrawCircle(wxCoord x
, wxCoord y
, wxCoord radius
);
220 void DrawCircle(const wxPoint
& pt
, wxCoord radius
);
225 Draws an ellipse contained in the rectangle specified either with the
226 given top left corner and the given size or directly. The current pen
227 is used for the outline and the current brush for filling the shape.
231 void DrawEllipse(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
232 void DrawEllipse(const wxPoint
& pt
, const wxSize
& size
);
233 void DrawEllipse(const wxRect
& rect
);
237 Draws an arc of an ellipse. The current pen is used for drawing the arc
238 and the current brush is used for drawing the pie.
240 @a x and @a y specify the x and y coordinates of the upper-left corner
241 of the rectangle that contains the ellipse.
243 @a width and @a height specify the width and height of the rectangle
244 that contains the ellipse.
246 @a start and @a end specify the start and end of the arc relative to
247 the three-o'clock position from the center of the rectangle. Angles are
248 specified in degrees (360 is a complete circle). Positive values mean
249 counter-clockwise motion. If @a start is equal to @e end, a complete
250 ellipse will be drawn.
252 void DrawEllipticArc(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
,
253 double start
, double end
);
256 Draw an icon on the display (does nothing if the device context is
257 PostScript). This can be the simplest way of drawing bitmaps on a
260 void DrawIcon(const wxIcon
& icon
, wxCoord x
, wxCoord y
);
264 Draw optional bitmap and the text into the given rectangle and aligns
265 it as specified by alignment parameter; it also will emphasize the
266 character with the given index if it is != -1 and return the bounding
267 rectangle if required.
269 virtual void DrawLabel(const wxString
& text
, const wxBitmap
& image
,
271 int alignment
= wxALIGN_LEFT
| wxALIGN_TOP
,
272 int indexAccel
= -1, wxRect
* rectBounding
= NULL
);
273 void DrawLabel(const wxString
& text
, const wxRect
& rect
,
274 int alignment
= wxALIGN_LEFT
| wxALIGN_TOP
,
275 int indexAccel
= -1);
279 Draws a line from the first point to the second. The current pen is
280 used for drawing the line. Note that the point (@a x2, @a y2) is not
281 part of the line and is not drawn by this function (this is consistent
282 with the behaviour of many other toolkits).
284 void DrawLine(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
);
287 Draws lines using an array of points of size @a n adding the optional
288 offset coordinate. The current pen is used for drawing the lines.
291 The wxPython version of this method accepts a Python list of wxPoint
295 void DrawLines(int n
, wxPoint points
[], wxCoord xoffset
= 0,
296 wxCoord yoffset
= 0);
298 This method uses a list of wxPoints, adding the optional offset
299 coordinate. The programmer is responsible for deleting the list of
303 The wxPython version of this method accepts a Python list of wxPoint
307 void DrawLines(const wxPointList
* points
,
308 wxCoord xoffset
= 0, wxCoord yoffset
= 0);
311 Draws a point using the color of the current pen. Note that the other
312 properties of the pen are not used, such as width.
314 void DrawPoint(wxCoord x
, wxCoord y
);
317 Draws a filled polygon using an array of points of size @a n, adding
318 the optional offset coordinate. The first and last points are
319 automatically closed.
321 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
322 default) or @b wxWINDING_RULE.
324 The current pen is used for drawing the outline, and the current brush
325 for filling the shape. Using a transparent brush suppresses filling.
327 void DrawPolygon(int n
, wxPoint points
[], wxCoord xoffset
= 0,
329 wxPolygonFillMode fill_style
= wxODDEVEN_RULE
);
331 This method draws a filled polygon using a list of wxPoints, adding the
332 optional offset coordinate. The first and last points are automatically
335 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
336 default) or @b wxWINDING_RULE.
338 The current pen is used for drawing the outline, and the current brush
339 for filling the shape. Using a transparent brush suppresses filling.
341 The programmer is responsible for deleting the list of points.
344 The wxPython version of this method accepts a Python list of wxPoint
348 void DrawPolygon(const wxPointList
* points
,
349 wxCoord xoffset
= 0, wxCoord yoffset
= 0,
350 wxPolygonFillMode fill_style
= wxODDEVEN_RULE
);
353 Draws two or more filled polygons using an array of @a points, adding
354 the optional offset coordinates.
356 Notice that for the platforms providing a native implementation of this
357 function (Windows and PostScript-based wxDC currently), this is more
358 efficient than using DrawPolygon() in a loop.
360 @a n specifies the number of polygons to draw, the array @e count of
361 size @a n specifies the number of points in each of the polygons in the
364 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
365 default) or @b wxWINDING_RULE.
367 The current pen is used for drawing the outline, and the current brush
368 for filling the shape. Using a transparent brush suppresses filling.
370 The polygons maybe disjoint or overlapping. Each polygon specified in a
371 call to DrawPolyPolygon() must be closed. Unlike polygons created by
372 the DrawPolygon() member function, the polygons created by this
373 method are not closed automatically.
379 void DrawPolyPolygon(int n
, int count
[], wxPoint points
[],
380 wxCoord xoffset
= 0, wxCoord yoffset
= 0,
381 wxPolygonFillMode fill_style
= wxODDEVEN_RULE
);
384 Draws a rectangle with the given top left corner, and with the given
385 size. The current pen is used for the outline and the current brush
386 for filling the shape.
388 void DrawRectangle(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
391 Draws the text rotated by @a angle degrees.
393 @note Under Win9x only TrueType fonts can be drawn by this function. In
394 particular, a font different from @c wxNORMAL_FONT should be used
395 as the latter is not a TrueType font. @c wxSWISS_FONT is an
396 example of a font which is.
400 void DrawRotatedText(const wxString
& text
, wxCoord x
, wxCoord y
,
404 Draws a rectangle with the given top left corner, and with the given
405 size. The corners are quarter-circles using the given radius. The
406 current pen is used for the outline and the current brush for filling
409 If @a radius is positive, the value is assumed to be the radius of the
410 rounded corner. If @a radius is negative, the absolute value is assumed
411 to be the @e proportion of the smallest dimension of the rectangle.
412 This means that the corner can be a sensible size relative to the size
413 of the rectangle, and also avoids the strange effects X produces when
414 the corners are too big for the rectangle.
416 void DrawRoundedRectangle(wxCoord x
, wxCoord y
, wxCoord width
,
417 wxCoord height
, double radius
);
421 Draws a spline between all given points using the current pen.
424 The wxPython version of this method accepts a Python list of wxPoint
428 void DrawSpline(int n
, wxPoint points
[]);
429 void DrawSpline(const wxPointList
* points
);
430 void DrawSpline(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
,
431 wxCoord x3
, wxCoord y3
);
435 Draws a text string at the specified point, using the current text
436 font, and the current text foreground and background colours.
438 The coordinates refer to the top-left corner of the rectangle bounding
439 the string. See GetTextExtent() for how to get the dimensions of a text
440 string, which can be used to position the text more precisely.
442 @note The current @ref GetLogicalFunction() "logical function" is
443 ignored by this function.
445 void DrawText(const wxString
& text
, wxCoord x
, wxCoord y
);
448 Ends a document (only relevant when outputting to a printer).
453 Ends a document page (only relevant when outputting to a printer).
458 Flood fills the device context starting from the given point, using
459 the current brush colour, and using a style:
461 - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
462 given colour is encountered.
463 - wxFLOOD_BORDER: The area to be flooded is bounded by the given
466 @return @false if the operation failed.
468 @note The present implementation for non-Windows platforms may fail to
469 find colour borders if the pixels do not match the colour
470 exactly. However the function will still return @true.
472 bool FloodFill(wxCoord x
, wxCoord y
, const wxColour
& colour
,
473 wxFloodFillStyle style
= wxFLOOD_SURFACE
);
476 Gets the brush used for painting the background.
478 @see wxDC::SetBackground()
480 const wxBrush
& GetBackground() const;
483 Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
485 @see SetBackgroundMode()
487 int GetBackgroundMode() const;
490 Gets the current brush.
492 @see wxDC::SetBrush()
494 const wxBrush
& GetBrush() const;
497 Gets the character height of the currently set font.
499 wxCoord
GetCharHeight() const;
502 Gets the average character width of the currently set font.
504 wxCoord
GetCharWidth() const;
507 Gets the rectangle surrounding the current clipping region.
510 No arguments are required and the four values defining the rectangle
511 are returned as a tuple.
514 void GetClippingBox(wxCoord
*x
, wxCoord
*y
, wxCoord
*width
, wxCoord
*height
) const;
517 Returns the depth (number of bits/pixel) of this DC.
519 @see wxDisplayDepth()
521 int GetDepth() const;
524 Gets the current font. Notice that even although each device context
525 object has some default font after creation, this method would return a
526 wxNullFont initially and only after calling SetFont() a valid font is
529 const wxFont
& GetFont() const;
532 Gets the current layout direction of the device context. On platforms
533 where RTL layout is supported, the return value will either be
534 @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
535 not supported, the return value will be @c wxLayout_Default.
537 @see SetLayoutDirection()
539 wxLayoutDirection
GetLayoutDirection() const;
542 Gets the current logical function.
544 @see SetLogicalFunction()
546 wxRasterOperationMode
GetLogicalFunction() const;
549 Gets the mapping mode for the device context.
553 wxMappingMode
GetMapMode() const;
556 Gets the dimensions of the string using the currently selected font.
557 @a string is the text string to measure, @e heightLine, if non @NULL,
558 is where to store the height of a single line.
560 The text extent is set in the given @a w and @a h pointers.
562 If the optional parameter @a font is specified and valid, then it is
563 used for the text extent calculation, otherwise the currently selected
566 @note This function works with both single-line and multi-line strings.
568 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
570 void GetMultiLineTextExtent(const wxString
& string
, wxCoord
* w
,
572 wxCoord
* heightLine
= NULL
,
573 const wxFont
* font
= NULL
) const;
575 Gets the dimensions of the string using the currently selected font.
576 @a string is the text string to measure, @e heightLine, if non @NULL,
577 is where to store the height of a single line.
579 @return The text extent as a wxSize object.
581 @note This function works with both single-line and multi-line strings.
583 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
585 wxSize
GetMultiLineTextExtent(const wxString
& string
) const;
588 Fills the @a widths array with the widths from the beginning of @a text
589 to the corresponding character of @a text. The generic version simply
590 builds a running total of the widths of each character using
591 GetTextExtent(), however if the various platforms have a native API
592 function that is faster or more accurate than the generic
593 implementation then it should be used instead.
596 This method only takes the @a text parameter and returns a Python list
600 @see GetMultiLineTextExtent(), GetTextExtent()
602 bool GetPartialTextExtents(const wxString
& text
,
603 wxArrayInt
& widths
) const;
606 Gets the current pen.
610 const wxPen
& GetPen() const;
613 Gets in @a colour the colour at the specified location. Not available
614 for wxPostScriptDC or wxMetafileDC.
616 @note Setting a pixel can be done using DrawPoint().
619 The wxColour value is returned and is not required as a parameter.
622 bool GetPixel(wxCoord x
, wxCoord y
, wxColour
* colour
) const;
625 Returns the resolution of the device in pixels per inch.
627 wxSize
GetPPI() const;
631 This gets the horizontal and vertical resolution in device units. It
632 can be used to scale graphics to fit the page.
634 For example, if @e maxX and @e maxY represent the maximum horizontal
635 and vertical 'pixel' values used in your application, the following
636 code will scale the graphic to fit on the printer page:
641 double scaleX = (double)(maxX / w);
642 double scaleY = (double)(maxY / h);
643 dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
647 In place of a single overloaded method name, wxPython implements the
649 - GetSize() - Returns a wxSize.
650 - GetSizeWH() - Returns a 2-tuple (width, height).
653 void GetSize(wxCoord
* width
, wxCoord
* height
) const;
654 const wxSize
GetSize() const;
659 Returns the horizontal and vertical resolution in millimetres.
661 void GetSizeMM(wxCoord
* width
, wxCoord
* height
) const;
662 const wxSize
GetSizeMM() const;
666 Gets the current text background colour.
668 @see SetTextBackground()
670 const wxColour
& GetTextBackground() const;
674 Gets the dimensions of the string using the currently selected font.
675 @a string is the text string to measure, @a descent is the dimension
676 from the baseline of the font to the bottom of the descender, and
677 @a externalLeading is any extra vertical space added to the font by the
678 font designer (usually is zero).
680 The text extent is returned in @a w and @a h pointers or as a wxSize
681 object depending on which version of this function is used.
683 If the optional parameter @a font is specified and valid, then it is
684 used for the text extent calculation. Otherwise the currently selected
687 @note This function only works with single-line strings.
690 The following methods are implemented in wxPython:
691 - GetTextExtent(string) - Returns a 2-tuple, (width, height).
692 - GetFullTextExtent(string, font=NULL) -
693 Returns a 4-tuple, (width, height, descent, externalLeading).
696 @see wxFont, SetFont(), GetPartialTextExtents(),
697 GetMultiLineTextExtent()
699 void GetTextExtent(const wxString
& string
, wxCoord
* w
, wxCoord
* h
,
700 wxCoord
* descent
= NULL
,
701 wxCoord
* externalLeading
= NULL
,
702 const wxFont
* font
= NULL
) const;
703 const wxSize
GetTextExtent(const wxString
& string
) const;
707 Gets the current text foreground colour.
709 @see SetTextForeground()
711 const wxColour
& GetTextForeground() const;
714 Gets the current user scale factor.
718 void GetUserScale(double* x
, double* y
) const;
722 Fill the area specified by rect with a radial gradient, starting from
723 @a initialColour at the centre of the circle and fading to
724 @a destColour on the circle outside.
726 @a circleCenter are the relative coordinates of centre of the circle in
727 the specified @e rect. If not specified, the circle is placed at the
730 @note Currently this function is very slow, don't use it for real-time
733 void GradientFillConcentric(const wxRect
& rect
,
734 const wxColour
& initialColour
,
735 const wxColour
& destColour
);
736 void GradientFillConcentric(const wxRect
& rect
,
737 const wxColour
& initialColour
,
738 const wxColour
& destColour
,
739 const wxPoint
& circleCenter
);
743 Fill the area specified by @a rect with a linear gradient, starting
744 from @a initialColour and eventually fading to @e destColour. The
745 @a nDirection specifies the direction of the colour change, default is
746 to use @a initialColour on the left part of the rectangle and
747 @a destColour on the right one.
749 void GradientFillLinear(const wxRect
& rect
, const wxColour
& initialColour
,
750 const wxColour
& destColour
,
751 wxDirection nDirection
= wxRIGHT
);
754 Returns @true if the DC is ok to use.
759 Converts logical X coordinate to device coordinate, using the current
760 mapping mode, user scale factor, device origin and axis orientation.
762 wxCoord
LogicalToDeviceX(wxCoord x
) const;
765 Converts logical X coordinate to relative device coordinate, using the
766 current mapping mode and user scale factor but ignoring the
767 axis orientation. Use this for converting a width, for example.
769 wxCoord
LogicalToDeviceXRel(wxCoord x
) const;
772 Converts logical Y coordinate to device coordinate, using the current
773 mapping mode, user scale factor, device origin and axis orientation.
775 wxCoord
LogicalToDeviceY(wxCoord y
) const;
778 Converts logical Y coordinate to relative device coordinate, using the
779 current mapping mode and user scale factor but ignoring the
780 axis orientation. Use this for converting a height, for example.
782 wxCoord
LogicalToDeviceYRel(wxCoord y
) const;
785 Gets the maximum horizontal extent used in drawing commands so far.
787 wxCoord
MaxX() const;
790 Gets the maximum vertical extent used in drawing commands so far.
792 wxCoord
MaxY() const;
795 Gets the minimum horizontal extent used in drawing commands so far.
797 wxCoord
MinX() const;
800 Gets the minimum vertical extent used in drawing commands so far.
802 wxCoord
MinY() const;
805 Resets the bounding box: after a call to this function, the bounding
806 box doesn't contain anything.
808 @see CalcBoundingBox()
810 void ResetBoundingBox();
813 Sets the x and y axis orientation (i.e., the direction from lowest to
814 highest values on the axis). The default orientation is x axis from
815 left to right and y axis from top down.
818 True to set the x axis orientation to the natural left to right
819 orientation, @false to invert it.
821 True to set the y axis orientation to the natural bottom up
822 orientation, @false to invert it.
824 void SetAxisOrientation(bool xLeftRight
, bool yBottomUp
);
827 Sets the current background brush for the DC.
829 void SetBackground(const wxBrush
& brush
);
832 @a mode may be one of wxSOLID and wxTRANSPARENT. This setting
833 determines whether text will be drawn with a background colour or not.
835 void SetBackgroundMode(int mode
);
838 Sets the current brush for the DC.
840 If the argument is wxNullBrush, the current brush is selected out of
841 the device context (leaving wxDC without any valid brush), allowing the
842 current brush to be destroyed safely.
844 @see wxBrush, wxMemoryDC (for the interpretation of colours when
845 drawing into a monochrome bitmap)
847 void SetBrush(const wxBrush
& brush
);
851 Sets the clipping region for this device context to the intersection of
852 the given region described by the parameters of this method and the
853 previously set clipping region. You should call DestroyClippingRegion()
854 if you want to set the clipping region exactly to the region specified.
856 The clipping region is an area to which drawing is restricted. Possible
857 uses for the clipping region are for clipping text or for speeding up
858 window redraws when only a known area of the screen is damaged.
860 @see DestroyClippingRegion(), wxRegion
862 void SetClippingRegion(wxCoord x
, wxCoord y
, wxCoord width
,
864 void SetClippingRegion(const wxPoint
& pt
, const wxSize
& sz
);
865 void SetClippingRegion(const wxRect
& rect
);
869 Sets the clipping region for this device context.
871 Unlike SetClippingRegion(), this function works with physical
872 coordinates and not with the logical ones.
874 void SetDeviceClippingRegion(const wxRegion
& region
);
877 Sets the device origin (i.e., the origin in pixels after scaling has
878 been applied). This function may be useful in Windows printing
879 operations for placing a graphic on a page.
881 void SetDeviceOrigin(wxCoord x
, wxCoord y
);
884 Sets the current font for the DC. It must be a valid font, in
885 particular you should not pass wxNullFont to this method.
889 void SetFont(const wxFont
& font
);
892 Sets the current layout direction for the device context. @a dir may be
893 either @c wxLayout_Default, @c wxLayout_LeftToRight or
894 @c wxLayout_RightToLeft.
896 @see GetLayoutDirection()
898 void SetLayoutDirection(wxLayoutDirection dir
);
901 Sets the current logical function for the device context. This
902 determines how a source pixel (from a pen or brush colour, or source
903 device context if using Blit()) combines with a destination pixel in
904 the current device context.
905 Text drawing is not affected by this function.
907 The possible values and their meaning in terms of source and
908 destination pixel values are as follows:
912 wxAND_INVERT (NOT src) AND dst
913 wxAND_REVERSE src AND (NOT dst)
916 wxEQUIV (NOT src) XOR dst
918 wxNAND (NOT src) OR (NOT dst)
919 wxNOR (NOT src) AND (NOT dst)
922 wxOR_INVERT (NOT src) OR dst
923 wxOR_REVERSE src OR (NOT dst)
929 The default is wxCOPY, which simply draws with the current colour. The
930 others combine the current colour and the background using a logical
931 operation. wxINVERT is commonly used for drawing rubber bands or moving
932 outlines, since drawing twice reverts to the original colour.
934 void SetLogicalFunction(wxRasterOperationMode function
);
937 The mapping mode of the device context defines the unit of measurement
938 used to convert logical units to device units. Note that in X, text
939 drawing isn't handled consistently with the mapping mode; a font is
940 always specified in point size. However, setting the user scale (see
941 SetUserScale()) scales the text appropriately. In Windows, scalable
942 TrueType fonts are always used; in X, results depend on availability of
943 fonts, but usually a reasonable match is found.
945 The coordinate origin is always at the top left of the screen/printer.
947 Drawing to a Windows printer device context uses the current mapping
948 mode, but mapping mode is currently ignored for PostScript output.
950 The mapping mode can be one of the following:
951 - wxMM_TWIPS: Each logical unit is 1/20 of a point, or 1/1440 of an
953 - wxMM_POINTS: Each logical unit is a point, or 1/72 of an inch.
954 - wxMM_METRIC: Each logical unit is 1 mm.
955 - wxMM_LOMETRIC: Each logical unit is 1/10 of a mm.
956 - wxMM_TEXT: Each logical unit is 1 device pixel.
958 void SetMapMode(wxMappingMode mode
);
961 If this is a window DC or memory DC, assigns the given palette to the
962 window or bitmap associated with the DC. If the argument is
963 wxNullPalette, the current palette is selected out of the device
964 context, and the original palette restored.
968 void SetPalette(const wxPalette
& palette
);
971 Sets the current pen for the DC. If the argument is wxNullPen, the
972 current pen is selected out of the device context (leaving wxDC without
973 any valid pen), allowing the current brush to be destroyed safely.
975 @see wxMemoryDC for the interpretation of colours when drawing into a
978 void SetPen(const wxPen
& pen
);
981 Sets the current text background colour for the DC.
983 void SetTextBackground(const wxColour
& colour
);
986 Sets the current text foreground colour for the DC.
988 @see wxMemoryDC for the interpretation of colours when drawing into a
991 void SetTextForeground(const wxColour
& colour
);
994 Sets the user scaling factor, useful for applications which require
997 void SetUserScale(double xScale
, double yScale
);
1000 Starts a document (only relevant when outputting to a printer).
1001 @a message is a message to show while printing.
1003 bool StartDoc(const wxString
& message
);
1006 Starts a document page (only relevant when outputting to a printer).
1011 Copy from a source DC to this DC, specifying the destination
1012 coordinates, destination size, source DC, source coordinates, size of
1013 source area to copy, logical function, whether to use a bitmap mask,
1014 and mask source position.
1017 Destination device context x position.
1019 Destination device context y position.
1021 Width of destination area.
1023 Height of destination area.
1025 Source device context.
1027 Source device context x position.
1029 Source device context y position.
1031 Width of source area to be copied.
1033 Height of source area to be copied.
1035 Logical function to use, see SetLogicalFunction().
1037 If @true, Blit does a transparent blit using the mask that is
1038 associated with the bitmap selected into the source device context.
1039 The Windows implementation does the following if MaskBlt cannot be
1042 <li>Creates a temporary bitmap and copies the destination area into
1044 <li>Copies the source area into the temporary bitmap using the
1045 specified logical function.</li>
1046 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1047 the mask bitmap with the temp bitmap with the foreground colour
1048 set to WHITE and the bg colour set to BLACK.</li>
1049 <li>Sets the unmasked area in the destination area to BLACK by
1050 ANDing the mask bitmap with the destination area with the
1051 foreground colour set to BLACK and the background colour set to
1053 <li>ORs the temporary bitmap with the destination area.</li>
1054 <li>Deletes the temporary bitmap.</li>
1056 This sequence of operations ensures that the source's transparent
1057 area need not be black, and logical functions are supported.
1058 @n @b Note: on Windows, blitting with masks can be speeded up
1059 considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
1060 enabled. You can also influence whether MaskBlt or the explicit
1061 mask blitting code above is used, by using wxSystemOptions and
1062 setting the @c no-maskblt option to 1.
1064 Source x position on the mask. If both xsrcMask and ysrcMask are
1065 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1066 source position. Currently only implemented on Windows.
1068 Source y position on the mask. If both xsrcMask and ysrcMask are
1069 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1070 source position. Currently only implemented on Windows.
1072 There is partial support for Blit() in wxPostScriptDC, under X.
1074 StretchBlit() is only implemented under wxMAC and wxMSW.
1076 See wxMemoryDC for typical usage.
1080 @see Blit(), wxMemoryDC, wxBitmap, wxMask
1082 bool StretchBlit(wxCoord xdest
, wxCoord ydest
,
1083 wxCoord dstWidth
, wxCoord dstHeight
,
1084 wxDC
* source
, wxCoord xsrc
, wxCoord ysrc
,
1085 wxCoord srcWidth
, wxCoord srcHeight
,
1086 wxRasterOperationMode logicalFunc
= wxCOPY
,
1087 bool useMask
= false,
1088 wxCoord xsrcMask
= wxDefaultCoord
,
1089 wxCoord ysrcMask
= wxDefaultCoord
);
1097 wxDCClipper is a small helper class for setting a clipping region on a wxDC
1098 and unsetting it automatically. An object of wxDCClipper class is typically
1099 created on the stack so that it is automatically destroyed when the object
1100 goes out of scope. A typical usage example:
1103 void MyFunction(wxDC& dc)
1105 wxDCClipper clip(dc, rect);
1106 // ... drawing functions here are affected by clipping rect ...
1109 void OtherFunction()
1113 // ... drawing functions here are not affected by clipping rect ...
1120 @see wxDC::SetClippingRegion()
1127 Sets the clipping region to the specified region/coordinates.
1129 The clipping region is automatically unset when this object is destroyed.
1131 wxDCClipper(wxDC
& dc
, const wxRegion
& r
);
1132 wxDCClipper(wxDC
& dc
, const wxRect
& rect
);
1133 wxDCClipper(wxDC
& dc
, int x
, int y
, int w
, int h
);
1137 Destroys the clipping region associated with the DC passed to the ctor.
1144 @class wxDCBrushChanger
1146 wxDCBrushChanger is a small helper class for setting a brush on a wxDC
1147 and unsetting it automatically in the destructor, restoring the previous one.
1152 @see wxDC::SetBrush()
1154 class wxDCBrushChanger
1158 Sets @a brush on the given @a dc, storing the old one.
1161 The DC where the brush must be temporary set.
1165 wxDCBrushChanger(wxDC
& dc
, const wxBrush
& brush
);
1168 Restores the brush originally selected in the DC passed to the ctor.
1170 ~wxDCBrushChanger();
1175 @class wxDCPenChanger
1177 wxDCPenChanger is a small helper class for setting a pen on a wxDC
1178 and unsetting it automatically in the destructor, restoring the previous one.
1185 class wxDCPenChanger
1189 Sets @a pen on the given @a dc, storing the old one.
1192 The DC where the pen must be temporary set.
1196 wxDCPenChanger(wxDC
& dc
, const wxPen
& pen
);
1199 Restores the pen originally selected in the DC passed to the ctor.
1207 @class wxDCTextColourChanger
1209 wxDCTextColourChanger is a small helper class for setting a foreground
1210 text colour on a wxDC and unsetting it automatically in the destructor,
1211 restoring the previous one.
1216 @see wxDC::SetTextForeground()
1218 class wxDCTextColourChanger
1222 Sets @a col on the given @a dc, storing the old one.
1225 The DC where the colour must be temporary set.
1229 wxDCTextColourChanger(wxDC
& dc
, const wxColour
& col
);
1232 Restores the colour originally selected in the DC passed to the ctor.
1234 ~wxDCTextColourChanger();
1240 @class wxDCFontChanger
1242 wxDCFontChanger is a small helper class for setting a font on a wxDC and
1243 unsetting it automatically in the destructor, restoring the previous one.
1250 @see wxDC::SetFont()
1252 class wxDCFontChanger
1256 Sets @a font on the given @a dc, storing the old one.
1259 The DC where the font must be temporary set.
1263 wxDCFontChanger(wxDC
& dc
, const wxFont
& font
);
1266 Restores the colour originally selected in the DC passed to the ctor.