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