1 \section{\class{wxDC
}}\label{wxdc
}
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.
9 Derived types of wxDC have documentation for specific features
10 only, so refer to this section for most device context information.
12 % VZ: we should really document them instead of this lame excuse, but I don't
13 % have time for it now, when it is done please remove this
14 Please note that in addition to the versions of the methods documented here,
15 there are also versions which accept single
{\tt wxPoint
} parameter instead of
16 two
{\tt wxCoord
} ones or
{\tt wxPoint
} and
{\tt wxSize
} instead of four of
19 \wxheading{Derived from
}
21 \helpref{wxObject
}{wxobject
}
23 \wxheading{Include files
}
29 \helpref{Overview
}{dcoverview
}
31 \latexignore{\rtfignore{\wxheading{Members
}}}
33 \membersection{wxDC::wxDC
}
39 \membersection{wxDC::
\destruct{wxDC
}}
41 \func{}{\destruct{wxDC
}}{\void}
45 \membersection{wxDC::BeginDrawing
}\label{wxdcbegindrawing
}
47 \func{void
}{BeginDrawing
}{\void}
49 Allows optimization of drawing code under MS Windows. Enclose
50 drawing primitives between
{\bf BeginDrawing
} and
{\bf EndDrawing
}\rtfsp
53 Drawing to a wxDialog panel device context outside of a
54 system-generated OnPaint event
{\it requires
} this pair of calls to
55 enclose drawing code. This is because a Windows dialog box does not have
56 a retained device context associated with it, and selections such as pen
57 and brush settings would be lost if the device context were obtained and
58 released for each drawing operation.
60 \membersection{wxDC::Blit
}\label{wxdcblit
}
62 \func{bool
}{Blit
}{\param{wxCoord
}{ xdest
},
\param{wxCoord
}{ ydest
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
},
63 \param{wxDC*
}{source
},
\param{wxCoord
}{ xsrc
},
\param{wxCoord
}{ ysrc
},
\param{int
}{ logicalFunc = wxCOPY
},
64 \param{bool
}{useMask = FALSE
}}
66 Copy from a source DC to this DC, specifying the destination
67 coordinates, size of area to copy, source DC, source coordinates, and
70 \wxheading{Parameters
}
72 \docparam{xdest
}{Destination device context x position.
}
74 \docparam{ydest
}{Destination device context y position.
}
76 \docparam{width
}{Width of source area to be copied.
}
78 \docparam{height
}{Height of source area to be copied.
}
80 \docparam{source
}{Source device context.
}
82 \docparam{xsrc
}{Source device context x position.
}
84 \docparam{ysrc
}{Source device context y position.
}
86 \docparam{logicalFunc
}{Logical function to use: see
\helpref{wxDC::SetLogicalFunction
}{wxdcsetlogicalfunction
}.
}
88 \docparam{useMask
}{If TRUE, Blit does a transparent blit using the mask that is associated with the bitmap
89 selected into the source device context. The Windows implementation does the following:
92 \item Creates a temporary bitmap and copies the destination area into it.
93 \item Copies the source area into the temporary bitmap using the specified logical function.
94 \item Sets the masked area in the temporary bitmap to BLACK by ANDing the
95 mask bitmap with the temp bitmap with the foreground colour set to WHITE
96 and the bg colour set to BLACK.
97 \item Sets the unmasked area in the destination area to BLACK by ANDing the
98 mask bitmap with the destination area with the foreground colour set to BLACK
99 and the background colour set to WHITE.
100 \item ORs the temporary bitmap with the destination area.
101 \item Deletes the temporary bitmap.
104 This sequence of operations ensures that the source's transparent area need not be black,
105 and logical functions are supported.
110 There is partial support for Blit in wxPostScriptDC, under X.
112 See
\helpref{wxMemoryDC
}{wxmemorydc
} for typical usage.
116 \helpref{wxMemoryDC
}{wxmemorydc
},
\helpref{wxBitmap
}{wxbitmap
},
\helpref{wxMask
}{wxmask
}
118 \membersection{wxDC::CalcBoundingBox
}\label{wxdccalcboundingbox
}
120 \func{void
}{CalcBoundingBox
}{\param{wxCoord
}{x
},
\param{wxCoord
}{y
}}
122 Adds the specified point to the bounding box which can be retrieved with
123 \helpref{MinX
}{wxdcminx
},
\helpref{MaxX
}{wxdcmaxx
} and
124 \helpref{MinY
}{wxdcminy
},
\helpref{MaxY
}{wxdcmaxy
} functions.
128 \helpref{ResetBoundingBox
}{wxdcresetboundingbox
}
130 \membersection{wxDC::Clear
}\label{wxdcclear
}
132 \func{void
}{Clear
}{\void}
134 Clears the device context using the current background brush.
136 \membersection{wxDC::CrossHair
}\label{wxdccrosshair
}
138 \func{void
}{CrossHair
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
}}
140 Displays a cross hair using the current pen. This is a vertical
141 and horizontal line the height and width of the window, centred
144 \membersection{wxDC::DestroyClippingRegion
}\label{wxdcdestroyclippingregion
}
146 \func{void
}{DestroyClippingRegion
}{\void}
148 Destroys the current clipping region so that none of the DC is clipped.
149 See also
\helpref{wxDC::SetClippingRegion
}{wxdcsetclippingregion
}.
151 \membersection{wxDC::DeviceToLogicalX
}\label{wxdcdevicetologicalx
}
153 \func{wxCoord
}{DeviceToLogicalX
}{\param{wxCoord
}{ x
}}
155 Convert device X coordinate to logical coordinate, using the current
158 \membersection{wxDC::DeviceToLogicalXRel
}\label{wxdcdevicetologicalxrel
}
160 \func{wxCoord
}{DeviceToLogicalXRel
}{\param{wxCoord
}{ x
}}
162 Convert device X coordinate to relative logical coordinate, using the current
163 mapping mode. Use this function for converting a width, for example.
165 \membersection{wxDC::DeviceToLogicalY
}\label{wxdcdevicetologicaly
}
167 \func{wxCoord
}{DeviceToLogicalY
}{\param{wxCoord
}{ y
}}
169 Converts device Y coordinate to logical coordinate, using the current
172 \membersection{wxDC::DeviceToLogicalYRel
}\label{wxdcdevicetologicalyrel
}
174 \func{wxCoord
}{DeviceToLogicalYRel
}{\param{wxCoord
}{ y
}}
176 Convert device Y coordinate to relative logical coordinate, using the current
177 mapping mode. Use this function for converting a height, for example.
179 \membersection{wxDC::DrawArc
}\label{wxdcdrawarc
}
181 \func{void
}{DrawArc
}{\param{wxCoord
}{ x1
},
\param{wxCoord
}{ y1
},
\param{wxCoord
}{ x2
},
\param{wxCoord
}{ y2
},
\param{double
}{ xc
},
\param{double
}{ yc
}}
183 Draws an arc of a circle, centred on (
{\it xc, yc
}), with starting point (
{\it x1, y1
})
184 and ending at (
{\it x2, y2
}). The current pen is used for the outline
185 and the current brush for filling the shape.
187 The arc is drawn in an anticlockwise direction from the start point to the end point.
189 \membersection{wxDC::DrawBitmap
}\label{wxdcdrawbitmap
}
191 \func{void
}{DrawBitmap
}{\param{const wxBitmap\&
}{ bitmap
},
\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{bool
}{ transparent
}}
193 Draw a bitmap on the device context at the specified point. If
{\it transparent
} is TRUE and the bitmap has
194 a transparency mask, the bitmap will be drawn transparently.
196 When drawing a mono-bitmap, the current text foreground colour will be used to draw the foreground
197 of the bitmap (all bits set to
1), and the current text background colour to draw the background
198 (all bits set to
0). See also
\helpref{SetTextForeground
}{wxdcsettextforeground
},
199 \helpref{SetTextBackground
}{wxdcsettextbackground
} and
\helpref{wxMemoryDC
}{wxmemorydc
}.
201 \membersection{wxDC::DrawCheckMark
}\label{wxdcdrawcheckmark
}
203 \func{void
}{DrawCheckMark
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
}}
205 \func{void
}{DrawCheckMark
}{\param{const wxRect \&
}{rect
}}
207 Draws a check mark inside the given rectangle.
209 \membersection{wxDC::DrawEllipse
}\label{wxdcdrawellipse
}
211 \func{void
}{DrawEllipse
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
}}
213 Draws an ellipse contained in the rectangle with the given top left corner, and with the
214 given size. The current pen is used for the outline and the current brush for
217 \membersection{wxDC::DrawEllipticArc
}\label{wxdcdrawellipticarc
}
219 \func{void
}{DrawEllipticArc
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
},
220 \param{double
}{ start
},
\param{double
}{ end
}}
222 Draws an arc of an ellipse. The current pen is used for drawing the arc and
223 the current brush is used for drawing the pie.
225 {\it x
} and
{\it y
} specify the x and y coordinates of the upper-left corner of the rectangle that contains
228 {\it width
} and
{\it height
} specify the width and height of the rectangle that contains
231 {\it start
} and
{\it end
} specify the start and end of the arc relative to the three-o'clock
232 position from the center of the rectangle. Angles are specified
233 in degrees (
360 is a complete circle). Positive values mean
234 counter-clockwise motion. If
{\it start
} is equal to
{\it end
}, a
235 complete ellipse will be drawn.
237 \membersection{wxDC::DrawIcon
}\label{wxdcdrawicon
}
239 \func{void
}{DrawIcon
}{\param{const wxIcon\&
}{ icon
},
\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
}}
241 Draw an icon on the display (does nothing if the device context is PostScript).
242 This can be the simplest way of drawing bitmaps on a window.
244 \membersection{wxDC::DrawLine
}\label{wxdcdrawline
}
246 \func{void
}{DrawLine
}{\param{wxCoord
}{ x1
},
\param{wxCoord
}{ y1
},
\param{wxCoord
}{ x2
},
\param{wxCoord
}{ y2
}}
248 Draws a line from the first point to the second. The current pen is used
249 for drawing the line.
251 \membersection{wxDC::DrawLines
}\label{wxdcdrawlines
}
253 \func{void
}{DrawLines
}{\param{int
}{ n
},
\param{wxPoint
}{ points
[]},
\param{wxCoord
}{ xoffset =
0},
\param{wxCoord
}{ yoffset =
0}}
255 \func{void
}{DrawLines
}{\param{wxList *
}{points
},
\param{wxCoord
}{ xoffset =
0},
\param{wxCoord
}{ yoffset =
0}}
257 Draws lines using an array of
{\it points
} of size
{\it n
}, or list of
258 pointers to points, adding the optional offset coordinate. The current
259 pen is used for drawing the lines. The programmer is responsible for
260 deleting the list of points.
262 \pythonnote{The wxPython version of this method accepts a Python list
265 \membersection{wxDC::DrawPolygon
}\label{wxdcdrawpolygon
}
267 \func{void
}{DrawPolygon
}{\param{int
}{ n
},
\param{wxPoint
}{ points
[]},
\param{wxCoord
}{ xoffset =
0},
\param{wxCoord
}{ yoffset =
0},\\
268 \param{int
}{fill
\_style = wxODDEVEN
\_RULE}}
270 \func{void
}{DrawPolygon
}{\param{wxList *
}{points
},
\param{wxCoord
}{ xoffset =
0},
\param{wxCoord
}{ yoffset =
0},\\
271 \param{int
}{fill
\_style = wxODDEVEN
\_RULE}}
273 Draws a filled polygon using an array of
{\it points
} of size
{\it n
},
274 or list of pointers to points, adding the optional offset coordinate.
276 The last argument specifies the fill rule:
{\bf wxODDEVEN
\_RULE} (the
277 default) or
{\bf wxWINDING
\_RULE}.
279 The current pen is used for drawing the outline, and the current brush
280 for filling the shape. Using a transparent brush suppresses filling.
281 The programmer is responsible for deleting the list of points.
283 Note that wxWindows automatically closes the first and last points.
285 \pythonnote{The wxPython version of this method accepts a Python list
288 \membersection{wxDC::DrawPoint
}\label{wxdcdrawpoint
}
290 \func{void
}{DrawPoint
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
}}
292 Draws a point using the current pen.
294 \membersection{wxDC::DrawRectangle
}\label{wxdcdrawrectangle
}
296 \func{void
}{DrawRectangle
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
}}
298 Draws a rectangle with the given top left corner, and with the given
299 size. The current pen is used for the outline and the current brush
300 for filling the shape.
302 \membersection{wxDC::DrawRotatedText
}\label{wxdcdrawrotatedtext
}
304 \func{void
}{DrawRotatedText
}{\param{const wxString\&
}{text
},
\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{double
}{ angle
}}
306 Draws the text rotated by
{\it angle
} degrees.
310 \helpref{DrawText
}{wxdcdrawtext
}
312 \membersection{wxDC::DrawRoundedRectangle
}\label{wxdcdrawroundedrectangle
}
314 \func{void
}{DrawRoundedRectangle
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
},
\param{double
}{ radius =
20}}
316 Draws a rectangle with the given top left corner, and with the given
317 size. The corners are quarter-circles using the given radius. The
318 current pen is used for the outline and the current brush for filling
321 If
{\it radius
} is positive, the value is assumed to be the
322 radius of the rounded corner. If
{\it radius
} is negative,
323 the absolute value is assumed to be the
{\it proportion
} of the smallest
324 dimension of the rectangle. This means that the corner can be
325 a sensible size relative to the size of the rectangle, and also avoids
326 the strange effects X produces when the corners are too big for
329 \membersection{wxDC::DrawSpline
}\label{wxdcdrawspline
}
331 \func{void
}{DrawSpline
}{\param{wxList *
}{points
}}
333 Draws a spline between all given control points, using the current
334 pen. Doesn't delete the wxList and contents. The spline is drawn
335 using a series of lines, using an algorithm taken from the X drawing
338 \func{void
}{DrawSpline
}{\param{wxCoord
}{ x1
},
\param{wxCoord
}{ y1
},
\param{wxCoord
}{ x2
},
\param{wxCoord
}{ y2
},
\param{wxCoord
}{ x3
},
\param{wxCoord
}{ y3
}}
340 Draws a three-point spline using the current pen.
342 \pythonnote{The wxPython version of this method accepts a Python list
345 \membersection{wxDC::DrawText
}\label{wxdcdrawtext
}
347 \func{void
}{DrawText
}{\param{const wxString\&
}{text
},
\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
}}
349 Draws a text string at the specified point, using the current text font,
350 and the current text foreground and background colours.
352 The coordinates refer to the top-left corner of the rectangle bounding
353 the string. See
\helpref{wxDC::GetTextExtent
}{wxdcgettextextent
} for how
354 to get the dimensions of a text string, which can be used to position the
357 {\bf NB:
} under wxGTK the current
358 \helpref{logical function
}{wxdcgetlogicalfunction
} is used by this function
359 but it is ignored by wxMSW. Thus, you should avoid using logical functions
360 with this function in portable programs.
362 \membersection{wxDC::EndDoc
}\label{wxdcenddoc
}
364 \func{void
}{EndDoc
}{\void}
366 Ends a
document (only relevant when outputting to a printer).
368 \membersection{wxDC::EndDrawing
}\label{wxdcenddrawing
}
370 \func{void
}{EndDrawing
}{\void}
372 Allows optimization of drawing code under MS Windows. Enclose
373 drawing primitives between
{\bf BeginDrawing
} and
{\bf EndDrawing
}\rtfsp
376 \membersection{wxDC::EndPage
}\label{wxdcendpage
}
378 \func{void
}{EndPage
}{\void}
380 Ends a
document page (only relevant when outputting to a printer).
382 \membersection{wxDC::FloodFill
}\label{wxdcfloodfill
}
384 \func{void
}{FloodFill
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{const wxColour\&
}{ colour
},
\param{int
}{ style=wxFLOOD
\_SURFACE}}
386 Flood fills the device context starting from the given point, using
387 the
{\it current brush colour
}, and using a style:
389 \begin{itemize
}\itemsep=
0pt
390 \item wxFLOOD
\_SURFACE: the flooding occurs until a colour other than the given colour is encountered.
391 \item wxFLOOD
\_BORDER: the area to be flooded is bounded by the given colour.
394 {\it Note:
} this function is available in MS Windows only.
396 \membersection{wxDC::GetBackground
}\label{wxdcgetbackground
}
398 \func{wxBrush\&
}{GetBackground
}{\void}
400 \constfunc{const wxBrush\&
}{GetBackground
}{\void}
402 Gets the brush used for painting the background (see
\helpref{wxDC::SetBackground
}{wxdcsetbackground
}).
404 \membersection{wxDC::GetBackgroundMode
}\label{wxdcgetbackgroundmode
}
406 \constfunc{int
}{GetBackgroundMode
}{\void}
408 Returns the current background mode:
{\tt wxSOLID
} or
{\tt wxTRANSPARENT
}.
412 \helpref{SetBackgroundMode
}{wxdcsetbackgroundmode
}
414 \membersection{wxDC::GetBrush
}\label{wxdcgetbrush
}
416 \func{wxBrush\&
}{GetBrush
}{\void}
418 \constfunc{const wxBrush\&
}{GetBrush
}{\void}
420 Gets the current brush (see
\helpref{wxDC::SetBrush
}{wxdcsetbrush
}).
422 \membersection{wxDC::GetCharHeight
}\label{wxdcgetcharheight
}
424 \func{wxCoord
}{GetCharHeight
}{\void}
426 Gets the character height of the currently set font.
428 \membersection{wxDC::GetCharWidth
}\label{wxdcgetcharwidth
}
430 \func{wxCoord
}{GetCharWidth
}{\void}
432 Gets the average character width of the currently set font.
434 \membersection{wxDC::GetClippingBox
}\label{wxdcgetclippingbox
}
436 \func{void
}{GetClippingBox
}{\param{wxCoord
}{ *x
},
\param{wxCoord
}{ *y
},
\param{wxCoord
}{ *width
},
\param{wxCoord
}{ *height
}}
438 Gets the rectangle surrounding the current clipping region.
440 \pythonnote{No arguments are required and the four values defining the
441 rectangle are returned as a tuple.
}
443 \perlnote{This method takes no arguments and returns a four element list
444 {\tt ( \$x, \$y, \$width, \$height )
}}
446 \membersection{wxDC::GetFont
}\label{wxdcgetfont
}
448 \func{wxFont\&
}{GetFont
}{\void}
450 \constfunc{const wxFont\&
}{GetFont
}{\void}
452 Gets the current font (see
\helpref{wxDC::SetFont
}{wxdcsetfont
}).
454 \membersection{wxDC::GetLogicalFunction
}\label{wxdcgetlogicalfunction
}
456 \func{int
}{GetLogicalFunction
}{\void}
458 Gets the current logical function (see
\helpref{wxDC::SetLogicalFunction
}{wxdcsetlogicalfunction
}).
460 \membersection{wxDC::GetMapMode
}\label{wxdcgetmapmode
}
462 \func{int
}{GetMapMode
}{\void}
464 Gets the
{\it mapping mode
} for the device context (see
\helpref{wxDC::SetMapMode
}{wxdcsetmapmode
}).
466 \membersection{wxDC::GetOptimization
}\label{wxdcgetoptimization
}
468 \func{bool
}{GetOptimization
}{\void}
470 Returns TRUE if device context optimization is on.
471 See
\helpref{wxDC::SetOptimization
}{wxsetoptimization
} for details.
473 \membersection{wxDC::GetPen
}\label{wxdcgetpen
}
475 \func{wxPen\&
}{GetPen
}{\void}
477 \constfunc{const wxPen\&
}{GetPen
}{\void}
479 Gets the current pen (see
\helpref{wxDC::SetPen
}{wxdcsetpen
}).
481 \membersection{wxDC::GetPixel
}\label{wxdcgetpixel
}
483 \func{bool
}{GetPixel
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxColour *
}{colour
}}
485 Sets
{\it colour
} to the colour at the specified location. Windows only; an X implementation
486 is being worked on. Not available for wxPostScriptDC or wxMetafileDC.
488 \pythonnote{For wxPython the wxColour value is returned and is not
489 required as a parameter.
}
491 \perlnote{This method only takes the parameters
{\tt x
} and
{\tt y
} and returns
494 \membersection{wxDC::GetSize
}\label{wxdcgetsize
}
496 \func{void
}{GetSize
}{\param{wxCoord *
}{width
},
\param{wxCoord *
}{height
}}
498 For a PostScript device context, this gets the maximum size of graphics
499 drawn so far on the device context.
501 For a Windows printer device context, this gets the horizontal and vertical
502 resolution. It can be used to scale graphics to fit the page when using
503 a Windows printer device context. For example, if
{\it maxX
} and
{\it maxY
}\rtfsp
504 represent the maximum horizontal and vertical `pixel' values used in your
505 application, the following code will scale the graphic to fit on the
511 double scaleX=(double)(maxX/w);
512 double scaleY=(double)(maxY/h);
513 dc.SetUserScale(min(scaleX,scaleY),min(scaleX,scaleY));
516 \pythonnote{In place of a single overloaded method name, wxPython
517 implements the following methods:
\par
518 \indented{2cm
}{\begin{twocollist
}
519 \twocolitem{{\bf GetSize()
}}{Returns a wxSize
}
520 \twocolitem{{\bf GetSizeTuple()
}}{Returns a
2-tuple (width, height)
}
524 \perlnote{In place of a single overloaded method, wxPerl uses:
\par
525 \indented{2cm
}{\begin{twocollist
}
526 \twocolitem{{\bf GetSize()
}}{Returns a Wx::Size
}
527 \twocolitem{{\bf GetSizeWH()
}}{Returns a
2-element list
528 {\tt ( \$width, \$height )
}}
532 \membersection{wxDC::GetTextBackground
}\label{wxdcgettextbackground
}
534 \func{wxColour\&
}{GetTextBackground
}{\void}
536 \constfunc{const wxColour\&
}{GetTextBackground
}{\void}
538 Gets the current text background colour (see
\helpref{wxDC::SetTextBackground
}{wxdcsettextbackground
}).
540 \membersection{wxDC::GetTextExtent
}\label{wxdcgettextextent
}
542 \func{void
}{GetTextExtent
}{\param{const wxString\&
}{string
},
\param{wxCoord *
}{w
},
\param{wxCoord *
}{h
},\\
543 \param{wxCoord *
}{descent = NULL
},
\param{wxCoord *
}{externalLeading = NULL
},
\param{wxFont *
}{font = NULL
}}
545 Gets the dimensions of the string using the currently selected font.
546 \rtfsp{\it string
} is the text string to measure,
{\it w
} and
{\it h
} are
547 the total width and height respectively,
{\it descent
} is the
548 dimension from the baseline of the font to the bottom of the
549 descender, and
{\it externalLeading
} is any extra vertical space added
550 to the font by the font designer (usually is zero).
552 The optional parameter
{\it font
} specifies an alternative
553 to the currently selected font: but note that this does not
554 yet work under Windows, so you need to set a font for
555 the device context first.
557 See also
\helpref{wxFont
}{wxfont
},
\helpref{wxDC::SetFont
}{wxdcsetfont
}.
559 \pythonnote{The following methods are implemented in wxPython:
\par
560 \indented{2cm
}{\begin{twocollist
}
561 \twocolitem{{\bf GetTextExtent(string)
}}{Returns a
2-tuple, (width, height)
}
562 \twocolitem{{\bf GetFullTextExtent(string, font=NULL)
}}{Returns a
563 4-tuple, (width, height, descent, externalLeading)
}
567 \perlnote{In wxPerl this method is implemented as
568 {\bf GetTextExtent( string, font = undef )
} returning a four element
569 array
{\tt ( \$width, \$height, \$descent, \$externalLeading )
}
572 \membersection{wxDC::GetTextForeground
}\label{wxdcgettextforeground
}
574 \func{wxColour\&
}{GetTextForeground
}{\void}
576 \constfunc{const wxColour\&
}{GetTextForeground
}{\void}
578 Gets the current text foreground colour (see
\helpref{wxDC::SetTextForeground
}{wxdcsettextforeground
}).
581 \membersection{wxDC::GetUserScale
}\label{wxdcgetuserscale
}
583 \func{void
}{GetUserScale
}{\param{double
}{ *x
},
\param{double
}{ *y
}}
585 Gets the current user scale factor (set by
\helpref{SetUserScale
}{wxdcsetuserscale
}).
587 \perlnote{In wxPerl this method takes no arguments and returna a two element
588 array
{\tt ( \$x, \$y )
}}
590 \membersection{wxDC::LogicalToDeviceX
}\label{wxdclogicaltodevicex
}
592 \func{wxCoord
}{LogicalToDeviceX
}{\param{wxCoord
}{ x
}}
594 Converts logical X coordinate to device coordinate, using the current
597 \membersection{wxDC::LogicalToDeviceXRel
}\label{wxdclogicaltodevicexrel
}
599 \func{wxCoord
}{LogicalToDeviceXRel
}{\param{wxCoord
}{ x
}}
601 Converts logical X coordinate to relative device coordinate, using the current
602 mapping mode. Use this for converting a width, for example.
604 \membersection{wxDC::LogicalToDeviceY
}\label{wxdclogicaltodevicey
}
606 \func{wxCoord
}{LogicalToDeviceY
}{\param{wxCoord
}{ y
}}
608 Converts logical Y coordinate to device coordinate, using the current
611 \membersection{wxDC::LogicalToDeviceYRel
}\label{wxdclogicaltodeviceyrel
}
613 \func{wxCoord
}{LogicalToDeviceYRel
}{\param{wxCoord
}{ y
}}
615 Converts logical Y coordinate to relative device coordinate, using the current
616 mapping mode. Use this for converting a height, for example.
618 \membersection{wxDC::MaxX
}\label{wxdcmaxx
}
620 \func{wxCoord
}{MaxX
}{\void}
622 Gets the maximum horizontal extent used in drawing commands so far.
624 \membersection{wxDC::MaxY
}\label{wxdcmaxy
}
626 \func{wxCoord
}{MaxY
}{\void}
628 Gets the maximum vertical extent used in drawing commands so far.
630 \membersection{wxDC::MinX
}\label{wxdcminx
}
632 \func{wxCoord
}{MinX
}{\void}
634 Gets the minimum horizontal extent used in drawing commands so far.
636 \membersection{wxDC::MinY
}\label{wxdcminy
}
638 \func{wxCoord
}{MinY
}{\void}
640 Gets the minimum vertical extent used in drawing commands so far.
642 \membersection{wxDC::Ok
}\label{wxdcok
}
644 \func{bool
}{Ok
}{\void}
646 Returns TRUE if the DC is ok to use.
648 \membersection{wxDC::ResetBoundingBox
}\label{wxdcresetboundingbox
}
650 \func{void
}{ResetBoundingBox
}{\void}
652 Resets the bounding box: after a call to this function, the bounding box
653 doesn't contain anything.
657 \helpref{CalcBoundingBox
}{wxdccalcboundingbox
}
659 \membersection{wxDC::SetDeviceOrigin
}\label{wxdcsetdeviceorigin
}
661 \func{void
}{SetDeviceOrigin
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
}}
663 Sets the device origin (i.e., the origin in pixels after scaling has been
666 This function may be useful in Windows printing
667 operations for placing a graphic on a page.
669 \membersection{wxDC::SetBackground
}\label{wxdcsetbackground
}
671 \func{void
}{SetBackground
}{\param{const wxBrush\&
}{brush
}}
673 Sets the current background brush for the DC.
675 \membersection{wxDC::SetBackgroundMode
}\label{wxdcsetbackgroundmode
}
677 \func{void
}{SetBackgroundMode
}{\param{int
}{ mode
}}
679 {\it mode
} may be one of wxSOLID and wxTRANSPARENT. This setting determines
680 whether text will be drawn with a background colour or not.
682 \membersection{wxDC::SetClippingRegion
}\label{wxdcsetclippingregion
}
684 \func{void
}{SetClippingRegion
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
}}
686 \func{void
}{SetClippingRegion
}{\param{const wxRegion\&
}{ region
}}
688 Sets the clipping region for the DC. The clipping region is an area
689 to which drawing is restricted. Possible uses for the clipping region are for clipping text
690 or for speeding up window redraws when only a known area of the screen is damaged.
694 \helpref{wxDC::DestroyClippingRegion
}{wxdcdestroyclippingregion
},
\helpref{wxRegion
}{wxregion
}
696 \membersection{wxDC::SetPalette
}\label{wxdcsetpalette
}
698 \func{void
}{SetPalette
}{\param{const wxPalette\&
}{palette
}}
700 If this is a window DC or memory DC, assigns the given palette to the window
701 or bitmap associated with the DC. If the argument is wxNullPalette, the current
702 palette is selected out of the device context, and the original palette
705 See
\helpref{wxPalette
}{wxpalette
} for further details.
707 \membersection{wxDC::SetBrush
}\label{wxdcsetbrush
}
709 \func{void
}{SetBrush
}{\param{const wxBrush\&
}{brush
}}
711 Sets the current brush for the DC.
713 If the argument is wxNullBrush, the current brush is selected out of the device
714 context, and the original brush restored, allowing the current brush to
717 See also
\helpref{wxBrush
}{wxbrush
}.
719 See also
\helpref{wxMemoryDC
}{wxmemorydc
} for the interpretation of colours
720 when drawing into a monochrome bitmap.
722 \membersection{wxDC::SetFont
}\label{wxdcsetfont
}
724 \func{void
}{SetFont
}{\param{const wxFont\&
}{font
}}
726 Sets the current font for the DC.
728 If the argument is wxNullFont, the current font is selected out of the device
729 context, and the original font restored, allowing the current font to
732 See also
\helpref{wxFont
}{wxfont
}.
734 \membersection{wxDC::SetLogicalFunction
}\label{wxdcsetlogicalfunction
}
736 \func{void
}{SetLogicalFunction
}{\param{int
}{ function
}}
738 Sets the current logical function for the device context. This determines how
739 a source pixel (from a pen or brush colour, or source device context if
740 using
\helpref{wxDC::Blit
}{wxdcblit
}) combines with a destination pixel in the
741 current device context.
744 and their meaning in terms of source and destination pixel values are
749 wxAND_INVERT (NOT src) AND dst
750 wxAND_REVERSE src AND (NOT dst)
753 wxEQUIV (NOT src) XOR dst
755 wxNAND (NOT src) OR (NOT dst)
756 wxNOR (NOT src) AND (NOT dst)
759 wxOR_INVERT (NOT src) OR dst
760 wxOR_REVERSE src OR (NOT dst)
766 The default is wxCOPY, which simply draws with the current colour.
767 The others combine the current colour and the background using a
768 logical operation. wxINVERT is commonly used for drawing rubber bands or
769 moving outlines, since drawing twice reverts to the original colour.
771 \membersection{wxDC::SetMapMode
}\label{wxdcsetmapmode
}
773 \func{void
}{SetMapMode
}{\param{int
}{ int
}}
775 The
{\it mapping mode
} of the device context defines the unit of
776 measurement used to convert logical units to device units. Note that
777 in X, text drawing isn't handled consistently with the mapping mode; a
778 font is always specified in point size. However, setting the
{\it
779 user scale
} (see
\helpref{wxDC::SetUserScale
}{wxdcsetuserscale
}) scales the text appropriately. In
780 Windows, scaleable TrueType fonts are always used; in X, results depend
781 on availability of fonts, but usually a reasonable match is found.
783 Note that the coordinate origin should ideally be selectable, but for
784 now is always at the top left of the screen/printer.
786 Drawing to a Windows printer device context under UNIX
787 uses the current mapping mode, but mapping mode is currently ignored for
790 The mapping mode can be one of the following:
792 \begin{twocollist
}\itemsep=
0pt
793 \twocolitem{wxMM
\_TWIPS}{Each logical unit is
1/
20 of a point, or
1/
1440 of
795 \twocolitem{wxMM
\_POINTS}{Each logical unit is a point, or
1/
72 of an inch.
}
796 \twocolitem{wxMM
\_METRIC}{Each logical unit is
1 mm.
}
797 \twocolitem{wxMM
\_LOMETRIC}{Each logical unit is
1/
10 of a mm.
}
798 \twocolitem{wxMM
\_TEXT}{Each logical unit is
1 pixel.
}
801 \membersection{wxDC::SetOptimization
}\label{wxsetoptimization
}
803 \func{void
}{SetOptimization
}{\param{bool
}{optimize
}}
805 If
{\it optimize
} is TRUE (the default), this function sets optimization mode on.
806 This currently means that under X, the device context will not try to set a pen or brush
807 property if it is known to be set already. This approach can fall down
808 if non-wxWindows code is using the same device context or window, for example
809 when the window is a panel on which the windowing system draws panel items.
810 The wxWindows device context 'memory' will now be out of step with reality.
812 Setting optimization off, drawing, then setting it back on again, is a trick
813 that must occasionally be employed.
815 \membersection{wxDC::SetPen
}\label{wxdcsetpen
}
817 \func{void
}{SetPen
}{\param{const wxPen\&
}{pen
}}
819 Sets the current pen for the DC.
821 If the argument is wxNullPen, the current pen is selected out of the device
822 context, and the original pen restored.
824 See also
\helpref{wxMemoryDC
}{wxmemorydc
} for the interpretation of colours
825 when drawing into a monochrome bitmap.
827 \membersection{wxDC::SetTextBackground
}\label{wxdcsettextbackground
}
829 \func{void
}{SetTextBackground
}{\param{const wxColour\&
}{colour
}}
831 Sets the current text background colour for the DC.
833 \membersection{wxDC::SetTextForeground
}\label{wxdcsettextforeground
}
835 \func{void
}{SetTextForeground
}{\param{const wxColour\&
}{colour
}}
837 Sets the current text foreground colour for the DC.
839 See also
\helpref{wxMemoryDC
}{wxmemorydc
} for the interpretation of colours
840 when drawing into a monochrome bitmap.
842 \membersection{wxDC::SetUserScale
}\label{wxdcsetuserscale
}
844 \func{void
}{SetUserScale
}{\param{double
}{ xScale
},
\param{double
}{ yScale
}}
846 Sets the user scaling factor, useful for applications which require
849 \membersection{wxDC::StartDoc
}\label{wxdcstartdoc
}
851 \func{bool
}{StartDoc
}{\param{const wxString\&
}{message
}}
853 Starts a
document (only relevant when outputting to a printer).
854 Message is a message to show whilst printing.
856 \membersection{wxDC::StartPage
}\label{wxdcstartpage
}
858 \func{bool
}{StartPage
}{\void}
860 Starts a
document page (only relevant when outputting to a printer).