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