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