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