]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/dc.h
add const synonyms for wxGridTableBase::GetNumberRows/Cols(), using const_cast<>...
[wxWidgets.git] / interface / wx / dc.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: dc.h
3 // Purpose: interface of wxDC
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxDC
11
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.
15
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.
20
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.
28
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
32 wxCoord parameters.
33
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.
39
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.
43
44 @library{wxcore}
45 @category{dc,gdi}
46
47 @see @ref overview_dc, wxGraphicsContext
48
49 @todo Precise definition of default/initial state.
50 @todo Pixelwise definition of operations (e.g. last point of a line not
51 drawn).
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.
55 */
56 class wxDC : public wxObject
57 {
58 public:
59 /**
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
63 position.
64
65 @param xdest
66 Destination device context x position.
67 @param ydest
68 Destination device context y position.
69 @param width
70 Width of source area to be copied.
71 @param height
72 Height of source area to be copied.
73 @param source
74 Source device context.
75 @param xsrc
76 Source device context x position.
77 @param ysrc
78 Source device context y position.
79 @param logicalFunc
80 Logical function to use, see SetLogicalFunction().
81 @param useMask
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
85 used:
86 <ol>
87 <li>Creates a temporary bitmap and copies the destination area into
88 it.</li>
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
97 WHITE.</li>
98 <li>ORs the temporary bitmap with the destination area.</li>
99 <li>Deletes the temporary bitmap.</li>
100 </ol>
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.
108 @param xsrcMask
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.
112 @param ysrcMask
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.
116
117 @remarks There is partial support for Blit() in wxPostScriptDC, under X.
118
119 @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
120 */
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);
125
126 /**
127 Adds the specified point to the bounding box which can be retrieved
128 with MinX(), MaxX() and MinY(), MaxY() functions.
129
130 @see ResetBoundingBox()
131 */
132 void CalcBoundingBox(wxCoord x, wxCoord y);
133
134 /**
135 Clears the device context using the current background brush.
136 */
137 void Clear();
138
139 /**
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.
143 */
144 virtual void ComputeScaleAndOrigin();
145
146 /**
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
149 given point.
150 */
151 void CrossHair(wxCoord x, wxCoord y);
152
153 /**
154 Destroys the current clipping region so that none of the DC is clipped.
155
156 @see SetClippingRegion()
157 */
158 void DestroyClippingRegion();
159
160 /**
161 Convert device X coordinate to logical coordinate, using the current
162 mapping mode, user scale factor, device origin and axis orientation.
163 */
164 virtual wxCoord DeviceToLogicalX(wxCoord x);
165
166 /**
167 Convert device X coordinate to relative logical coordinate, using the
168 current mapping mode and user scale factor but ignoring the
169 axis orientation. Use this for converting a width, for example.
170 */
171 virtual wxCoord DeviceToLogicalXRel(wxCoord x);
172
173 /**
174 Converts device Y coordinate to logical coordinate, using the current
175 mapping mode, user scale factor, device origin and axis orientation.
176 */
177 virtual wxCoord DeviceToLogicalY(wxCoord y);
178
179 /**
180 Convert device Y coordinate to relative logical coordinate, using the
181 current mapping mode and user scale factor but ignoring the
182 axis orientation. Use this for converting a height, for example.
183 */
184 virtual wxCoord DeviceToLogicalYRel(wxCoord y);
185
186 /**
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.
190
191 The arc is drawn in a counter-clockwise direction from the start point
192 to the end point.
193 */
194 void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
195 wxCoord xc, wxCoord yc);
196
197 /**
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.
201
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
205 0).
206
207 @see SetTextForeground(), SetTextBackground(), wxMemoryDC
208 */
209 void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y,
210 bool transparent);
211
212 //@{
213 /**
214 Draws a check mark inside the given rectangle.
215 */
216 void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
217 void DrawCheckMark(const wxRect& rect);
218 //@}
219
220 //@{
221 /**
222 Draws a circle with the given centre and radius.
223
224 @see DrawEllipse()
225 */
226 void DrawCircle(wxCoord x, wxCoord y, wxCoord radius);
227 void DrawCircle(const wxPoint& pt, wxCoord radius);
228 //@}
229
230 //@{
231 /**
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.
235
236 @see DrawCircle()
237 */
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);
241 //@}
242
243 /**
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.
246
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.
249
250 @a width and @a height specify the width and height of the rectangle
251 that contains the ellipse.
252
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.
258 */
259 void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height,
260 double start, double end);
261
262 /**
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
265 window.
266 */
267 void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);
268
269 //@{
270 /**
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.
275 */
276 virtual void DrawLabel(const wxString& text, const wxBitmap& image,
277 const wxRect& rect,
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);
283 //@}
284
285 /**
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).
290 */
291 void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
292
293 /**
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.
296
297 @beginWxPythonOnly
298 The wxPython version of this method accepts a Python list of wxPoint
299 objects.
300 @endWxPythonOnly
301 */
302 void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0,
303 wxCoord yoffset = 0);
304 /**
305 This method uses a list of wxPoints, adding the optional offset
306 coordinate. The programmer is responsible for deleting the list of
307 points.
308
309 @beginWxPythonOnly
310 The wxPython version of this method accepts a Python list of wxPoint
311 objects.
312 @endWxPythonOnly
313 */
314 void DrawLines(const wxPointList* points,
315 wxCoord xoffset = 0, wxCoord yoffset = 0);
316
317 /**
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.
320 */
321 void DrawPoint(wxCoord x, wxCoord y);
322
323 /**
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.
327
328 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
329 default) or @b wxWINDING_RULE.
330
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.
333 */
334 void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0,
335 wxCoord yoffset = 0, int fill_style = wxODDEVEN_RULE);
336 /**
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
339 closed.
340
341 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
342 default) or @b wxWINDING_RULE.
343
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.
346
347 The programmer is responsible for deleting the list of points.
348
349 @beginWxPythonOnly
350 The wxPython version of this method accepts a Python list of wxPoint
351 objects.
352 @endWxPythonOnly
353 */
354 void DrawPolygon(const wxPointList* points,
355 wxCoord xoffset = 0, wxCoord yoffset = 0,
356 int fill_style = wxODDEVEN_RULE);
357
358 /**
359 Draws two or more filled polygons using an array of @a points, adding
360 the optional offset coordinates.
361
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.
365
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
368 @a points array.
369
370 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
371 default) or @b wxWINDING_RULE.
372
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.
375
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.
380
381 @beginWxPythonOnly
382 Not implemented yet.
383 @endWxPythonOnly
384 */
385 void DrawPolyPolygon(int n, int count[], wxPoint points[],
386 wxCoord xoffset = 0, wxCoord yoffset = 0,
387 int fill_style = wxODDEVEN_RULE);
388
389 /**
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.
393 */
394 void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
395
396 /**
397 Draws the text rotated by @a angle degrees.
398
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.
403
404 @see DrawText()
405 */
406 void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y,
407 double angle);
408
409 /**
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
413 the shape.
414
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.
421 */
422 void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width,
423 wxCoord height, double radius);
424
425 //@{
426 /**
427 Draws a spline between all given points using the current pen.
428
429 @beginWxPythonOnly
430 The wxPython version of this method accepts a Python list of wxPoint
431 objects.
432 @endWxPythonOnly
433 */
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);
438 //@}
439
440 /**
441 Draws a text string at the specified point, using the current text
442 font, and the current text foreground and background colours.
443
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.
447
448 @note The current @ref GetLogicalFunction() "logical function" is
449 ignored by this function.
450 */
451 void DrawText(const wxString& text, wxCoord x, wxCoord y);
452
453 /**
454 Ends a document (only relevant when outputting to a printer).
455 */
456 void EndDoc();
457
458 /**
459 Ends a document page (only relevant when outputting to a printer).
460 */
461 void EndPage();
462
463 /**
464 Flood fills the device context starting from the given point, using
465 the current brush colour, and using a style:
466
467 - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
468 given colour is encountered.
469 - wxFLOOD_BORDER: The area to be flooded is bounded by the given
470 colour.
471
472 @return @false if the operation failed.
473
474 @note The present implementation for non-Windows platforms may fail to
475 find colour borders if the pixels do not match the colour
476 exactly. However the function will still return @true.
477 */
478 bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
479 int style = wxFLOOD_SURFACE);
480
481 /**
482 Gets the brush used for painting the background.
483
484 @see wxDC::SetBackground()
485 */
486 const wxBrush GetBackground() const;
487
488 /**
489 Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
490
491 @see SetBackgroundMode()
492 */
493 int GetBackgroundMode() const;
494
495 /**
496 Gets the current brush.
497
498 @see wxDC::SetBrush()
499 */
500 const wxBrush GetBrush() const;
501
502 /**
503 Gets the character height of the currently set font.
504 */
505 wxCoord GetCharHeight();
506
507 /**
508 Gets the average character width of the currently set font.
509 */
510 wxCoord GetCharWidth();
511
512 /**
513 Gets the rectangle surrounding the current clipping region.
514
515 @beginWxPythonOnly
516 No arguments are required and the four values defining the rectangle
517 are returned as a tuple.
518 @endWxPythonOnly
519 */
520 void GetClippingBox(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
521
522 /**
523 Returns the depth (number of bits/pixel) of this DC.
524
525 @see wxDisplayDepth()
526 */
527 int GetDepth() const;
528
529 /**
530 Gets the current font. Notice that even although each device context
531 object has some default font after creation, this method would return a
532 wxNullFont initially and only after calling SetFont() a valid font is
533 returned.
534 */
535 const wxFont GetFont() const;
536
537 /**
538 Gets the current layout direction of the device context. On platforms
539 where RTL layout is supported, the return value will either be
540 @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
541 not supported, the return value will be @c wxLayout_Default.
542
543 @see SetLayoutDirection()
544 */
545 wxLayoutDirection GetLayoutDirection() const;
546
547 /**
548 Gets the current logical function.
549
550 @see SetLogicalFunction()
551 */
552 int GetLogicalFunction();
553
554 /**
555 Gets the mapping mode for the device context.
556
557 @see SetMapMode()
558 */
559 int GetMapMode();
560
561 /**
562 Gets the dimensions of the string using the currently selected font.
563 @a string is the text string to measure, @e heightLine, if non @NULL,
564 is where to store the height of a single line.
565
566 The text extent is set in the given @a w and @a h pointers.
567
568 If the optional parameter @a font is specified and valid, then it is
569 used for the text extent calculation, otherwise the currently selected
570 font is used.
571
572 @note This function works with both single-line and multi-line strings.
573
574 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
575 */
576 void GetMultiLineTextExtent(const wxString& string, wxCoord* w,
577 wxCoord* h,
578 wxCoord* heightLine = NULL,
579 wxFont* font = NULL) const;
580 /**
581 Gets the dimensions of the string using the currently selected font.
582 @a string is the text string to measure, @e heightLine, if non @NULL,
583 is where to store the height of a single line.
584
585 @return The text extent as a wxSize object.
586
587 @note This function works with both single-line and multi-line strings.
588
589 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
590 */
591 const wxSize GetMultiLineTextExtent(const wxString& string) const;
592
593 /**
594 Fills the @a widths array with the widths from the beginning of @a text
595 to the corresponding character of @a text. The generic version simply
596 builds a running total of the widths of each character using
597 GetTextExtent(), however if the various platforms have a native API
598 function that is faster or more accurate than the generic
599 implementation then it should be used instead.
600
601 @beginWxPythonOnly
602 This method only takes the @a text parameter and returns a Python list
603 of integers.
604 @endWxPythonOnly
605
606 @see GetMultiLineTextExtent(), GetTextExtent()
607 */
608 bool GetPartialTextExtents(const wxString& text,
609 wxArrayInt& widths) const;
610
611 /**
612 Gets the current pen.
613
614 @see SetPen()
615 */
616 const wxPen GetPen() const;
617
618 /**
619 Gets in @a colour the colour at the specified location. Not available
620 for wxPostScriptDC or wxMetafileDC.
621
622 @note Setting a pixel can be done using DrawPoint().
623
624 @beginWxPythonOnly
625 The wxColour value is returned and is not required as a parameter.
626 @endWxPythonOnly
627 */
628 bool GetPixel(wxCoord x, wxCoord y, wxColour* colour);
629
630 /**
631 Returns the resolution of the device in pixels per inch.
632 */
633 wxSize GetPPI() const;
634
635 //@{
636 /**
637 This gets the horizontal and vertical resolution in device units. It
638 can be used to scale graphics to fit the page.
639
640 For example, if @e maxX and @e maxY represent the maximum horizontal
641 and vertical 'pixel' values used in your application, the following
642 code will scale the graphic to fit on the printer page:
643
644 @code
645 wxCoord w, h;
646 dc.GetSize(&w, &h);
647 double scaleX = (double)(maxX / w);
648 double scaleY = (double)(maxY / h);
649 dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
650 @endcode
651
652 @beginWxPythonOnly
653 In place of a single overloaded method name, wxPython implements the
654 following methods:
655 - GetSize() - Returns a wxSize.
656 - GetSizeWH() - Returns a 2-tuple (width, height).
657 @endWxPythonOnly
658 */
659 void GetSize(wxCoord* width, wxCoord* height) const;
660 const wxSize GetSize() const;
661 //@}
662
663 //@{
664 /**
665 Returns the horizontal and vertical resolution in millimetres.
666 */
667 void GetSizeMM(wxCoord* width, wxCoord* height) const;
668 const wxSize GetSizeMM() const;
669 //@}
670
671 /**
672 Gets the current text background colour.
673
674 @see SetTextBackground()
675 */
676 const wxColour GetTextBackground() const;
677
678 //@{
679 /**
680 Gets the dimensions of the string using the currently selected font.
681 @a string is the text string to measure, @a descent is the dimension
682 from the baseline of the font to the bottom of the descender, and
683 @a externalLeading is any extra vertical space added to the font by the
684 font designer (usually is zero).
685
686 The text extent is returned in @a w and @a h pointers or as a wxSize
687 object depending on which version of this function is used.
688
689 If the optional parameter @a font is specified and valid, then it is
690 used for the text extent calculation. Otherwise the currently selected
691 font is.
692
693 @note This function only works with single-line strings.
694
695 @beginWxPythonOnly
696 The following methods are implemented in wxPython:
697 - GetTextExtent(string) - Returns a 2-tuple, (width, height).
698 - GetFullTextExtent(string, font=NULL) -
699 Returns a 4-tuple, (width, height, descent, externalLeading).
700 @endWxPythonOnly
701
702 @see wxFont, SetFont(), GetPartialTextExtents(),
703 GetMultiLineTextExtent()
704 */
705 void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
706 wxCoord* descent = NULL,
707 wxCoord* externalLeading = NULL,
708 const wxFont* font = NULL) const;
709 const wxSize GetTextExtent(const wxString& string) const;
710 //@}
711
712 /**
713 Gets the current text foreground colour.
714
715 @see SetTextForeground()
716 */
717 const wxColour GetTextForeground() const;
718
719 /**
720 Gets the current user scale factor.
721
722 @see SetUserScale()
723 */
724 void GetUserScale(double x, double y);
725
726 //@{
727 /**
728 Fill the area specified by rect with a radial gradient, starting from
729 @a initialColour at the centre of the circle and fading to
730 @a destColour on the circle outside.
731
732 @a circleCenter are the relative coordinates of centre of the circle in
733 the specified @e rect. If not specified, the circle is placed at the
734 centre of rect.
735
736 @note Currently this function is very slow, don't use it for real-time
737 drawing.
738 */
739 void GradientFillConcentric(const wxRect& rect,
740 const wxColour& initialColour,
741 const wxColour& destColour);
742 void GradientFillConcentric(const wxRect& rect,
743 const wxColour& initialColour,
744 const wxColour& destColour,
745 const wxPoint& circleCenter);
746 //@}
747
748 /**
749 Fill the area specified by @a rect with a linear gradient, starting
750 from @a initialColour and eventually fading to @e destColour. The
751 @a nDirection specifies the direction of the colour change, default is
752 to use @a initialColour on the left part of the rectangle and
753 @a destColour on the right one.
754 */
755 void GradientFillLinear(const wxRect& rect,
756 const wxColour& initialColour,
757 const wxColour& destColour,
758 wxDirection nDirection = wxEAST);
759
760 /**
761 Returns @true if the DC is ok to use.
762 */
763 bool Ok();
764
765 /**
766 Converts logical X coordinate to device coordinate, using the current
767 mapping mode, user scale factor, device origin and axis orientation.
768 */
769 virtual wxCoord LogicalToDeviceX(wxCoord x);
770
771 /**
772 Converts logical X coordinate to relative device coordinate, using the
773 current mapping mode and user scale factor but ignoring the
774 axis orientation. Use this for converting a width, for example.
775 */
776 virtual wxCoord LogicalToDeviceXRel(wxCoord x);
777
778 /**
779 Converts logical Y coordinate to device coordinate, using the current
780 mapping mode, user scale factor, device origin and axis orientation.
781 */
782 virtual wxCoord LogicalToDeviceY(wxCoord y);
783
784 /**
785 Converts logical Y coordinate to relative device coordinate, using the
786 current mapping mode and user scale factor but ignoring the
787 axis orientation. Use this for converting a height, for example.
788 */
789 virtual wxCoord LogicalToDeviceYRel(wxCoord y);
790
791 /**
792 Gets the maximum horizontal extent used in drawing commands so far.
793 */
794 wxCoord MaxX();
795
796 /**
797 Gets the maximum vertical extent used in drawing commands so far.
798 */
799 wxCoord MaxY();
800
801 /**
802 Gets the minimum horizontal extent used in drawing commands so far.
803 */
804 wxCoord MinX();
805
806 /**
807 Gets the minimum vertical extent used in drawing commands so far.
808 */
809 wxCoord MinY();
810
811 /**
812 Resets the bounding box: after a call to this function, the bounding
813 box doesn't contain anything.
814
815 @see CalcBoundingBox()
816 */
817 void ResetBoundingBox();
818
819 /**
820 Sets the x and y axis orientation (i.e., the direction from lowest to
821 highest values on the axis). The default orientation is x axis from
822 left to right and y axis from top down.
823
824 @param xLeftRight
825 True to set the x axis orientation to the natural left to right
826 orientation, @false to invert it.
827 @param yBottomUp
828 True to set the y axis orientation to the natural bottom up
829 orientation, @false to invert it.
830 */
831 void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
832
833 /**
834 Sets the current background brush for the DC.
835 */
836 void SetBackground(const wxBrush& brush);
837
838 /**
839 @a mode may be one of wxSOLID and wxTRANSPARENT. This setting
840 determines whether text will be drawn with a background colour or not.
841 */
842 void SetBackgroundMode(int mode);
843
844 /**
845 Sets the current brush for the DC.
846
847 If the argument is wxNullBrush, the current brush is selected out of
848 the device context (leaving wxDC without any valid brush), allowing the
849 current brush to be destroyed safely.
850
851 @see wxBrush, wxMemoryDC (for the interpretation of colours when
852 drawing into a monochrome bitmap)
853 */
854 void SetBrush(const wxBrush& brush);
855
856 //@{
857 /**
858 Sets the clipping region for this device context to the intersection of
859 the given region described by the parameters of this method and the
860 previously set clipping region. You should call DestroyClippingRegion()
861 if you want to set the clipping region exactly to the region specified.
862
863 The clipping region is an area to which drawing is restricted. Possible
864 uses for the clipping region are for clipping text or for speeding up
865 window redraws when only a known area of the screen is damaged.
866
867 @see DestroyClippingRegion(), wxRegion
868 */
869 void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width,
870 wxCoord height);
871 void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
872 void SetClippingRegion(const wxRect& rect);
873 //@}
874
875 /**
876 Sets the clipping region for this device context.
877
878 Unlike SetClippingRegion(), this function works with physical
879 coordinates and not with the logical ones.
880 */
881 void SetDeviceClippingRegion(const wxRegion& region);
882
883 /**
884 Sets the device origin (i.e., the origin in pixels after scaling has
885 been applied). This function may be useful in Windows printing
886 operations for placing a graphic on a page.
887 */
888 void SetDeviceOrigin(wxCoord x, wxCoord y);
889
890 /**
891 Sets the current font for the DC. It must be a valid font, in
892 particular you should not pass wxNullFont to this method.
893
894 @see wxFont
895 */
896 void SetFont(const wxFont& font);
897
898 /**
899 Sets the current layout direction for the device context. @a dir may be
900 either @c wxLayout_Default, @c wxLayout_LeftToRight or
901 @c wxLayout_RightToLeft.
902
903 @see GetLayoutDirection()
904 */
905 void SetLayoutDirection(wxLayoutDirection dir);
906
907 /**
908 Sets the current logical function for the device context. This
909 determines how a source pixel (from a pen or brush colour, or source
910 device context if using Blit()) combines with a destination pixel in
911 the current device context.
912 Text drawing is not affected by this function.
913
914 The possible values and their meaning in terms of source and
915 destination pixel values are as follows:
916
917 @verbatim
918 wxAND src AND dst
919 wxAND_INVERT (NOT src) AND dst
920 wxAND_REVERSE src AND (NOT dst)
921 wxCLEAR 0
922 wxCOPY src
923 wxEQUIV (NOT src) XOR dst
924 wxINVERT NOT dst
925 wxNAND (NOT src) OR (NOT dst)
926 wxNOR (NOT src) AND (NOT dst)
927 wxNO_OP dst
928 wxOR src OR dst
929 wxOR_INVERT (NOT src) OR dst
930 wxOR_REVERSE src OR (NOT dst)
931 wxSET 1
932 wxSRC_INVERT NOT src
933 wxXOR src XOR dst
934 @endverbatim
935
936 The default is wxCOPY, which simply draws with the current colour. The
937 others combine the current colour and the background using a logical
938 operation. wxINVERT is commonly used for drawing rubber bands or moving
939 outlines, since drawing twice reverts to the original colour.
940 */
941 void SetLogicalFunction(int function);
942
943 /**
944 The mapping mode of the device context defines the unit of measurement
945 used to convert logical units to device units. Note that in X, text
946 drawing isn't handled consistently with the mapping mode; a font is
947 always specified in point size. However, setting the user scale (see
948 SetUserScale()) scales the text appropriately. In Windows, scalable
949 TrueType fonts are always used; in X, results depend on availability of
950 fonts, but usually a reasonable match is found.
951
952 The coordinate origin is always at the top left of the screen/printer.
953
954 Drawing to a Windows printer device context uses the current mapping
955 mode, but mapping mode is currently ignored for PostScript output.
956
957 The mapping mode can be one of the following:
958 - wxMM_TWIPS: Each logical unit is 1/20 of a point, or 1/1440 of an
959 inch.
960 - wxMM_POINTS: Each logical unit is a point, or 1/72 of an inch.
961 - wxMM_METRIC: Each logical unit is 1 mm.
962 - wxMM_LOMETRIC: Each logical unit is 1/10 of a mm.
963 - wxMM_TEXT: Each logical unit is 1 device pixel.
964 */
965 void SetMapMode(int mode);
966
967 /**
968 If this is a window DC or memory DC, assigns the given palette to the
969 window or bitmap associated with the DC. If the argument is
970 wxNullPalette, the current palette is selected out of the device
971 context, and the original palette restored.
972
973 @see wxPalette
974 */
975 void SetPalette(const wxPalette& palette);
976
977 /**
978 Sets the current pen for the DC. If the argument is wxNullPen, the
979 current pen is selected out of the device context (leaving wxDC without
980 any valid pen), allowing the current brush to be destroyed safely.
981
982 @see wxMemoryDC for the interpretation of colours when drawing into a
983 monochrome bitmap.
984 */
985 void SetPen(const wxPen& pen);
986
987 /**
988 Sets the current text background colour for the DC.
989 */
990 void SetTextBackground(const wxColour& colour);
991
992 /**
993 Sets the current text foreground colour for the DC.
994
995 @see wxMemoryDC for the interpretation of colours when drawing into a
996 monochrome bitmap.
997 */
998 void SetTextForeground(const wxColour& colour);
999
1000 /**
1001 Sets the user scaling factor, useful for applications which require
1002 'zooming'.
1003 */
1004 void SetUserScale(double xScale, double yScale);
1005
1006 /**
1007 Starts a document (only relevant when outputting to a printer).
1008 @a message is a message to show while printing.
1009 */
1010 bool StartDoc(const wxString& message);
1011
1012 /**
1013 Starts a document page (only relevant when outputting to a printer).
1014 */
1015 bool StartPage();
1016
1017 /**
1018 Copy from a source DC to this DC, specifying the destination
1019 coordinates, destination size, source DC, source coordinates, size of
1020 source area to copy, logical function, whether to use a bitmap mask,
1021 and mask source position.
1022
1023 @param xdest
1024 Destination device context x position.
1025 @param ydest
1026 Destination device context y position.
1027 @param dstWidth
1028 Width of destination area.
1029 @param dstHeight
1030 Height of destination area.
1031 @param source
1032 Source device context.
1033 @param xsrc
1034 Source device context x position.
1035 @param ysrc
1036 Source device context y position.
1037 @param srcWidth
1038 Width of source area to be copied.
1039 @param srcHeight
1040 Height of source area to be copied.
1041 @param logicalFunc
1042 Logical function to use, see SetLogicalFunction().
1043 @param useMask
1044 If @true, Blit does a transparent blit using the mask that is
1045 associated with the bitmap selected into the source device context.
1046 The Windows implementation does the following if MaskBlt cannot be
1047 used:
1048 <ol>
1049 <li>Creates a temporary bitmap and copies the destination area into
1050 it.</li>
1051 <li>Copies the source area into the temporary bitmap using the
1052 specified logical function.</li>
1053 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1054 the mask bitmap with the temp bitmap with the foreground colour
1055 set to WHITE and the bg colour set to BLACK.</li>
1056 <li>Sets the unmasked area in the destination area to BLACK by
1057 ANDing the mask bitmap with the destination area with the
1058 foreground colour set to BLACK and the background colour set to
1059 WHITE.</li>
1060 <li>ORs the temporary bitmap with the destination area.</li>
1061 <li>Deletes the temporary bitmap.</li>
1062 </ol>
1063 This sequence of operations ensures that the source's transparent
1064 area need not be black, and logical functions are supported.
1065 @n @b Note: on Windows, blitting with masks can be speeded up
1066 considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
1067 enabled. You can also influence whether MaskBlt or the explicit
1068 mask blitting code above is used, by using wxSystemOptions and
1069 setting the @c no-maskblt option to 1.
1070 @param xsrcMask
1071 Source x position on the mask. If both xsrcMask and ysrcMask are
1072 -1, xsrc and ysrc will be assumed for the mask source position.
1073 Currently only implemented on Windows.
1074 @param ysrcMask
1075 Source y position on the mask. If both xsrcMask and ysrcMask are
1076 -1, xsrc and ysrc will be assumed for the mask source position.
1077 Currently only implemented on Windows.
1078
1079 There is partial support for Blit() in wxPostScriptDC, under X.
1080
1081 StretchBlit() is only implemented under wxMAC and wxMSW.
1082
1083 See wxMemoryDC for typical usage.
1084
1085 @since 2.9.0
1086
1087 @see Blit(), wxMemoryDC, wxBitmap, wxMask
1088 */
1089 bool StretchBlit(wxCoord xdest, wxCoord ydest,
1090 wxCoord dstWidth, wxCoord dstHeight,
1091 wxDC* source, wxCoord xsrc, wxCoord ysrc,
1092 wxCoord srcWidth, wxCoord srcHeight,
1093 int logicalFunc = wxCOPY,
1094 bool useMask = false,
1095 wxCoord xsrcMask = -1, wxCoord ysrcMask = -1);
1096 };
1097
1098
1099
1100 /**
1101 @class wxDCClipper
1102
1103 wxDCClipper is a small helper class for setting a clipping region on a wxDC
1104 and unsetting it automatically. An object of wxDCClipper class is typically
1105 created on the stack so that it is automatically destroyed when the object
1106 goes out of scope. A typical usage example:
1107
1108 @code
1109 void MyFunction(wxDC& dc)
1110 {
1111 wxDCClipper clip(dc, rect);
1112 // ... drawing functions here are affected by clipping rect ...
1113 }
1114
1115 void OtherFunction()
1116 {
1117 wxDC dc;
1118 MyFunction(dc);
1119 // ... drawing functions here are not affected by clipping rect ...
1120 }
1121 @endcode
1122
1123 @library{wxcore}
1124 @category{gdi}
1125
1126 @see wxDC::SetClippingRegion()
1127 */
1128 class wxDCClipper
1129 {
1130 public:
1131 //@{
1132 /**
1133 Sets the clipping region to the specified region/coordinates.
1134
1135 The clipping region is automatically unset when this object is destroyed.
1136 */
1137 wxDCClipper(wxDC& dc, const wxRegion& r);
1138 wxDCClipper(wxDC& dc, const wxRect& rect);
1139 wxDCClipper(wxDC& dc, int x, int y, int w, int h);
1140 //@}
1141 };
1142