]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/dc.tex
on Linux, not GTK
[wxWidgets.git] / docs / latex / wx / dc.tex
CommitLineData
a660d684
KB
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,
fe604ccd 5so a window can have a device context associated with it, and a printer also has a device context.
a660d684
KB
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
eb750029
VZ
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
a660d684
KB
19\wxheading{Derived from}
20
21\helpref{wxObject}{wxobject}
22
954b8ae6
JS
23\wxheading{Include files}
24
25<wx/dc.h>
26
a660d684
KB
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
1f897d25
VZ
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},
cc81d32f 64 \param{bool }{useMask = false}, \param{wxCoord}{ xsrcMask = -1}, \param{wxCoord}{ ysrcMask = -1}}
a660d684
KB
65
66Copy from a source DC to this DC, specifying the destination
0cbff120
JS
67coordinates, size of area to copy, source DC, source coordinates,
68logical function, whether to use a bitmap mask, and mask source position.
a660d684
KB
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
cc81d32f 88\docparam{useMask}{If true, Blit does a transparent blit using the mask that is associated with the bitmap
0cbff120 89selected into the source device context. The Windows implementation does the following if MaskBlt cannot be used:
a660d684
KB
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.
0cbff120 106
aef94d68
JS
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
0cbff120
JS
109or the explicit mask blitting code above is used, by using \helpref{wxSystemOptions}{wxsystemoptions} and
110setting the {\bf no-maskblt} option to 1.
111
a660d684
KB
112}
113
0cbff120
JS
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
a660d684
KB
121\wxheading{Remarks}
122
123There is partial support for Blit in wxPostScriptDC, under X.
124
125See \helpref{wxMemoryDC}{wxmemorydc} for typical usage.
126
ac1edf35 127\wxheading{See also}
a660d684
KB
128
129\helpref{wxMemoryDC}{wxmemorydc}, \helpref{wxBitmap}{wxbitmap}, \helpref{wxMask}{wxmask}
130
aef94d68 131\begin{comment}
0cbff120
JS
132\membersection{wxDC::CacheEnabled}\label{wxdccacheenabled}
133
134\func{static bool}{CacheEnabled}{\void}
135
cc81d32f 136On supported platforms (currently only Windows), returns true
0cbff120
JS
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}
aef94d68 147\end{comment}
0cbff120 148
f6bcfd97
BP
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
a660d684
KB
161\membersection{wxDC::Clear}\label{wxdcclear}
162
163\func{void}{Clear}{\void}
164
165Clears the device context using the current background brush.
166
aef94d68 167\begin{comment}
0cbff120
JS
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}
aef94d68 185\end{comment}
0cbff120 186
a660d684
KB
187\membersection{wxDC::CrossHair}\label{wxdccrosshair}
188
1f897d25 189\func{void}{CrossHair}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
a660d684
KB
190
191Displays a cross hair using the current pen. This is a vertical
fe604ccd 192and horizontal line the height and width of the window, centred
a660d684
KB
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
1f897d25 204\func{wxCoord}{DeviceToLogicalX}{\param{wxCoord}{ x}}
a660d684
KB
205
206Convert device X coordinate to logical coordinate, using the current
207mapping mode.
208
209\membersection{wxDC::DeviceToLogicalXRel}\label{wxdcdevicetologicalxrel}
210
1f897d25 211\func{wxCoord}{DeviceToLogicalXRel}{\param{wxCoord}{ x}}
a660d684
KB
212
213Convert device X coordinate to relative logical coordinate, using the current
1387b68a
GD
214mapping mode but ignoring the x axis orientation.
215Use this function for converting a width, for example.
a660d684
KB
216
217\membersection{wxDC::DeviceToLogicalY}\label{wxdcdevicetologicaly}
218
1f897d25 219\func{wxCoord}{DeviceToLogicalY}{\param{wxCoord}{ y}}
a660d684
KB
220
221Converts device Y coordinate to logical coordinate, using the current
222mapping mode.
223
224\membersection{wxDC::DeviceToLogicalYRel}\label{wxdcdevicetologicalyrel}
225
1f897d25 226\func{wxCoord}{DeviceToLogicalYRel}{\param{wxCoord}{ y}}
a660d684
KB
227
228Convert device Y coordinate to relative logical coordinate, using the current
1387b68a
GD
229mapping mode but ignoring the y axis orientation.
230Use this function for converting a height, for example.
a660d684
KB
231
232\membersection{wxDC::DrawArc}\label{wxdcdrawarc}
233
1f897d25 234\func{void}{DrawArc}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}, \param{double}{ xc}, \param{double}{ yc}}
a660d684 235
b8de493f 236Draws an arc of a circle, centred on ({\it xc, yc}), with starting point ({\it x1, y1})
a660d684
KB
237and ending at ({\it x2, y2}). The current pen is used for the outline
238and the current brush for filling the shape.
239
b8de493f
JS
240The arc is drawn in an anticlockwise direction from the start point to the end point.
241
72fd19a1
JS
242\membersection{wxDC::DrawBitmap}\label{wxdcdrawbitmap}
243
1f897d25 244\func{void}{DrawBitmap}{\param{const wxBitmap\&}{ bitmap}, \param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{bool}{ transparent}}
72fd19a1 245
cc81d32f 246Draw a bitmap on the device context at the specified point. If {\it transparent} is true and the bitmap has
72fd19a1
JS
247a transparency mask, the bitmap will be drawn transparently.
248
41fbc841 249When drawing a mono-bitmap, the current text foreground colour will be used to draw the foreground
9000c624 250of the bitmap (all bits set to 1), and the current text background colour to draw the background
fa482912 251(all bits set to 0). See also \helpref{SetTextForeground}{wxdcsettextforeground},
9000c624 252\helpref{SetTextBackground}{wxdcsettextbackground} and \helpref{wxMemoryDC}{wxmemorydc}.
41fbc841 253
cd9da200
VZ
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
260Draws a check mark inside the given rectangle.
261
0371e9a8
VZ
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
268Draws a circle with the given centre and radius.
269
270\wxheading{See also}
271
272\helpref{DrawEllipse}{wxdcdrawellipse}
273
a660d684
KB
274\membersection{wxDC::DrawEllipse}\label{wxdcdrawellipse}
275
1f897d25 276\func{void}{DrawEllipse}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
a660d684 277
0371e9a8
VZ
278\func{void}{DrawEllipse}{\param{const wxPoint\&}{ pt}, \param{const wxSize\&}{ size}}
279
280\func{void}{DrawEllipse}{\param{const wxRect\&}{ rect}}
281
282Draws an ellipse contained in the rectangle specified either with the given top
283left corner and the given size or directly. The current pen is used for the
284outline and the current brush for filling the shape.
285
286\wxheading{See also}
287
288\helpref{DrawCircle}{wxdcdrawcircle}
a660d684
KB
289
290\membersection{wxDC::DrawEllipticArc}\label{wxdcdrawellipticarc}
291
1f897d25 292\func{void}{DrawEllipticArc}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height},
a660d684
KB
293 \param{double}{ start}, \param{double}{ end}}
294
06d20283 295Draws an arc of an ellipse. The current pen is used for drawing the arc and
267a7108 296the current brush is used for drawing the pie.
a660d684
KB
297
298{\it x} and {\it y} specify the x and y coordinates of the upper-left corner of the rectangle that contains
299the ellipse.
300
06d20283 301{\it width} and {\it height} specify the width and height of the rectangle that contains
a660d684
KB
302the ellipse.
303
304{\it start} and {\it end} specify the start and end of the arc relative to the three-o'clock
305position from the center of the rectangle. Angles are specified
306in degrees (360 is a complete circle). Positive values mean
307counter-clockwise motion. If {\it start} is equal to {\it end}, a
308complete ellipse will be drawn.
309
310\membersection{wxDC::DrawIcon}\label{wxdcdrawicon}
311
1f897d25 312\func{void}{DrawIcon}{\param{const wxIcon\&}{ icon}, \param{wxCoord}{ x}, \param{wxCoord}{ y}}
a660d684
KB
313
314Draw an icon on the display (does nothing if the device context is PostScript).
fe604ccd 315This can be the simplest way of drawing bitmaps on a window.
a660d684
KB
316
317\membersection{wxDC::DrawLine}\label{wxdcdrawline}
318
1f897d25 319\func{void}{DrawLine}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}}
a660d684
KB
320
321Draws a line from the first point to the second. The current pen is used
322for drawing the line.
323
324\membersection{wxDC::DrawLines}\label{wxdcdrawlines}
325
1f897d25 326\func{void}{DrawLines}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0}}
a660d684 327
1f897d25 328\func{void}{DrawLines}{\param{wxList *}{points}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0}}
a660d684
KB
329
330Draws lines using an array of {\it points} of size {\it n}, or list of
331pointers to points, adding the optional offset coordinate. The current
332pen is used for drawing the lines. The programmer is responsible for
333deleting the list of points.
334
06d20283
RD
335\pythonnote{The wxPython version of this method accepts a Python list
336of wxPoint objects.}
337
f3539882
VZ
338\perlnote{The wxPerl version of this method accepts
339 as its first parameter a reference to an array
340 of wxPoint objects.}
341
a660d684
KB
342\membersection{wxDC::DrawPolygon}\label{wxdcdrawpolygon}
343
1f897d25 344\func{void}{DrawPolygon}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0},\\
a660d684
KB
345 \param{int }{fill\_style = wxODDEVEN\_RULE}}
346
1f897d25 347\func{void}{DrawPolygon}{\param{wxList *}{points}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0},\\
a660d684
KB
348 \param{int }{fill\_style = wxODDEVEN\_RULE}}
349
350Draws a filled polygon using an array of {\it points} of size {\it n},
351or list of pointers to points, adding the optional offset coordinate.
352
353The last argument specifies the fill rule: {\bf wxODDEVEN\_RULE} (the
354default) or {\bf wxWINDING\_RULE}.
355
356The current pen is used for drawing the outline, and the current brush
357for filling the shape. Using a transparent brush suppresses filling.
358The programmer is responsible for deleting the list of points.
359
360Note that wxWindows automatically closes the first and last points.
361
06d20283
RD
362\pythonnote{The wxPython version of this method accepts a Python list
363of wxPoint objects.}
364
f3539882
VZ
365\perlnote{The wxPerl version of this method accepts
366 as its first parameter a reference to an array
367 of wxPoint objects.}
368
a660d684
KB
369\membersection{wxDC::DrawPoint}\label{wxdcdrawpoint}
370
1f897d25 371\func{void}{DrawPoint}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
a660d684
KB
372
373Draws a point using the current pen.
374
375\membersection{wxDC::DrawRectangle}\label{wxdcdrawrectangle}
376
1f897d25 377\func{void}{DrawRectangle}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
a660d684
KB
378
379Draws a rectangle with the given top left corner, and with the given
380size. The current pen is used for the outline and the current brush
381for filling the shape.
382
1f897d25
VZ
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
387Draws the text rotated by {\it angle} degrees.
388
4770df95
VZ
389{\bf NB:} Under Win9x only TrueType fonts can be drawn by this function. In
390particular, a font different from {\tt wxNORMAL\_FONT} should be used as the
391latter is not a TrueType font. {\tt wxSWISS\_FONT} is an example of a font
392which is.
393
1f897d25
VZ
394\wxheading{See also}
395
396\helpref{DrawText}{wxdcdrawtext}
397
a660d684
KB
398\membersection{wxDC::DrawRoundedRectangle}\label{wxdcdrawroundedrectangle}
399
1f897d25 400\func{void}{DrawRoundedRectangle}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}, \param{double}{ radius = 20}}
a660d684
KB
401
402Draws a rectangle with the given top left corner, and with the given
403size. The corners are quarter-circles using the given radius. The
404current pen is used for the outline and the current brush for filling
405the shape.
406
407If {\it radius} is positive, the value is assumed to be the
408radius of the rounded corner. If {\it radius} is negative,
409the absolute value is assumed to be the {\it proportion} of the smallest
410dimension of the rectangle. This means that the corner can be
411a sensible size relative to the size of the rectangle, and also avoids
412the strange effects X produces when the corners are too big for
413the rectangle.
414
415\membersection{wxDC::DrawSpline}\label{wxdcdrawspline}
416
417\func{void}{DrawSpline}{\param{wxList *}{points}}
418
419Draws a spline between all given control points, using the current
420pen. Doesn't delete the wxList and contents. The spline is drawn
421using a series of lines, using an algorithm taken from the X drawing
422program `XFIG'.
423
1f897d25 424\func{void}{DrawSpline}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}, \param{wxCoord}{ x3}, \param{wxCoord}{ y3}}
a660d684
KB
425
426Draws a three-point spline using the current pen.
427
06d20283
RD
428\pythonnote{The wxPython version of this method accepts a Python list
429of wxPoint objects.}
430
f3539882
VZ
431\perlnote{The wxPerl version of this method accepts a reference to an array
432 of wxPoint objects.}
433
a660d684
KB
434\membersection{wxDC::DrawText}\label{wxdcdrawtext}
435
1f897d25 436\func{void}{DrawText}{\param{const wxString\& }{text}, \param{wxCoord}{ x}, \param{wxCoord}{ y}}
a660d684
KB
437
438Draws a text string at the specified point, using the current text font,
439and the current text foreground and background colours.
440
441The coordinates refer to the top-left corner of the rectangle bounding
442the string. See \helpref{wxDC::GetTextExtent}{wxdcgettextextent} for how
443to get the dimensions of a text string, which can be used to position the
444text more precisely.
445
f6bcfd97
BP
446{\bf NB:} under wxGTK the current
447\helpref{logical function}{wxdcgetlogicalfunction} is used by this function
448but it is ignored by wxMSW. Thus, you should avoid using logical functions
449with this function in portable programs.
450
aef94d68 451\begin{comment}
0cbff120
JS
452\membersection{wxDC::EnableCache}\label{wxdcenablecache}
453
454\func{static void}{EnableCache}{\param{bool}{ enableCache}}
455
456On supported platforms (currently only Windows), enables the DC cache
457which can speed up the \helpref{Blit}{wxdcblit} operation when
458drawing a large number of masked bitmaps.
459
460If using the cache functions in your code, please test for the
461wxUSE\_DC\_CACHEING preprocessor symbol for portability.
462
463\wxheading{See also}
464
465\helpref{wxDC::CacheEnabled}{wxdccacheenabled}, \helpref{wxDC::ClearCache}
aef94d68 466\end{comment}
0cbff120 467
a660d684
KB
468\membersection{wxDC::EndDoc}\label{wxdcenddoc}
469
470\func{void}{EndDoc}{\void}
471
472Ends a document (only relevant when outputting to a printer).
473
474\membersection{wxDC::EndDrawing}\label{wxdcenddrawing}
475
476\func{void}{EndDrawing}{\void}
477
478Allows optimization of drawing code under MS Windows. Enclose
479drawing primitives between {\bf BeginDrawing} and {\bf EndDrawing}\rtfsp
480calls.
481
482\membersection{wxDC::EndPage}\label{wxdcendpage}
483
484\func{void}{EndPage}{\void}
485
486Ends a document page (only relevant when outputting to a printer).
487
488\membersection{wxDC::FloodFill}\label{wxdcfloodfill}
489
387ebd3e 490\func{bool}{FloodFill}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{const wxColour\&}{ colour}, \param{int}{ style=wxFLOOD\_SURFACE}}
a660d684 491
15770d1a
JS
492Flood fills the device context starting from the given point, using
493the {\it current brush colour}, and using a style:
a660d684
KB
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
cc81d32f 500Returns false if the operation failed.
387ebd3e 501
b1699cd3 502{\it Note:} The present implementation for non-Windows platforms may fail to find
387ebd3e 503colour borders if the pixels do not match the colour exactly. However the
cc81d32f 504function will still return true.
a660d684
KB
505
506\membersection{wxDC::GetBackground}\label{wxdcgetbackground}
507
c0ed460c 508\func{wxBrush\&}{GetBackground}{\void}
a660d684 509
f6bcfd97
BP
510\constfunc{const wxBrush\&}{GetBackground}{\void}
511
a660d684
KB
512Gets the brush used for painting the background (see \helpref{wxDC::SetBackground}{wxdcsetbackground}).
513
f6bcfd97
BP
514\membersection{wxDC::GetBackgroundMode}\label{wxdcgetbackgroundmode}
515
516\constfunc{int}{GetBackgroundMode}{\void}
517
518Returns the current background mode: {\tt wxSOLID} or {\tt wxTRANSPARENT}.
519
520\wxheading{See also}
521
522\helpref{SetBackgroundMode}{wxdcsetbackgroundmode}
523
a660d684
KB
524\membersection{wxDC::GetBrush}\label{wxdcgetbrush}
525
c0ed460c 526\func{wxBrush\&}{GetBrush}{\void}
a660d684 527
f6bcfd97
BP
528\constfunc{const wxBrush\&}{GetBrush}{\void}
529
a660d684
KB
530Gets the current brush (see \helpref{wxDC::SetBrush}{wxdcsetbrush}).
531
532\membersection{wxDC::GetCharHeight}\label{wxdcgetcharheight}
533
1f897d25 534\func{wxCoord}{GetCharHeight}{\void}
a660d684
KB
535
536Gets the character height of the currently set font.
537
538\membersection{wxDC::GetCharWidth}\label{wxdcgetcharwidth}
539
1f897d25 540\func{wxCoord}{GetCharWidth}{\void}
a660d684
KB
541
542Gets the average character width of the currently set font.
543
fe604ccd 544\membersection{wxDC::GetClippingBox}\label{wxdcgetclippingbox}
a660d684 545
1f897d25 546\func{void}{GetClippingBox}{\param{wxCoord}{ *x}, \param{wxCoord}{ *y}, \param{wxCoord}{ *width}, \param{wxCoord}{ *height}}
a660d684
KB
547
548Gets the rectangle surrounding the current clipping region.
549
06d20283
RD
550\pythonnote{No arguments are required and the four values defining the
551rectangle are returned as a tuple.}
552
5873607e 553\perlnote{This method takes no arguments and returns a four element list
0a67eeac 554{\tt ( x, y, width, height )}}
5873607e 555
a660d684
KB
556\membersection{wxDC::GetFont}\label{wxdcgetfont}
557
c0ed460c 558\func{wxFont\&}{GetFont}{\void}
a660d684 559
f6bcfd97
BP
560\constfunc{const wxFont\&}{GetFont}{\void}
561
a660d684
KB
562Gets the current font (see \helpref{wxDC::SetFont}{wxdcsetfont}).
563
564\membersection{wxDC::GetLogicalFunction}\label{wxdcgetlogicalfunction}
565
566\func{int}{GetLogicalFunction}{\void}
567
568Gets the current logical function (see \helpref{wxDC::SetLogicalFunction}{wxdcsetlogicalfunction}).
569
570\membersection{wxDC::GetMapMode}\label{wxdcgetmapmode}
571
572\func{int}{GetMapMode}{\void}
573
574Gets 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
cc81d32f 580Returns true if device context optimization is on.
a660d684
KB
581See \helpref{wxDC::SetOptimization}{wxsetoptimization} for details.
582
583\membersection{wxDC::GetPen}\label{wxdcgetpen}
584
c0ed460c 585\func{wxPen\&}{GetPen}{\void}
a660d684 586
f6bcfd97
BP
587\constfunc{const wxPen\&}{GetPen}{\void}
588
a660d684
KB
589Gets the current pen (see \helpref{wxDC::SetPen}{wxdcsetpen}).
590
591\membersection{wxDC::GetPixel}\label{wxdcgetpixel}
592
1f897d25 593\func{bool}{GetPixel}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxColour *}{colour}}
a660d684
KB
594
595Sets {\it colour} to the colour at the specified location. Windows only; an X implementation
e2a6f233 596is being worked on. Not available for wxPostScriptDC or wxMetafileDC.
a660d684 597
86e78222
RD
598\pythonnote{For wxPython the wxColour value is returned and is not
599required as a parameter.}
600
5873607e
VZ
601\perlnote{This method only takes the parameters {\tt x} and {\tt y} and returns
602a Wx::Colour value}
603
a660d684
KB
604\membersection{wxDC::GetSize}\label{wxdcgetsize}
605
1f897d25 606\func{void}{GetSize}{\param{wxCoord *}{width}, \param{wxCoord *}{height}}
a660d684
KB
607
608For a PostScript device context, this gets the maximum size of graphics
609drawn so far on the device context.
610
611For a Windows printer device context, this gets the horizontal and vertical
612resolution. It can be used to scale graphics to fit the page when using
613a Windows printer device context. For example, if {\it maxX} and {\it maxY}\rtfsp
614represent the maximum horizontal and vertical `pixel' values used in your
615application, the following code will scale the graphic to fit on the
616printer page:
617
618\begin{verbatim}
1f897d25 619 wxCoord w, h;
a660d684
KB
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
2233e5b8
RD
626\pythonnote{In place of a single overloaded method name, wxPython
627implements the following methods:\par
628\indented{2cm}{\begin{twocollist}
c9110876
VS
629\twocolitem{{\bf GetSize()}}{Returns a wxSize}
630\twocolitem{{\bf GetSizeTuple()}}{Returns a 2-tuple (width, height)}
2233e5b8
RD
631\end{twocollist}}
632}
06d20283 633
5873607e
VZ
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
0a67eeac 638 {\tt ( width, height )}}
5873607e
VZ
639\end{twocollist}
640}}
641
a660d684
KB
642\membersection{wxDC::GetTextBackground}\label{wxdcgettextbackground}
643
644\func{wxColour\&}{GetTextBackground}{\void}
645
f6bcfd97
BP
646\constfunc{const wxColour\&}{GetTextBackground}{\void}
647
a660d684
KB
648Gets the current text background colour (see \helpref{wxDC::SetTextBackground}{wxdcsettextbackground}).
649
650\membersection{wxDC::GetTextExtent}\label{wxdcgettextextent}
651
1f897d25
VZ
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}}
a660d684
KB
654
655Gets 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
657the total width and height respectively, {\it descent} is the
658dimension from the baseline of the font to the bottom of the
659descender, and {\it externalLeading} is any extra vertical space added
660to the font by the font designer (usually is zero).
661
662The optional parameter {\it font} specifies an alternative
663to the currently selected font: but note that this does not
664yet work under Windows, so you need to set a font for
665the device context first.
666
667See also \helpref{wxFont}{wxfont}, \helpref{wxDC::SetFont}{wxdcsetfont}.
668
06d20283
RD
669\pythonnote{The following methods are implemented in wxPython:\par
670\indented{2cm}{\begin{twocollist}
c9110876
VS
671\twocolitem{{\bf GetTextExtent(string)}}{Returns a 2-tuple, (width, height)}
672\twocolitem{{\bf GetFullTextExtent(string, font=NULL)}}{Returns a
06d20283
RD
6734-tuple, (width, height, descent, externalLeading) }
674\end{twocollist}}
675}
676
5873607e
VZ
677\perlnote{In wxPerl this method is implemented as
678 {\bf GetTextExtent( string, font = undef )} returning a four element
0a67eeac 679 array {\tt ( width, height, descent, externalLeading )}
5873607e
VZ
680}
681
a660d684
KB
682\membersection{wxDC::GetTextForeground}\label{wxdcgettextforeground}
683
684\func{wxColour\&}{GetTextForeground}{\void}
685
f6bcfd97
BP
686\constfunc{const wxColour\&}{GetTextForeground}{\void}
687
a660d684
KB
688Gets the current text foreground colour (see \helpref{wxDC::SetTextForeground}{wxdcsettextforeground}).
689
16964b5e
VS
690
691\membersection{wxDC::GetUserScale}\label{wxdcgetuserscale}
692
693\func{void}{GetUserScale}{\param{double}{ *x}, \param{double}{ *y}}
694
695Gets the current user scale factor (set by \helpref{SetUserScale}{wxdcsetuserscale}).
696
2edb0bde 697\perlnote{In wxPerl this method takes no arguments and return a two element
0a67eeac 698 array {\tt ( x, y )}}
16964b5e 699
a660d684
KB
700\membersection{wxDC::LogicalToDeviceX}\label{wxdclogicaltodevicex}
701
1f897d25 702\func{wxCoord}{LogicalToDeviceX}{\param{wxCoord}{ x}}
a660d684
KB
703
704Converts logical X coordinate to device coordinate, using the current
705mapping mode.
706
707\membersection{wxDC::LogicalToDeviceXRel}\label{wxdclogicaltodevicexrel}
708
1f897d25 709\func{wxCoord}{LogicalToDeviceXRel}{\param{wxCoord}{ x}}
a660d684
KB
710
711Converts logical X coordinate to relative device coordinate, using the current
1387b68a
GD
712mapping mode but ignoring the x axis orientation.
713Use this for converting a width, for example.
a660d684
KB
714
715\membersection{wxDC::LogicalToDeviceY}\label{wxdclogicaltodevicey}
716
1f897d25 717\func{wxCoord}{LogicalToDeviceY}{\param{wxCoord}{ y}}
a660d684
KB
718
719Converts logical Y coordinate to device coordinate, using the current
720mapping mode.
721
722\membersection{wxDC::LogicalToDeviceYRel}\label{wxdclogicaltodeviceyrel}
723
1f897d25 724\func{wxCoord}{LogicalToDeviceYRel}{\param{wxCoord}{ y}}
a660d684
KB
725
726Converts logical Y coordinate to relative device coordinate, using the current
1387b68a
GD
727mapping mode but ignoring the y axis orientation.
728Use this for converting a height, for example.
a660d684
KB
729
730\membersection{wxDC::MaxX}\label{wxdcmaxx}
731
1f897d25 732\func{wxCoord}{MaxX}{\void}
a660d684
KB
733
734Gets the maximum horizontal extent used in drawing commands so far.
735
736\membersection{wxDC::MaxY}\label{wxdcmaxy}
737
1f897d25 738\func{wxCoord}{MaxY}{\void}
a660d684
KB
739
740Gets the maximum vertical extent used in drawing commands so far.
741
742\membersection{wxDC::MinX}\label{wxdcminx}
743
1f897d25 744\func{wxCoord}{MinX}{\void}
a660d684
KB
745
746Gets the minimum horizontal extent used in drawing commands so far.
747
748\membersection{wxDC::MinY}\label{wxdcminy}
749
1f897d25 750\func{wxCoord}{MinY}{\void}
a660d684
KB
751
752Gets the minimum vertical extent used in drawing commands so far.
753
754\membersection{wxDC::Ok}\label{wxdcok}
755
756\func{bool}{Ok}{\void}
757
cc81d32f 758Returns true if the DC is ok to use.
a660d684 759
f6bcfd97
BP
760\membersection{wxDC::ResetBoundingBox}\label{wxdcresetboundingbox}
761
762\func{void}{ResetBoundingBox}{\void}
763
764Resets the bounding box: after a call to this function, the bounding box
765doesn't contain anything.
766
767\wxheading{See also}
768
769\helpref{CalcBoundingBox}{wxdccalcboundingbox}
770
1387b68a
GD
771\membersection{wxDC::SetAxisOrientation}\label{wxdcsetaxisorientation}
772
773\func{void}{SetAxisOrientation}{\param{bool}{ xLeftRight},
774 \param{bool}{ yBottomUp}}
775
776Sets the x and y axis orientation (i.e., the direction from lowest to
777highest values on the axis). The default orientation is the natural
778orientation, 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
783left to right orientation, false to invert it.}
784
785\docparam{yBottomUp}{True to set the y axis orientation to the natural
786bottom up orientation, false to invert it.}
787
a660d684
KB
788\membersection{wxDC::SetDeviceOrigin}\label{wxdcsetdeviceorigin}
789
1f897d25 790\func{void}{SetDeviceOrigin}{\param{wxCoord}{ x}, \param{wxCoord}{ y}}
a660d684
KB
791
792Sets the device origin (i.e., the origin in pixels after scaling has been
793applied).
794
795This function may be useful in Windows printing
796operations for placing a graphic on a page.
797
798\membersection{wxDC::SetBackground}\label{wxdcsetbackground}
799
800\func{void}{SetBackground}{\param{const wxBrush\& }{brush}}
801
802Sets 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
809whether text will be drawn with a background colour or not.
810
811\membersection{wxDC::SetClippingRegion}\label{wxdcsetclippingregion}
812
1f897d25 813\func{void}{SetClippingRegion}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}}
a660d684 814
5230934a
VZ
815\func{void}{SetClippingRegion}{\param{const wxPoint\& }{pt}, \param{const wxSize\& }{sz}}
816
817\func{void}{SetClippingRegion}{\param{const wxRect\&}{ rect}}
818
a724d789
JS
819\func{void}{SetClippingRegion}{\param{const wxRegion\&}{ region}}
820
5230934a
VZ
821Sets the clipping region for this device context to the intersection of the
822given region described by the parameters of this method and the previously set
823clipping region. You should call
824\helpref{DestroyClippingRegion}{wxdcdestroyclippingregion} if you want to set
825the clipping region exactly to the region specified.
826
827The clipping region is an area to which drawing is restricted. Possible uses
828for the clipping region are for clipping text or for speeding up window redraws
829when only a known area of the screen is damaged.
a660d684 830
a724d789
JS
831\wxheading{See also}
832
833\helpref{wxDC::DestroyClippingRegion}{wxdcdestroyclippingregion}, \helpref{wxRegion}{wxregion}
a660d684
KB
834
835\membersection{wxDC::SetPalette}\label{wxdcsetpalette}
836
837\func{void}{SetPalette}{\param{const wxPalette\& }{palette}}
838
fe604ccd 839If this is a window DC or memory DC, assigns the given palette to the window
a660d684
KB
840or bitmap associated with the DC. If the argument is wxNullPalette, the current
841palette is selected out of the device context, and the original palette
842restored.
843
844See \helpref{wxPalette}{wxpalette} for further details.
845
846\membersection{wxDC::SetBrush}\label{wxdcsetbrush}
847
848\func{void}{SetBrush}{\param{const wxBrush\& }{brush}}
849
850Sets the current brush for the DC.
851
852If the argument is wxNullBrush, the current brush is selected out of the device
853context, and the original brush restored, allowing the current brush to
854be destroyed safely.
855
856See also \helpref{wxBrush}{wxbrush}.
857
9000c624
RR
858See also \helpref{wxMemoryDC}{wxmemorydc} for the interpretation of colours
859when drawing into a monochrome bitmap.
860
a660d684
KB
861\membersection{wxDC::SetFont}\label{wxdcsetfont}
862
863\func{void}{SetFont}{\param{const wxFont\& }{font}}
864
3e482a64
VZ
865Sets the current font for the DC. It must be a valid font, in particular you
866should not pass {\tt wxNullFont} to this method.
a660d684
KB
867
868See also \helpref{wxFont}{wxfont}.
869
870\membersection{wxDC::SetLogicalFunction}\label{wxdcsetlogicalfunction}
871
872\func{void}{SetLogicalFunction}{\param{int}{ function}}
873
fe604ccd 874Sets the current logical function for the device context. This determines how
a660d684
KB
875a source pixel (from a pen or brush colour, or source device context if
876using \helpref{wxDC::Blit}{wxdcblit}) combines with a destination pixel in the
877current device context.
878
879The possible values
880and their meaning in terms of source and destination pixel values are
881as follows:
882
883\begin{verbatim}
884wxAND src AND dst
885wxAND_INVERT (NOT src) AND dst
886wxAND_REVERSE src AND (NOT dst)
887wxCLEAR 0
888wxCOPY src
889wxEQUIV (NOT src) XOR dst
890wxINVERT NOT dst
891wxNAND (NOT src) OR (NOT dst)
892wxNOR (NOT src) AND (NOT dst)
893wxNO_OP dst
894wxOR src OR dst
895wxOR_INVERT (NOT src) OR dst
896wxOR_REVERSE src OR (NOT dst)
897wxSET 1
898wxSRC_INVERT NOT src
899wxXOR src XOR dst
900\end{verbatim}
901
902The default is wxCOPY, which simply draws with the current colour.
903The others combine the current colour and the background using a
6453876e 904logical operation. wxINVERT is commonly used for drawing rubber bands or
a660d684
KB
905moving 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
911The {\it mapping mode} of the device context defines the unit of
912measurement used to convert logical units to device units. Note that
913in X, text drawing isn't handled consistently with the mapping mode; a
914font is always specified in point size. However, setting the {\it
915user scale} (see \helpref{wxDC::SetUserScale}{wxdcsetuserscale}) scales the text appropriately. In
2edb0bde 916Windows, scalable TrueType fonts are always used; in X, results depend
a660d684
KB
917on availability of fonts, but usually a reasonable match is found.
918
919Note that the coordinate origin should ideally be selectable, but for
920now is always at the top left of the screen/printer.
921
922Drawing to a Windows printer device context under UNIX
923uses the current mapping mode, but mapping mode is currently ignored for
924PostScript output.
925
926The mapping mode can be one of the following:
927
928\begin{twocollist}\itemsep=0pt
e3065973 929\twocolitem{wxMM\_TWIPS}{Each logical unit is 1/20 of a point, or 1/1440 of
a660d684 930 an inch.}
e3065973
JS
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.}
a660d684
KB
935\end{twocollist}
936
937\membersection{wxDC::SetOptimization}\label{wxsetoptimization}
938
939\func{void}{SetOptimization}{\param{bool }{optimize}}
940
cc81d32f 941If {\it optimize} is true (the default), this function sets optimization mode on.
a660d684
KB
942This currently means that under X, the device context will not try to set a pen or brush
943property if it is known to be set already. This approach can fall down
944if non-wxWindows code is using the same device context or window, for example
945when the window is a panel on which the windowing system draws panel items.
946The wxWindows device context 'memory' will now be out of step with reality.
947
948Setting optimization off, drawing, then setting it back on again, is a trick
949that must occasionally be employed.
950
951\membersection{wxDC::SetPen}\label{wxdcsetpen}
952
953\func{void}{SetPen}{\param{const wxPen\& }{pen}}
954
955Sets the current pen for the DC.
956
957If the argument is wxNullPen, the current pen is selected out of the device
958context, and the original pen restored.
959
9000c624
RR
960See also \helpref{wxMemoryDC}{wxmemorydc} for the interpretation of colours
961when drawing into a monochrome bitmap.
962
a660d684
KB
963\membersection{wxDC::SetTextBackground}\label{wxdcsettextbackground}
964
965\func{void}{SetTextBackground}{\param{const wxColour\& }{colour}}
966
967Sets 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
973Sets the current text foreground colour for the DC.
974
9000c624
RR
975See also \helpref{wxMemoryDC}{wxmemorydc} for the interpretation of colours
976when drawing into a monochrome bitmap.
977
a660d684
KB
978\membersection{wxDC::SetUserScale}\label{wxdcsetuserscale}
979
980\func{void}{SetUserScale}{\param{double}{ xScale}, \param{double}{ yScale}}
981
982Sets 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
989Starts a document (only relevant when outputting to a printer).
990Message is a message to show whilst printing.
991
992\membersection{wxDC::StartPage}\label{wxdcstartpage}
993
994\func{bool}{StartPage}{\void}
995
996Starts a document page (only relevant when outputting to a printer).
997
6c975af1
VZ
998\section{\class{wxDCClipper}}\label{wxdcclipper}
999
1000This is a small helper class which sets the specified to its constructor
2edb0bde 1001clipping region and then automatically destroys it in its destructor. Using
6c975af1
VZ
1002it ensures that unwanted clipping region is not left set on the DC.
1003
1004\wxheading{Derived from}
1005
1006No 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
1024Constructor: sets the the clipping region for the given device context to the
1025specified rectangle.
1026
1027\membersection{wxDCClipper::\destruct{wxDCClipper}}
1028
1029\func{}{\destruct{wxDCClipper}}{\void}
1030
2edb0bde 1031Destructor: destroys the clipping region set in the constructor.
6c975af1 1032