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