]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/dc.h
fix GetTextExtent with non-null font argument, fixes #13750
[wxWidgets.git] / interface / wx / dc.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: dc.h
e54c96f1 3// Purpose: interface of wxDC
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
526954c5 6// Licence: wxWindows licence
23324ae1
FM
7/////////////////////////////////////////////////////////////////////////////
8
97929f6b
FM
9
10/**
11 Logical raster operations which can be used with wxDC::SetLogicalFunction
12 and some other wxDC functions (e.g. wxDC::Blit and wxDC::StretchBlit).
13
14 The description of the values below refer to how a generic @e src source pixel
15 and the corresponding @e dst destination pixel gets combined together to produce
16 the final pixel. E.g. @c wxCLEAR and @c wxSET completely ignore the source
17 and the destination pixel and always put zeroes or ones in the final surface.
18*/
19enum wxRasterOperationMode
20{
21 wxCLEAR, //!< 0
22 wxXOR, //!< @e src XOR @e dst
23 wxINVERT, //!< NOT @e dst
24 wxOR_REVERSE, //!< @e src OR (NOT @e dst)
25 wxAND_REVERSE, //!< @e src AND (NOT @e dst)
26 wxCOPY, //!< @e src
27 wxAND, //!< @e src AND @e dst
28 wxAND_INVERT, //!< (NOT @e src) AND @e dst
29 wxNO_OP, //!< @e dst
30 wxNOR, //!< (NOT @e src) AND (NOT @e dst)
31 wxEQUIV, //!< (NOT @e src) XOR @e dst
32 wxSRC_INVERT, //!< (NOT @e src)
33 wxOR_INVERT, //!< (NOT @e src) OR @e dst
34 wxNAND, //!< (NOT @e src) OR (NOT @e dst)
35 wxOR, //!< @e src OR @e dst
36 wxSET //!< 1
37};
38
39/**
40 Flood styles used by wxDC::FloodFill.
41*/
42enum wxFloodFillStyle
43{
44 /** The flooding occurs until a colour other than the given colour is encountered. */
45 wxFLOOD_SURFACE = 1,
46
47 /** The area to be flooded is bounded by the given colour. */
48 wxFLOOD_BORDER
49};
50
51/**
e65a6cc1
FM
52 The mapping used to transform @e logical units to @e device units.
53 See wxDC::SetMapMode.
97929f6b
FM
54*/
55enum wxMappingMode
56{
e65a6cc1
FM
57 /**
58 Each logical unit is 1 device pixel.
59 This is the default mapping mode for all wxDC-derived classes.
60 */
97929f6b
FM
61 wxMM_TEXT = 1,
62
e65a6cc1
FM
63 /** Each logical unit is 1 millimeter. */
64 wxMM_METRIC,
97929f6b 65
e65a6cc1
FM
66 /** Each logical unit is 1/10 of a millimeter. */
67 wxMM_LOMETRIC,
97929f6b 68
e65a6cc1
FM
69 /**
70 Each logical unit is 1/20 of a @e "printer point", or 1/1440 of an inch
71 (also known as "twip"). Equivalent to about 17.64 micrometers.
72 */
97929f6b
FM
73 wxMM_TWIPS,
74
e65a6cc1
FM
75 /**
76 Each logical unit is a @e "printer point" i.e. 1/72 of an inch.
77 Equivalent to about 353 micrometers.
78 */
79 wxMM_POINTS
80};
97929f6b 81
e29bf4b0
VZ
82/**
83 Simple collection of various font metrics.
84
85 This object is returned by wxDC::GetFontMetrics().
86
87 @since 2.9.2
88
89 @library{wxcore}
90 @category{dc,gdi}
91 */
92struct wxFontMetrics
93{
94 /// Constructor initializes all fields to 0.
95 wxFontMetrics();
96
97 int height, ///< Total character height.
98 ascent, ///< Part of the height above the baseline.
99 descent, ///< Part of the height below the baseline.
100 internalLeading, ///< Intra-line spacing.
101 externalLeading, ///< Inter-line spacing.
102 averageWidth; ///< Average font width, a.k.a. "x-width".
103};
97929f6b 104
97929f6b 105
23324ae1
FM
106/**
107 @class wxDC
7c913512 108
f09b5681 109 A wxDC is a @e "device context" onto which graphics and text can be drawn.
318b0bd5
RR
110 It is intended to represent different output devices and offers a common
111 abstract API for drawing on any of them.
edc51344 112
318b0bd5 113 wxWidgets offers an alternative drawing API based on the modern drawing
12133c3b 114 backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer
6d99a337 115 and related classes. There is also a wxGCDC linking the APIs by offering
403695b3 116 the wxDC API on top of a wxGraphicsContext.
7c913512 117
318b0bd5
RR
118 wxDC is an abstract base class and cannot be created directly.
119 Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or
edc51344
VZ
120 wxPrinterDC. Notice that device contexts which are associated with windows
121 (i.e. wxClientDC, wxWindowDC and wxPaintDC) use the window font and colours
122 by default (starting with wxWidgets 2.9.0) but the other device context
123 classes use system-default values so you always must set the appropriate
124 fonts and colours before using them.
f09b5681 125
318b0bd5
RR
126 In addition to the versions of the methods documented below, there
127 are also versions which accept single wxPoint parameter instead
128 of the two wxCoord ones or wxPoint and wxSize instead of the four
129 wxCoord parameters.
f09b5681 130
318b0bd5
RR
131 Beginning with wxWidgets 2.9.0 the entire wxDC code has been
132 reorganized. All platform dependent code (actually all drawing code)
133 has been moved into backend classes which derive from a common
134 wxDCImpl class. The user-visible classes such as wxClientDC and
135 wxPaintDC merely forward all calls to the backend implementation.
f09b5681 136
e65a6cc1
FM
137
138 @section dc_units Device and logical units
139
140 In the wxDC context there is a distinction between @e logical units and @e device units.
141
142 @b Device units are the units native to the particular device; e.g. for a screen,
143 a device unit is a @e pixel. For a printer, the device unit is defined by the
144 resolution of the printer (usually given in @c DPI: dot-per-inch).
145
4c51a665 146 All wxDC functions use instead @b logical units, unless where explicitly
e65a6cc1
FM
147 stated. Logical units are arbitrary units mapped to device units using
148 the current mapping mode (see wxDC::SetMapMode).
149
150 This mechanism allows to reuse the same code which prints on e.g. a window
151 on the screen to print on e.g. a paper.
152
153
e3995493
FM
154 @section dc_alpha_support Support for Transparency / Alpha Channel
155
403695b3
VZ
156 In general wxDC methods don't support alpha transparency and the alpha
157 component of wxColour is simply ignored and you need to use wxGraphicsContext
158 for full transparency support. There are, however, a few exceptions: first,
159 under Mac OS X colours with alpha channel are supported in all the normal
160 wxDC-derived classes as they use wxGraphicsContext internally. Second,
161 under all platforms wxSVGFileDC also fully supports alpha channel. In both
162 of these cases the instances of wxPen or wxBrush that are built from
163 wxColour use the colour's alpha values when stroking or filling.
e3995493
FM
164
165
e71508e1
VZ
166 @section Support for Transformation Matrix
167
168 On some platforms (currently only under MSW and only on Windows NT, i.e.
169 not Windows 9x/ME, systems) wxDC has support for applying an arbitrary
170 affine transformation matrix to its coordinate system. Call
171 CanUseTransformMatrix() to check if this support is available and then call
172 SetTransformMatrix() if it is. If the transformation matrix is not
173 supported, SetTransformMatrix() always simply returns false and doesn't do
174 anything.
175
176
23324ae1 177 @library{wxcore}
c0cc7004 178 @category{dc,gdi}
7c913512 179
382f12e4
FM
180 @see @ref overview_dc, wxGraphicsContext, wxDCFontChanger, wxDCTextColourChanger,
181 wxDCPenChanger, wxDCBrushChanger, wxDCClipper
f09b5681
BP
182
183 @todo Precise definition of default/initial state.
184 @todo Pixelwise definition of operations (e.g. last point of a line not
185 drawn).
23324ae1
FM
186*/
187class wxDC : public wxObject
188{
189public:
190 /**
e3995493 191 @name Coordinate conversion functions
23324ae1 192 */
e3995493 193 //@{
23324ae1
FM
194
195 /**
e3995493
FM
196 Convert @e device X coordinate to logical coordinate, using the current
197 mapping mode, user scale factor, device origin and axis orientation.
23324ae1 198 */
e3995493 199 wxCoord DeviceToLogicalX(wxCoord x) const;
23324ae1
FM
200
201 /**
e3995493
FM
202 Convert @e device X coordinate to relative logical coordinate, using the
203 current mapping mode and user scale factor but ignoring the
204 axis orientation. Use this for converting a width, for example.
23324ae1 205 */
e3995493 206 wxCoord DeviceToLogicalXRel(wxCoord x) const;
23324ae1 207
23324ae1 208 /**
e3995493
FM
209 Converts @e device Y coordinate to logical coordinate, using the current
210 mapping mode, user scale factor, device origin and axis orientation.
23324ae1 211 */
e3995493 212 wxCoord DeviceToLogicalY(wxCoord y) const;
23324ae1
FM
213
214 /**
e3995493
FM
215 Convert @e device Y coordinate to relative logical coordinate, using the
216 current mapping mode and user scale factor but ignoring the
217 axis orientation. Use this for converting a height, for example.
23324ae1 218 */
e3995493 219 wxCoord DeviceToLogicalYRel(wxCoord y) const;
23324ae1
FM
220
221 /**
e3995493 222 Converts logical X coordinate to device coordinate, using the current
63408203 223 mapping mode, user scale factor, device origin and axis orientation.
23324ae1 224 */
e3995493 225 wxCoord LogicalToDeviceX(wxCoord x) const;
23324ae1
FM
226
227 /**
e3995493 228 Converts logical X coordinate to relative device coordinate, using the
63408203
VZ
229 current mapping mode and user scale factor but ignoring the
230 axis orientation. Use this for converting a width, for example.
23324ae1 231 */
e3995493 232 wxCoord LogicalToDeviceXRel(wxCoord x) const;
23324ae1
FM
233
234 /**
e3995493 235 Converts logical Y coordinate to device coordinate, using the current
63408203 236 mapping mode, user scale factor, device origin and axis orientation.
23324ae1 237 */
e3995493 238 wxCoord LogicalToDeviceY(wxCoord y) const;
23324ae1
FM
239
240 /**
e3995493 241 Converts logical Y coordinate to relative device coordinate, using the
63408203
VZ
242 current mapping mode and user scale factor but ignoring the
243 axis orientation. Use this for converting a height, for example.
23324ae1 244 */
e3995493
FM
245 wxCoord LogicalToDeviceYRel(wxCoord y) const;
246
247 //@}
248
249
250
251 /**
252 @name Drawing functions
253 */
254 //@{
255
256 /**
257 Clears the device context using the current background brush.
258 */
259 void Clear();
23324ae1
FM
260
261 /**
f09b5681 262 Draws an arc of a circle, centred on (@a xc, @a yc), with starting
12194090
FM
263 point (@a xStart, @a yStart) and ending at (@a xEnd, @a yEnd).
264 The current pen is used for the outline and the current brush for
265 filling the shape.
f09b5681
BP
266
267 The arc is drawn in a counter-clockwise direction from the start point
268 to the end point.
23324ae1 269 */
12194090 270 void DrawArc(wxCoord xStart, wxCoord yStart, wxCoord xEnd, wxCoord yEnd,
e3995493 271 wxCoord xc, wxCoord yc);
23324ae1 272
83b4d26c
VZ
273 /**
274 @overload
275 */
12194090 276 void DrawArc(const wxPoint& ptStart, const wxPoint& ptEnd, const wxPoint& centre);
83b4d26c 277
23324ae1 278 /**
f09b5681
BP
279 Draw a bitmap on the device context at the specified point. If
280 @a transparent is @true and the bitmap has a transparency mask, the
281 bitmap will be drawn transparently.
282
283 When drawing a mono-bitmap, the current text foreground colour will be
284 used to draw the foreground of the bitmap (all bits set to 1), and the
285 current text background colour to draw the background (all bits set to
286 0).
287
288 @see SetTextForeground(), SetTextBackground(), wxMemoryDC
23324ae1
FM
289 */
290 void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y,
408776d0 291 bool useMask = false);
23324ae1 292
83b4d26c
VZ
293 /**
294 @overload
295 */
296 void DrawBitmap(const wxBitmap &bmp, const wxPoint& pt,
297 bool useMask = false);
298
23324ae1
FM
299 /**
300 Draws a check mark inside the given rectangle.
301 */
f09b5681 302 void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
e3995493
FM
303
304 /**
305 @overload
306 */
4cc4bfaf 307 void DrawCheckMark(const wxRect& rect);
23324ae1 308
23324ae1
FM
309 /**
310 Draws a circle with the given centre and radius.
3c4f71cc 311
4cc4bfaf 312 @see DrawEllipse()
23324ae1
FM
313 */
314 void DrawCircle(wxCoord x, wxCoord y, wxCoord radius);
e3995493
FM
315
316 /**
317 @overload
318 */
7c913512 319 void DrawCircle(const wxPoint& pt, wxCoord radius);
23324ae1 320
23324ae1 321 /**
f09b5681
BP
322 Draws an ellipse contained in the rectangle specified either with the
323 given top left corner and the given size or directly. The current pen
324 is used for the outline and the current brush for filling the shape.
3c4f71cc 325
4cc4bfaf 326 @see DrawCircle()
23324ae1 327 */
f09b5681 328 void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
e3995493
FM
329
330 /**
331 @overload
332 */
7c913512 333 void DrawEllipse(const wxPoint& pt, const wxSize& size);
e3995493
FM
334
335 /**
336 @overload
337 */
7c913512 338 void DrawEllipse(const wxRect& rect);
23324ae1
FM
339
340 /**
f09b5681
BP
341 Draws an arc of an ellipse. The current pen is used for drawing the arc
342 and the current brush is used for drawing the pie.
343
344 @a x and @a y specify the x and y coordinates of the upper-left corner
345 of the rectangle that contains the ellipse.
346
347 @a width and @a height specify the width and height of the rectangle
348 that contains the ellipse.
349
350 @a start and @a end specify the start and end of the arc relative to
351 the three-o'clock position from the center of the rectangle. Angles are
352 specified in degrees (360 is a complete circle). Positive values mean
353 counter-clockwise motion. If @a start is equal to @e end, a complete
354 ellipse will be drawn.
23324ae1 355 */
f09b5681
BP
356 void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height,
357 double start, double end);
23324ae1 358
83b4d26c
VZ
359 /**
360 @overload
361 */
362 void DrawEllipticArc(const wxPoint& pt, const wxSize& sz,
363 double sa, double ea);
364
23324ae1 365 /**
f09b5681
BP
366 Draw an icon on the display (does nothing if the device context is
367 PostScript). This can be the simplest way of drawing bitmaps on a
368 window.
23324ae1
FM
369 */
370 void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);
371
83b4d26c
VZ
372 /**
373 @overload
374 */
375 void DrawIcon(const wxIcon& icon, const wxPoint& pt);
376
23324ae1 377 /**
f09b5681
BP
378 Draw optional bitmap and the text into the given rectangle and aligns
379 it as specified by alignment parameter; it also will emphasize the
380 character with the given index if it is != -1 and return the bounding
381 rectangle if required.
23324ae1 382 */
9a077460 383 void DrawLabel(const wxString& text, const wxBitmap& bitmap,
882678eb
FM
384 const wxRect& rect,
385 int alignment = wxALIGN_LEFT | wxALIGN_TOP,
386 int indexAccel = -1, wxRect* rectBounding = NULL);
e3995493
FM
387
388 /**
389 @overload
390 */
7c913512
FM
391 void DrawLabel(const wxString& text, const wxRect& rect,
392 int alignment = wxALIGN_LEFT | wxALIGN_TOP,
393 int indexAccel = -1);
23324ae1
FM
394
395 /**
f09b5681
BP
396 Draws a line from the first point to the second. The current pen is
397 used for drawing the line. Note that the point (@a x2, @a y2) is not
398 part of the line and is not drawn by this function (this is consistent
399 with the behaviour of many other toolkits).
23324ae1
FM
400 */
401 void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
402
83b4d26c
VZ
403 /**
404 @overload
405 */
406 void DrawLine(const wxPoint& pt1, const wxPoint& pt2);
407
23324ae1 408 /**
f09b5681
BP
409 Draws lines using an array of points of size @a n adding the optional
410 offset coordinate. The current pen is used for drawing the lines.
411
412 @beginWxPythonOnly
413 The wxPython version of this method accepts a Python list of wxPoint
414 objects.
415 @endWxPythonOnly
1058f652
MB
416
417 @beginWxPerlOnly
418 Not supported by wxPerl.
419 @endWxPerlOnly
23324ae1
FM
420 */
421 void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0,
422 wxCoord yoffset = 0);
f09b5681
BP
423 /**
424 This method uses a list of wxPoints, adding the optional offset
425 coordinate. The programmer is responsible for deleting the list of
426 points.
427
428 @beginWxPythonOnly
429 The wxPython version of this method accepts a Python list of wxPoint
430 objects.
431 @endWxPythonOnly
1058f652
MB
432
433 @beginWxPerlOnly
434 The wxPerl version of this method accepts
435 as its first parameter a reference to an array
436 of wxPoint objects.
437 @endWxPerlOnly
f09b5681 438 */
4cc4bfaf 439 void DrawLines(const wxPointList* points,
f09b5681 440 wxCoord xoffset = 0, wxCoord yoffset = 0);
23324ae1
FM
441
442 /**
443 Draws a point using the color of the current pen. Note that the other
f09b5681 444 properties of the pen are not used, such as width.
23324ae1
FM
445 */
446 void DrawPoint(wxCoord x, wxCoord y);
447
83b4d26c
VZ
448 /**
449 @overload
450 */
451 void DrawPoint(const wxPoint& pt);
452
23324ae1 453 /**
f09b5681
BP
454 Draws a filled polygon using an array of points of size @a n, adding
455 the optional offset coordinate. The first and last points are
456 automatically closed.
23324ae1 457
f09b5681
BP
458 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
459 default) or @b wxWINDING_RULE.
460
461 The current pen is used for drawing the outline, and the current brush
462 for filling the shape. Using a transparent brush suppresses filling.
1058f652
MB
463
464 @beginWxPerlOnly
465 Not supported by wxPerl.
466 @endWxPerlOnly
f09b5681
BP
467 */
468 void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0,
89efaf2b
FM
469 wxCoord yoffset = 0,
470 wxPolygonFillMode fill_style = wxODDEVEN_RULE);
23324ae1 471 /**
f09b5681
BP
472 This method draws a filled polygon using a list of wxPoints, adding the
473 optional offset coordinate. The first and last points are automatically
474 closed.
475
23324ae1
FM
476 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
477 default) or @b wxWINDING_RULE.
f09b5681 478
23324ae1 479 The current pen is used for drawing the outline, and the current brush
f09b5681
BP
480 for filling the shape. Using a transparent brush suppresses filling.
481
23324ae1 482 The programmer is responsible for deleting the list of points.
f09b5681
BP
483
484 @beginWxPythonOnly
485 The wxPython version of this method accepts a Python list of wxPoint
486 objects.
487 @endWxPythonOnly
1058f652
MB
488
489 @beginWxPerlOnly
490 The wxPerl version of this method accepts
491 as its first parameter a reference to an array
492 of wxPoint objects.
493 @endWxPerlOnly
23324ae1 494 */
4cc4bfaf 495 void DrawPolygon(const wxPointList* points,
f09b5681 496 wxCoord xoffset = 0, wxCoord yoffset = 0,
89efaf2b 497 wxPolygonFillMode fill_style = wxODDEVEN_RULE);
f09b5681
BP
498
499 /**
500 Draws two or more filled polygons using an array of @a points, adding
501 the optional offset coordinates.
502
503 Notice that for the platforms providing a native implementation of this
504 function (Windows and PostScript-based wxDC currently), this is more
505 efficient than using DrawPolygon() in a loop.
506
507 @a n specifies the number of polygons to draw, the array @e count of
508 size @a n specifies the number of points in each of the polygons in the
509 @a points array.
510
511 The last argument specifies the fill rule: @b wxODDEVEN_RULE (the
512 default) or @b wxWINDING_RULE.
513
514 The current pen is used for drawing the outline, and the current brush
515 for filling the shape. Using a transparent brush suppresses filling.
516
517 The polygons maybe disjoint or overlapping. Each polygon specified in a
518 call to DrawPolyPolygon() must be closed. Unlike polygons created by
519 the DrawPolygon() member function, the polygons created by this
520 method are not closed automatically.
521
522 @beginWxPythonOnly
523 Not implemented yet.
524 @endWxPythonOnly
525 */
526 void DrawPolyPolygon(int n, int count[], wxPoint points[],
527 wxCoord xoffset = 0, wxCoord yoffset = 0,
89efaf2b 528 wxPolygonFillMode fill_style = wxODDEVEN_RULE);
23324ae1
FM
529
530 /**
531 Draws a rectangle with the given top left corner, and with the given
532 size. The current pen is used for the outline and the current brush
533 for filling the shape.
534 */
f09b5681 535 void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
23324ae1 536
83b4d26c
VZ
537 /**
538 @overload
539 */
540 void DrawRectangle(const wxPoint& pt, const wxSize& sz);
541
542 /**
543 @overload
544 */
545 void DrawRectangle(const wxRect& rect);
546
23324ae1 547 /**
aff647c1
FM
548 Draws the text rotated by @a angle degrees
549 (positive angles are counterclockwise; the full angle is 360 degrees).
f09b5681 550
1f1d2182 551 @note Under Win9x only TrueType fonts can be drawn by this function. In
f09b5681
BP
552 particular, a font different from @c wxNORMAL_FONT should be used
553 as the latter is not a TrueType font. @c wxSWISS_FONT is an
554 example of a font which is.
3c4f71cc 555
4cc4bfaf 556 @see DrawText()
23324ae1
FM
557 */
558 void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y,
559 double angle);
560
83b4d26c
VZ
561 /**
562 @overload
563 */
8ff9b17d 564 void DrawRotatedText(const wxString& text, const wxPoint& point,
83b4d26c
VZ
565 double angle);
566
23324ae1
FM
567 /**
568 Draws a rectangle with the given top left corner, and with the given
f09b5681 569 size. The corners are quarter-circles using the given radius. The
23324ae1
FM
570 current pen is used for the outline and the current brush for filling
571 the shape.
f09b5681
BP
572
573 If @a radius is positive, the value is assumed to be the radius of the
574 rounded corner. If @a radius is negative, the absolute value is assumed
575 to be the @e proportion of the smallest dimension of the rectangle.
576 This means that the corner can be a sensible size relative to the size
577 of the rectangle, and also avoids the strange effects X produces when
578 the corners are too big for the rectangle.
23324ae1
FM
579 */
580 void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width,
f09b5681 581 wxCoord height, double radius);
23324ae1 582
83b4d26c
VZ
583 /**
584 @overload
585 */
586 void DrawRoundedRectangle(const wxPoint& pt, const wxSize& sz,
587 double radius);
588
589 /**
590 @overload
591 */
592 void DrawRoundedRectangle(const wxRect& rect, double radius);
593
23324ae1 594 /**
f09b5681
BP
595 Draws a spline between all given points using the current pen.
596
597 @beginWxPythonOnly
598 The wxPython version of this method accepts a Python list of wxPoint
599 objects.
600 @endWxPythonOnly
1058f652
MB
601
602 @beginWxPerlOnly
603 Not supported by wxPerl.
604 @endWxPerlOnly
23324ae1
FM
605 */
606 void DrawSpline(int n, wxPoint points[]);
e3995493
FM
607
608 /**
609 @overload
1058f652
MB
610
611
612 @beginWxPerlOnly
613 The wxPerl version of this method accepts
614 as its first parameter a reference to an array
615 of wxPoint objects.
616 @endWxPerlOnly
e3995493 617 */
4cc4bfaf 618 void DrawSpline(const wxPointList* points);
e3995493
FM
619
620 /**
621 @overload
1058f652
MB
622
623
624 @beginWxPerlOnly
625 Not supported by wxPerl.
626 @endWxPerlOnly
e3995493 627 */
f09b5681
BP
628 void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
629 wxCoord x3, wxCoord y3);
23324ae1
FM
630
631 /**
f09b5681
BP
632 Draws a text string at the specified point, using the current text
633 font, and the current text foreground and background colours.
634
23324ae1 635 The coordinates refer to the top-left corner of the rectangle bounding
f09b5681 636 the string. See GetTextExtent() for how to get the dimensions of a text
a5bb4514
VZ
637 string, which can be used to position the text more precisely and
638 DrawLabel() if you need to align the string differently.
639
640 Starting from wxWidgets 2.9.2 @a text parameter can be a multi-line
641 string, i.e. contain new line characters, and will be rendered
642 correctly.
f09b5681 643
408776d0 644 @note The current @ref GetLogicalFunction() "logical function" is
e928566f 645 ignored by this function.
23324ae1
FM
646 */
647 void DrawText(const wxString& text, wxCoord x, wxCoord y);
648
83b4d26c
VZ
649 /**
650 @overload
651 */
652 void DrawText(const wxString& text, const wxPoint& pt);
653
23324ae1 654 /**
e3995493
FM
655 Fill the area specified by rect with a radial gradient, starting from
656 @a initialColour at the centre of the circle and fading to
657 @a destColour on the circle outside.
658
659 The circle is placed at the centre of @a rect.
660
661 @note Currently this function is very slow, don't use it for real-time
662 drawing.
23324ae1 663 */
e3995493
FM
664 void GradientFillConcentric(const wxRect& rect,
665 const wxColour& initialColour,
666 const wxColour& destColour);
23324ae1
FM
667
668 /**
e3995493
FM
669 Fill the area specified by rect with a radial gradient, starting from
670 @a initialColour at the centre of the circle and fading to
671 @a destColour on the circle outside.
672
673 @a circleCenter are the relative coordinates of centre of the circle in
674 the specified @a rect.
675
676 @note Currently this function is very slow, don't use it for real-time
677 drawing.
23324ae1 678 */
e3995493
FM
679 void GradientFillConcentric(const wxRect& rect,
680 const wxColour& initialColour,
681 const wxColour& destColour,
682 const wxPoint& circleCenter);
683
684 /**
685 Fill the area specified by @a rect with a linear gradient, starting
686 from @a initialColour and eventually fading to @e destColour.
687
688 The @a nDirection specifies the direction of the colour change, default is
689 to use @a initialColour on the left part of the rectangle and
690 @a destColour on the right one.
691 */
692 void GradientFillLinear(const wxRect& rect, const wxColour& initialColour,
693 const wxColour& destColour,
694 wxDirection nDirection = wxRIGHT);
23324ae1
FM
695
696 /**
697 Flood fills the device context starting from the given point, using
f09b5681
BP
698 the current brush colour, and using a style:
699
700 - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
701 given colour is encountered.
702 - wxFLOOD_BORDER: The area to be flooded is bounded by the given
703 colour.
704
d29a9a8a 705 @return @false if the operation failed.
f09b5681
BP
706
707 @note The present implementation for non-Windows platforms may fail to
708 find colour borders if the pixels do not match the colour
709 exactly. However the function will still return @true.
23324ae1
FM
710 */
711 bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
89efaf2b 712 wxFloodFillStyle style = wxFLOOD_SURFACE);
23324ae1 713
83b4d26c
VZ
714 /**
715 @overload
716 */
717 bool FloodFill(const wxPoint& pt, const wxColour& col,
8ff9b17d 718 wxFloodFillStyle style = wxFLOOD_SURFACE);
83b4d26c 719
23324ae1 720 /**
e3995493
FM
721 Displays a cross hair using the current pen. This is a vertical and
722 horizontal line the height and width of the window, centred on the
723 given point.
23324ae1 724 */
e3995493 725 void CrossHair(wxCoord x, wxCoord y);
23324ae1 726
83b4d26c
VZ
727 /**
728 @overload
729 */
730 void CrossHair(const wxPoint& pt);
731
e3995493 732 //@}
3c4f71cc 733
23324ae1
FM
734
735 /**
e3995493 736 @name Clipping region functions
23324ae1 737 */
e3995493 738 //@{
23324ae1
FM
739
740 /**
e3995493 741 Destroys the current clipping region so that none of the DC is clipped.
23324ae1 742
e3995493 743 @see SetClippingRegion()
23324ae1 744 */
e3995493 745 void DestroyClippingRegion();
23324ae1
FM
746
747 /**
748 Gets the rectangle surrounding the current clipping region.
f09b5681
BP
749
750 @beginWxPythonOnly
751 No arguments are required and the four values defining the rectangle
752 are returned as a tuple.
753 @endWxPythonOnly
23324ae1 754 */
408776d0 755 void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const;
23324ae1
FM
756
757 /**
e3995493
FM
758 Sets the clipping region for this device context to the intersection of
759 the given region described by the parameters of this method and the
3821ccfa 760 previously set clipping region.
3c4f71cc 761
e3995493
FM
762 The clipping region is an area to which drawing is restricted. Possible
763 uses for the clipping region are for clipping text or for speeding up
764 window redraws when only a known area of the screen is damaged.
23324ae1 765
3821ccfa
VZ
766 Notice that you need to call DestroyClippingRegion() if you want to set
767 the clipping region exactly to the region specified.
768
769 Also note that if the clipping region is empty, any previously set
770 clipping region is destroyed, i.e. it is equivalent to calling
771 DestroyClippingRegion(), and not to clipping out all drawing on the DC
772 as might be expected.
773
e3995493 774 @see DestroyClippingRegion(), wxRegion
23324ae1 775 */
e3995493 776 void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
23324ae1
FM
777
778 /**
e3995493 779 @overload
23324ae1 780 */
e3995493 781 void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
23324ae1
FM
782
783 /**
e3995493 784 @overload
23324ae1 785 */
e3995493 786 void SetClippingRegion(const wxRect& rect);
23324ae1
FM
787
788 /**
e3995493 789 Sets the clipping region for this device context.
f09b5681 790
e3995493
FM
791 Unlike SetClippingRegion(), this function works with physical
792 coordinates and not with the logical ones.
793 */
794 void SetDeviceClippingRegion(const wxRegion& region);
795
796 //@}
797
798
799 /**
800 @name Text/character extent functions
23324ae1 801 */
e3995493
FM
802 //@{
803
804 /**
805 Gets the character height of the currently set font.
806 */
807 wxCoord GetCharHeight() const;
808
809 /**
810 Gets the average character width of the currently set font.
811 */
812 wxCoord GetCharWidth() const;
23324ae1 813
e29bf4b0
VZ
814 /**
815 Returns the various font characteristics.
816
817 This method allows to retrieve some of the font characteristics not
818 returned by GetTextExtent(), notably internal leading and average
819 character width.
820
821 Currently this method returns correct results only under wxMSW, in the
822 other ports the internal leading will always be 0 and the average
823 character width will be computed as the width of the character 'x'.
824
825 @since 2.9.2
826 */
827 wxFontMetrics GetFontMetrics() const;
828
23324ae1
FM
829 /**
830 Gets the dimensions of the string using the currently selected font.
4cc4bfaf 831 @a string is the text string to measure, @e heightLine, if non @NULL,
23324ae1 832 is where to store the height of a single line.
f09b5681
BP
833
834 The text extent is set in the given @a w and @a h pointers.
835
836 If the optional parameter @a font is specified and valid, then it is
837 used for the text extent calculation, otherwise the currently selected
838 font is used.
839
840 @note This function works with both single-line and multi-line strings.
3c4f71cc 841
1058f652
MB
842 @beginWxPerlOnly
843 In wxPerl this method is implemented as
844 GetMultiLineTextExtent(string, font = undef) returning a
845 3-element list (width, height, line_height)
846 @endWxPerlOnly
847
4cc4bfaf 848 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
23324ae1 849 */
4cc4bfaf
FM
850 void GetMultiLineTextExtent(const wxString& string, wxCoord* w,
851 wxCoord* h,
852 wxCoord* heightLine = NULL,
408776d0 853 const wxFont* font = NULL) const;
23324ae1 854 /**
f09b5681
BP
855 Gets the dimensions of the string using the currently selected font.
856 @a string is the text string to measure, @e heightLine, if non @NULL,
857 is where to store the height of a single line.
858
d29a9a8a 859 @return The text extent as a wxSize object.
f09b5681
BP
860
861 @note This function works with both single-line and multi-line strings.
862
1058f652
MB
863 @beginWxPerlOnly
864 Not supported by wxPerl.
865 @endWxPerlOnly
866
f09b5681 867 @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
23324ae1 868 */
408776d0 869 wxSize GetMultiLineTextExtent(const wxString& string) const;
23324ae1
FM
870
871 /**
f09b5681
BP
872 Fills the @a widths array with the widths from the beginning of @a text
873 to the corresponding character of @a text. The generic version simply
874 builds a running total of the widths of each character using
875 GetTextExtent(), however if the various platforms have a native API
876 function that is faster or more accurate than the generic
877 implementation then it should be used instead.
878
879 @beginWxPythonOnly
880 This method only takes the @a text parameter and returns a Python list
881 of integers.
882 @endWxPythonOnly
3c4f71cc 883
1058f652
MB
884 @beginWxPerlOnly
885 In wxPerl this method only takes the @a text parameter and
886 returns the widths as a list of integers.
887 @endWxPerlOnly
888
4cc4bfaf 889 @see GetMultiLineTextExtent(), GetTextExtent()
23324ae1
FM
890 */
891 bool GetPartialTextExtents(const wxString& text,
328f5751 892 wxArrayInt& widths) const;
23324ae1 893
23324ae1
FM
894 /**
895 Gets the dimensions of the string using the currently selected font.
f09b5681
BP
896 @a string is the text string to measure, @a descent is the dimension
897 from the baseline of the font to the bottom of the descender, and
898 @a externalLeading is any extra vertical space added to the font by the
899 font designer (usually is zero).
900
901 The text extent is returned in @a w and @a h pointers or as a wxSize
902 object depending on which version of this function is used.
903
904 If the optional parameter @a font is specified and valid, then it is
905 used for the text extent calculation. Otherwise the currently selected
906 font is.
907
908 @note This function only works with single-line strings.
909
910 @beginWxPythonOnly
911 The following methods are implemented in wxPython:
912 - GetTextExtent(string) - Returns a 2-tuple, (width, height).
913 - GetFullTextExtent(string, font=NULL) -
914 Returns a 4-tuple, (width, height, descent, externalLeading).
915 @endWxPythonOnly
3c4f71cc 916
1058f652
MB
917 @beginWxPerlOnly
918 In wxPerl this method is implemented as GetTextExtent(string,
919 font = undef) returning a 4-element list (width, height,
920 descent, externalLeading)
921 @endWxPerlOnly
922
4cc4bfaf
FM
923 @see wxFont, SetFont(), GetPartialTextExtents(),
924 GetMultiLineTextExtent()
925 */
f09b5681 926 void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
4cc4bfaf
FM
927 wxCoord* descent = NULL,
928 wxCoord* externalLeading = NULL,
328f5751 929 const wxFont* font = NULL) const;
e3995493
FM
930
931 /**
932 @overload
1058f652
MB
933
934
935 @beginWxPerlOnly
936 Not supported by wxPerl.
937 @endWxPerlOnly
e3995493 938 */
382f12e4 939 wxSize GetTextExtent(const wxString& string) const;
e3995493 940
23324ae1
FM
941 //@}
942
e3995493 943
23324ae1 944 /**
e3995493
FM
945 @name Text properties functions
946 */
947 //@{
f09b5681 948
e3995493
FM
949 /**
950 Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
951
952 @see SetBackgroundMode()
23324ae1 953 */
e3995493 954 int GetBackgroundMode() const;
23324ae1
FM
955
956 /**
ac55e6b0
FM
957 Gets the current font.
958
959 Notice that even although each device context object has some default font
960 after creation, this method would return a ::wxNullFont initially and only
961 after calling SetFont() a valid font is returned.
e3995493
FM
962 */
963 const wxFont& GetFont() const;
f09b5681 964
e3995493
FM
965 /**
966 Gets the current layout direction of the device context. On platforms
967 where RTL layout is supported, the return value will either be
968 @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
969 not supported, the return value will be @c wxLayout_Default.
970
971 @see SetLayoutDirection()
23324ae1 972 */
e3995493 973 wxLayoutDirection GetLayoutDirection() const;
23324ae1 974
23324ae1 975 /**
e3995493 976 Gets the current text background colour.
f09b5681 977
e3995493
FM
978 @see SetTextBackground()
979 */
980 const wxColour& GetTextBackground() const;
f09b5681 981
e3995493
FM
982 /**
983 Gets the current text foreground colour.
984
985 @see SetTextForeground()
23324ae1 986 */
e3995493 987 const wxColour& GetTextForeground() const;
23324ae1
FM
988
989 /**
ac55e6b0
FM
990 @a mode may be one of @c wxSOLID and @c wxTRANSPARENT.
991
992 This setting determines whether text will be drawn with a background
993 colour or not.
23324ae1 994 */
e3995493 995 void SetBackgroundMode(int mode);
23324ae1
FM
996
997 /**
ac55e6b0
FM
998 Sets the current font for the DC.
999
1000 If the argument is ::wxNullFont (or another invalid font; see wxFont::IsOk),
1001 the current font is selected out of the device context (leaving wxDC without
1002 any valid font), allowing the current font to be destroyed safely.
e3995493
FM
1003
1004 @see wxFont
23324ae1 1005 */
e3995493 1006 void SetFont(const wxFont& font);
23324ae1
FM
1007
1008 /**
e3995493 1009 Sets the current text background colour for the DC.
23324ae1 1010 */
e3995493 1011 void SetTextBackground(const wxColour& colour);
23324ae1
FM
1012
1013 /**
e3995493
FM
1014 Sets the current text foreground colour for the DC.
1015
1016 @see wxMemoryDC for the interpretation of colours when drawing into a
1017 monochrome bitmap.
23324ae1 1018 */
e3995493 1019 void SetTextForeground(const wxColour& colour);
23324ae1
FM
1020
1021 /**
ac55e6b0
FM
1022 Sets the current layout direction for the device context.
1023
1024 @param dir
1025 May be either @c wxLayout_Default, @c wxLayout_LeftToRight or
1026 @c wxLayout_RightToLeft.
e3995493
FM
1027
1028 @see GetLayoutDirection()
23324ae1 1029 */
e3995493
FM
1030 void SetLayoutDirection(wxLayoutDirection dir);
1031
1032 //@}
1033
23324ae1
FM
1034
1035 /**
e3995493 1036 @name Bounding box functions
23324ae1 1037 */
e3995493
FM
1038 //@{
1039
1040 /**
1041 Adds the specified point to the bounding box which can be retrieved
1042 with MinX(), MaxX() and MinY(), MaxY() functions.
1043
1044 @see ResetBoundingBox()
1045 */
1046 void CalcBoundingBox(wxCoord x, wxCoord y);
23324ae1
FM
1047
1048 /**
1049 Gets the maximum horizontal extent used in drawing commands so far.
1050 */
adaaa686 1051 wxCoord MaxX() const;
23324ae1
FM
1052
1053 /**
1054 Gets the maximum vertical extent used in drawing commands so far.
1055 */
adaaa686 1056 wxCoord MaxY() const;
23324ae1
FM
1057
1058 /**
1059 Gets the minimum horizontal extent used in drawing commands so far.
1060 */
adaaa686 1061 wxCoord MinX() const;
23324ae1
FM
1062
1063 /**
1064 Gets the minimum vertical extent used in drawing commands so far.
1065 */
adaaa686 1066 wxCoord MinY() const;
23324ae1
FM
1067
1068 /**
f09b5681
BP
1069 Resets the bounding box: after a call to this function, the bounding
1070 box doesn't contain anything.
3c4f71cc 1071
4cc4bfaf 1072 @see CalcBoundingBox()
23324ae1
FM
1073 */
1074 void ResetBoundingBox();
1075
e3995493 1076 //@}
3c4f71cc 1077
23324ae1
FM
1078
1079 /**
e3995493 1080 @name Page and document start/end functions
23324ae1 1081 */
e3995493 1082 //@{
23324ae1
FM
1083
1084 /**
e3995493
FM
1085 Starts a document (only relevant when outputting to a printer).
1086 @a message is a message to show while printing.
23324ae1 1087 */
e3995493 1088 bool StartDoc(const wxString& message);
23324ae1
FM
1089
1090 /**
e3995493 1091 Starts a document page (only relevant when outputting to a printer).
23324ae1 1092 */
e3995493 1093 void StartPage();
23324ae1 1094
23324ae1 1095 /**
e3995493
FM
1096 Ends a document (only relevant when outputting to a printer).
1097 */
1098 void EndDoc();
3c4f71cc 1099
e3995493
FM
1100 /**
1101 Ends a document page (only relevant when outputting to a printer).
23324ae1 1102 */
e3995493
FM
1103 void EndPage();
1104
23324ae1
FM
1105 //@}
1106
23324ae1
FM
1107
1108 /**
e3995493 1109 @name Bit-Block Transfer operations (blit)
23324ae1 1110 */
e3995493 1111 //@{
23324ae1
FM
1112
1113 /**
e3995493
FM
1114 Copy from a source DC to this DC, specifying the destination
1115 coordinates, size of area to copy, source DC, source coordinates,
1116 logical function, whether to use a bitmap mask, and mask source
1117 position.
23324ae1 1118
e3995493
FM
1119 @param xdest
1120 Destination device context x position.
1121 @param ydest
1122 Destination device context y position.
1123 @param width
1124 Width of source area to be copied.
1125 @param height
1126 Height of source area to be copied.
1127 @param source
1128 Source device context.
1129 @param xsrc
1130 Source device context x position.
1131 @param ysrc
1132 Source device context y position.
1133 @param logicalFunc
1134 Logical function to use, see SetLogicalFunction().
1135 @param useMask
1136 If @true, Blit does a transparent blit using the mask that is
1137 associated with the bitmap selected into the source device context.
1138 The Windows implementation does the following if MaskBlt cannot be
1139 used:
1140 <ol>
1141 <li>Creates a temporary bitmap and copies the destination area into
1142 it.</li>
1143 <li>Copies the source area into the temporary bitmap using the
1144 specified logical function.</li>
1145 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1146 the mask bitmap with the temp bitmap with the foreground colour
1147 set to WHITE and the bg colour set to BLACK.</li>
1148 <li>Sets the unmasked area in the destination area to BLACK by
1149 ANDing the mask bitmap with the destination area with the
1150 foreground colour set to BLACK and the background colour set to
1151 WHITE.</li>
1152 <li>ORs the temporary bitmap with the destination area.</li>
1153 <li>Deletes the temporary bitmap.</li>
1154 </ol>
1155 This sequence of operations ensures that the source's transparent
1156 area need not be black, and logical functions are supported.
1157 @n @b Note: on Windows, blitting with masks can be speeded up
519d7f23 1158 considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
e3995493
FM
1159 enabled. You can also influence whether MaskBlt or the explicit
1160 mask blitting code above is used, by using wxSystemOptions and
1161 setting the @c no-maskblt option to 1.
1162 @param xsrcMask
1163 Source x position on the mask. If both xsrcMask and ysrcMask are
1164 @c -1, xsrc and ysrc will be assumed for the mask source position.
1165 Currently only implemented on Windows.
1166 @param ysrcMask
1167 Source y position on the mask. If both xsrcMask and ysrcMask are
1168 @c -1, xsrc and ysrc will be assumed for the mask source position.
1169 Currently only implemented on Windows.
23324ae1 1170
e3995493 1171 @remarks There is partial support for Blit() in wxPostScriptDC, under X.
23324ae1 1172
e3995493 1173 @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
23324ae1 1174 */
e3995493
FM
1175 bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width,
1176 wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc,
1177 wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false,
1178 wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord);
23324ae1
FM
1179
1180 /**
1181 Copy from a source DC to this DC, specifying the destination
f09b5681
BP
1182 coordinates, destination size, source DC, source coordinates, size of
1183 source area to copy, logical function, whether to use a bitmap mask,
23324ae1 1184 and mask source position.
3c4f71cc 1185
7c913512 1186 @param xdest
4cc4bfaf 1187 Destination device context x position.
7c913512 1188 @param ydest
4cc4bfaf 1189 Destination device context y position.
7c913512 1190 @param dstWidth
4cc4bfaf 1191 Width of destination area.
7c913512 1192 @param dstHeight
4cc4bfaf 1193 Height of destination area.
7c913512 1194 @param source
4cc4bfaf 1195 Source device context.
7c913512 1196 @param xsrc
4cc4bfaf 1197 Source device context x position.
7c913512 1198 @param ysrc
4cc4bfaf 1199 Source device context y position.
7c913512 1200 @param srcWidth
4cc4bfaf 1201 Width of source area to be copied.
7c913512 1202 @param srcHeight
4cc4bfaf 1203 Height of source area to be copied.
7c913512 1204 @param logicalFunc
f09b5681 1205 Logical function to use, see SetLogicalFunction().
7c913512 1206 @param useMask
f09b5681
BP
1207 If @true, Blit does a transparent blit using the mask that is
1208 associated with the bitmap selected into the source device context.
1209 The Windows implementation does the following if MaskBlt cannot be
1210 used:
1211 <ol>
1212 <li>Creates a temporary bitmap and copies the destination area into
1213 it.</li>
1214 <li>Copies the source area into the temporary bitmap using the
1215 specified logical function.</li>
1216 <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
1217 the mask bitmap with the temp bitmap with the foreground colour
1218 set to WHITE and the bg colour set to BLACK.</li>
1219 <li>Sets the unmasked area in the destination area to BLACK by
1220 ANDing the mask bitmap with the destination area with the
1221 foreground colour set to BLACK and the background colour set to
1222 WHITE.</li>
1223 <li>ORs the temporary bitmap with the destination area.</li>
1224 <li>Deletes the temporary bitmap.</li>
1225 </ol>
1226 This sequence of operations ensures that the source's transparent
1227 area need not be black, and logical functions are supported.
1228 @n @b Note: on Windows, blitting with masks can be speeded up
519d7f23 1229 considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
f09b5681
BP
1230 enabled. You can also influence whether MaskBlt or the explicit
1231 mask blitting code above is used, by using wxSystemOptions and
1232 setting the @c no-maskblt option to 1.
7c913512 1233 @param xsrcMask
f09b5681 1234 Source x position on the mask. If both xsrcMask and ysrcMask are
408776d0
FM
1235 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1236 source position. Currently only implemented on Windows.
7c913512 1237 @param ysrcMask
f09b5681 1238 Source y position on the mask. If both xsrcMask and ysrcMask are
408776d0
FM
1239 wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
1240 source position. Currently only implemented on Windows.
f09b5681
BP
1241
1242 There is partial support for Blit() in wxPostScriptDC, under X.
1243
1244 StretchBlit() is only implemented under wxMAC and wxMSW.
1245
1246 See wxMemoryDC for typical usage.
1247
1e24c2af 1248 @since 2.9.0
f09b5681
BP
1249
1250 @see Blit(), wxMemoryDC, wxBitmap, wxMask
1251 */
1252 bool StretchBlit(wxCoord xdest, wxCoord ydest,
1253 wxCoord dstWidth, wxCoord dstHeight,
1254 wxDC* source, wxCoord xsrc, wxCoord ysrc,
1255 wxCoord srcWidth, wxCoord srcHeight,
89efaf2b 1256 wxRasterOperationMode logicalFunc = wxCOPY,
4cc4bfaf 1257 bool useMask = false,
408776d0
FM
1258 wxCoord xsrcMask = wxDefaultCoord,
1259 wxCoord ysrcMask = wxDefaultCoord);
e3995493
FM
1260 //@}
1261
1262
1263 /**
1264 @name Background/foreground brush and pen
1265 */
1266 //@{
1267
1268 /**
1269 Gets the brush used for painting the background.
1270
1271 @see wxDC::SetBackground()
1272 */
1273 const wxBrush& GetBackground() const;
1274
1275 /**
1276 Gets the current brush.
1277
1278 @see wxDC::SetBrush()
1279 */
1280 const wxBrush& GetBrush() const;
1281
1282 /**
1283 Gets the current pen.
1284
1285 @see SetPen()
1286 */
1287 const wxPen& GetPen() const;
1288
1289 /**
1290 Sets the current background brush for the DC.
1291 */
1292 void SetBackground(const wxBrush& brush);
1293
1294 /**
1295 Sets the current brush for the DC.
1296
ac55e6b0
FM
1297 If the argument is ::wxNullBrush (or another invalid brush; see wxBrush::IsOk),
1298 the current brush is selected out of the device context (leaving wxDC without
1299 any valid brush), allowing the current brush to be destroyed safely.
e3995493
FM
1300
1301 @see wxBrush, wxMemoryDC (for the interpretation of colours when
1302 drawing into a monochrome bitmap)
1303 */
1304 void SetBrush(const wxBrush& brush);
1305
1306 /**
ac55e6b0
FM
1307 Sets the current pen for the DC.
1308
1309 If the argument is ::wxNullPen (or another invalid pen; see wxPen::IsOk),
1310 the current pen is selected out of the device context (leaving wxDC without any
1311 valid pen), allowing the current pen to be destroyed safely.
e3995493
FM
1312
1313 @see wxMemoryDC for the interpretation of colours when drawing into a
1314 monochrome bitmap.
1315 */
1316 void SetPen(const wxPen& pen);
1317
1318 //@}
1319
1320
4feecbb9
VZ
1321 /**
1322 Copy attributes from another DC.
1323
1324 The copied attributes currently are:
1325 - Font
1326 - Text foreground and background colours
1327 - Background brush
1328 - Layout direction
1329
1330 @param dc
1331 A valid (i.e. its IsOk() must return @true) source device context.
1332 */
1333 void CopyAttributes(const wxDC& dc);
e3995493
FM
1334
1335 /**
1336 Returns the depth (number of bits/pixel) of this DC.
1337
1338 @see wxDisplayDepth()
1339 */
1340 int GetDepth() const;
1341
1342 /**
1343 Returns the current device origin.
1344
1345 @see SetDeviceOrigin()
1346 */
1347 wxPoint GetDeviceOrigin() const;
1348
1349 /**
1350 Gets the current logical function.
1351
1352 @see SetLogicalFunction()
1353 */
1354 wxRasterOperationMode GetLogicalFunction() const;
1355
1356 /**
1357 Gets the current mapping mode for the device context.
1358
1359 @see SetMapMode()
1360 */
1361 wxMappingMode GetMapMode() const;
1362
1363 /**
1364 Gets in @a colour the colour at the specified location. Not available
1365 for wxPostScriptDC or wxMetafileDC.
1366
1367 @note Setting a pixel can be done using DrawPoint().
1368
1369 @beginWxPythonOnly
1370 The wxColour value is returned and is not required as a parameter.
1371 @endWxPythonOnly
1372 */
1373 bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
1374
1375 /**
1376 Returns the resolution of the device in pixels per inch.
1377 */
1378 wxSize GetPPI() const;
1379
1380 /**
1381 Gets the horizontal and vertical extent of this device context in @e device units.
1382 It can be used to scale graphics to fit the page.
1383
1384 For example, if @e maxX and @e maxY represent the maximum horizontal
1385 and vertical 'pixel' values used in your application, the following
1386 code will scale the graphic to fit on the printer page:
1387
1388 @code
1389 wxCoord w, h;
1390 dc.GetSize(&w, &h);
1391 double scaleX = (double)(maxX / w);
1392 double scaleY = (double)(maxY / h);
1393 dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
1394 @endcode
1395
1396 @beginWxPythonOnly
1397 In place of a single overloaded method name, wxPython implements the
1398 following methods:
1399 - GetSize() - Returns a wxSize.
1400 - GetSizeWH() - Returns a 2-tuple (width, height).
1401 @endWxPythonOnly
1058f652
MB
1402
1403 @beginWxPerlOnly
1404 In wxPerl there are two methods instead of a single overloaded
1405 method:
1406 - GetSize(): returns a Wx::Size object.
1407 - GetSizeWH(): returns a 2-element list (width, height).
1408 @endWxPerlOnly
e3995493
FM
1409 */
1410 void GetSize(wxCoord* width, wxCoord* height) const;
1411
1412 /**
1413 @overload
1414 */
1415 wxSize GetSize() const;
1416
1417 /**
1418 Returns the horizontal and vertical resolution in millimetres.
1419 */
1420 void GetSizeMM(wxCoord* width, wxCoord* height) const;
1421
1422 /**
1423 @overload
1424 */
1425 wxSize GetSizeMM() const;
1426
1427 /**
1428 Gets the current user scale factor.
1429
1058f652
MB
1430 @beginWxPerlOnly
1431 In wxPerl this method takes no arguments and return a two
1432 element array (x, y).
1433 @endWxPerlOnly
1434
e3995493
FM
1435 @see SetUserScale()
1436 */
1437 void GetUserScale(double* x, double* y) const;
1438
1439 /**
1440 Returns @true if the DC is ok to use.
1441 */
1442 bool IsOk() const;
1443
1444 /**
1445 Sets the x and y axis orientation (i.e., the direction from lowest to
1446 highest values on the axis). The default orientation is x axis from
1447 left to right and y axis from top down.
1448
1449 @param xLeftRight
1450 True to set the x axis orientation to the natural left to right
1451 orientation, @false to invert it.
1452 @param yBottomUp
1453 True to set the y axis orientation to the natural bottom up
1454 orientation, @false to invert it.
1455 */
1456 void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
1457
1458 /**
1459 Sets the device origin (i.e., the origin in pixels after scaling has
1460 been applied). This function may be useful in Windows printing
1461 operations for placing a graphic on a page.
1462 */
1463 void SetDeviceOrigin(wxCoord x, wxCoord y);
1464
1465 /**
1466 Sets the current logical function for the device context.
1467 It determines how a @e source pixel (from a pen or brush colour, or source
1468 device context if using Blit()) combines with a @e destination pixel in
1469 the current device context.
1470 Text drawing is not affected by this function.
1471
1472 See ::wxRasterOperationMode enumeration values for more info.
1473
1474 The default is @c wxCOPY, which simply draws with the current colour.
1475 The others combine the current colour and the background using a logical
1476 operation. @c wxINVERT is commonly used for drawing rubber bands or moving
1477 outlines, since drawing twice reverts to the original colour.
1478 */
1479 void SetLogicalFunction(wxRasterOperationMode function);
1480
1481 /**
1482 The mapping mode of the device context defines the unit of measurement
1483 used to convert @e logical units to @e device units.
1484
1485 Note that in X, text drawing isn't handled consistently with the mapping mode;
1486 a font is always specified in point size. However, setting the user scale (see
1487 SetUserScale()) scales the text appropriately. In Windows, scalable
1488 TrueType fonts are always used; in X, results depend on availability of
1489 fonts, but usually a reasonable match is found.
1490
1491 The coordinate origin is always at the top left of the screen/printer.
1492
1493 Drawing to a Windows printer device context uses the current mapping
1494 mode, but mapping mode is currently ignored for PostScript output.
1495 */
1496 void SetMapMode(wxMappingMode mode);
1497
1498 /**
1499 If this is a window DC or memory DC, assigns the given palette to the
1500 window or bitmap associated with the DC. If the argument is
1501 ::wxNullPalette, the current palette is selected out of the device
1502 context, and the original palette restored.
1503
1504 @see wxPalette
1505 */
1506 void SetPalette(const wxPalette& palette);
1507
1508 /**
1509 Sets the user scaling factor, useful for applications which require
1510 'zooming'.
1511 */
1512 void SetUserScale(double xScale, double yScale);
e71508e1
VZ
1513
1514
1515 /**
1516 @name Transformation matrix
1517
1518 See the notes about the availability of these functions in the class
1519 documentation.
1520 */
1521 //@{
1522
1523 /**
1524 Check if the use of transformation matrix is supported by the current
1525 system.
1526
1527 Currently this function always returns @false for non-MSW platforms and
1528 may return @false for old (Windows 9x/ME) Windows systems. Normally
1529 support for the transformation matrix is always available in any
1530 relatively recent Windows versions.
1531
1532 @since 2.9.2
1533 */
1534 bool CanUseTransformMatrix() const;
1535
1536 /**
1537 Set the transformation matrix.
1538
1539 If transformation matrix is supported on the current system, the
1540 specified @a matrix will be used to transform between wxDC and physical
1541 coordinates. Otherwise the function returns @false and doesn't change
1542 the coordinate mapping.
1543
1544 @since 2.9.2
1545 */
1546 bool SetTransformMatrix(const wxAffineMatrix2D& matrix);
1547
1548 /**
1549 Return the transformation matrix used by this device context.
1550
1551 By default the transformation matrix is the identity matrix.
1552
1553 @since 2.9.2
1554 */
1555 wxAffineMatrix2D GetTransformMatrix() const;
1556
1557 /**
1558 Revert the transformation matrix to identity matrix.
1559
1560 @since 2.9.2
1561 */
1562 void ResetTransformMatrix();
1563
1564 //@}
9a077460
RD
1565
1566
1567 void SetLogicalScale(double x, double y);
1568 void GetLogicalScale(double *x, double *y) const;
1569 void SetLogicalOrigin(wxCoord x, wxCoord y);
1570 void GetLogicalOrigin(wxCoord *x, wxCoord *y) const;
1571 wxPoint GetLogicalOrigin() const;
1572
23324ae1
FM
1573};
1574
1575
e54c96f1 1576
23324ae1
FM
1577/**
1578 @class wxDCClipper
7c913512 1579
f09b5681
BP
1580 wxDCClipper is a small helper class for setting a clipping region on a wxDC
1581 and unsetting it automatically. An object of wxDCClipper class is typically
1582 created on the stack so that it is automatically destroyed when the object
1583 goes out of scope. A typical usage example:
7c913512 1584
23324ae1
FM
1585 @code
1586 void MyFunction(wxDC& dc)
f09b5681
BP
1587 {
1588 wxDCClipper clip(dc, rect);
1589 // ... drawing functions here are affected by clipping rect ...
1590 }
1591
1592 void OtherFunction()
1593 {
1594 wxDC dc;
1595 MyFunction(dc);
1596 // ... drawing functions here are not affected by clipping rect ...
1597 }
23324ae1 1598 @endcode
7c913512 1599
23324ae1
FM
1600 @library{wxcore}
1601 @category{gdi}
7c913512 1602
382f12e4
FM
1603 @see wxDC::SetClippingRegion(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1604 wxDCBrushChanger
23324ae1 1605*/
7c913512 1606class wxDCClipper
23324ae1
FM
1607{
1608public:
1609 //@{
1610 /**
f09b5681
BP
1611 Sets the clipping region to the specified region/coordinates.
1612
23324ae1
FM
1613 The clipping region is automatically unset when this object is destroyed.
1614 */
9a077460 1615 wxDCClipper(wxDC& dc, const wxRegion& region);
7c913512 1616 wxDCClipper(wxDC& dc, const wxRect& rect);
882678eb 1617 wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h);
23324ae1 1618 //@}
c48d6cdf
FM
1619
1620 /**
1621 Destroys the clipping region associated with the DC passed to the ctor.
1622 */
1623 ~wxDCClipper();
1624};
1625
1626
1627/**
1628 @class wxDCBrushChanger
1629
1630 wxDCBrushChanger is a small helper class for setting a brush on a wxDC
1631 and unsetting it automatically in the destructor, restoring the previous one.
1632
1633 @library{wxcore}
1634 @category{gdi}
1635
382f12e4
FM
1636 @see wxDC::SetBrush(), wxDCFontChanger, wxDCTextColourChanger, wxDCPenChanger,
1637 wxDCClipper
c48d6cdf
FM
1638*/
1639class wxDCBrushChanger
1640{
1641public:
1642 /**
1643 Sets @a brush on the given @a dc, storing the old one.
1644
1645 @param dc
1646 The DC where the brush must be temporary set.
1647 @param brush
1648 The brush to set.
1649 */
1650 wxDCBrushChanger(wxDC& dc, const wxBrush& brush);
1651
1652 /**
1653 Restores the brush originally selected in the DC passed to the ctor.
1654 */
1655 ~wxDCBrushChanger();
1656};
1657
1658
1659/**
1660 @class wxDCPenChanger
1661
1662 wxDCPenChanger is a small helper class for setting a pen on a wxDC
1663 and unsetting it automatically in the destructor, restoring the previous one.
1664
1665 @library{wxcore}
1666 @category{gdi}
1667
382f12e4
FM
1668 @see wxDC::SetPen(), wxDCFontChanger, wxDCTextColourChanger, wxDCBrushChanger,
1669 wxDCClipper
c48d6cdf
FM
1670*/
1671class wxDCPenChanger
1672{
1673public:
1674 /**
1675 Sets @a pen on the given @a dc, storing the old one.
1676
1677 @param dc
1678 The DC where the pen must be temporary set.
1679 @param pen
1680 The pen to set.
1681 */
1682 wxDCPenChanger(wxDC& dc, const wxPen& pen);
1683
1684 /**
1685 Restores the pen originally selected in the DC passed to the ctor.
1686 */
1687 ~wxDCPenChanger();
1688};
1689
1690
1691
1692/**
1693 @class wxDCTextColourChanger
1694
1695 wxDCTextColourChanger is a small helper class for setting a foreground
1696 text colour on a wxDC and unsetting it automatically in the destructor,
1697 restoring the previous one.
1698
1699 @library{wxcore}
1700 @category{gdi}
1701
382f12e4
FM
1702 @see wxDC::SetTextForeground(), wxDCFontChanger, wxDCPenChanger, wxDCBrushChanger,
1703 wxDCClipper
c48d6cdf
FM
1704*/
1705class wxDCTextColourChanger
1706{
1707public:
489cc69b
VZ
1708 /**
1709 Trivial constructor not changing anything.
1710
1711 This constructor is useful if you don't know beforehand if the colour
1712 needs to be changed or not. It simply creates the object which won't do
1713 anything in its destructor unless Set() is called -- in which case it
1714 would reset the previous colour.
1715 */
1716 wxDCTextColourChanger(wxDC& dc);
1717
c48d6cdf
FM
1718 /**
1719 Sets @a col on the given @a dc, storing the old one.
1720
1721 @param dc
1722 The DC where the colour must be temporary set.
1723 @param col
1724 The colour to set.
1725 */
1726 wxDCTextColourChanger(wxDC& dc, const wxColour& col);
1727
489cc69b
VZ
1728 /**
1729 Set the colour to use.
1730
1731 This method is meant to be called once only and only on the objects
1732 created with the constructor overload not taking wxColour argument and
1733 has the same effect as the other constructor, i.e. sets the colour to
1734 the given @a col and ensures that the old value is restored when this
1735 object is destroyed.
1736 */
1737 void Set(const wxColour& col);
1738
c48d6cdf
FM
1739 /**
1740 Restores the colour originally selected in the DC passed to the ctor.
1741 */
1742 ~wxDCTextColourChanger();
1743};
1744
1745
1746
1747/**
1748 @class wxDCFontChanger
1749
1750 wxDCFontChanger is a small helper class for setting a font on a wxDC and
1751 unsetting it automatically in the destructor, restoring the previous one.
1752
1753 @since 2.9.0
1754
1755 @library{wxcore}
1756 @category{gdi}
1757
382f12e4
FM
1758 @see wxDC::SetFont(), wxDCTextColourChanger, wxDCPenChanger, wxDCBrushChanger,
1759 wxDCClipper
c48d6cdf
FM
1760*/
1761class wxDCFontChanger
1762{
1763public:
ca4adfd0
VZ
1764 /**
1765 Trivial constructor not changing anything.
1766
1767 This constructor is useful if you don't know beforehand if the font
1768 needs to be changed or not. It simply creates the object which won't do
1769 anything in its destructor unless Set() is called -- in which case it
1770 would reset the previous font.
1771
1772 @since 2.9.1
1773 */
1774 wxDCFontChanger(wxDC& dc);
1775
c48d6cdf
FM
1776 /**
1777 Sets @a font on the given @a dc, storing the old one.
1778
1779 @param dc
1780 The DC where the font must be temporary set.
1781 @param font
1782 The font to set.
1783 */
1784 wxDCFontChanger(wxDC& dc, const wxFont& font);
1785
1786 /**
ca4adfd0
VZ
1787 Set the font to use.
1788
1789 This method is meant to be called once only and only on the objects
1790 created with the constructor overload not taking wxColour argument and
1791 has the same effect as the other constructor, i.e. sets the font to
1792 the given @a font and ensures that the old value is restored when this
1793 object is destroyed.
1794 */
1795 void Set(const wxFont& font);
1796
1797 /**
1798 Restores the font originally selected in the DC passed to the ctor.
c48d6cdf
FM
1799 */
1800 ~wxDCFontChanger();
23324ae1 1801};
e54c96f1 1802