]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/dc.tex
Fixed some wxDragImage bugs
[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}}
65
66 Copy from a source DC to this DC, specifying the destination
67 coordinates, size of area to copy, source DC, source coordinates, and
68 logical function.
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:
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
108 \wxheading{Remarks}
109
110 There is partial support for Blit in wxPostScriptDC, under X.
111
112 See \helpref{wxMemoryDC}{wxmemorydc} for typical usage.
113
114 \wxheading{See also}
115
116 \helpref{wxMemoryDC}{wxmemorydc}, \helpref{wxBitmap}{wxbitmap}, \helpref{wxMask}{wxmask}
117
118 \membersection{wxDC::CalcBoundingBox}\label{wxdccalcboundingbox}
119
120 \func{void}{CalcBoundingBox}{\param{wxCoord }{x}, \param{wxCoord }{y}}
121
122 Adds the specified point to the bounding box which can be retrieved with
123 \helpref{MinX}{wxdcminx}, \helpref{MaxX}{wxdcmaxx} and
124 \helpref{MinY}{wxdcminy}, \helpref{MaxY}{wxdcmaxy} functions.
125
126 \wxheading{See also}
127
128 \helpref{ResetBoundingBox}{wxdcresetboundingbox}
129
130 \membersection{wxDC::Clear}\label{wxdcclear}
131
132 \func{void}{Clear}{\void}
133
134 Clears the device context using the current background brush.
135
136 \membersection{wxDC::CrossHair}\label{wxdccrosshair}
137
138 \func{void}{CrossHair}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
139
140 Displays a cross hair using the current pen. This is a vertical
141 and horizontal line the height and width of the window, centred
142 on the given point.
143
144 \membersection{wxDC::DestroyClippingRegion}\label{wxdcdestroyclippingregion}
145
146 \func{void}{DestroyClippingRegion}{\void}
147
148 Destroys the current clipping region so that none of the DC is clipped.
149 See also \helpref{wxDC::SetClippingRegion}{wxdcsetclippingregion}.
150
151 \membersection{wxDC::DeviceToLogicalX}\label{wxdcdevicetologicalx}
152
153 \func{wxCoord}{DeviceToLogicalX}{\param{wxCoord}{ x}}
154
155 Convert device X coordinate to logical coordinate, using the current
156 mapping mode.
157
158 \membersection{wxDC::DeviceToLogicalXRel}\label{wxdcdevicetologicalxrel}
159
160 \func{wxCoord}{DeviceToLogicalXRel}{\param{wxCoord}{ x}}
161
162 Convert device X coordinate to relative logical coordinate, using the current
163 mapping mode. Use this function for converting a width, for example.
164
165 \membersection{wxDC::DeviceToLogicalY}\label{wxdcdevicetologicaly}
166
167 \func{wxCoord}{DeviceToLogicalY}{\param{wxCoord}{ y}}
168
169 Converts device Y coordinate to logical coordinate, using the current
170 mapping mode.
171
172 \membersection{wxDC::DeviceToLogicalYRel}\label{wxdcdevicetologicalyrel}
173
174 \func{wxCoord}{DeviceToLogicalYRel}{\param{wxCoord}{ y}}
175
176 Convert device Y coordinate to relative logical coordinate, using the current
177 mapping mode. Use this function for converting a height, for example.
178
179 \membersection{wxDC::DrawArc}\label{wxdcdrawarc}
180
181 \func{void}{DrawArc}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}, \param{double}{ xc}, \param{double}{ yc}}
182
183 Draws an arc of a circle, centred on ({\it xc, yc}), with starting point ({\it x1, y1})
184 and ending at ({\it x2, y2}). The current pen is used for the outline
185 and the current brush for filling the shape.
186
187 The arc is drawn in an anticlockwise direction from the start point to the end point.
188
189 \membersection{wxDC::DrawBitmap}\label{wxdcdrawbitmap}
190
191 \func{void}{DrawBitmap}{\param{const wxBitmap\&}{ bitmap}, \param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{bool}{ transparent}}
192
193 Draw a bitmap on the device context at the specified point. If {\it transparent} is TRUE and the bitmap has
194 a transparency mask, the bitmap will be drawn transparently.
195
196 When drawing a mono-bitmap, the current text foreground colour will be used to draw the foreground
197 of the bitmap (all bits set to 1), and the current text background colour to draw the background
198 (all bits set to 0). See also \helpref{SetTextForeground}{wxdcsettextforeground},
199 \helpref{SetTextBackground}{wxdcsettextbackground} and \helpref{wxMemoryDC}{wxmemorydc}.
200
201 \membersection{wxDC::DrawCheckMark}\label{wxdcdrawcheckmark}
202
203 \func{void}{DrawCheckMark}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
204
205 \func{void}{DrawCheckMark}{\param{const wxRect \&}{rect}}
206
207 Draws a check mark inside the given rectangle.
208
209 \membersection{wxDC::DrawEllipse}\label{wxdcdrawellipse}
210
211 \func{void}{DrawEllipse}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
212
213 Draws an ellipse contained in the rectangle with the given top left corner, and with the
214 given size. The current pen is used for the outline and the current brush for
215 filling the shape.
216
217 \membersection{wxDC::DrawEllipticArc}\label{wxdcdrawellipticarc}
218
219 \func{void}{DrawEllipticArc}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height},
220 \param{double}{ start}, \param{double}{ end}}
221
222 Draws an arc of an ellipse. The current pen is used for drawing the arc and
223 the current brush is used for drawing the pie.
224
225 {\it x} and {\it y} specify the x and y coordinates of the upper-left corner of the rectangle that contains
226 the ellipse.
227
228 {\it width} and {\it height} specify the width and height of the rectangle that contains
229 the ellipse.
230
231 {\it start} and {\it end} specify the start and end of the arc relative to the three-o'clock
232 position from the center of the rectangle. Angles are specified
233 in degrees (360 is a complete circle). Positive values mean
234 counter-clockwise motion. If {\it start} is equal to {\it end}, a
235 complete ellipse will be drawn.
236
237 \membersection{wxDC::DrawIcon}\label{wxdcdrawicon}
238
239 \func{void}{DrawIcon}{\param{const wxIcon\&}{ icon}, \param{wxCoord}{ x}, \param{wxCoord}{ y}}
240
241 Draw an icon on the display (does nothing if the device context is PostScript).
242 This can be the simplest way of drawing bitmaps on a window.
243
244 \membersection{wxDC::DrawLine}\label{wxdcdrawline}
245
246 \func{void}{DrawLine}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}}
247
248 Draws a line from the first point to the second. The current pen is used
249 for drawing the line.
250
251 \membersection{wxDC::DrawLines}\label{wxdcdrawlines}
252
253 \func{void}{DrawLines}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0}}
254
255 \func{void}{DrawLines}{\param{wxList *}{points}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0}}
256
257 Draws lines using an array of {\it points} of size {\it n}, or list of
258 pointers to points, adding the optional offset coordinate. The current
259 pen is used for drawing the lines. The programmer is responsible for
260 deleting the list of points.
261
262 \pythonnote{The wxPython version of this method accepts a Python list
263 of wxPoint objects.}
264
265 \membersection{wxDC::DrawPolygon}\label{wxdcdrawpolygon}
266
267 \func{void}{DrawPolygon}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0},\\
268 \param{int }{fill\_style = wxODDEVEN\_RULE}}
269
270 \func{void}{DrawPolygon}{\param{wxList *}{points}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0},\\
271 \param{int }{fill\_style = wxODDEVEN\_RULE}}
272
273 Draws a filled polygon using an array of {\it points} of size {\it n},
274 or list of pointers to points, adding the optional offset coordinate.
275
276 The last argument specifies the fill rule: {\bf wxODDEVEN\_RULE} (the
277 default) or {\bf wxWINDING\_RULE}.
278
279 The current pen is used for drawing the outline, and the current brush
280 for filling the shape. Using a transparent brush suppresses filling.
281 The programmer is responsible for deleting the list of points.
282
283 Note that wxWindows automatically closes the first and last points.
284
285 \pythonnote{The wxPython version of this method accepts a Python list
286 of wxPoint objects.}
287
288 \membersection{wxDC::DrawPoint}\label{wxdcdrawpoint}
289
290 \func{void}{DrawPoint}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
291
292 Draws a point using the current pen.
293
294 \membersection{wxDC::DrawRectangle}\label{wxdcdrawrectangle}
295
296 \func{void}{DrawRectangle}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
297
298 Draws a rectangle with the given top left corner, and with the given
299 size. The current pen is used for the outline and the current brush
300 for filling the shape.
301
302 \membersection{wxDC::DrawRotatedText}\label{wxdcdrawrotatedtext}
303
304 \func{void}{DrawRotatedText}{\param{const wxString\& }{text}, \param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{double}{ angle}}
305
306 Draws the text rotated by {\it angle} degrees.
307
308 \wxheading{See also}
309
310 \helpref{DrawText}{wxdcdrawtext}
311
312 \membersection{wxDC::DrawRoundedRectangle}\label{wxdcdrawroundedrectangle}
313
314 \func{void}{DrawRoundedRectangle}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}, \param{double}{ radius = 20}}
315
316 Draws a rectangle with the given top left corner, and with the given
317 size. The corners are quarter-circles using the given radius. The
318 current pen is used for the outline and the current brush for filling
319 the shape.
320
321 If {\it radius} is positive, the value is assumed to be the
322 radius of the rounded corner. If {\it radius} is negative,
323 the absolute value is assumed to be the {\it proportion} of the smallest
324 dimension of the rectangle. This means that the corner can be
325 a sensible size relative to the size of the rectangle, and also avoids
326 the strange effects X produces when the corners are too big for
327 the rectangle.
328
329 \membersection{wxDC::DrawSpline}\label{wxdcdrawspline}
330
331 \func{void}{DrawSpline}{\param{wxList *}{points}}
332
333 Draws a spline between all given control points, using the current
334 pen. Doesn't delete the wxList and contents. The spline is drawn
335 using a series of lines, using an algorithm taken from the X drawing
336 program `XFIG'.
337
338 \func{void}{DrawSpline}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}, \param{wxCoord}{ x3}, \param{wxCoord}{ y3}}
339
340 Draws a three-point spline using the current pen.
341
342 \pythonnote{The wxPython version of this method accepts a Python list
343 of wxPoint objects.}
344
345 \membersection{wxDC::DrawText}\label{wxdcdrawtext}
346
347 \func{void}{DrawText}{\param{const wxString\& }{text}, \param{wxCoord}{ x}, \param{wxCoord}{ y}}
348
349 Draws a text string at the specified point, using the current text font,
350 and the current text foreground and background colours.
351
352 The coordinates refer to the top-left corner of the rectangle bounding
353 the string. See \helpref{wxDC::GetTextExtent}{wxdcgettextextent} for how
354 to get the dimensions of a text string, which can be used to position the
355 text more precisely.
356
357 {\bf NB:} under wxGTK the current
358 \helpref{logical function}{wxdcgetlogicalfunction} is used by this function
359 but it is ignored by wxMSW. Thus, you should avoid using logical functions
360 with this function in portable programs.
361
362 \membersection{wxDC::EndDoc}\label{wxdcenddoc}
363
364 \func{void}{EndDoc}{\void}
365
366 Ends a document (only relevant when outputting to a printer).
367
368 \membersection{wxDC::EndDrawing}\label{wxdcenddrawing}
369
370 \func{void}{EndDrawing}{\void}
371
372 Allows optimization of drawing code under MS Windows. Enclose
373 drawing primitives between {\bf BeginDrawing} and {\bf EndDrawing}\rtfsp
374 calls.
375
376 \membersection{wxDC::EndPage}\label{wxdcendpage}
377
378 \func{void}{EndPage}{\void}
379
380 Ends a document page (only relevant when outputting to a printer).
381
382 \membersection{wxDC::FloodFill}\label{wxdcfloodfill}
383
384 \func{void}{FloodFill}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{const wxColour\&}{ colour}, \param{int}{ style=wxFLOOD\_SURFACE}}
385
386 Flood fills the device context starting from the given point, using
387 the {\it current brush colour}, and using a style:
388
389 \begin{itemize}\itemsep=0pt
390 \item wxFLOOD\_SURFACE: the flooding occurs until a colour other than the given colour is encountered.
391 \item wxFLOOD\_BORDER: the area to be flooded is bounded by the given colour.
392 \end{itemize}
393
394 {\it Note:} this function is available in MS Windows only.
395
396 \membersection{wxDC::GetBackground}\label{wxdcgetbackground}
397
398 \func{wxBrush\&}{GetBackground}{\void}
399
400 \constfunc{const wxBrush\&}{GetBackground}{\void}
401
402 Gets the brush used for painting the background (see \helpref{wxDC::SetBackground}{wxdcsetbackground}).
403
404 \membersection{wxDC::GetBackgroundMode}\label{wxdcgetbackgroundmode}
405
406 \constfunc{int}{GetBackgroundMode}{\void}
407
408 Returns the current background mode: {\tt wxSOLID} or {\tt wxTRANSPARENT}.
409
410 \wxheading{See also}
411
412 \helpref{SetBackgroundMode}{wxdcsetbackgroundmode}
413
414 \membersection{wxDC::GetBrush}\label{wxdcgetbrush}
415
416 \func{wxBrush\&}{GetBrush}{\void}
417
418 \constfunc{const wxBrush\&}{GetBrush}{\void}
419
420 Gets the current brush (see \helpref{wxDC::SetBrush}{wxdcsetbrush}).
421
422 \membersection{wxDC::GetCharHeight}\label{wxdcgetcharheight}
423
424 \func{wxCoord}{GetCharHeight}{\void}
425
426 Gets the character height of the currently set font.
427
428 \membersection{wxDC::GetCharWidth}\label{wxdcgetcharwidth}
429
430 \func{wxCoord}{GetCharWidth}{\void}
431
432 Gets the average character width of the currently set font.
433
434 \membersection{wxDC::GetClippingBox}\label{wxdcgetclippingbox}
435
436 \func{void}{GetClippingBox}{\param{wxCoord}{ *x}, \param{wxCoord}{ *y}, \param{wxCoord}{ *width}, \param{wxCoord}{ *height}}
437
438 Gets the rectangle surrounding the current clipping region.
439
440 \pythonnote{No arguments are required and the four values defining the
441 rectangle are returned as a tuple.}
442
443 \perlnote{This method takes no arguments and returns a four element list
444 {\tt ( \$x, \$y, \$width, \$height )}}
445
446 \membersection{wxDC::GetFont}\label{wxdcgetfont}
447
448 \func{wxFont\&}{GetFont}{\void}
449
450 \constfunc{const wxFont\&}{GetFont}{\void}
451
452 Gets the current font (see \helpref{wxDC::SetFont}{wxdcsetfont}).
453
454 \membersection{wxDC::GetLogicalFunction}\label{wxdcgetlogicalfunction}
455
456 \func{int}{GetLogicalFunction}{\void}
457
458 Gets the current logical function (see \helpref{wxDC::SetLogicalFunction}{wxdcsetlogicalfunction}).
459
460 \membersection{wxDC::GetMapMode}\label{wxdcgetmapmode}
461
462 \func{int}{GetMapMode}{\void}
463
464 Gets the {\it mapping mode} for the device context (see \helpref{wxDC::SetMapMode}{wxdcsetmapmode}).
465
466 \membersection{wxDC::GetOptimization}\label{wxdcgetoptimization}
467
468 \func{bool}{GetOptimization}{\void}
469
470 Returns TRUE if device context optimization is on.
471 See \helpref{wxDC::SetOptimization}{wxsetoptimization} for details.
472
473 \membersection{wxDC::GetPen}\label{wxdcgetpen}
474
475 \func{wxPen\&}{GetPen}{\void}
476
477 \constfunc{const wxPen\&}{GetPen}{\void}
478
479 Gets the current pen (see \helpref{wxDC::SetPen}{wxdcsetpen}).
480
481 \membersection{wxDC::GetPixel}\label{wxdcgetpixel}
482
483 \func{bool}{GetPixel}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxColour *}{colour}}
484
485 Sets {\it colour} to the colour at the specified location. Windows only; an X implementation
486 is being worked on. Not available for wxPostScriptDC or wxMetafileDC.
487
488 \pythonnote{For wxPython the wxColour value is returned and is not
489 required as a parameter.}
490
491 \perlnote{This method only takes the parameters {\tt x} and {\tt y} and returns
492 a Wx::Colour value}
493
494 \membersection{wxDC::GetSize}\label{wxdcgetsize}
495
496 \func{void}{GetSize}{\param{wxCoord *}{width}, \param{wxCoord *}{height}}
497
498 For a PostScript device context, this gets the maximum size of graphics
499 drawn so far on the device context.
500
501 For a Windows printer device context, this gets the horizontal and vertical
502 resolution. It can be used to scale graphics to fit the page when using
503 a Windows printer device context. For example, if {\it maxX} and {\it maxY}\rtfsp
504 represent the maximum horizontal and vertical `pixel' values used in your
505 application, the following code will scale the graphic to fit on the
506 printer page:
507
508 \begin{verbatim}
509 wxCoord w, h;
510 dc.GetSize(&w, &h);
511 double scaleX=(double)(maxX/w);
512 double scaleY=(double)(maxY/h);
513 dc.SetUserScale(min(scaleX,scaleY),min(scaleX,scaleY));
514 \end{verbatim}
515
516 \pythonnote{In place of a single overloaded method name, wxPython
517 implements the following methods:\par
518 \indented{2cm}{\begin{twocollist}
519 \twocolitem{{\bf GetSize()}}{Returns a wxSize}
520 \twocolitem{{\bf GetSizeTuple()}}{Returns a 2-tuple (width, height)}
521 \end{twocollist}}
522 }
523
524 \perlnote{In place of a single overloaded method, wxPerl uses:\par
525 \indented{2cm}{\begin{twocollist}
526 \twocolitem{{\bf GetSize()}}{Returns a Wx::Size}
527 \twocolitem{{\bf GetSizeWH()}}{Returns a 2-element list
528 {\tt ( \$width, \$height )}}
529 \end{twocollist}
530 }}
531
532 \membersection{wxDC::GetTextBackground}\label{wxdcgettextbackground}
533
534 \func{wxColour\&}{GetTextBackground}{\void}
535
536 \constfunc{const wxColour\&}{GetTextBackground}{\void}
537
538 Gets the current text background colour (see \helpref{wxDC::SetTextBackground}{wxdcsettextbackground}).
539
540 \membersection{wxDC::GetTextExtent}\label{wxdcgettextextent}
541
542 \func{void}{GetTextExtent}{\param{const wxString\& }{string}, \param{wxCoord *}{w}, \param{wxCoord *}{h},\\
543 \param{wxCoord *}{descent = NULL}, \param{wxCoord *}{externalLeading = NULL}, \param{wxFont *}{font = NULL}}
544
545 Gets the dimensions of the string using the currently selected font.
546 \rtfsp{\it string} is the text string to measure, {\it w} and {\it h} are
547 the total width and height respectively, {\it descent} is the
548 dimension from the baseline of the font to the bottom of the
549 descender, and {\it externalLeading} is any extra vertical space added
550 to the font by the font designer (usually is zero).
551
552 The optional parameter {\it font} specifies an alternative
553 to the currently selected font: but note that this does not
554 yet work under Windows, so you need to set a font for
555 the device context first.
556
557 See also \helpref{wxFont}{wxfont}, \helpref{wxDC::SetFont}{wxdcsetfont}.
558
559 \pythonnote{The following methods are implemented in wxPython:\par
560 \indented{2cm}{\begin{twocollist}
561 \twocolitem{{\bf GetTextExtent(string)}}{Returns a 2-tuple, (width, height)}
562 \twocolitem{{\bf GetFullTextExtent(string, font=NULL)}}{Returns a
563 4-tuple, (width, height, descent, externalLeading) }
564 \end{twocollist}}
565 }
566
567 \perlnote{In wxPerl this method is implemented as
568 {\bf GetTextExtent( string, font = undef )} returning a four element
569 array {\tt ( \$width, \$height, \$descent, \$externalLeading )}
570 }
571
572 \membersection{wxDC::GetTextForeground}\label{wxdcgettextforeground}
573
574 \func{wxColour\&}{GetTextForeground}{\void}
575
576 \constfunc{const wxColour\&}{GetTextForeground}{\void}
577
578 Gets the current text foreground colour (see \helpref{wxDC::SetTextForeground}{wxdcsettextforeground}).
579
580
581 \membersection{wxDC::GetUserScale}\label{wxdcgetuserscale}
582
583 \func{void}{GetUserScale}{\param{double}{ *x}, \param{double}{ *y}}
584
585 Gets the current user scale factor (set by \helpref{SetUserScale}{wxdcsetuserscale}).
586
587 \perlnote{In wxPerl this method takes no arguments and returna a two element
588 array {\tt ( \$x, \$y )}}
589
590 \membersection{wxDC::LogicalToDeviceX}\label{wxdclogicaltodevicex}
591
592 \func{wxCoord}{LogicalToDeviceX}{\param{wxCoord}{ x}}
593
594 Converts logical X coordinate to device coordinate, using the current
595 mapping mode.
596
597 \membersection{wxDC::LogicalToDeviceXRel}\label{wxdclogicaltodevicexrel}
598
599 \func{wxCoord}{LogicalToDeviceXRel}{\param{wxCoord}{ x}}
600
601 Converts logical X coordinate to relative device coordinate, using the current
602 mapping mode. Use this for converting a width, for example.
603
604 \membersection{wxDC::LogicalToDeviceY}\label{wxdclogicaltodevicey}
605
606 \func{wxCoord}{LogicalToDeviceY}{\param{wxCoord}{ y}}
607
608 Converts logical Y coordinate to device coordinate, using the current
609 mapping mode.
610
611 \membersection{wxDC::LogicalToDeviceYRel}\label{wxdclogicaltodeviceyrel}
612
613 \func{wxCoord}{LogicalToDeviceYRel}{\param{wxCoord}{ y}}
614
615 Converts logical Y coordinate to relative device coordinate, using the current
616 mapping mode. Use this for converting a height, for example.
617
618 \membersection{wxDC::MaxX}\label{wxdcmaxx}
619
620 \func{wxCoord}{MaxX}{\void}
621
622 Gets the maximum horizontal extent used in drawing commands so far.
623
624 \membersection{wxDC::MaxY}\label{wxdcmaxy}
625
626 \func{wxCoord}{MaxY}{\void}
627
628 Gets the maximum vertical extent used in drawing commands so far.
629
630 \membersection{wxDC::MinX}\label{wxdcminx}
631
632 \func{wxCoord}{MinX}{\void}
633
634 Gets the minimum horizontal extent used in drawing commands so far.
635
636 \membersection{wxDC::MinY}\label{wxdcminy}
637
638 \func{wxCoord}{MinY}{\void}
639
640 Gets the minimum vertical extent used in drawing commands so far.
641
642 \membersection{wxDC::Ok}\label{wxdcok}
643
644 \func{bool}{Ok}{\void}
645
646 Returns TRUE if the DC is ok to use.
647
648 \membersection{wxDC::ResetBoundingBox}\label{wxdcresetboundingbox}
649
650 \func{void}{ResetBoundingBox}{\void}
651
652 Resets the bounding box: after a call to this function, the bounding box
653 doesn't contain anything.
654
655 \wxheading{See also}
656
657 \helpref{CalcBoundingBox}{wxdccalcboundingbox}
658
659 \membersection{wxDC::SetDeviceOrigin}\label{wxdcsetdeviceorigin}
660
661 \func{void}{SetDeviceOrigin}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
662
663 Sets the device origin (i.e., the origin in pixels after scaling has been
664 applied).
665
666 This function may be useful in Windows printing
667 operations for placing a graphic on a page.
668
669 \membersection{wxDC::SetBackground}\label{wxdcsetbackground}
670
671 \func{void}{SetBackground}{\param{const wxBrush\& }{brush}}
672
673 Sets the current background brush for the DC.
674
675 \membersection{wxDC::SetBackgroundMode}\label{wxdcsetbackgroundmode}
676
677 \func{void}{SetBackgroundMode}{\param{int}{ mode}}
678
679 {\it mode} may be one of wxSOLID and wxTRANSPARENT. This setting determines
680 whether text will be drawn with a background colour or not.
681
682 \membersection{wxDC::SetClippingRegion}\label{wxdcsetclippingregion}
683
684 \func{void}{SetClippingRegion}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
685
686 \func{void}{SetClippingRegion}{\param{const wxRegion\&}{ region}}
687
688 Sets the clipping region for the DC. The clipping region is an area
689 to which drawing is restricted. Possible uses for the clipping region are for clipping text
690 or for speeding up window redraws when only a known area of the screen is damaged.
691
692 \wxheading{See also}
693
694 \helpref{wxDC::DestroyClippingRegion}{wxdcdestroyclippingregion}, \helpref{wxRegion}{wxregion}
695
696 \membersection{wxDC::SetPalette}\label{wxdcsetpalette}
697
698 \func{void}{SetPalette}{\param{const wxPalette\& }{palette}}
699
700 If this is a window DC or memory DC, assigns the given palette to the window
701 or bitmap associated with the DC. If the argument is wxNullPalette, the current
702 palette is selected out of the device context, and the original palette
703 restored.
704
705 See \helpref{wxPalette}{wxpalette} for further details.
706
707 \membersection{wxDC::SetBrush}\label{wxdcsetbrush}
708
709 \func{void}{SetBrush}{\param{const wxBrush\& }{brush}}
710
711 Sets the current brush for the DC.
712
713 If the argument is wxNullBrush, the current brush is selected out of the device
714 context, and the original brush restored, allowing the current brush to
715 be destroyed safely.
716
717 See also \helpref{wxBrush}{wxbrush}.
718
719 See also \helpref{wxMemoryDC}{wxmemorydc} for the interpretation of colours
720 when drawing into a monochrome bitmap.
721
722 \membersection{wxDC::SetFont}\label{wxdcsetfont}
723
724 \func{void}{SetFont}{\param{const wxFont\& }{font}}
725
726 Sets the current font for the DC.
727
728 If the argument is wxNullFont, the current font is selected out of the device
729 context, and the original font restored, allowing the current font to
730 be destroyed safely.
731
732 See also \helpref{wxFont}{wxfont}.
733
734 \membersection{wxDC::SetLogicalFunction}\label{wxdcsetlogicalfunction}
735
736 \func{void}{SetLogicalFunction}{\param{int}{ function}}
737
738 Sets the current logical function for the device context. This determines how
739 a source pixel (from a pen or brush colour, or source device context if
740 using \helpref{wxDC::Blit}{wxdcblit}) combines with a destination pixel in the
741 current device context.
742
743 The possible values
744 and their meaning in terms of source and destination pixel values are
745 as follows:
746
747 \begin{verbatim}
748 wxAND src AND dst
749 wxAND_INVERT (NOT src) AND dst
750 wxAND_REVERSE src AND (NOT dst)
751 wxCLEAR 0
752 wxCOPY src
753 wxEQUIV (NOT src) XOR dst
754 wxINVERT NOT dst
755 wxNAND (NOT src) OR (NOT dst)
756 wxNOR (NOT src) AND (NOT dst)
757 wxNO_OP dst
758 wxOR src OR dst
759 wxOR_INVERT (NOT src) OR dst
760 wxOR_REVERSE src OR (NOT dst)
761 wxSET 1
762 wxSRC_INVERT NOT src
763 wxXOR src XOR dst
764 \end{verbatim}
765
766 The default is wxCOPY, which simply draws with the current colour.
767 The others combine the current colour and the background using a
768 logical operation. wxINVERT is commonly used for drawing rubber bands or
769 moving outlines, since drawing twice reverts to the original colour.
770
771 \membersection{wxDC::SetMapMode}\label{wxdcsetmapmode}
772
773 \func{void}{SetMapMode}{\param{int}{ int}}
774
775 The {\it mapping mode} of the device context defines the unit of
776 measurement used to convert logical units to device units. Note that
777 in X, text drawing isn't handled consistently with the mapping mode; a
778 font is always specified in point size. However, setting the {\it
779 user scale} (see \helpref{wxDC::SetUserScale}{wxdcsetuserscale}) scales the text appropriately. In
780 Windows, scaleable TrueType fonts are always used; in X, results depend
781 on availability of fonts, but usually a reasonable match is found.
782
783 Note that the coordinate origin should ideally be selectable, but for
784 now is always at the top left of the screen/printer.
785
786 Drawing to a Windows printer device context under UNIX
787 uses the current mapping mode, but mapping mode is currently ignored for
788 PostScript output.
789
790 The mapping mode can be one of the following:
791
792 \begin{twocollist}\itemsep=0pt
793 \twocolitem{wxMM\_TWIPS}{Each logical unit is 1/20 of a point, or 1/1440 of
794 an inch.}
795 \twocolitem{wxMM\_POINTS}{Each logical unit is a point, or 1/72 of an inch.}
796 \twocolitem{wxMM\_METRIC}{Each logical unit is 1 mm.}
797 \twocolitem{wxMM\_LOMETRIC}{Each logical unit is 1/10 of a mm.}
798 \twocolitem{wxMM\_TEXT}{Each logical unit is 1 pixel.}
799 \end{twocollist}
800
801 \membersection{wxDC::SetOptimization}\label{wxsetoptimization}
802
803 \func{void}{SetOptimization}{\param{bool }{optimize}}
804
805 If {\it optimize} is TRUE (the default), this function sets optimization mode on.
806 This currently means that under X, the device context will not try to set a pen or brush
807 property if it is known to be set already. This approach can fall down
808 if non-wxWindows code is using the same device context or window, for example
809 when the window is a panel on which the windowing system draws panel items.
810 The wxWindows device context 'memory' will now be out of step with reality.
811
812 Setting optimization off, drawing, then setting it back on again, is a trick
813 that must occasionally be employed.
814
815 \membersection{wxDC::SetPen}\label{wxdcsetpen}
816
817 \func{void}{SetPen}{\param{const wxPen\& }{pen}}
818
819 Sets the current pen for the DC.
820
821 If the argument is wxNullPen, the current pen is selected out of the device
822 context, and the original pen restored.
823
824 See also \helpref{wxMemoryDC}{wxmemorydc} for the interpretation of colours
825 when drawing into a monochrome bitmap.
826
827 \membersection{wxDC::SetTextBackground}\label{wxdcsettextbackground}
828
829 \func{void}{SetTextBackground}{\param{const wxColour\& }{colour}}
830
831 Sets the current text background colour for the DC.
832
833 \membersection{wxDC::SetTextForeground}\label{wxdcsettextforeground}
834
835 \func{void}{SetTextForeground}{\param{const wxColour\& }{colour}}
836
837 Sets the current text foreground colour for the DC.
838
839 See also \helpref{wxMemoryDC}{wxmemorydc} for the interpretation of colours
840 when drawing into a monochrome bitmap.
841
842 \membersection{wxDC::SetUserScale}\label{wxdcsetuserscale}
843
844 \func{void}{SetUserScale}{\param{double}{ xScale}, \param{double}{ yScale}}
845
846 Sets the user scaling factor, useful for applications which require
847 `zooming'.
848
849 \membersection{wxDC::StartDoc}\label{wxdcstartdoc}
850
851 \func{bool}{StartDoc}{\param{const wxString\& }{message}}
852
853 Starts a document (only relevant when outputting to a printer).
854 Message is a message to show whilst printing.
855
856 \membersection{wxDC::StartPage}\label{wxdcstartpage}
857
858 \func{bool}{StartPage}{\void}
859
860 Starts a document page (only relevant when outputting to a printer).
861