]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/dc.tex
Unicode overview added
[wxWidgets.git] / docs / latex / wx / dc.tex
1 \section{\class{wxDC}}\label{wxdc}
2
3 A wxDC is a {\it device context} onto which graphics and text can be drawn.
4 It is intended to represent a number of output devices in a generic way,
5 so a window can have a device context associated with it, and a printer also has a device context.
6 In this way, the same piece of code may write to a number of different devices,
7 if the device context is used as a parameter.
8
9 Derived types of wxDC have documentation for specific features
10 only, so refer to this section for most device context information.
11
12 \wxheading{Derived from}
13
14 \helpref{wxObject}{wxobject}
15
16 \wxheading{Include files}
17
18 <wx/dc.h>
19
20 \wxheading{See also}
21
22 \helpref{Overview}{dcoverview}
23
24 \latexignore{\rtfignore{\wxheading{Members}}}
25
26 \membersection{wxDC::wxDC}
27
28 \func{}{wxDC}{\void}
29
30 Constructor.
31
32 \membersection{wxDC::\destruct{wxDC}}
33
34 \func{}{\destruct{wxDC}}{\void}
35
36 Destructor.
37
38 \membersection{wxDC::BeginDrawing}\label{wxdcbegindrawing}
39
40 \func{void}{BeginDrawing}{\void}
41
42 Allows optimization of drawing code under MS Windows. Enclose
43 drawing primitives between {\bf BeginDrawing} and {\bf EndDrawing}\rtfsp
44 calls.
45
46 Drawing to a wxDialog panel device context outside of a
47 system-generated OnPaint event {\it requires} this pair of calls to
48 enclose drawing code. This is because a Windows dialog box does not have
49 a retained device context associated with it, and selections such as pen
50 and brush settings would be lost if the device context were obtained and
51 released for each drawing operation.
52
53 \membersection{wxDC::Blit}\label{wxdcblit}
54
55 \func{bool}{Blit}{\param{long}{ xdest}, \param{long}{ ydest}, \param{long}{ width}, \param{long}{ height},
56 \param{wxDC* }{source}, \param{long}{ xsrc}, \param{long}{ ysrc}, \param{int}{ logicalFunc = wxCOPY},
57 \param{bool }{useMask = FALSE}}
58
59 Copy from a source DC to this DC, specifying the destination
60 coordinates, size of area to copy, source DC, source coordinates, and
61 logical function.
62
63 \wxheading{Parameters}
64
65 \docparam{xdest}{Destination device context x position.}
66
67 \docparam{ydest}{Destination device context y position.}
68
69 \docparam{width}{Width of source area to be copied.}
70
71 \docparam{height}{Height of source area to be copied.}
72
73 \docparam{source}{Source device context.}
74
75 \docparam{xsrc}{Source device context x position.}
76
77 \docparam{ysrc}{Source device context y position.}
78
79 \docparam{logicalFunc}{Logical function to use: see \helpref{wxDC::SetLogicalFunction}{wxdcsetlogicalfunction}.}
80
81 \docparam{useMask}{If TRUE, Blit does a transparent blit using the mask that is associated with the bitmap
82 selected into the source device context. The Windows implementation does the following:
83
84 \begin{enumerate}
85 \item Creates a temporary bitmap and copies the destination area into it.
86 \item Copies the source area into the temporary bitmap using the specified logical function.
87 \item Sets the masked area in the temporary bitmap to BLACK by ANDing the
88 mask bitmap with the temp bitmap with the foreground colour set to WHITE
89 and the bg colour set to BLACK.
90 \item Sets the unmasked area in the destination area to BLACK by ANDing the
91 mask bitmap with the destination area with the foreground colour set to BLACK
92 and the background colour set to WHITE.
93 \item ORs the temporary bitmap with the destination area.
94 \item Deletes the temporary bitmap.
95 \end{enumerate}
96
97 This sequence of operations ensures that the source's transparent area need not be black,
98 and logical functions are supported.
99 }
100
101 \wxheading{Remarks}
102
103 There is partial support for Blit in wxPostScriptDC, under X.
104
105 See \helpref{wxMemoryDC}{wxmemorydc} for typical usage.
106
107 \wxheading{See also}
108
109 \helpref{wxMemoryDC}{wxmemorydc}, \helpref{wxBitmap}{wxbitmap}, \helpref{wxMask}{wxmask}
110
111 \membersection{wxDC::Clear}\label{wxdcclear}
112
113 \func{void}{Clear}{\void}
114
115 Clears the device context using the current background brush.
116
117 \membersection{wxDC::CrossHair}\label{wxdccrosshair}
118
119 \func{void}{CrossHair}{\param{long}{ x}, \param{long}{ y}}
120
121 Displays a cross hair using the current pen. This is a vertical
122 and horizontal line the height and width of the window, centred
123 on the given point.
124
125 \membersection{wxDC::DestroyClippingRegion}\label{wxdcdestroyclippingregion}
126
127 \func{void}{DestroyClippingRegion}{\void}
128
129 Destroys the current clipping region so that none of the DC is clipped.
130 See also \helpref{wxDC::SetClippingRegion}{wxdcsetclippingregion}.
131
132 \membersection{wxDC::DeviceToLogicalX}\label{wxdcdevicetologicalx}
133
134 \func{long}{DeviceToLogicalX}{\param{long}{ x}}
135
136 Convert device X coordinate to logical coordinate, using the current
137 mapping mode.
138
139 \membersection{wxDC::DeviceToLogicalXRel}\label{wxdcdevicetologicalxrel}
140
141 \func{long}{DeviceToLogicalXRel}{\param{long}{ x}}
142
143 Convert device X coordinate to relative logical coordinate, using the current
144 mapping mode. Use this function for converting a width, for example.
145
146 \membersection{wxDC::DeviceToLogicalY}\label{wxdcdevicetologicaly}
147
148 \func{long}{DeviceToLogicalY}{\param{long}{ y}}
149
150 Converts device Y coordinate to logical coordinate, using the current
151 mapping mode.
152
153 \membersection{wxDC::DeviceToLogicalYRel}\label{wxdcdevicetologicalyrel}
154
155 \func{long}{DeviceToLogicalYRel}{\param{long}{ y}}
156
157 Convert device Y coordinate to relative logical coordinate, using the current
158 mapping mode. Use this function for converting a height, for example.
159
160 \membersection{wxDC::DrawArc}\label{wxdcdrawarc}
161
162 \func{void}{DrawArc}{\param{long}{ x1}, \param{long}{ y1}, \param{long}{ x2}, \param{long}{ y2}, \param{double}{ xc}, \param{double}{ yc}}
163
164 Draws an arc of a circle, centred on ({\it xc, yc}), with starting point ({\it x1, y1})
165 and ending at ({\it x2, y2}). The current pen is used for the outline
166 and the current brush for filling the shape.
167
168 The arc is drawn in an anticlockwise direction from the start point to the end point.
169
170 \membersection{wxDC::DrawBitmap}\label{wxdcdrawbitmap}
171
172 \func{void}{DrawBitmap}{\param{const wxBitmap\&}{ bitmap}, \param{long}{ x}, \param{long}{ y}, \param{bool}{ transparent}}
173
174 Draw a bitmap on the device context at the specified point. If {\it transparent} is TRUE and the bitmap has
175 a transparency mask, the bitmap will be drawn transparently.
176
177 \membersection{wxDC::DrawEllipse}\label{wxdcdrawellipse}
178
179 \func{void}{DrawEllipse}{\param{long}{ x}, \param{long}{ y}, \param{long}{ width}, \param{long}{ height}}
180
181 Draws an ellipse contained in the rectangle with the given top left corner, and with the
182 given size. The current pen is used for the outline and the current brush for
183 filling the shape.
184
185 \membersection{wxDC::DrawEllipticArc}\label{wxdcdrawellipticarc}
186
187 \func{void}{DrawEllipticArc}{\param{long}{ x}, \param{long}{ y}, \param{long}{ width}, \param{long}{ height},
188 \param{double}{ start}, \param{double}{ end}}
189
190 Draws an arc of an ellipse. The current pen is used for drawing the arc and
191 the current brush is used for drawing the pie. This function is currently only available for
192 X window and PostScript device contexts.
193
194 {\it x} and {\it y} specify the x and y coordinates of the upper-left corner of the rectangle that contains
195 the ellipse.
196
197 {\it width} and {\it height} specify the width and height of the rectangle that contains
198 the ellipse.
199
200 {\it start} and {\it end} specify the start and end of the arc relative to the three-o'clock
201 position from the center of the rectangle. Angles are specified
202 in degrees (360 is a complete circle). Positive values mean
203 counter-clockwise motion. If {\it start} is equal to {\it end}, a
204 complete ellipse will be drawn.
205
206 \membersection{wxDC::DrawIcon}\label{wxdcdrawicon}
207
208 \func{void}{DrawIcon}{\param{const wxIcon\&}{ icon}, \param{long}{ x}, \param{long}{ y}}
209
210 Draw an icon on the display (does nothing if the device context is PostScript).
211 This can be the simplest way of drawing bitmaps on a window.
212
213 \membersection{wxDC::DrawLine}\label{wxdcdrawline}
214
215 \func{void}{DrawLine}{\param{long}{ x1}, \param{long}{ y1}, \param{long}{ x2}, \param{long}{ y2}}
216
217 Draws a line from the first point to the second. The current pen is used
218 for drawing the line.
219
220 \membersection{wxDC::DrawLines}\label{wxdcdrawlines}
221
222 \func{void}{DrawLines}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{long}{ xoffset = 0}, \param{long}{ yoffset = 0}}
223
224 \func{void}{DrawLines}{\param{wxList *}{points}, \param{long}{ xoffset = 0}, \param{long}{ yoffset = 0}}
225
226 Draws lines using an array of {\it points} of size {\it n}, or list of
227 pointers to points, adding the optional offset coordinate. The current
228 pen is used for drawing the lines. The programmer is responsible for
229 deleting the list of points.
230
231 \pythonnote{The wxPython version of this method accepts a Python list
232 of wxPoint objects.}
233
234 \membersection{wxDC::DrawPolygon}\label{wxdcdrawpolygon}
235
236 \func{void}{DrawPolygon}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{long}{ xoffset = 0}, \param{long}{ yoffset = 0},\\
237 \param{int }{fill\_style = wxODDEVEN\_RULE}}
238
239 \func{void}{DrawPolygon}{\param{wxList *}{points}, \param{long}{ xoffset = 0}, \param{long}{ yoffset = 0},\\
240 \param{int }{fill\_style = wxODDEVEN\_RULE}}
241
242 Draws a filled polygon using an array of {\it points} of size {\it n},
243 or list of pointers to points, adding the optional offset coordinate.
244
245 The last argument specifies the fill rule: {\bf wxODDEVEN\_RULE} (the
246 default) or {\bf wxWINDING\_RULE}.
247
248 The current pen is used for drawing the outline, and the current brush
249 for filling the shape. Using a transparent brush suppresses filling.
250 The programmer is responsible for deleting the list of points.
251
252 Note that wxWindows automatically closes the first and last points.
253
254 \pythonnote{The wxPython version of this method accepts a Python list
255 of wxPoint objects.}
256
257 \membersection{wxDC::DrawPoint}\label{wxdcdrawpoint}
258
259 \func{void}{DrawPoint}{\param{long}{ x}, \param{long}{ y}}
260
261 Draws a point using the current pen.
262
263 \membersection{wxDC::DrawRectangle}\label{wxdcdrawrectangle}
264
265 \func{void}{DrawRectangle}{\param{long}{ x}, \param{long}{ y}, \param{long}{ width}, \param{long}{ height}}
266
267 Draws a rectangle with the given top left corner, and with the given
268 size. The current pen is used for the outline and the current brush
269 for filling the shape.
270
271 \membersection{wxDC::DrawRoundedRectangle}\label{wxdcdrawroundedrectangle}
272
273 \func{void}{DrawRoundedRectangle}{\param{long}{ x}, \param{long}{ y}, \param{long}{ width}, \param{long}{ height}, \param{double}{ radius = 20}}
274
275 Draws a rectangle with the given top left corner, and with the given
276 size. The corners are quarter-circles using the given radius. The
277 current pen is used for the outline and the current brush for filling
278 the shape.
279
280 If {\it radius} is positive, the value is assumed to be the
281 radius of the rounded corner. If {\it radius} is negative,
282 the absolute value is assumed to be the {\it proportion} of the smallest
283 dimension of the rectangle. This means that the corner can be
284 a sensible size relative to the size of the rectangle, and also avoids
285 the strange effects X produces when the corners are too big for
286 the rectangle.
287
288 \membersection{wxDC::DrawSpline}\label{wxdcdrawspline}
289
290 \func{void}{DrawSpline}{\param{wxList *}{points}}
291
292 Draws a spline between all given control points, using the current
293 pen. Doesn't delete the wxList and contents. The spline is drawn
294 using a series of lines, using an algorithm taken from the X drawing
295 program `XFIG'.
296
297 \func{void}{DrawSpline}{\param{long}{ x1}, \param{long}{ y1}, \param{long}{ x2}, \param{long}{ y2}, \param{long}{ x3}, \param{long}{ y3}}
298
299 Draws a three-point spline using the current pen.
300
301 \pythonnote{The wxPython version of this method accepts a Python list
302 of wxPoint objects.}
303
304 \membersection{wxDC::DrawText}\label{wxdcdrawtext}
305
306 \func{void}{DrawText}{\param{const wxString\& }{text}, \param{long}{ x}, \param{long}{ y}}
307
308 Draws a text string at the specified point, using the current text font,
309 and the current text foreground and background colours.
310
311 The coordinates refer to the top-left corner of the rectangle bounding
312 the string. See \helpref{wxDC::GetTextExtent}{wxdcgettextextent} for how
313 to get the dimensions of a text string, which can be used to position the
314 text more precisely.
315
316 \membersection{wxDC::EndDoc}\label{wxdcenddoc}
317
318 \func{void}{EndDoc}{\void}
319
320 Ends a document (only relevant when outputting to a printer).
321
322 \membersection{wxDC::EndDrawing}\label{wxdcenddrawing}
323
324 \func{void}{EndDrawing}{\void}
325
326 Allows optimization of drawing code under MS Windows. Enclose
327 drawing primitives between {\bf BeginDrawing} and {\bf EndDrawing}\rtfsp
328 calls.
329
330 \membersection{wxDC::EndPage}\label{wxdcendpage}
331
332 \func{void}{EndPage}{\void}
333
334 Ends a document page (only relevant when outputting to a printer).
335
336 \membersection{wxDC::FloodFill}\label{wxdcfloodfill}
337
338 \func{void}{FloodFill}{\param{long}{ x}, \param{long}{ y}, \param{wxColour *}{colour}, \param{int}{ style=wxFLOOD\_SURFACE}}
339
340 Flood fills the device context starting from the given point, in the given colour,
341 and using a style:
342
343 \begin{itemize}\itemsep=0pt
344 \item wxFLOOD\_SURFACE: the flooding occurs until a colour other than the given colour is encountered.
345 \item wxFLOOD\_BORDER: the area to be flooded is bounded by the given colour.
346 \end{itemize}
347
348 {\it Note:} this function is available in MS Windows only.
349
350 \membersection{wxDC::GetBackground}\label{wxdcgetbackground}
351
352 \func{wxBrush\&}{GetBackground}{\void}
353
354 Gets the brush used for painting the background (see \helpref{wxDC::SetBackground}{wxdcsetbackground}).
355
356 \membersection{wxDC::GetBrush}\label{wxdcgetbrush}
357
358 \func{wxBrush\&}{GetBrush}{\void}
359
360 Gets the current brush (see \helpref{wxDC::SetBrush}{wxdcsetbrush}).
361
362 \membersection{wxDC::GetCharHeight}\label{wxdcgetcharheight}
363
364 \func{long}{GetCharHeight}{\void}
365
366 Gets the character height of the currently set font.
367
368 \membersection{wxDC::GetCharWidth}\label{wxdcgetcharwidth}
369
370 \func{long}{GetCharWidth}{\void}
371
372 Gets the average character width of the currently set font.
373
374 \membersection{wxDC::GetClippingBox}\label{wxdcgetclippingbox}
375
376 \func{void}{GetClippingBox}{\param{long}{ *x}, \param{long}{ *y}, \param{long}{ *width}, \param{long}{ *height}}
377
378 Gets the rectangle surrounding the current clipping region.
379
380 \pythonnote{No arguments are required and the four values defining the
381 rectangle are returned as a tuple.}
382
383 \membersection{wxDC::GetFont}\label{wxdcgetfont}
384
385 \func{wxFont\&}{GetFont}{\void}
386
387 Gets the current font (see \helpref{wxDC::SetFont}{wxdcsetfont}).
388
389 \membersection{wxDC::GetLogicalFunction}\label{wxdcgetlogicalfunction}
390
391 \func{int}{GetLogicalFunction}{\void}
392
393 Gets the current logical function (see \helpref{wxDC::SetLogicalFunction}{wxdcsetlogicalfunction}).
394
395 \membersection{wxDC::GetMapMode}\label{wxdcgetmapmode}
396
397 \func{int}{GetMapMode}{\void}
398
399 Gets the {\it mapping mode} for the device context (see \helpref{wxDC::SetMapMode}{wxdcsetmapmode}).
400
401 \membersection{wxDC::GetOptimization}\label{wxdcgetoptimization}
402
403 \func{bool}{GetOptimization}{\void}
404
405 Returns TRUE if device context optimization is on.
406 See \helpref{wxDC::SetOptimization}{wxsetoptimization} for details.
407
408 \membersection{wxDC::GetPen}\label{wxdcgetpen}
409
410 \func{wxPen\&}{GetPen}{\void}
411
412 Gets the current pen (see \helpref{wxDC::SetPen}{wxdcsetpen}).
413
414 \membersection{wxDC::GetPixel}\label{wxdcgetpixel}
415
416 \func{bool}{GetPixel}{\param{long}{ x}, \param{long}{ y}, \param{wxColour *}{colour}}
417
418 Sets {\it colour} to the colour at the specified location. Windows only; an X implementation
419 is being worked on. Not available for wxPostScriptDC or wxMetafileDC.
420
421 \membersection{wxDC::GetSize}\label{wxdcgetsize}
422
423 \func{void}{GetSize}{\param{long *}{width}, \param{long *}{height}}
424
425 For a PostScript device context, this gets the maximum size of graphics
426 drawn so far on the device context.
427
428 For a Windows printer device context, this gets the horizontal and vertical
429 resolution. It can be used to scale graphics to fit the page when using
430 a Windows printer device context. For example, if {\it maxX} and {\it maxY}\rtfsp
431 represent the maximum horizontal and vertical `pixel' values used in your
432 application, the following code will scale the graphic to fit on the
433 printer page:
434
435 \begin{verbatim}
436 long w, h;
437 dc.GetSize(&w, &h);
438 double scaleX=(double)(maxX/w);
439 double scaleY=(double)(maxY/h);
440 dc.SetUserScale(min(scaleX,scaleY),min(scaleX,scaleY));
441 \end{verbatim}
442
443 \pythonnote{In place of a single overloaded method name, wxPython
444 implements the following methods:\par
445 \indented{2cm}{\begin{twocollist}
446 \twocolitem{\bf{GetSize()}}{Returns a wxSize}
447 \twocolitem{\bf{GetSizeTuple()}}{Returns a 2-tuple (width, height)}
448 \end{twocollist}}
449 }
450
451 \membersection{wxDC::GetTextBackground}\label{wxdcgettextbackground}
452
453 \func{wxColour\&}{GetTextBackground}{\void}
454
455 Gets the current text background colour (see \helpref{wxDC::SetTextBackground}{wxdcsettextbackground}).
456
457 \membersection{wxDC::GetTextExtent}\label{wxdcgettextextent}
458
459 \func{void}{GetTextExtent}{\param{const wxString\& }{string}, \param{long *}{w}, \param{long *}{h},\\
460 \param{long *}{descent = NULL}, \param{long *}{externalLeading = NULL}, \param{wxFont *}{font = NULL}}
461
462 Gets the dimensions of the string using the currently selected font.
463 \rtfsp{\it string} is the text string to measure, {\it w} and {\it h} are
464 the total width and height respectively, {\it descent} is the
465 dimension from the baseline of the font to the bottom of the
466 descender, and {\it externalLeading} is any extra vertical space added
467 to the font by the font designer (usually is zero).
468
469 The optional parameter {\it font} specifies an alternative
470 to the currently selected font: but note that this does not
471 yet work under Windows, so you need to set a font for
472 the device context first.
473
474 See also \helpref{wxFont}{wxfont}, \helpref{wxDC::SetFont}{wxdcsetfont}.
475
476 \pythonnote{The following methods are implemented in wxPython:\par
477 \indented{2cm}{\begin{twocollist}
478 \twocolitem{\bf{GetTextExtent(string)}}{Returns a 2-tuple, (width, height)}
479 \twocolitem{\bf{GetFullTextExtent(string, font=NULL)}}{Returns a
480 4-tuple, (width, height, descent, externalLeading) }
481 \end{twocollist}}
482 }
483
484 \membersection{wxDC::GetTextForeground}\label{wxdcgettextforeground}
485
486 \func{wxColour\&}{GetTextForeground}{\void}
487
488 Gets the current text foreground colour (see \helpref{wxDC::SetTextForeground}{wxdcsettextforeground}).
489
490 \membersection{wxDC::LogicalToDeviceX}\label{wxdclogicaltodevicex}
491
492 \func{long}{LogicalToDeviceX}{\param{long}{ x}}
493
494 Converts logical X coordinate to device coordinate, using the current
495 mapping mode.
496
497 \membersection{wxDC::LogicalToDeviceXRel}\label{wxdclogicaltodevicexrel}
498
499 \func{long}{LogicalToDeviceXRel}{\param{long}{ x}}
500
501 Converts logical X coordinate to relative device coordinate, using the current
502 mapping mode. Use this for converting a width, for example.
503
504 \membersection{wxDC::LogicalToDeviceY}\label{wxdclogicaltodevicey}
505
506 \func{long}{LogicalToDeviceY}{\param{long}{ y}}
507
508 Converts logical Y coordinate to device coordinate, using the current
509 mapping mode.
510
511 \membersection{wxDC::LogicalToDeviceYRel}\label{wxdclogicaltodeviceyrel}
512
513 \func{long}{LogicalToDeviceYRel}{\param{long}{ y}}
514
515 Converts logical Y coordinate to relative device coordinate, using the current
516 mapping mode. Use this for converting a height, for example.
517
518 \membersection{wxDC::MaxX}\label{wxdcmaxx}
519
520 \func{long}{MaxX}{\void}
521
522 Gets the maximum horizontal extent used in drawing commands so far.
523
524 \membersection{wxDC::MaxY}\label{wxdcmaxy}
525
526 \func{long}{MaxY}{\void}
527
528 Gets the maximum vertical extent used in drawing commands so far.
529
530 \membersection{wxDC::MinX}\label{wxdcminx}
531
532 \func{long}{MinX}{\void}
533
534 Gets the minimum horizontal extent used in drawing commands so far.
535
536 \membersection{wxDC::MinY}\label{wxdcminy}
537
538 \func{long}{MinY}{\void}
539
540 Gets the minimum vertical extent used in drawing commands so far.
541
542 \membersection{wxDC::Ok}\label{wxdcok}
543
544 \func{bool}{Ok}{\void}
545
546 Returns TRUE if the DC is ok to use.
547
548 \membersection{wxDC::SetDeviceOrigin}\label{wxdcsetdeviceorigin}
549
550 \func{void}{SetDeviceOrigin}{\param{long}{ x}, \param{long}{ y}}
551
552 Sets the device origin (i.e., the origin in pixels after scaling has been
553 applied).
554
555 This function may be useful in Windows printing
556 operations for placing a graphic on a page.
557
558 \membersection{wxDC::SetBackground}\label{wxdcsetbackground}
559
560 \func{void}{SetBackground}{\param{const wxBrush\& }{brush}}
561
562 Sets the current background brush for the DC.
563
564 \membersection{wxDC::SetBackgroundMode}\label{wxdcsetbackgroundmode}
565
566 \func{void}{SetBackgroundMode}{\param{int}{ mode}}
567
568 {\it mode} may be one of wxSOLID and wxTRANSPARENT. This setting determines
569 whether text will be drawn with a background colour or not.
570
571 \membersection{wxDC::SetClippingRegion}\label{wxdcsetclippingregion}
572
573 \func{void}{SetClippingRegion}{\param{long}{ x}, \param{long}{ y}, \param{long}{ width}, \param{long}{ height}}
574
575 \func{void}{SetClippingRegion}{\param{const wxRegion\&}{ region}}
576
577 Sets the clipping region for the DC. The clipping region is an area
578 to which drawing is restricted. Possible uses for the clipping region are for clipping text
579 or for speeding up window redraws when only a known area of the screen is damaged.
580
581 \wxheading{See also}
582
583 \helpref{wxDC::DestroyClippingRegion}{wxdcdestroyclippingregion}, \helpref{wxRegion}{wxregion}
584
585 \membersection{wxDC::SetPalette}\label{wxdcsetpalette}
586
587 \func{void}{SetPalette}{\param{const wxPalette\& }{palette}}
588
589 If this is a window DC or memory DC, assigns the given palette to the window
590 or bitmap associated with the DC. If the argument is wxNullPalette, the current
591 palette is selected out of the device context, and the original palette
592 restored.
593
594 See \helpref{wxPalette}{wxpalette} for further details.
595
596 \membersection{wxDC::SetBrush}\label{wxdcsetbrush}
597
598 \func{void}{SetBrush}{\param{const wxBrush\& }{brush}}
599
600 Sets the current brush for the DC.
601
602 If the argument is wxNullBrush, the current brush is selected out of the device
603 context, and the original brush restored, allowing the current brush to
604 be destroyed safely.
605
606 See also \helpref{wxBrush}{wxbrush}.
607
608 \membersection{wxDC::SetFont}\label{wxdcsetfont}
609
610 \func{void}{SetFont}{\param{const wxFont\& }{font}}
611
612 Sets the current font for the DC.
613
614 If the argument is wxNullFont, the current font is selected out of the device
615 context, and the original font restored, allowing the current font to
616 be destroyed safely.
617
618 See also \helpref{wxFont}{wxfont}.
619
620 \membersection{wxDC::SetLogicalFunction}\label{wxdcsetlogicalfunction}
621
622 \func{void}{SetLogicalFunction}{\param{int}{ function}}
623
624 Sets the current logical function for the device context. This determines how
625 a source pixel (from a pen or brush colour, or source device context if
626 using \helpref{wxDC::Blit}{wxdcblit}) combines with a destination pixel in the
627 current device context.
628
629 The possible values
630 and their meaning in terms of source and destination pixel values are
631 as follows:
632
633 \begin{verbatim}
634 wxAND src AND dst
635 wxAND_INVERT (NOT src) AND dst
636 wxAND_REVERSE src AND (NOT dst)
637 wxCLEAR 0
638 wxCOPY src
639 wxEQUIV (NOT src) XOR dst
640 wxINVERT NOT dst
641 wxNAND (NOT src) OR (NOT dst)
642 wxNOR (NOT src) AND (NOT dst)
643 wxNO_OP dst
644 wxOR src OR dst
645 wxOR_INVERT (NOT src) OR dst
646 wxOR_REVERSE src OR (NOT dst)
647 wxSET 1
648 wxSRC_INVERT NOT src
649 wxXOR src XOR dst
650 \end{verbatim}
651
652 The default is wxCOPY, which simply draws with the current colour.
653 The others combine the current colour and the background using a
654 logical operation. wxINVERT is commonly used for drawing rubber bands or
655 moving outlines, since drawing twice reverts to the original colour.
656
657 \membersection{wxDC::SetMapMode}\label{wxdcsetmapmode}
658
659 \func{void}{SetMapMode}{\param{int}{ int}}
660
661 The {\it mapping mode} of the device context defines the unit of
662 measurement used to convert logical units to device units. Note that
663 in X, text drawing isn't handled consistently with the mapping mode; a
664 font is always specified in point size. However, setting the {\it
665 user scale} (see \helpref{wxDC::SetUserScale}{wxdcsetuserscale}) scales the text appropriately. In
666 Windows, scaleable TrueType fonts are always used; in X, results depend
667 on availability of fonts, but usually a reasonable match is found.
668
669 Note that the coordinate origin should ideally be selectable, but for
670 now is always at the top left of the screen/printer.
671
672 Drawing to a Windows printer device context under UNIX
673 uses the current mapping mode, but mapping mode is currently ignored for
674 PostScript output.
675
676 The mapping mode can be one of the following:
677
678 \begin{twocollist}\itemsep=0pt
679 \twocolitem{wxMM\_TWIPS}{Each logical unit is 1/20 of a point, or 1/1440 of
680 an inch.}
681 \twocolitem{wxMM\_POINTS}{Each logical unit is a point, or 1/72 of an inch.}
682 \twocolitem{wxMM\_METRIC}{Each logical unit is 1 mm.}
683 \twocolitem{wxMM\_LOMETRIC}{Each logical unit is 1/10 of a mm.}
684 \twocolitem{wxMM\_TEXT}{Each logical unit is 1 pixel.}
685 \end{twocollist}
686
687 \membersection{wxDC::SetOptimization}\label{wxsetoptimization}
688
689 \func{void}{SetOptimization}{\param{bool }{optimize}}
690
691 If {\it optimize} is TRUE (the default), this function sets optimization mode on.
692 This currently means that under X, the device context will not try to set a pen or brush
693 property if it is known to be set already. This approach can fall down
694 if non-wxWindows code is using the same device context or window, for example
695 when the window is a panel on which the windowing system draws panel items.
696 The wxWindows device context 'memory' will now be out of step with reality.
697
698 Setting optimization off, drawing, then setting it back on again, is a trick
699 that must occasionally be employed.
700
701 \membersection{wxDC::SetPen}\label{wxdcsetpen}
702
703 \func{void}{SetPen}{\param{const wxPen\& }{pen}}
704
705 Sets the current pen for the DC.
706
707 If the argument is wxNullPen, the current pen is selected out of the device
708 context, and the original pen restored.
709
710 \membersection{wxDC::SetTextBackground}\label{wxdcsettextbackground}
711
712 \func{void}{SetTextBackground}{\param{const wxColour\& }{colour}}
713
714 Sets the current text background colour for the DC.
715
716 \membersection{wxDC::SetTextForeground}\label{wxdcsettextforeground}
717
718 \func{void}{SetTextForeground}{\param{const wxColour\& }{colour}}
719
720 Sets the current text foreground colour for the DC.
721
722 \membersection{wxDC::SetUserScale}\label{wxdcsetuserscale}
723
724 \func{void}{SetUserScale}{\param{double}{ xScale}, \param{double}{ yScale}}
725
726 Sets the user scaling factor, useful for applications which require
727 `zooming'.
728
729 \membersection{wxDC::StartDoc}\label{wxdcstartdoc}
730
731 \func{bool}{StartDoc}{\param{const wxString\& }{message}}
732
733 Starts a document (only relevant when outputting to a printer).
734 Message is a message to show whilst printing.
735
736 \membersection{wxDC::StartPage}\label{wxdcstartpage}
737
738 \func{bool}{StartPage}{\void}
739
740 Starts a document page (only relevant when outputting to a printer).
741