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