]>
git.saurik.com Git - wxWidgets.git/blob - interface/wx/dc.h
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 -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 -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 int logicalFunc
= wxCOPY
, bool useMask
= false,
124 wxCoord xsrcMask
= -1, wxCoord ysrcMask
= -1);
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 Performs all necessary computations for given platform and context type
141 after each change of scale and origin parameters. Usually called
142 automatically internally after such changes.
144 virtual void ComputeScaleAndOrigin();
147 Displays a cross hair using the current pen. This is a vertical and
148 horizontal line the height and width of the window, centred on the
151 void CrossHair(wxCoord x
, wxCoord y
);
154 Destroys the current clipping region so that none of the DC is clipped.
156 @see SetClippingRegion()
158 void DestroyClippingRegion();
161 Convert device X coordinate to logical coordinate, using the current
164 virtual wxCoord
DeviceToLogicalX(wxCoord x
);
167 Convert device X coordinate to relative logical coordinate, using the
168 current mapping mode but ignoring the x axis orientation. Use this
169 function for converting a width, for example.
171 virtual wxCoord
DeviceToLogicalXRel(wxCoord x
);
174 Converts device Y coordinate to logical coordinate, using the current
177 virtual wxCoord
DeviceToLogicalY(wxCoord y
);
180 Convert device Y coordinate to relative logical coordinate, using the
181 current mapping mode but ignoring the y axis orientation. Use this
182 function for converting a height, for example.
184 virtual wxCoord
DeviceToLogicalYRel(wxCoord y
);
187 Draws an arc of a circle, centred on (@a xc, @a yc), with starting
188 point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is
189 used for the outline and the current brush for filling the shape.
191 The arc is drawn in a counter-clockwise direction from the start point
194 void DrawArc(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
,
195 wxCoord xc
, wxCoord yc
);
198 Draw a bitmap on the device context at the specified point. If
199 @a transparent is @true and the bitmap has a transparency mask, the
200 bitmap will be drawn transparently.
202 When drawing a mono-bitmap, the current text foreground colour will be
203 used to draw the foreground of the bitmap (all bits set to 1), and the
204 current text background colour to draw the background (all bits set to
207 @see SetTextForeground(), SetTextBackground(), wxMemoryDC
209 void DrawBitmap(const wxBitmap
& bitmap
, wxCoord x
, wxCoord y
,
214 Draws a check mark inside the given rectangle.
216 void DrawCheckMark(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
217 void DrawCheckMark(const wxRect
& rect
);
222 Draws a circle with the given centre and radius.
226 void DrawCircle(wxCoord x
, wxCoord y
, wxCoord radius
);
227 void DrawCircle(const wxPoint
& pt
, wxCoord radius
);
232 Draws an ellipse contained in the rectangle specified either with the
233 given top left corner and the given size or directly. The current pen
234 is used for the outline and the current brush for filling the shape.
238 void DrawEllipse(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
239 void DrawEllipse(const wxPoint
& pt
, const wxSize
& size
);
240 void DrawEllipse(const wxRect
& rect
);
244 Draws an arc of an ellipse. The current pen is used for drawing the arc
245 and the current brush is used for drawing the pie.
247 @a x and @a y specify the x and y coordinates of the upper-left corner
248 of the rectangle that contains the ellipse.
250 @a width and @a height specify the width and height of the rectangle
251 that contains the ellipse.
253 @a start and @a end specify the start and end of the arc relative to
254 the three-o'clock position from the center of the rectangle. Angles are
255 specified in degrees (360 is a complete circle). Positive values mean
256 counter-clockwise motion. If @a start is equal to @e end, a complete
257 ellipse will be drawn.
259 void DrawEllipticArc(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
,
260 double start
, double end
);
263 Draw an icon on the display (does nothing if the device context is
264 PostScript). This can be the simplest way of drawing bitmaps on a
267 void DrawIcon(const wxIcon
& icon
, wxCoord x
, wxCoord y
);
271 Draw optional bitmap and the text into the given rectangle and aligns
272 it as specified by alignment parameter; it also will emphasize the
273 character with the given index if it is != -1 and return the bounding
274 rectangle if required.
276 virtual void DrawLabel(const wxString
& text
, const wxBitmap
& image
,
278 int alignment
= wxALIGN_LEFT
| wxALIGN_TOP
,
279 int indexAccel
= -1, wxRect
* rectBounding
= NULL
);
280 void DrawLabel(const wxString
& text
, const wxRect
& rect
,
281 int alignment
= wxALIGN_LEFT
| wxALIGN_TOP
,
282 int indexAccel
= -1);
286 Draws a line from the first point to the second. The current pen is
287 used for drawing the line. Note that the point (@a x2, @a y2) is not
288 part of the line and is not drawn by this function (this is consistent
289 with the behaviour of many other toolkits).
291 void DrawLine(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
);
294 Draws lines using an array of points of size @a n adding the optional
295 offset coordinate. The current pen is used for drawing the lines.
298 The wxPython version of this method accepts a Python list of wxPoint
302 void DrawLines(int n
, wxPoint points
[], wxCoord xoffset
= 0,
303 wxCoord yoffset
= 0);
305 This method uses a list of wxPoints, adding the optional offset
306 coordinate. The programmer is responsible for deleting the list of
310 The wxPython version of this method accepts a Python list of wxPoint
314 void DrawLines(const wxPointList
* points
,
315 wxCoord xoffset
= 0, wxCoord yoffset
= 0);
318 Draws a point using the color of the current pen. Note that the other
319 properties of the pen are not used, such as width.
321 void DrawPoint(wxCoord x
, wxCoord y
);
324 Draws a filled polygon using an array of points of size @a n, adding
325 the optional offset coordinate. The first and last points are
326 automatically closed.
328 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
329 default) or @b wxWINDING_RULE.
331 The current pen is used for drawing the outline, and the current brush
332 for filling the shape. Using a transparent brush suppresses filling.
334 void DrawPolygon(int n
, wxPoint points
[], wxCoord xoffset
= 0,
335 wxCoord yoffset
= 0, int fill_style
= wxODDEVEN_RULE
);
337 This method draws a filled polygon using a list of wxPoints, adding the
338 optional offset coordinate. The first and last points are automatically
341 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
342 default) or @b wxWINDING_RULE.
344 The current pen is used for drawing the outline, and the current brush
345 for filling the shape. Using a transparent brush suppresses filling.
347 The programmer is responsible for deleting the list of points.
350 The wxPython version of this method accepts a Python list of wxPoint
354 void DrawPolygon(const wxPointList
* points
,
355 wxCoord xoffset
= 0, wxCoord yoffset
= 0,
356 int fill_style
= wxODDEVEN_RULE
);
359 Draws two or more filled polygons using an array of @a points, adding
360 the optional offset coordinates.
362 Notice that for the platforms providing a native implementation of this
363 function (Windows and PostScript-based wxDC currently), this is more
364 efficient than using DrawPolygon() in a loop.
366 @a n specifies the number of polygons to draw, the array @e count of
367 size @a n specifies the number of points in each of the polygons in the
370 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
371 default) or @b wxWINDING_RULE.
373 The current pen is used for drawing the outline, and the current brush
374 for filling the shape. Using a transparent brush suppresses filling.
376 The polygons maybe disjoint or overlapping. Each polygon specified in a
377 call to DrawPolyPolygon() must be closed. Unlike polygons created by
378 the DrawPolygon() member function, the polygons created by this
379 method are not closed automatically.
385 void DrawPolyPolygon(int n
, int count
[], wxPoint points
[],
386 wxCoord xoffset
= 0, wxCoord yoffset
= 0,
387 int fill_style
= wxODDEVEN_RULE
);
390 Draws a rectangle with the given top left corner, and with the given
391 size. The current pen is used for the outline and the current brush
392 for filling the shape.
394 void DrawRectangle(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
397 Draws the text rotated by @a angle degrees.
399 @note Under Win9x only TrueType fonts can be drawn by this function. In
400 particular, a font different from @c wxNORMAL_FONT should be used
401 as the latter is not a TrueType font. @c wxSWISS_FONT is an
402 example of a font which is.
406 void DrawRotatedText(const wxString
& text
, wxCoord x
, wxCoord y
,
410 Draws a rectangle with the given top left corner, and with the given
411 size. The corners are quarter-circles using the given radius. The
412 current pen is used for the outline and the current brush for filling
415 If @a radius is positive, the value is assumed to be the radius of the
416 rounded corner. If @a radius is negative, the absolute value is assumed
417 to be the @e proportion of the smallest dimension of the rectangle.
418 This means that the corner can be a sensible size relative to the size
419 of the rectangle, and also avoids the strange effects X produces when
420 the corners are too big for the rectangle.
422 void DrawRoundedRectangle(wxCoord x
, wxCoord y
, wxCoord width
,
423 wxCoord height
, double radius
);
427 Draws a spline between all given points using the current pen.
430 The wxPython version of this method accepts a Python list of wxPoint
434 void DrawSpline(int n
, wxPoint points
[]);
435 void DrawSpline(const wxPointList
* points
);
436 void DrawSpline(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
,
437 wxCoord x3
, wxCoord y3
);
441 Draws a text string at the specified point, using the current text
442 font, and the current text foreground and background colours.
444 The coordinates refer to the top-left corner of the rectangle bounding
445 the string. See GetTextExtent() for how to get the dimensions of a text
446 string, which can be used to position the text more precisely.
448 @note Under wxGTK, the current
449 @ref GetLogicalFunction() "logical function" is used by this
450 function but it is ignored by wxMSW. Thus, you should avoid using
451 logical functions with this function in portable programs.
453 void DrawText(const wxString
& text
, wxCoord x
, wxCoord y
);
456 Ends a document (only relevant when outputting to a printer).
461 Ends a document page (only relevant when outputting to a printer).
466 Flood fills the device context starting from the given point, using
467 the current brush colour, and using a style:
469 - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
470 given colour is encountered.
471 - wxFLOOD_BORDER: The area to be flooded is bounded by the given
474 @return @false if the operation failed.
476 @note The present implementation for non-Windows platforms may fail to
477 find colour borders if the pixels do not match the colour
478 exactly. However the function will still return @true.
480 bool FloodFill(wxCoord x
, wxCoord y
, const wxColour
& colour
,
481 int style
= wxFLOOD_SURFACE
);
484 Gets the brush used for painting the background.
486 @see wxDC::SetBackground()
488 const wxBrush
GetBackground() const;
491 Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
493 @see SetBackgroundMode()
495 int GetBackgroundMode() const;
498 Gets the current brush.
500 @see wxDC::SetBrush()
502 const wxBrush
GetBrush() const;
505 Gets the character height of the currently set font.
507 wxCoord
GetCharHeight();
510 Gets the average character width of the currently set font.
512 wxCoord
GetCharWidth();
515 Gets the rectangle surrounding the current clipping region.
518 No arguments are required and the four values defining the rectangle
519 are returned as a tuple.
522 void GetClippingBox(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
525 Returns the depth (number of bits/pixel) of this DC.
527 @see wxDisplayDepth()
529 int GetDepth() const;
532 Gets the current font. Notice that even although each device context
533 object has some default font after creation, this method would return a
534 wxNullFont initially and only after calling SetFont() a valid font is
537 const wxFont
GetFont() const;
540 Gets the current layout direction of the device context. On platforms
541 where RTL layout is supported, the return value will either be
542 @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
543 not supported, the return value will be @c wxLayout_Default.
545 @see SetLayoutDirection()
547 wxLayoutDirection
GetLayoutDirection() const;
550 Gets the current logical function.
552 @see SetLogicalFunction()
554 int GetLogicalFunction();
557 Gets the mapping mode for the device context.
564 Gets the dimensions of the string using the currently selected font.
565 @a string is the text string to measure, @e heightLine, if non @NULL,
566 is where to store the height of a single line.
568 The text extent is set in the given @a w and @a h pointers.
570 If the optional parameter @a font is specified and valid, then it is
571 used for the text extent calculation, otherwise the currently selected
574 @note This function works with both single-line and multi-line strings.
576 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
578 void GetMultiLineTextExtent(const wxString
& string
, wxCoord
* w
,
580 wxCoord
* heightLine
= NULL
,
581 wxFont
* font
= NULL
) const;
583 Gets the dimensions of the string using the currently selected font.
584 @a string is the text string to measure, @e heightLine, if non @NULL,
585 is where to store the height of a single line.
587 @return The text extent as a wxSize object.
589 @note This function works with both single-line and multi-line strings.
591 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
593 const wxSize
GetMultiLineTextExtent(const wxString
& string
) const;
596 Fills the @a widths array with the widths from the beginning of @a text
597 to the corresponding character of @a text. The generic version simply
598 builds a running total of the widths of each character using
599 GetTextExtent(), however if the various platforms have a native API
600 function that is faster or more accurate than the generic
601 implementation then it should be used instead.
604 This method only takes the @a text parameter and returns a Python list
608 @see GetMultiLineTextExtent(), GetTextExtent()
610 bool GetPartialTextExtents(const wxString
& text
,
611 wxArrayInt
& widths
) const;
614 Gets the current pen.
618 const wxPen
GetPen() const;
621 Gets in @a colour the colour at the specified location. Not available
622 for wxPostScriptDC or wxMetafileDC.
624 @note Setting a pixel can be done using DrawPoint().
627 The wxColour value is returned and is not required as a parameter.
630 bool GetPixel(wxCoord x
, wxCoord y
, wxColour
* colour
);
633 Returns the resolution of the device in pixels per inch.
635 wxSize
GetPPI() const;
639 This gets the horizontal and vertical resolution in device units. It
640 can be used to scale graphics to fit the page.
642 For example, if @e maxX and @e maxY represent the maximum horizontal
643 and vertical 'pixel' values used in your application, the following
644 code will scale the graphic to fit on the printer page:
649 double scaleX = (double)(maxX / w);
650 double scaleY = (double)(maxY / h);
651 dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
655 In place of a single overloaded method name, wxPython implements the
657 - GetSize() - Returns a wxSize.
658 - GetSizeWH() - Returns a 2-tuple (width, height).
661 void GetSize(wxCoord
* width
, wxCoord
* height
) const;
662 const wxSize
GetSize() const;
667 Returns the horizontal and vertical resolution in millimetres.
669 void GetSizeMM(wxCoord
* width
, wxCoord
* height
) const;
670 const wxSize
GetSizeMM() const;
674 Gets the current text background colour.
676 @see SetTextBackground()
678 const wxColour
GetTextBackground() const;
682 Gets the dimensions of the string using the currently selected font.
683 @a string is the text string to measure, @a descent is the dimension
684 from the baseline of the font to the bottom of the descender, and
685 @a externalLeading is any extra vertical space added to the font by the
686 font designer (usually is zero).
688 The text extent is returned in @a w and @a h pointers or as a wxSize
689 object depending on which version of this function is used.
691 If the optional parameter @a font is specified and valid, then it is
692 used for the text extent calculation. Otherwise the currently selected
695 @note This function only works with single-line strings.
698 The following methods are implemented in wxPython:
699 - GetTextExtent(string) - Returns a 2-tuple, (width, height).
700 - GetFullTextExtent(string, font=NULL) -
701 Returns a 4-tuple, (width, height, descent, externalLeading).
704 @see wxFont, SetFont(), GetPartialTextExtents(),
705 GetMultiLineTextExtent()
707 void GetTextExtent(const wxString
& string
, wxCoord
* w
, wxCoord
* h
,
708 wxCoord
* descent
= NULL
,
709 wxCoord
* externalLeading
= NULL
,
710 const wxFont
* font
= NULL
) const;
711 const wxSize
GetTextExtent(const wxString
& string
) const;
715 Gets the current text foreground colour.
717 @see SetTextForeground()
719 const wxColour
GetTextForeground() const;
722 Gets the current user scale factor.
726 void GetUserScale(double x
, double y
);
730 Fill the area specified by rect with a radial gradient, starting from
731 @a initialColour at the centre of the circle and fading to
732 @a destColour on the circle outside.
734 @a circleCenter are the relative coordinates of centre of the circle in
735 the specified @e rect. If not specified, the circle is placed at the
738 @note Currently this function is very slow, don't use it for real-time
741 void GradientFillConcentric(const wxRect
& rect
,
742 const wxColour
& initialColour
,
743 const wxColour
& destColour
);
744 void GradientFillConcentric(const wxRect
& rect
,
745 const wxColour
& initialColour
,
746 const wxColour
& destColour
,
747 const wxPoint
& circleCenter
);
751 Fill the area specified by @a rect with a linear gradient, starting
752 from @a initialColour and eventually fading to @e destColour. The
753 @a nDirection specifies the direction of the colour change, default is
754 to use @a initialColour on the left part of the rectangle and
755 @a destColour on the right one.
757 void GradientFillLinear(const wxRect
& rect
,
758 const wxColour
& initialColour
,
759 const wxColour
& destColour
,
760 wxDirection nDirection
= wxEAST
);
763 Returns @true if the DC is ok to use.
768 Converts logical X coordinate to device coordinate, using the current
771 virtual wxCoord
LogicalToDeviceX(wxCoord x
);
774 Converts logical X coordinate to relative device coordinate, using the
775 current mapping mode but ignoring the x axis orientation. Use this for
776 converting a width, for example.
778 virtual wxCoord
LogicalToDeviceXRel(wxCoord x
);
781 Converts logical Y coordinate to device coordinate, using the current
784 virtual wxCoord
LogicalToDeviceY(wxCoord y
);
787 Converts logical Y coordinate to relative device coordinate, using the
788 current mapping mode but ignoring the y axis orientation. Use this for
789 converting a height, for example.
791 virtual wxCoord
LogicalToDeviceYRel(wxCoord y
);
794 Gets the maximum horizontal extent used in drawing commands so far.
799 Gets the maximum vertical extent used in drawing commands so far.
804 Gets the minimum horizontal extent used in drawing commands so far.
809 Gets the minimum vertical extent used in drawing commands so far.
814 Resets the bounding box: after a call to this function, the bounding
815 box doesn't contain anything.
817 @see CalcBoundingBox()
819 void ResetBoundingBox();
822 Sets the x and y axis orientation (i.e., the direction from lowest to
823 highest values on the axis). The default orientation is x axis from
824 left to right and y axis from top down.
827 True to set the x axis orientation to the natural left to right
828 orientation, @false to invert it.
830 True to set the y axis orientation to the natural bottom up
831 orientation, @false to invert it.
833 void SetAxisOrientation(bool xLeftRight
, bool yBottomUp
);
836 Sets the current background brush for the DC.
838 void SetBackground(const wxBrush
& brush
);
841 @a mode may be one of wxSOLID and wxTRANSPARENT. This setting
842 determines whether text will be drawn with a background colour or not.
844 void SetBackgroundMode(int mode
);
847 Sets the current brush for the DC.
849 If the argument is wxNullBrush, the current brush is selected out of
850 the device context (leaving wxDC without any valid brush), allowing the
851 current brush to be destroyed safely.
853 @see wxBrush, wxMemoryDC (for the interpretation of colours when
854 drawing into a monochrome bitmap)
856 void SetBrush(const wxBrush
& brush
);
860 Sets the clipping region for this device context to the intersection of
861 the given region described by the parameters of this method and the
862 previously set clipping region. You should call DestroyClippingRegion()
863 if you want to set the clipping region exactly to the region specified.
865 The clipping region is an area to which drawing is restricted. Possible
866 uses for the clipping region are for clipping text or for speeding up
867 window redraws when only a known area of the screen is damaged.
869 @see DestroyClippingRegion(), wxRegion
871 void SetClippingRegion(wxCoord x
, wxCoord y
, wxCoord width
,
873 void SetClippingRegion(const wxPoint
& pt
, const wxSize
& sz
);
874 void SetClippingRegion(const wxRect
& rect
);
878 Sets the clipping region for this device context.
880 Unlike SetClippingRegion(), this function works with physical
881 coordinates and not with the logical ones.
883 void SetDeviceClippingRegion(const wxRegion
& region
);
886 Sets the device origin (i.e., the origin in pixels after scaling has
887 been applied). This function may be useful in Windows printing
888 operations for placing a graphic on a page.
890 void SetDeviceOrigin(wxCoord x
, wxCoord y
);
893 Sets the current font for the DC. It must be a valid font, in
894 particular you should not pass wxNullFont to this method.
898 void SetFont(const wxFont
& font
);
901 Sets the current layout direction for the device context. @a dir may be
902 either @c wxLayout_Default, @c wxLayout_LeftToRight or
903 @c wxLayout_RightToLeft.
905 @see GetLayoutDirection()
907 void SetLayoutDirection(wxLayoutDirection dir
);
910 Sets the current logical function for the device context. This
911 determines how a source pixel (from a pen or brush colour, or source
912 device context if using Blit()) combines with a destination pixel in
913 the current device context.
915 The possible values and their meaning in terms of source and
916 destination pixel values are as follows:
920 wxAND_INVERT (NOT src) AND dst
921 wxAND_REVERSE src AND (NOT dst)
924 wxEQUIV (NOT src) XOR dst
926 wxNAND (NOT src) OR (NOT dst)
927 wxNOR (NOT src) AND (NOT dst)
930 wxOR_INVERT (NOT src) OR dst
931 wxOR_REVERSE src OR (NOT dst)
937 The default is wxCOPY, which simply draws with the current colour. The
938 others combine the current colour and the background using a logical
939 operation. wxINVERT is commonly used for drawing rubber bands or moving
940 outlines, since drawing twice reverts to the original colour.
942 void SetLogicalFunction(int function
);
945 The mapping mode of the device context defines the unit of measurement
946 used to convert logical units to device units. Note that in X, text
947 drawing isn't handled consistently with the mapping mode; a font is
948 always specified in point size. However, setting the user scale (see
949 SetUserScale()) scales the text appropriately. In Windows, scalable
950 TrueType fonts are always used; in X, results depend on availability of
951 fonts, but usually a reasonable match is found.
953 The coordinate origin is always at the top left of the screen/printer.
955 Drawing to a Windows printer device context uses the current mapping
956 mode, but mapping mode is currently ignored for PostScript output.
958 The mapping mode can be one of the following:
959 - wxMM_TWIPS: Each logical unit is 1/20 of a point, or 1/1440 of an
961 - wxMM_POINTS: Each logical unit is a point, or 1/72 of an inch.
962 - wxMM_METRIC: Each logical unit is 1 mm.
963 - wxMM_LOMETRIC: Each logical unit is 1/10 of a mm.
964 - wxMM_TEXT: Each logical unit is 1 device pixel.
966 void SetMapMode(int mode
);
969 If this is a window DC or memory DC, assigns the given palette to the
970 window or bitmap associated with the DC. If the argument is
971 wxNullPalette, the current palette is selected out of the device
972 context, and the original palette restored.
976 void SetPalette(const wxPalette
& palette
);
979 Sets the current pen for the DC. If the argument is wxNullPen, the
980 current pen is selected out of the device context (leaving wxDC without
981 any valid pen), allowing the current brush to be destroyed safely.
983 @see wxMemoryDC for the interpretation of colours when drawing into a
986 void SetPen(const wxPen
& pen
);
989 Sets the current text background colour for the DC.
991 void SetTextBackground(const wxColour
& colour
);
994 Sets the current text foreground colour for the DC.
996 @see wxMemoryDC for the interpretation of colours when drawing into a
999 void SetTextForeground(const wxColour
& colour
);
1002 Sets the user scaling factor, useful for applications which require
1005 void SetUserScale(double xScale
, double yScale
);
1008 Starts a document (only relevant when outputting to a printer).
1009 @a message is a message to show while printing.
1011 bool StartDoc(const wxString
& message
);
1014 Starts a document page (only relevant when outputting to a printer).
1019 Copy from a source DC to this DC, specifying the destination
1020 coordinates, destination size, source DC, source coordinates, size of
1021 source area to copy, logical function, whether to use a bitmap mask,
1022 and mask source position.
1025 Destination device context x position.
1027 Destination device context y position.
1029 Width of destination area.
1031 Height of destination area.
1033 Source device context.
1035 Source device context x position.
1037 Source device context y position.
1039 Width of source area to be copied.
1041 Height of source area to be copied.
1043 Logical function to use, see SetLogicalFunction().
1045 If @true, Blit does a transparent blit using the mask that is
1046 associated with the bitmap selected into the source device context.
1047 The Windows implementation does the following if MaskBlt cannot be
1050 <li>Creates a temporary bitmap and copies the destination area into
1052 <li>Copies the source area into the temporary bitmap using the
1053 specified logical function.</li>
1054 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1055 the mask bitmap with the temp bitmap with the foreground colour
1056 set to WHITE and the bg colour set to BLACK.</li>
1057 <li>Sets the unmasked area in the destination area to BLACK by
1058 ANDing the mask bitmap with the destination area with the
1059 foreground colour set to BLACK and the background colour set to
1061 <li>ORs the temporary bitmap with the destination area.</li>
1062 <li>Deletes the temporary bitmap.</li>
1064 This sequence of operations ensures that the source's transparent
1065 area need not be black, and logical functions are supported.
1066 @n @b Note: on Windows, blitting with masks can be speeded up
1067 considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
1068 enabled. You can also influence whether MaskBlt or the explicit
1069 mask blitting code above is used, by using wxSystemOptions and
1070 setting the @c no-maskblt option to 1.
1072 Source x position on the mask. If both xsrcMask and ysrcMask are
1073 -1, xsrc and ysrc will be assumed for the mask source position.
1074 Currently only implemented on Windows.
1076 Source y position on the mask. If both xsrcMask and ysrcMask are
1077 -1, xsrc and ysrc will be assumed for the mask source position.
1078 Currently only implemented on Windows.
1080 There is partial support for Blit() in wxPostScriptDC, under X.
1082 StretchBlit() is only implemented under wxMAC and wxMSW.
1084 See wxMemoryDC for typical usage.
1088 @see Blit(), wxMemoryDC, wxBitmap, wxMask
1090 bool StretchBlit(wxCoord xdest
, wxCoord ydest
,
1091 wxCoord dstWidth
, wxCoord dstHeight
,
1092 wxDC
* source
, wxCoord xsrc
, wxCoord ysrc
,
1093 wxCoord srcWidth
, wxCoord srcHeight
,
1094 int logicalFunc
= wxCOPY
,
1095 bool useMask
= false,
1096 wxCoord xsrcMask
= -1, wxCoord ysrcMask
= -1);
1104 wxDCClipper is a small helper class for setting a clipping region on a wxDC
1105 and unsetting it automatically. An object of wxDCClipper class is typically
1106 created on the stack so that it is automatically destroyed when the object
1107 goes out of scope. A typical usage example:
1110 void MyFunction(wxDC& dc)
1112 wxDCClipper clip(dc, rect);
1113 // ... drawing functions here are affected by clipping rect ...
1116 void OtherFunction()
1120 // ... drawing functions here are not affected by clipping rect ...
1127 @see wxDC::SetClippingRegion()
1134 Sets the clipping region to the specified region/coordinates.
1136 The clipping region is automatically unset when this object is destroyed.
1138 wxDCClipper(wxDC
& dc
, const wxRegion
& r
);
1139 wxDCClipper(wxDC
& dc
, const wxRect
& rect
);
1140 wxDCClipper(wxDC
& dc
, int x
, int y
, int w
, int h
);