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