]>
git.saurik.com Git - wxWidgets.git/blob - interface/dc.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxDC
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
13 A wxDC is a @e "device context" onto which graphics and text can be drawn.
14 It is intended to represent different output devices and offers a common
15 abstract API for drawing on any of them.
17 wxWidgets offers an alternative drawing API based on the modern drawing
18 backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer
19 and related classes. There is also a wxGCDC linking the APIs by offering
20 the wxDC API ontop of a wxGraphicsContext.
22 wxDC is an abstract base class and cannot be created directly.
23 Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or
24 wxPrinterDC. Notice that device contexts which are associated with windows
25 (i.e. wxClientDC, wxWindowDC and wxPaintDC) use the window font and colours
26 by default (starting with wxWidgets 2.9.0) but the other device context
27 classes use system-default values so you always must set the appropriate
28 fonts and colours before using them.
30 In addition to the versions of the methods documented below, there
31 are also versions which accept single wxPoint parameter instead
32 of the two wxCoord ones or wxPoint and wxSize instead of the four
35 Beginning with wxWidgets 2.9.0 the entire wxDC code has been
36 reorganized. All platform dependent code (actually all drawing code)
37 has been moved into backend classes which derive from a common
38 wxDCImpl class. The user-visible classes such as wxClientDC and
39 wxPaintDC merely forward all calls to the backend implementation.
41 On Mac OS X colours with alpha channel are supported. Instances wxPen
42 or wxBrush that are built from wxColour use the colour's alpha values
43 when stroking or filling.
48 @see @ref overview_dc, wxGraphicsContext
50 @todo Precise definition of default/initial state.
51 @todo Pixelwise definition of operations (e.g. last point of a line not
53 @todo Coordinates: state clearly which type of coordinates are returned by
54 the various Get*Point() or similar functions - often they are client
55 coordinates but not always.
57 class wxDC
: public wxObject
61 Copy from a source DC to this DC, specifying the destination
62 coordinates, size of area to copy, source DC, source coordinates,
63 logical function, whether to use a bitmap mask, and mask source
67 Destination device context x position.
69 Destination device context y position.
71 Width of source area to be copied.
73 Height of source area to be copied.
75 Source device context.
77 Source device context x position.
79 Source device context y position.
81 Logical function to use, see SetLogicalFunction().
83 If @true, Blit does a transparent blit using the mask that is
84 associated with the bitmap selected into the source device context.
85 The Windows implementation does the following if MaskBlt cannot be
88 <li>Creates a temporary bitmap and copies the destination area into
90 <li>Copies the source area into the temporary bitmap using the
91 specified logical function.</li>
92 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
93 the mask bitmap with the temp bitmap with the foreground colour
94 set to WHITE and the bg colour set to BLACK.</li>
95 <li>Sets the unmasked area in the destination area to BLACK by
96 ANDing the mask bitmap with the destination area with the
97 foreground colour set to BLACK and the background colour set to
99 <li>ORs the temporary bitmap with the destination area.</li>
100 <li>Deletes the temporary bitmap.</li>
102 This sequence of operations ensures that the source's transparent
103 area need not be black, and logical functions are supported.
104 @n @b Note: on Windows, blitting with masks can be speeded up
105 considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
106 enabled. You can also influence whether MaskBlt or the explicit
107 mask blitting code above is used, by using wxSystemOptions and
108 setting the @c no-maskblt option to 1.
110 Source x position on the mask. If both xsrcMask and ysrcMask are
111 -1, xsrc and ysrc will be assumed for the mask source position.
112 Currently only implemented on Windows.
114 Source y position on the mask. If both xsrcMask and ysrcMask are
115 -1, xsrc and ysrc will be assumed for the mask source position.
116 Currently only implemented on Windows.
118 @remarks There is partial support for Blit() in wxPostScriptDC, under X.
120 @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
122 bool Blit(wxCoord xdest
, wxCoord ydest
, wxCoord width
,
123 wxCoord height
, wxDC
* source
, wxCoord xsrc
, wxCoord ysrc
,
124 int logicalFunc
= wxCOPY
, bool useMask
= false,
125 wxCoord xsrcMask
= -1, wxCoord ysrcMask
= -1);
128 Adds the specified point to the bounding box which can be retrieved
129 with MinX(), MaxX() and MinY(), MaxY() functions.
131 @see ResetBoundingBox()
133 void CalcBoundingBox(wxCoord x
, wxCoord y
);
136 Clears the device context using the current background brush.
141 Performs all necessary computations for given platform and context type
142 after each change of scale and origin parameters. Usually called
143 automatically internally after such changes.
145 virtual void ComputeScaleAndOrigin();
148 Displays a cross hair using the current pen. This is a vertical and
149 horizontal line the height and width of the window, centred on the
152 void CrossHair(wxCoord x
, wxCoord y
);
155 Destroys the current clipping region so that none of the DC is clipped.
157 @see SetClippingRegion()
159 void DestroyClippingRegion();
162 Convert device X coordinate to logical coordinate, using the current
165 virtual wxCoord
DeviceToLogicalX(wxCoord x
);
168 Convert device X coordinate to relative logical coordinate, using the
169 current mapping mode but ignoring the x axis orientation. Use this
170 function for converting a width, for example.
172 virtual wxCoord
DeviceToLogicalXRel(wxCoord x
);
175 Converts device Y coordinate to logical coordinate, using the current
178 virtual wxCoord
DeviceToLogicalY(wxCoord y
);
181 Convert device Y coordinate to relative logical coordinate, using the
182 current mapping mode but ignoring the y axis orientation. Use this
183 function for converting a height, for example.
185 virtual wxCoord
DeviceToLogicalYRel(wxCoord y
);
188 Draws an arc of a circle, centred on (@a xc, @a yc), with starting
189 point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is
190 used for the outline and the current brush for filling the shape.
192 The arc is drawn in a counter-clockwise direction from the start point
195 void DrawArc(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
,
196 wxCoord xc
, wxCoord yc
);
199 Draw a bitmap on the device context at the specified point. If
200 @a transparent is @true and the bitmap has a transparency mask, the
201 bitmap will be drawn transparently.
203 When drawing a mono-bitmap, the current text foreground colour will be
204 used to draw the foreground of the bitmap (all bits set to 1), and the
205 current text background colour to draw the background (all bits set to
208 @see SetTextForeground(), SetTextBackground(), wxMemoryDC
210 void DrawBitmap(const wxBitmap
& bitmap
, wxCoord x
, wxCoord y
,
215 Draws a check mark inside the given rectangle.
217 void DrawCheckMark(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
218 void DrawCheckMark(const wxRect
& rect
);
223 Draws a circle with the given centre and radius.
227 void DrawCircle(wxCoord x
, wxCoord y
, wxCoord radius
);
228 void DrawCircle(const wxPoint
& pt
, wxCoord radius
);
233 Draws an ellipse contained in the rectangle specified either with the
234 given top left corner and the given size or directly. The current pen
235 is used for the outline and the current brush for filling the shape.
239 void DrawEllipse(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
240 void DrawEllipse(const wxPoint
& pt
, const wxSize
& size
);
241 void DrawEllipse(const wxRect
& rect
);
245 Draws an arc of an ellipse. The current pen is used for drawing the arc
246 and the current brush is used for drawing the pie.
248 @a x and @a y specify the x and y coordinates of the upper-left corner
249 of the rectangle that contains the ellipse.
251 @a width and @a height specify the width and height of the rectangle
252 that contains the ellipse.
254 @a start and @a end specify the start and end of the arc relative to
255 the three-o'clock position from the center of the rectangle. Angles are
256 specified in degrees (360 is a complete circle). Positive values mean
257 counter-clockwise motion. If @a start is equal to @e end, a complete
258 ellipse will be drawn.
260 void DrawEllipticArc(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
,
261 double start
, double end
);
264 Draw an icon on the display (does nothing if the device context is
265 PostScript). This can be the simplest way of drawing bitmaps on a
268 void DrawIcon(const wxIcon
& icon
, wxCoord x
, wxCoord y
);
272 Draw optional bitmap and the text into the given rectangle and aligns
273 it as specified by alignment parameter; it also will emphasize the
274 character with the given index if it is != -1 and return the bounding
275 rectangle if required.
277 virtual void DrawLabel(const wxString
& text
, const wxBitmap
& image
,
279 int alignment
= wxALIGN_LEFT
| wxALIGN_TOP
,
280 int indexAccel
= -1, wxRect
* rectBounding
= NULL
);
281 void DrawLabel(const wxString
& text
, const wxRect
& rect
,
282 int alignment
= wxALIGN_LEFT
| wxALIGN_TOP
,
283 int indexAccel
= -1);
287 Draws a line from the first point to the second. The current pen is
288 used for drawing the line. Note that the point (@a x2, @a y2) is not
289 part of the line and is not drawn by this function (this is consistent
290 with the behaviour of many other toolkits).
292 void DrawLine(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
);
295 Draws lines using an array of points of size @a n adding the optional
296 offset coordinate. The current pen is used for drawing the lines.
299 The wxPython version of this method accepts a Python list of wxPoint
303 void DrawLines(int n
, wxPoint points
[], wxCoord xoffset
= 0,
304 wxCoord yoffset
= 0);
306 This method uses a list of wxPoints, adding the optional offset
307 coordinate. The programmer is responsible for deleting the list of
311 The wxPython version of this method accepts a Python list of wxPoint
315 void DrawLines(const wxPointList
* points
,
316 wxCoord xoffset
= 0, wxCoord yoffset
= 0);
319 Draws a point using the color of the current pen. Note that the other
320 properties of the pen are not used, such as width.
322 void DrawPoint(wxCoord x
, wxCoord y
);
325 Draws a filled polygon using an array of points of size @a n, adding
326 the optional offset coordinate. The first and last points are
327 automatically closed.
329 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
330 default) or @b wxWINDING_RULE.
332 The current pen is used for drawing the outline, and the current brush
333 for filling the shape. Using a transparent brush suppresses filling.
335 void DrawPolygon(int n
, wxPoint points
[], wxCoord xoffset
= 0,
336 wxCoord yoffset
= 0, int fill_style
= wxODDEVEN_RULE
);
338 This method draws a filled polygon using a list of wxPoints, adding the
339 optional offset coordinate. The first and last points are automatically
342 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
343 default) or @b wxWINDING_RULE.
345 The current pen is used for drawing the outline, and the current brush
346 for filling the shape. Using a transparent brush suppresses filling.
348 The programmer is responsible for deleting the list of points.
351 The wxPython version of this method accepts a Python list of wxPoint
355 void DrawPolygon(const wxPointList
* points
,
356 wxCoord xoffset
= 0, wxCoord yoffset
= 0,
357 int fill_style
= wxODDEVEN_RULE
);
360 Draws two or more filled polygons using an array of @a points, adding
361 the optional offset coordinates.
363 Notice that for the platforms providing a native implementation of this
364 function (Windows and PostScript-based wxDC currently), this is more
365 efficient than using DrawPolygon() in a loop.
367 @a n specifies the number of polygons to draw, the array @e count of
368 size @a n specifies the number of points in each of the polygons in the
371 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
372 default) or @b wxWINDING_RULE.
374 The current pen is used for drawing the outline, and the current brush
375 for filling the shape. Using a transparent brush suppresses filling.
377 The polygons maybe disjoint or overlapping. Each polygon specified in a
378 call to DrawPolyPolygon() must be closed. Unlike polygons created by
379 the DrawPolygon() member function, the polygons created by this
380 method are not closed automatically.
386 void DrawPolyPolygon(int n
, int count
[], wxPoint points
[],
387 wxCoord xoffset
= 0, wxCoord yoffset
= 0,
388 int fill_style
= wxODDEVEN_RULE
);
391 Draws a rectangle with the given top left corner, and with the given
392 size. The current pen is used for the outline and the current brush
393 for filling the shape.
395 void DrawRectangle(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
398 Draws the text rotated by @a angle degrees.
400 @note Under Win9x only TrueType fonts can be drawn by this function. In
401 particular, a font different from @c wxNORMAL_FONT should be used
402 as the latter is not a TrueType font. @c wxSWISS_FONT is an
403 example of a font which is.
407 void DrawRotatedText(const wxString
& text
, wxCoord x
, wxCoord y
,
411 Draws a rectangle with the given top left corner, and with the given
412 size. The corners are quarter-circles using the given radius. The
413 current pen is used for the outline and the current brush for filling
416 If @a radius is positive, the value is assumed to be the radius of the
417 rounded corner. If @a radius is negative, the absolute value is assumed
418 to be the @e proportion of the smallest dimension of the rectangle.
419 This means that the corner can be a sensible size relative to the size
420 of the rectangle, and also avoids the strange effects X produces when
421 the corners are too big for the rectangle.
423 void DrawRoundedRectangle(wxCoord x
, wxCoord y
, wxCoord width
,
424 wxCoord height
, double radius
);
428 Draws a spline between all given points using the current pen.
431 The wxPython version of this method accepts a Python list of wxPoint
435 void DrawSpline(int n
, wxPoint points
[]);
436 void DrawSpline(const wxPointList
* points
);
437 void DrawSpline(wxCoord x1
, wxCoord y1
, wxCoord x2
, wxCoord y2
,
438 wxCoord x3
, wxCoord y3
);
442 Draws a text string at the specified point, using the current text
443 font, and the current text foreground and background colours.
445 The coordinates refer to the top-left corner of the rectangle bounding
446 the string. See GetTextExtent() for how to get the dimensions of a text
447 string, which can be used to position the text more precisely.
449 @note Under wxGTK, the current
450 @ref GetLogicalFunction() "logical function" is used by this
451 function but it is ignored by wxMSW. Thus, you should avoid using
452 logical functions with this function in portable programs.
454 void DrawText(const wxString
& text
, wxCoord x
, wxCoord y
);
457 Ends a document (only relevant when outputting to a printer).
462 Ends a document page (only relevant when outputting to a printer).
467 Flood fills the device context starting from the given point, using
468 the current brush colour, and using a style:
470 - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
471 given colour is encountered.
472 - wxFLOOD_BORDER: The area to be flooded is bounded by the given
475 @return @false if the operation failed.
477 @note The present implementation for non-Windows platforms may fail to
478 find colour borders if the pixels do not match the colour
479 exactly. However the function will still return @true.
481 bool FloodFill(wxCoord x
, wxCoord y
, const wxColour
& colour
,
482 int style
= wxFLOOD_SURFACE
);
485 Gets the brush used for painting the background.
487 @see wxDC::SetBackground()
489 const wxBrush
GetBackground() const;
492 Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
494 @see SetBackgroundMode()
496 int GetBackgroundMode() const;
499 Gets the current brush.
501 @see wxDC::SetBrush()
503 const wxBrush
GetBrush() const;
506 Gets the character height of the currently set font.
508 wxCoord
GetCharHeight();
511 Gets the average character width of the currently set font.
513 wxCoord
GetCharWidth();
516 Gets the rectangle surrounding the current clipping region.
519 No arguments are required and the four values defining the rectangle
520 are returned as a tuple.
523 void GetClippingBox(wxCoord x
, wxCoord y
, wxCoord width
, wxCoord height
);
526 Returns the depth (number of bits/pixel) of this DC.
528 @see wxDisplayDepth()
530 int GetDepth() const;
533 Gets the current font. Notice that even although each device context
534 object has some default font after creation, this method would return a
535 wxNullFont initially and only after calling SetFont() a valid font is
538 const wxFont
GetFont() const;
541 Gets the current layout direction of the device context. On platforms
542 where RTL layout is supported, the return value will either be
543 @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
544 not supported, the return value will be @c wxLayout_Default.
546 @see SetLayoutDirection()
548 wxLayoutDirection
GetLayoutDirection() const;
551 Gets the current logical function.
553 @see SetLogicalFunction()
555 int GetLogicalFunction();
558 Gets the mapping mode for the device context.
565 Gets the dimensions of the string using the currently selected font.
566 @a string is the text string to measure, @e heightLine, if non @NULL,
567 is where to store the height of a single line.
569 The text extent is set in the given @a w and @a h pointers.
571 If the optional parameter @a font is specified and valid, then it is
572 used for the text extent calculation, otherwise the currently selected
575 @note This function works with both single-line and multi-line strings.
577 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
579 void GetMultiLineTextExtent(const wxString
& string
, wxCoord
* w
,
581 wxCoord
* heightLine
= NULL
,
582 wxFont
* font
= NULL
) const;
584 Gets the dimensions of the string using the currently selected font.
585 @a string is the text string to measure, @e heightLine, if non @NULL,
586 is where to store the height of a single line.
588 @return The text extent as a wxSize object.
590 @note This function works with both single-line and multi-line strings.
592 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
594 const wxSize
GetMultiLineTextExtent(const wxString
& string
) const;
597 Fills the @a widths array with the widths from the beginning of @a text
598 to the corresponding character of @a text. The generic version simply
599 builds a running total of the widths of each character using
600 GetTextExtent(), however if the various platforms have a native API
601 function that is faster or more accurate than the generic
602 implementation then it should be used instead.
605 This method only takes the @a text parameter and returns a Python list
609 @see GetMultiLineTextExtent(), GetTextExtent()
611 bool GetPartialTextExtents(const wxString
& text
,
612 wxArrayInt
& widths
) const;
615 Gets the current pen.
619 const wxPen
GetPen() const;
622 Gets in @a colour the colour at the specified location. Not available
623 for wxPostScriptDC or wxMetafileDC.
625 @note Setting a pixel can be done using DrawPoint().
628 The wxColour value is returned and is not required as a parameter.
631 bool GetPixel(wxCoord x
, wxCoord y
, wxColour
* colour
);
634 Returns the resolution of the device in pixels per inch.
636 wxSize
GetPPI() const;
640 This gets the horizontal and vertical resolution in device units. It
641 can be used to scale graphics to fit the page.
643 For example, if @e maxX and @e maxY represent the maximum horizontal
644 and vertical 'pixel' values used in your application, the following
645 code will scale the graphic to fit on the printer page:
650 double scaleX = (double)(maxX / w);
651 double scaleY = (double)(maxY / h);
652 dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
656 In place of a single overloaded method name, wxPython implements the
658 - GetSize() - Returns a wxSize.
659 - GetSizeWH() - Returns a 2-tuple (width, height).
662 void GetSize(wxCoord
* width
, wxCoord
* height
) const;
663 const wxSize
GetSize() const;
668 Returns the horizontal and vertical resolution in millimetres.
670 void GetSizeMM(wxCoord
* width
, wxCoord
* height
) const;
671 const wxSize
GetSizeMM() const;
675 Gets the current text background colour.
677 @see SetTextBackground()
679 const wxColour
GetTextBackground() const;
683 Gets the dimensions of the string using the currently selected font.
684 @a string is the text string to measure, @a descent is the dimension
685 from the baseline of the font to the bottom of the descender, and
686 @a externalLeading is any extra vertical space added to the font by the
687 font designer (usually is zero).
689 The text extent is returned in @a w and @a h pointers or as a wxSize
690 object depending on which version of this function is used.
692 If the optional parameter @a font is specified and valid, then it is
693 used for the text extent calculation. Otherwise the currently selected
696 @note This function only works with single-line strings.
699 The following methods are implemented in wxPython:
700 - GetTextExtent(string) - Returns a 2-tuple, (width, height).
701 - GetFullTextExtent(string, font=NULL) -
702 Returns a 4-tuple, (width, height, descent, externalLeading).
705 @see wxFont, SetFont(), GetPartialTextExtents(),
706 GetMultiLineTextExtent()
708 void GetTextExtent(const wxString
& string
, wxCoord
* w
, wxCoord
* h
,
709 wxCoord
* descent
= NULL
,
710 wxCoord
* externalLeading
= NULL
,
711 const wxFont
* font
= NULL
) const;
712 const wxSize
GetTextExtent(const wxString
& string
) const;
716 Gets the current text foreground colour.
718 @see SetTextForeground()
720 const wxColour
GetTextForeground() const;
723 Gets the current user scale factor.
727 void GetUserScale(double x
, double y
);
731 Fill the area specified by rect with a radial gradient, starting from
732 @a initialColour at the centre of the circle and fading to
733 @a destColour on the circle outside.
735 @a circleCenter are the relative coordinates of centre of the circle in
736 the specified @e rect. If not specified, the circle is placed at the
739 @note Currently this function is very slow, don't use it for real-time
742 void GradientFillConcentric(const wxRect
& rect
,
743 const wxColour
& initialColour
,
744 const wxColour
& destColour
);
745 void GradientFillConcentric(const wxRect
& rect
,
746 const wxColour
& initialColour
,
747 const wxColour
& destColour
,
748 const wxPoint
& circleCenter
);
752 Fill the area specified by @a rect with a linear gradient, starting
753 from @a initialColour and eventually fading to @e destColour. The
754 @a nDirection specifies the direction of the colour change, default is
755 to use @a initialColour on the left part of the rectangle and
756 @a destColour on the right one.
758 void GradientFillLinear(const wxRect
& rect
,
759 const wxColour
& initialColour
,
760 const wxColour
& destColour
,
761 wxDirection nDirection
= wxEAST
);
764 Returns @true if the DC is ok to use.
769 Converts logical X coordinate to device coordinate, using the current
772 virtual wxCoord
LogicalToDeviceX(wxCoord x
);
775 Converts logical X coordinate to relative device coordinate, using the
776 current mapping mode but ignoring the x axis orientation. Use this for
777 converting a width, for example.
779 virtual wxCoord
LogicalToDeviceXRel(wxCoord x
);
782 Converts logical Y coordinate to device coordinate, using the current
785 virtual wxCoord
LogicalToDeviceY(wxCoord y
);
788 Converts logical Y coordinate to relative device coordinate, using the
789 current mapping mode but ignoring the y axis orientation. Use this for
790 converting a height, for example.
792 virtual wxCoord
LogicalToDeviceYRel(wxCoord y
);
795 Gets the maximum horizontal extent used in drawing commands so far.
800 Gets the maximum vertical extent used in drawing commands so far.
805 Gets the minimum horizontal extent used in drawing commands so far.
810 Gets the minimum vertical extent used in drawing commands so far.
815 Resets the bounding box: after a call to this function, the bounding
816 box doesn't contain anything.
818 @see CalcBoundingBox()
820 void ResetBoundingBox();
823 Sets the x and y axis orientation (i.e., the direction from lowest to
824 highest values on the axis). The default orientation is x axis from
825 left to right and y axis from top down.
828 True to set the x axis orientation to the natural left to right
829 orientation, @false to invert it.
831 True to set the y axis orientation to the natural bottom up
832 orientation, @false to invert it.
834 void SetAxisOrientation(bool xLeftRight
, bool yBottomUp
);
837 Sets the current background brush for the DC.
839 void SetBackground(const wxBrush
& brush
);
842 @a mode may be one of wxSOLID and wxTRANSPARENT. This setting
843 determines whether text will be drawn with a background colour or not.
845 void SetBackgroundMode(int mode
);
848 Sets the current brush for the DC.
850 If the argument is wxNullBrush, the current brush is selected out of
851 the device context (leaving wxDC without any valid brush), allowing the
852 current brush to be destroyed safely.
854 @see wxBrush, wxMemoryDC (for the interpretation of colours when
855 drawing into a monochrome bitmap)
857 void SetBrush(const wxBrush
& brush
);
861 Sets the clipping region for this device context to the intersection of
862 the given region described by the parameters of this method and the
863 previously set clipping region. You should call DestroyClippingRegion()
864 if you want to set the clipping region exactly to the region specified.
866 The clipping region is an area to which drawing is restricted. Possible
867 uses for the clipping region are for clipping text or for speeding up
868 window redraws when only a known area of the screen is damaged.
870 @see DestroyClippingRegion(), wxRegion
872 void SetClippingRegion(wxCoord x
, wxCoord y
, wxCoord width
,
874 void SetClippingRegion(const wxPoint
& pt
, const wxSize
& sz
);
875 void SetClippingRegion(const wxRect
& rect
);
879 Sets the clipping region for this device context.
881 Unlike SetClippingRegion(), this function works with physical
882 coordinates and not with the logical ones.
884 void SetDeviceClippingRegion(const wxRegion
& region
);
887 Sets the device origin (i.e., the origin in pixels after scaling has
888 been applied). This function may be useful in Windows printing
889 operations for placing a graphic on a page.
891 void SetDeviceOrigin(wxCoord x
, wxCoord y
);
894 Sets the current font for the DC. It must be a valid font, in
895 particular you should not pass wxNullFont to this method.
899 void SetFont(const wxFont
& font
);
902 Sets the current layout direction for the device context. @a dir may be
903 either @c wxLayout_Default, @c wxLayout_LeftToRight or
904 @c wxLayout_RightToLeft.
906 @see GetLayoutDirection()
908 void SetLayoutDirection(wxLayoutDirection dir
);
911 Sets the current logical function for the device context. This
912 determines how a source pixel (from a pen or brush colour, or source
913 device context if using Blit()) combines with a destination pixel in
914 the current device context.
916 The possible values and their meaning in terms of source and
917 destination pixel values are as follows:
921 wxAND_INVERT (NOT src) AND dst
922 wxAND_REVERSE src AND (NOT dst)
925 wxEQUIV (NOT src) XOR dst
927 wxNAND (NOT src) OR (NOT dst)
928 wxNOR (NOT src) AND (NOT dst)
931 wxOR_INVERT (NOT src) OR dst
932 wxOR_REVERSE src OR (NOT dst)
938 The default is wxCOPY, which simply draws with the current colour. The
939 others combine the current colour and the background using a logical
940 operation. wxINVERT is commonly used for drawing rubber bands or moving
941 outlines, since drawing twice reverts to the original colour.
943 void SetLogicalFunction(int function
);
946 The mapping mode of the device context defines the unit of measurement
947 used to convert logical units to device units. Note that in X, text
948 drawing isn't handled consistently with the mapping mode; a font is
949 always specified in point size. However, setting the user scale (see
950 SetUserScale()) scales the text appropriately. In Windows, scalable
951 TrueType fonts are always used; in X, results depend on availability of
952 fonts, but usually a reasonable match is found.
954 The coordinate origin is always at the top left of the screen/printer.
956 Drawing to a Windows printer device context uses the current mapping
957 mode, but mapping mode is currently ignored for PostScript output.
959 The mapping mode can be one of the following:
960 - wxMM_TWIPS: Each logical unit is 1/20 of a point, or 1/1440 of an
962 - wxMM_POINTS: Each logical unit is a point, or 1/72 of an inch.
963 - wxMM_METRIC: Each logical unit is 1 mm.
964 - wxMM_LOMETRIC: Each logical unit is 1/10 of a mm.
965 - wxMM_TEXT: Each logical unit is 1 device pixel.
967 void SetMapMode(int mode
);
970 If this is a window DC or memory DC, assigns the given palette to the
971 window or bitmap associated with the DC. If the argument is
972 wxNullPalette, the current palette is selected out of the device
973 context, and the original palette restored.
977 void SetPalette(const wxPalette
& palette
);
980 Sets the current pen for the DC. If the argument is wxNullPen, the
981 current pen is selected out of the device context (leaving wxDC without
982 any valid pen), allowing the current brush to be destroyed safely.
984 @see wxMemoryDC for the interpretation of colours when drawing into a
987 void SetPen(const wxPen
& pen
);
990 Sets the current text background colour for the DC.
992 void SetTextBackground(const wxColour
& colour
);
995 Sets the current text foreground colour for the DC.
997 @see wxMemoryDC for the interpretation of colours when drawing into a
1000 void SetTextForeground(const wxColour
& colour
);
1003 Sets the user scaling factor, useful for applications which require
1006 void SetUserScale(double xScale
, double yScale
);
1009 Starts a document (only relevant when outputting to a printer).
1010 @a message is a message to show while printing.
1012 bool StartDoc(const wxString
& message
);
1015 Starts a document page (only relevant when outputting to a printer).
1020 Copy from a source DC to this DC, specifying the destination
1021 coordinates, destination size, source DC, source coordinates, size of
1022 source area to copy, logical function, whether to use a bitmap mask,
1023 and mask source position.
1026 Destination device context x position.
1028 Destination device context y position.
1030 Width of destination area.
1032 Height of destination area.
1034 Source device context.
1036 Source device context x position.
1038 Source device context y position.
1040 Width of source area to be copied.
1042 Height of source area to be copied.
1044 Logical function to use, see SetLogicalFunction().
1046 If @true, Blit does a transparent blit using the mask that is
1047 associated with the bitmap selected into the source device context.
1048 The Windows implementation does the following if MaskBlt cannot be
1051 <li>Creates a temporary bitmap and copies the destination area into
1053 <li>Copies the source area into the temporary bitmap using the
1054 specified logical function.</li>
1055 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1056 the mask bitmap with the temp bitmap with the foreground colour
1057 set to WHITE and the bg colour set to BLACK.</li>
1058 <li>Sets the unmasked area in the destination area to BLACK by
1059 ANDing the mask bitmap with the destination area with the
1060 foreground colour set to BLACK and the background colour set to
1062 <li>ORs the temporary bitmap with the destination area.</li>
1063 <li>Deletes the temporary bitmap.</li>
1065 This sequence of operations ensures that the source's transparent
1066 area need not be black, and logical functions are supported.
1067 @n @b Note: on Windows, blitting with masks can be speeded up
1068 considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
1069 enabled. You can also influence whether MaskBlt or the explicit
1070 mask blitting code above is used, by using wxSystemOptions and
1071 setting the @c no-maskblt option to 1.
1073 Source x position on the mask. If both xsrcMask and ysrcMask are
1074 -1, xsrc and ysrc will be assumed for the mask source position.
1075 Currently only implemented on Windows.
1077 Source y position on the mask. If both xsrcMask and ysrcMask are
1078 -1, xsrc and ysrc will be assumed for the mask source position.
1079 Currently only implemented on Windows.
1081 There is partial support for Blit() in wxPostScriptDC, under X.
1083 StretchBlit() is only implemented under wxMAC and wxMSW.
1085 See wxMemoryDC for typical usage.
1089 @see Blit(), wxMemoryDC, wxBitmap, wxMask
1091 bool StretchBlit(wxCoord xdest
, wxCoord ydest
,
1092 wxCoord dstWidth
, wxCoord dstHeight
,
1093 wxDC
* source
, wxCoord xsrc
, wxCoord ysrc
,
1094 wxCoord srcWidth
, wxCoord srcHeight
,
1095 int logicalFunc
= wxCOPY
,
1096 bool useMask
= false,
1097 wxCoord xsrcMask
= -1, wxCoord ysrcMask
= -1);
1106 wxDCClipper is a small helper class for setting a clipping region on a wxDC
1107 and unsetting it automatically. An object of wxDCClipper class is typically
1108 created on the stack so that it is automatically destroyed when the object
1109 goes out of scope. A typical usage example:
1112 void MyFunction(wxDC& dc)
1114 wxDCClipper clip(dc, rect);
1115 // ... drawing functions here are affected by clipping rect ...
1118 void OtherFunction()
1122 // ... drawing functions here are not affected by clipping rect ...
1129 @see wxDC::SetClippingRegion()
1136 Sets the clipping region to the specified region/coordinates.
1138 The clipping region is automatically unset when this object is destroyed.
1140 wxDCClipper(wxDC
& dc
, const wxRegion
& r
);
1141 wxDCClipper(wxDC
& dc
, const wxRect
& rect
);
1142 wxDCClipper(wxDC
& dc
, int x
, int y
, int w
, int h
);