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 Notice that wxDC is an abstract base class and can't be created directly,
10 please use
\helpref{wxPaintDC
}{wxpaintdc
},
\helpref{wxClientDC
}{wxclientdc
},
11 \helpref{wxWindowDC
}{wxwindowdc
},
\helpref{wxScreenDC
}{wxscreendc
},
12 \helpref{wxMemoryDC
}{wxmemorydc
} or
\helpref{wxPrinterDC
}{wxprinterdc
}.
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
16 Please note that in addition to the versions of the methods documented here,
17 there are also versions which accept single
{\tt wxPoint
} parameter instead of
18 two
{\tt wxCoord
} ones or
{\tt wxPoint
} and
{\tt wxSize
} instead of four of
21 \wxheading{Support for Transparency / Alpha Channel
}
23 On Mac OS X when using Core Graphics (wx
\_MAC\_USE\_CORE\_GRAPHICS set to
1)
24 colors with alpha are supported, so instances
{\tt wxPen
} or
{\tt wxBrush
} that are built from
{\tt wxColour
} use
25 the
color's alpha values when stroking or filling.
27 \wxheading{Derived from
}
29 \helpref{wxObject
}{wxobject
}
31 \wxheading{Include files
}
37 \helpref{wxCore
}{librarieslist
}
41 \helpref{Overview
}{dcoverview
}
43 \latexignore{\rtfignore{\wxheading{Members
}}}
46 \membersection{wxDC::Blit
}\label{wxdcblit
}
48 \func{bool
}{Blit
}{\param{wxCoord
}{ xdest
},
\param{wxCoord
}{ ydest
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
},
49 \param{wxDC*
}{source
},
\param{wxCoord
}{ xsrc
},
\param{wxCoord
}{ ysrc
},
\param{int
}{ logicalFunc = wxCOPY
},
50 \param{bool
}{useMask = false
},
\param{wxCoord
}{ xsrcMask = -
1},
\param{wxCoord
}{ ysrcMask = -
1}}
52 Copy from a source DC to this DC, specifying the destination
53 coordinates, size of area to copy, source DC, source coordinates,
54 logical function, whether to use a bitmap mask, and mask source position.
56 \wxheading{Parameters
}
58 \docparam{xdest
}{Destination device context x position.
}
60 \docparam{ydest
}{Destination device context y position.
}
62 \docparam{width
}{Width of source area to be copied.
}
64 \docparam{height
}{Height of source area to be copied.
}
66 \docparam{source
}{Source device context.
}
68 \docparam{xsrc
}{Source device context x position.
}
70 \docparam{ysrc
}{Source device context y position.
}
72 \docparam{logicalFunc
}{Logical function to use: see
\helpref{wxDC::SetLogicalFunction
}{wxdcsetlogicalfunction
}.
}
74 \docparam{useMask
}{If true, Blit does a transparent blit using the mask that is associated with the bitmap
75 selected into the source device context. The Windows implementation does the following if MaskBlt cannot be used:
78 \item Creates a temporary bitmap and copies the destination area into it.
79 \item Copies the source area into the temporary bitmap using the specified logical function.
80 \item Sets the masked area in the temporary bitmap to BLACK by ANDing the
81 mask bitmap with the temp bitmap with the foreground colour set to WHITE
82 and the bg colour set to BLACK.
83 \item Sets the unmasked area in the destination area to BLACK by ANDing the
84 mask bitmap with the destination area with the foreground colour set to BLACK
85 and the background colour set to WHITE.
86 \item ORs the temporary bitmap with the destination area.
87 \item Deletes the temporary bitmap.
90 This sequence of operations ensures that the source's transparent area need not be black,
91 and logical functions are supported.
93 {\bf Note:
} on Windows, blitting with masks can be speeded up considerably by compiling
94 wxWidgets with the wxUSE
\_DC\_CACHE option enabled. You can also influence whether MaskBlt
95 or the explicit mask blitting code above is used, by using
\helpref{wxSystemOptions
}{wxsystemoptions
} and
96 setting the
{\bf no-maskblt
} option to
1.
100 \docparam{xsrcMask
}{Source x position on the mask. If both xsrcMask and ysrcMask are -
1, xsrc and ysrc
101 will be assumed for the mask source position. Currently only implemented on Windows.
}
103 \docparam{ysrcMask
}{Source y position on the mask. If both xsrcMask and ysrcMask are -
1, xsrc and ysrc
104 will be assumed for the mask source position. Currently only implemented on Windows.
}
109 There is partial support for Blit in wxPostScriptDC, under X.
111 See
\helpref{wxMemoryDC
}{wxmemorydc
} for typical usage.
115 \helpref{wxDC::StretchBlit
}{wxdcstretchblit
},
\helpref{wxMemoryDC
}{wxmemorydc
},
\helpref{wxBitmap
}{wxbitmap
},
\helpref{wxMask
}{wxmask
}
119 \membersection{wxDC::CacheEnabled
}\label{wxdccacheenabled
}
121 \func{static bool
}{CacheEnabled
}{\void}
123 On supported platforms (currently only Windows), returns true
124 if the DC cache is enabled. The DC cache
125 can speed up the
\helpref{Blit
}{wxdcblit
} operation when
126 drawing a large number of masked bitmaps.
128 If using the cache functions in your code, please test for the
129 wxUSE
\_DC\_CACHEING preprocessor symbol for portability.
133 \helpref{wxDC::EnableCache
}{wxdcenablecache
},
\helpref{wxDC::ClearCache
}
137 \membersection{wxDC::CalcBoundingBox
}\label{wxdccalcboundingbox
}
139 \func{void
}{CalcBoundingBox
}{\param{wxCoord
}{x
},
\param{wxCoord
}{y
}}
141 Adds the specified point to the bounding box which can be retrieved with
142 \helpref{MinX
}{wxdcminx
},
\helpref{MaxX
}{wxdcmaxx
} and
143 \helpref{MinY
}{wxdcminy
},
\helpref{MaxY
}{wxdcmaxy
} functions.
147 \helpref{ResetBoundingBox
}{wxdcresetboundingbox
}
150 \membersection{wxDC::Clear
}\label{wxdcclear
}
152 \func{void
}{Clear
}{\void}
154 Clears the device context using the current background brush.
158 \membersection{wxDC::ClearCache
}\label{wxdcclearcache
}
160 \func{static void
}{ClearCache
}{\void}
162 On supported platforms (currently only Windows), clears
163 the contents of the DC cache (one bitmap and two Windows device contexts). The DC cache
164 can speed up the
\helpref{Blit
}{wxdcblit
} operation when
165 drawing a large number of masked bitmaps. You should
166 call ClearCache at the end of length DC operations if you wish to only use
167 the cache transiently; you should also call it as your application exits.
169 If using the cache functions in your code, please test for the
170 wxUSE
\_DC\_CACHEING preprocessor symbol for portability.
174 \helpref{wxDC::EnableCache
}{wxdcenablecache
},
\helpref{wxDC::CacheEnabled
}
178 \membersection{wxDC::ComputeScaleAndOrigin
}\label{wxdccomputescaleandorigin
}
180 \func{virtual void
}{ComputeScaleAndOrigin
}{\void}
182 Performs all necessary computations for given platform and context type
183 after each change of scale and origin parameters. Usually called automatically
184 internally after such changes.
187 \membersection{wxDC::CrossHair
}\label{wxdccrosshair
}
189 \func{void
}{CrossHair
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
}}
191 Displays a cross hair using the current pen. This is a vertical
192 and horizontal line the height and width of the window, centred
196 \membersection{wxDC::DestroyClippingRegion
}\label{wxdcdestroyclippingregion
}
198 \func{void
}{DestroyClippingRegion
}{\void}
200 Destroys the current clipping region so that none of the DC is clipped.
201 See also
\helpref{wxDC::SetClippingRegion
}{wxdcsetclippingregion
}.
204 \membersection{wxDC::DeviceToLogicalX
}\label{wxdcdevicetologicalx
}
206 \func{virtual wxCoord
}{DeviceToLogicalX
}{\param{wxCoord
}{ x
}}
208 Convert device X coordinate to logical coordinate, using the current
212 \membersection{wxDC::DeviceToLogicalXRel
}\label{wxdcdevicetologicalxrel
}
214 \func{virtual wxCoord
}{DeviceToLogicalXRel
}{\param{wxCoord
}{ x
}}
216 Convert device X coordinate to relative logical coordinate, using the current
217 mapping mode but ignoring the x axis orientation.
218 Use this function for converting a width, for example.
221 \membersection{wxDC::DeviceToLogicalY
}\label{wxdcdevicetologicaly
}
223 \func{virtual wxCoord
}{DeviceToLogicalY
}{\param{wxCoord
}{ y
}}
225 Converts device Y coordinate to logical coordinate, using the current
229 \membersection{wxDC::DeviceToLogicalYRel
}\label{wxdcdevicetologicalyrel
}
231 \func{virtual wxCoord
}{DeviceToLogicalYRel
}{\param{wxCoord
}{ y
}}
233 Convert device Y coordinate to relative logical coordinate, using the current
234 mapping mode but ignoring the y axis orientation.
235 Use this function for converting a height, for example.
238 \membersection{wxDC::DrawArc
}\label{wxdcdrawarc
}
240 \func{void
}{DrawArc
}{\param{wxCoord
}{ x1
},
\param{wxCoord
}{ y1
},
\param{wxCoord
}{ x2
},
\param{wxCoord
}{ y2
},
\param{wxCoord
}{ xc
},
\param{wxCoord
}{ yc
}}
242 Draws an arc of a circle, centred on (
{\it xc, yc
}), with starting point (
{\it x1, y1
})
243 and ending at (
{\it x2, y2
}). The current pen is used for the outline
244 and the current brush for filling the shape.
246 The arc is drawn in an anticlockwise direction from the start point to the end point.
249 \membersection{wxDC::DrawBitmap
}\label{wxdcdrawbitmap
}
251 \func{void
}{DrawBitmap
}{\param{const wxBitmap\&
}{ bitmap
},
\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{bool
}{ transparent
}}
253 Draw a bitmap on the device context at the specified point. If
{\it transparent
} is true and the bitmap has
254 a transparency mask, the bitmap will be drawn transparently.
256 When drawing a mono-bitmap, the current text foreground colour will be used to draw the foreground
257 of the bitmap (all bits set to
1), and the current text background colour to draw the background
258 (all bits set to
0). See also
\helpref{SetTextForeground
}{wxdcsettextforeground
},
259 \helpref{SetTextBackground
}{wxdcsettextbackground
} and
\helpref{wxMemoryDC
}{wxmemorydc
}.
262 \membersection{wxDC::DrawCheckMark
}\label{wxdcdrawcheckmark
}
264 \func{void
}{DrawCheckMark
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
}}
266 \func{void
}{DrawCheckMark
}{\param{const wxRect \&
}{rect
}}
268 Draws a check mark inside the given rectangle.
271 \membersection{wxDC::DrawCircle
}\label{wxdcdrawcircle
}
273 \func{void
}{DrawCircle
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ radius
}}
275 \func{void
}{DrawCircle
}{\param{const wxPoint\&
}{ pt
},
\param{wxCoord
}{ radius
}}
277 Draws a circle with the given centre and radius.
281 \helpref{DrawEllipse
}{wxdcdrawellipse
}
284 \membersection{wxDC::DrawEllipse
}\label{wxdcdrawellipse
}
286 \func{void
}{DrawEllipse
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
}}
288 \func{void
}{DrawEllipse
}{\param{const wxPoint\&
}{ pt
},
\param{const wxSize\&
}{ size
}}
290 \func{void
}{DrawEllipse
}{\param{const wxRect\&
}{ rect
}}
292 Draws an ellipse contained in the rectangle specified either with the given top
293 left corner and the given size or directly. The current pen is used for the
294 outline and the current brush for filling the shape.
298 \helpref{DrawCircle
}{wxdcdrawcircle
}
301 \membersection{wxDC::DrawEllipticArc
}\label{wxdcdrawellipticarc
}
303 \func{void
}{DrawEllipticArc
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
},
304 \param{double
}{ start
},
\param{double
}{ end
}}
306 Draws an arc of an ellipse. The current pen is used for drawing the arc and
307 the current brush is used for drawing the pie.
309 {\it x
} and
{\it y
} specify the x and y coordinates of the upper-left corner of the rectangle that contains
312 {\it width
} and
{\it height
} specify the width and height of the rectangle that contains
315 {\it start
} and
{\it end
} specify the start and end of the arc relative to the three-o'clock
316 position from the center of the rectangle. Angles are specified
317 in degrees (
360 is a complete circle). Positive values mean
318 counter-clockwise motion. If
{\it start
} is equal to
{\it end
}, a
319 complete ellipse will be drawn.
322 \membersection{wxDC::DrawIcon
}\label{wxdcdrawicon
}
324 \func{void
}{DrawIcon
}{\param{const wxIcon\&
}{ icon
},
\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
}}
326 Draw an icon on the display (does nothing if the device context is PostScript).
327 This can be the simplest way of drawing bitmaps on a window.
330 \membersection{wxDC::DrawLabel
}\label{wxdcdrawlabel
}
332 \func{virtual void
}{DrawLabel
}{\param{const wxString\&
}{ text
},
333 \param{const wxBitmap\&
}{ image
},
334 \param{const wxRect\&
}{ rect
},
335 \param{int
}{ alignment = wxALIGN
\_LEFT | wxALIGN
\_TOP},
336 \param{int
}{ indexAccel = -
1},
337 \param{wxRect *
}{rectBounding = NULL
}}
339 \func{void
}{DrawLabel
}{\param{const wxString\&
}{ text
},
\param{const wxRect\&
}{ rect
},
340 \param{int
}{ alignment = wxALIGN
\_LEFT | wxALIGN
\_TOP},
341 \param{int
}{ indexAccel = -
1}}
343 Draw optional bitmap and the text into the given rectangle and aligns it as specified
344 by alignment parameter; it also will emphasize the character with the given index if
345 it is != -
1 and return the bounding rectangle if required.
348 \membersection{wxDC::DrawLine
}\label{wxdcdrawline
}
350 \func{void
}{DrawLine
}{\param{wxCoord
}{ x1
},
\param{wxCoord
}{ y1
},
\param{wxCoord
}{ x2
},
\param{wxCoord
}{ y2
}}
352 Draws a line from the first point to the second. The current pen is used
353 for drawing the line. Note that the point $(x2, y2)$ is
{\emph not
} part of the
354 line and is not drawn by this function (this is consistent with the behaviour
355 of many other toolkits).
358 \membersection{wxDC::DrawLines
}\label{wxdcdrawlines
}
360 \func{void
}{DrawLines
}{\param{int
}{ n
},
\param{wxPoint
}{ points
[]},
\param{wxCoord
}{ xoffset =
0},
\param{wxCoord
}{ yoffset =
0}}
362 Draws lines using an array of
{\it points
} of size
{\it n
}
363 adding the optional offset coordinate. The current pen is
364 used for drawing the lines.
366 \func{void
}{DrawLines
}{\param{const wxPointList *
}{points
},
\param{wxCoord
}{ xoffset =
0},
\param{wxCoord
}{ yoffset =
0}}
368 This method uses a list of wxPoints, adding the optional offset
369 coordinate. The programmer is responsible for deleting the list
372 \pythonnote{The wxPython version of this method accepts a Python list
375 \perlnote{The wxPerl version of this method accepts
376 as its first parameter a reference to an array
380 \membersection{wxDC::DrawPolygon
}\label{wxdcdrawpolygon
}
382 \func{void
}{DrawPolygon
}{\param{int
}{ n
},
\param{wxPoint
}{ points
[]},
\param{wxCoord
}{ xoffset =
0},
\param{wxCoord
}{ yoffset =
0},\\
383 \param{int
}{fill
\_style = wxODDEVEN
\_RULE}}
385 Draws a filled polygon using an array of
{\it points
} of size
{\it n
},
386 adding the optional offset coordinate.
388 \func{void
}{DrawPolygon
}{\param{const wxPointList *
}{points
},
\param{wxCoord
}{ xoffset =
0},
\param{wxCoord
}{ yoffset =
0},\\
389 \param{int
}{fill
\_style = wxODDEVEN
\_RULE}}
391 This method draws a filled polygon using a list of wxPoints,
392 adding the optional offset coordinate.
394 The last argument specifies the fill rule:
{\bf wxODDEVEN
\_RULE} (the
395 default) or
{\bf wxWINDING
\_RULE}.
397 The current pen is used for drawing the outline, and the current brush
398 for filling the shape. Using a transparent brush suppresses filling.
399 The programmer is responsible for deleting the list of points.
401 Note that wxWidgets automatically closes the first and last points.
403 \pythonnote{The wxPython version of this method accepts a Python list
406 \perlnote{The wxPerl version of this method accepts
407 as its first parameter a reference to an array
411 \membersection{wxDC::DrawPolyPolygon
}\label{wxdcdrawpolypolygon
}
413 \func{void
}{DrawPolyPolygon
}{\param{int
}{ n
},
\param{int
}{ count
[]},
\param{wxPoint
}{ points
[]},
\param{wxCoord
}{ xoffset =
0},
\param{wxCoord
}{ yoffset =
0},\\
414 \param{int
}{fill
\_style = wxODDEVEN
\_RULE}}
416 Draws two or more filled polygons using an array of
{\it points
}, adding the
417 optional offset coordinates.
419 Notice that for the platforms providing a native implementation
420 of this function (Windows and PostScript-based wxDC currently), this is more
421 efficient than using
\helpref{DrawPolygon
}{wxdcdrawpolygon
} in a loop.
423 {\it n
} specifies the number of polygons to draw, the array
{\it count
} of size
424 {\it n
} specifies the number of points in each of the polygons in the
427 The last argument specifies the fill rule:
{\bf wxODDEVEN
\_RULE} (the default)
428 or
{\bf wxWINDING
\_RULE}.
430 The current pen is used for drawing the outline, and the current brush for
431 filling the shape. Using a transparent brush suppresses filling.
433 The polygons maybe disjoint or overlapping. Each polygon specified in a call to
434 {\bf DrawPolyPolygon
} must be closed. Unlike polygons created by the
435 \helpref{DrawPolygon
}{wxdcdrawpolygon
} member function, the polygons created by
436 {\bf DrawPolyPolygon
} are not closed automatically.
438 \pythonnote{Not implemented yet
}
440 \perlnote{Not implemented yet
}
443 \membersection{wxDC::DrawPoint
}\label{wxdcdrawpoint
}
445 \func{void
}{DrawPoint
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
}}
447 Draws a point using the
color of the current pen. Note that the other properties of the pen are not used, such as width etc..
450 \membersection{wxDC::DrawRectangle
}\label{wxdcdrawrectangle
}
452 \func{void
}{DrawRectangle
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
}}
454 Draws a rectangle with the given top left corner, and with the given
455 size. The current pen is used for the outline and the current brush
456 for filling the shape.
459 \membersection{wxDC::DrawRotatedText
}\label{wxdcdrawrotatedtext
}
461 \func{void
}{DrawRotatedText
}{\param{const wxString\&
}{text
},
\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{double
}{ angle
}}
463 Draws the text rotated by
{\it angle
} degrees.
465 {\bf NB:
} Under Win9x only TrueType fonts can be drawn by this function. In
466 particular, a font different from
{\tt wxNORMAL
\_FONT} should be used as the
467 latter is not a TrueType font.
{\tt wxSWISS
\_FONT} is an example of a font
472 \helpref{DrawText
}{wxdcdrawtext
}
475 \membersection{wxDC::DrawRoundedRectangle
}\label{wxdcdrawroundedrectangle
}
477 \func{void
}{DrawRoundedRectangle
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
},
\param{double
}{ radius
}}
479 Draws a rectangle with the given top left corner, and with the given
480 size. The corners are quarter-circles using the given radius. The
481 current pen is used for the outline and the current brush for filling
484 If
{\it radius
} is positive, the value is assumed to be the
485 radius of the rounded corner. If
{\it radius
} is negative,
486 the absolute value is assumed to be the
{\it proportion
} of the smallest
487 dimension of the rectangle. This means that the corner can be
488 a sensible size relative to the size of the rectangle, and also avoids
489 the strange effects X produces when the corners are too big for
493 \membersection{wxDC::DrawSpline
}\label{wxdcdrawspline
}
495 \func{void
}{DrawSpline
}{\param{int
}{n
},
\param{wxPoint
}{points
[]}}
497 Draws a spline between all given control points, using the current
500 \func{void
}{DrawSpline
}{\param{const wxPointList *
}{points
}}
502 Draws a spline between all given control points.
504 \func{void
}{DrawSpline
}{\param{wxCoord
}{ x1
},
\param{wxCoord
}{ y1
},
\param{wxCoord
}{ x2
},
\param{wxCoord
}{ y2
},
\param{wxCoord
}{ x3
},
\param{wxCoord
}{ y3
}}
506 Draws a three-point spline using the current pen.
508 \pythonnote{The wxPython version of this method accepts a Python list
511 \perlnote{The wxPerl version of this method accepts a reference to an array
515 \membersection{wxDC::DrawText
}\label{wxdcdrawtext
}
517 \func{void
}{DrawText
}{\param{const wxString\&
}{text
},
\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
}}
519 Draws a text string at the specified point, using the current text font,
520 and the current text foreground and background colours.
522 The coordinates refer to the top-left corner of the rectangle bounding
523 the string. See
\helpref{wxDC::GetTextExtent
}{wxdcgettextextent
} for how
524 to get the dimensions of a text string, which can be used to position the
527 {\bf NB:
} under wxGTK the current
528 \helpref{logical function
}{wxdcgetlogicalfunction
} is used by this function
529 but it is ignored by wxMSW. Thus, you should avoid using logical functions
530 with this function in portable programs.
534 \membersection{wxDC::EnableCache
}\label{wxdcenablecache
}
536 \func{static void
}{EnableCache
}{\param{bool
}{ enableCache
}}
538 On supported platforms (currently only Windows), enables the DC cache
539 which can speed up the
\helpref{Blit
}{wxdcblit
} operation when
540 drawing a large number of masked bitmaps.
542 If using the cache functions in your code, please test for the
543 wxUSE
\_DC\_CACHEING preprocessor symbol for portability.
547 \helpref{wxDC::CacheEnabled
}{wxdccacheenabled
},
\helpref{wxDC::ClearCache
}
551 \membersection{wxDC::EndDoc
}\label{wxdcenddoc
}
553 \func{void
}{EndDoc
}{\void}
555 Ends a
document (only relevant when outputting to a printer).
558 \membersection{wxDC::EndPage
}\label{wxdcendpage
}
560 \func{void
}{EndPage
}{\void}
562 Ends a
document page (only relevant when outputting to a printer).
565 \membersection{wxDC::FloodFill
}\label{wxdcfloodfill
}
567 \func{bool
}{FloodFill
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{const wxColour\&
}{ colour
},
\param{int
}{ style=wxFLOOD
\_SURFACE}}
569 Flood fills the device context starting from the given point, using
570 the
{\it current brush colour
}, and using a style:
572 \begin{itemize
}\itemsep=
0pt
573 \item wxFLOOD
\_SURFACE: the flooding occurs until a colour other than the given colour is encountered.
574 \item wxFLOOD
\_BORDER: the area to be flooded is bounded by the given colour.
577 Returns false if the operation failed.
579 {\it Note:
} The present implementation for non-Windows platforms may fail to find
580 colour borders if the pixels do not match the colour exactly. However the
581 function will still return true.
584 \membersection{wxDC::GetBackground
}\label{wxdcgetbackground
}
586 \constfunc{const wxBrush\&
}{GetBackground
}{\void}
588 Gets the brush used for painting the background (see
\helpref{wxDC::SetBackground
}{wxdcsetbackground
}).
591 \membersection{wxDC::GetBackgroundMode
}\label{wxdcgetbackgroundmode
}
593 \constfunc{int
}{GetBackgroundMode
}{\void}
595 Returns the current background mode:
{\tt wxSOLID
} or
{\tt wxTRANSPARENT
}.
599 \helpref{SetBackgroundMode
}{wxdcsetbackgroundmode
}
602 \membersection{wxDC::GetBrush
}\label{wxdcgetbrush
}
604 \constfunc{const wxBrush\&
}{GetBrush
}{\void}
606 Gets the current brush (see
\helpref{wxDC::SetBrush
}{wxdcsetbrush
}).
609 \membersection{wxDC::GetCharHeight
}\label{wxdcgetcharheight
}
611 \func{wxCoord
}{GetCharHeight
}{\void}
613 Gets the character height of the currently set font.
616 \membersection{wxDC::GetCharWidth
}\label{wxdcgetcharwidth
}
618 \func{wxCoord
}{GetCharWidth
}{\void}
620 Gets the average character width of the currently set font.
623 \membersection{wxDC::GetClippingBox
}\label{wxdcgetclippingbox
}
625 \func{void
}{GetClippingBox
}{\param{wxCoord
}{ *x
},
\param{wxCoord
}{ *y
},
\param{wxCoord
}{ *width
},
\param{wxCoord
}{ *height
}}
627 Gets the rectangle surrounding the current clipping region.
629 \pythonnote{No arguments are required and the four values defining the
630 rectangle are returned as a tuple.
}
632 \perlnote{This method takes no arguments and returns a four element list
633 {\tt ( x, y, width, height )
}}
636 \membersection{wxDC::GetFont
}\label{wxdcgetfont
}
638 \constfunc{const wxFont\&
}{GetFont
}{\void}
640 Gets the current font. Notice that even although each device context object has
641 some default font after creation, this method would return a
\texttt{wxNullFont
}
642 initially and only after calling
\helpref{wxDC::SetFont
}{wxdcsetfont
} a valid
646 \membersection{wxDC::GetLayoutDirection
}\label{wxdcgetlayoutdirection
}
648 \constfunc{wxLayoutDirection
}{GetLayoutDirection
}{\void}
650 Gets the current layout direction of the device context. On platforms where RTL layout
651 is supported, the return value will either be
\texttt{wxLayout
\_LeftToRight} or
652 \texttt{wxLayout
\_RightToLeft}. If RTL layout is not supported, the return value will
653 be
\texttt{wxLayout
\_Default}.
657 \helpref{SetLayoutDirection
}{wxdcsetlayoutdirection
}
660 \membersection{wxDC::GetLogicalFunction
}\label{wxdcgetlogicalfunction
}
662 \func{int
}{GetLogicalFunction
}{\void}
664 Gets the current logical function (see
\helpref{wxDC::SetLogicalFunction
}{wxdcsetlogicalfunction
}).
667 \membersection{wxDC::GetMapMode
}\label{wxdcgetmapmode
}
669 \func{int
}{GetMapMode
}{\void}
671 Gets the
{\it mapping mode
} for the device context (see
\helpref{wxDC::SetMapMode
}{wxdcsetmapmode
}).
674 \membersection{wxDC::GetMultiLineTextExtent
}\label{wxdcgetmultilinetextextent
}
676 \constfunc{void
}{GetMultiLineTextExtent
}{\param{const wxString\&
}{string
},
\param{wxCoord *
}{w
},\\
677 \param{wxCoord *
}{h
},
\param{wxCoord *
}{heightLine = NULL
},
\param{wxFont *
}{font = NULL
}}
679 \constfunc{wxSize
}{GetMultiLineTextExtent
}{\param{const wxString\&
}{string
}}
681 Gets the dimensions of the string using the currently selected font.
682 \rtfsp{\it string
} is the text string to measure,
{\it heightLine
}, if non NULL,
683 is where to store the height of a single line.
685 The text extent is returned in
{\it w
} and
{\it h
} pointers (first form) or as
686 a
\helpref{wxSize
}{wxsize
} object (second form).
688 If the optional parameter
{\it font
} is specified and valid, then it is used
689 for the text extent calculation. Otherwise the currently selected font is.
691 Note that this function works both with single-line and multi-line strings.
695 \helpref{wxFont
}{wxfont
},
\rtfsp
696 \helpref{wxDC::SetFont
}{wxdcsetfont
},
\rtfsp
697 \helpref{wxDC::GetPartialTextExtents
}{wxdcgetpartialtextextents
},
\rtfsp
698 \helpref{wxDC::GetTextExtent
}{wxdcgettextextent
}
701 \membersection{wxDC::GetPartialTextExtents
}\label{wxdcgetpartialtextextents
}
703 \constfunc{bool
}{GetPartialTextExtents
}{\param{const wxString\&
}{text
},
704 \param{wxArrayInt\&
}{widths
}}
706 Fills the
{\it widths
} array with the widths from the beginning of
707 {\it text
} to the corresponding character of
{\it text
}. The generic
708 version simply builds a running total of the widths of each character
709 using
\helpref{GetTextExtent
}{wxdcgettextextent
}, however if the
710 various platforms have a native API function that is faster or more
711 accurate than the generic implementation then it should be used
716 \helpref{wxDC::GetMultiLineTextExtent
}{wxdcgetmultilinetextextent
},
\rtfsp
717 \helpref{wxDC::GetTextExtent
}{wxdcgettextextent
}
719 \pythonnote{This method only takes the
{\it text
} parameter and
720 returns a Python list of integers.
}
723 \membersection{wxDC::GetPen
}\label{wxdcgetpen
}
725 \constfunc{const wxPen\&
}{GetPen
}{\void}
727 Gets the current pen (see
\helpref{wxDC::SetPen
}{wxdcsetpen
}).
730 \membersection{wxDC::GetPixel
}\label{wxdcgetpixel
}
732 \func{bool
}{GetPixel
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxColour *
}{colour
}}
734 Gets in
{\it colour
} the colour at the specified location.
735 Not available for wxPostScriptDC or wxMetafileDC.
737 Note that setting a pixel can be done using
\helpref{DrawPoint
}{wxdcdrawpoint
}.
739 \pythonnote{For wxPython the wxColour value is returned and is not
740 required as a parameter.
}
742 \perlnote{This method only takes the parameters
{\tt x
} and
{\tt y
} and returns
745 \membersection{wxDC::GetPPI
}\label{wxdcgetppi
}
747 \constfunc{wxSize
}{GetPPI
}{\void}
749 Returns the resolution of the device in pixels per inch.
751 \membersection{wxDC::GetSize
}\label{wxdcgetsize
}
753 \constfunc{void
}{GetSize
}{\param{wxCoord *
}{width
},
\param{wxCoord *
}{height
}}
755 \constfunc{wxSize
}{GetSize
}{\void}
757 This gets the horizontal and vertical resolution in device units. It can be used to scale graphics to fit the page.
758 For example, if
{\it maxX
} and
{\it maxY
}\rtfsp
759 represent the maximum horizontal and vertical `pixel' values used in your
760 application, the following code will scale the graphic to fit on the
766 double scaleX=(double)(maxX/w);
767 double scaleY=(double)(maxY/h);
768 dc.SetUserScale(min(scaleX,scaleY),min(scaleX,scaleY));
771 \pythonnote{In place of a single overloaded method name, wxPython
772 implements the following methods:
\par
773 \indented{2cm
}{\begin{twocollist
}
774 \twocolitem{{\bf GetSize()
}}{Returns a wxSize
}
775 \twocolitem{{\bf GetSizeTuple()
}}{Returns a
2-tuple (width, height)
}
779 \perlnote{In place of a single overloaded method, wxPerl uses:
\par
780 \indented{2cm
}{\begin{twocollist
}
781 \twocolitem{{\bf GetSize()
}}{Returns a Wx::Size
}
782 \twocolitem{{\bf GetSizeWH()
}}{Returns a
2-element list
783 {\tt ( width, height )
}}
787 \membersection{wxDC::GetSizeMM
}\label{wxdcgetsizemm
}
789 \constfunc{void
}{GetSizeMM
}{\param{wxCoord *
}{width
},
\param{wxCoord *
}{height
}}
791 \constfunc{wxSize
}{GetSizeMM
}{\void}
793 Returns the horizontal and vertical resolution in millimetres.
795 \membersection{wxDC::GetTextBackground
}\label{wxdcgettextbackground
}
797 \constfunc{const wxColour\&
}{GetTextBackground
}{\void}
799 Gets the current text background colour (see
\helpref{wxDC::SetTextBackground
}{wxdcsettextbackground
}).
802 \membersection{wxDC::GetTextExtent
}\label{wxdcgettextextent
}
804 \constfunc{void
}{GetTextExtent
}{\param{const wxString\&
}{string
},
\param{wxCoord *
}{w
},
\param{wxCoord *
}{h
},\\
805 \param{wxCoord *
}{descent = NULL
},
\param{wxCoord *
}{externalLeading = NULL
},
\param{const wxFont *
}{font = NULL
}}
807 \constfunc{wxSize
}{GetTextExtent
}{\param{const wxString\&
}{string
}}
809 Gets the dimensions of the string using the currently selected font.
810 \rtfsp{\it string
} is the text string to measure,
{\it descent
} is the
811 dimension from the baseline of the font to the bottom of the
812 descender, and
{\it externalLeading
} is any extra vertical space added
813 to the font by the font designer (usually is zero).
815 The text extent is returned in
{\it w
} and
{\it h
} pointers (first form) or as
816 a
\helpref{wxSize
}{wxsize
} object (second form).
818 If the optional parameter
{\it font
} is specified and valid, then it is used
819 for the text extent calculation. Otherwise the currently selected font is.
821 Note that this function only works with single-line strings.
825 \helpref{wxFont
}{wxfont
},
\rtfsp
826 \helpref{wxDC::SetFont
}{wxdcsetfont
},
\rtfsp
827 \helpref{wxDC::GetPartialTextExtents
}{wxdcgetpartialtextextents
},
\rtfsp
828 \helpref{wxDC::GetMultiLineTextExtent
}{wxdcgetmultilinetextextent
}
830 \pythonnote{The following methods are implemented in wxPython:
\par
831 \indented{2cm
}{\begin{twocollist
}
832 \twocolitem{{\bf GetTextExtent(string)
}}{Returns a
2-tuple, (width, height)
}
833 \twocolitem{{\bf GetFullTextExtent(string, font=NULL)
}}{Returns a
834 4-tuple, (width, height, descent, externalLeading)
}
838 \perlnote{In wxPerl this method is implemented as
839 {\bf GetTextExtent( string, font = undef )
} returning a four element
840 array
{\tt ( width, height, descent, externalLeading )
}
844 \membersection{wxDC::GetTextForeground
}\label{wxdcgettextforeground
}
846 \constfunc{const wxColour\&
}{GetTextForeground
}{\void}
848 Gets the current text foreground colour (see
\helpref{wxDC::SetTextForeground
}{wxdcsettextforeground
}).
851 \membersection{wxDC::GetUserScale
}\label{wxdcgetuserscale
}
853 \func{void
}{GetUserScale
}{\param{double
}{ *x
},
\param{double
}{ *y
}}
855 Gets the current user scale factor (set by
\helpref{SetUserScale
}{wxdcsetuserscale
}).
857 \perlnote{In wxPerl this method takes no arguments and return a two element
858 array
{\tt ( x, y )
}}
861 \membersection{wxDC::GradientFillConcentric
}\label{wxdcgradientfillconcentric
}
863 \func{void
}{GradientFillConcentric
}{\param{const wxRect\&
}{ rect
},
\param{const wxColour\&
}{ initialColour
},
\param{const wxColour\&
}{ destColour
}}
865 \func{void
}{GradientFillConcentric
}{\param{const wxRect\&
}{ rect
},
\param{const wxColour\&
}{ initialColour
},
\param{const wxColour\&
}{ destColour
},
\param{const wxPoint\&
}{circleCenter
}}
867 Fill the area specified by rect with a radial gradient, starting from
868 \arg{initialColour
} at the centre of the circle and fading to
\arg{destColour
}
869 on the circle outside.
871 \arg{circleCenter
} are the relative coordinates of centre of the circle in
872 the specified
\arg{rect
}. If not specified, the cercle is placed at the
875 \textbf{Note:
} Currently this function is very slow, don't use it for
879 \membersection{wxDC::GradientFillLinear
}\label{wxdcgradientfilllinear
}
881 \func{void
}{GradientFillLinear
}{\param{const wxRect\&
}{ rect
},
\param{const wxColour\&
}{ initialColour
},
\param{const wxColour\&
}{ destColour
},
\param{wxDirection
}{ nDirection = wxEAST
}}
883 Fill the area specified by
\arg{rect
} with a linear gradient, starting from
884 \arg{initialColour
} and eventually fading to
\arg{destColour
}. The
885 \arg{nDirection
} specifies the direction of the colour change, default is to
886 use
\arg{initialColour
} on the left part of the rectangle and
887 \arg{destColour
} on the right one.
890 \membersection{wxDC::LogicalToDeviceX
}\label{wxdclogicaltodevicex
}
892 \func{virtual wxCoord
}{LogicalToDeviceX
}{\param{wxCoord
}{ x
}}
894 Converts logical X coordinate to device coordinate, using the current
898 \membersection{wxDC::LogicalToDeviceXRel
}\label{wxdclogicaltodevicexrel
}
900 \func{virtual wxCoord
}{LogicalToDeviceXRel
}{\param{wxCoord
}{ x
}}
902 Converts logical X coordinate to relative device coordinate, using the current
903 mapping mode but ignoring the x axis orientation.
904 Use this for converting a width, for example.
907 \membersection{wxDC::LogicalToDeviceY
}\label{wxdclogicaltodevicey
}
909 \func{virtual wxCoord
}{LogicalToDeviceY
}{\param{wxCoord
}{ y
}}
911 Converts logical Y coordinate to device coordinate, using the current
915 \membersection{wxDC::LogicalToDeviceYRel
}\label{wxdclogicaltodeviceyrel
}
917 \func{virtual wxCoord
}{LogicalToDeviceYRel
}{\param{wxCoord
}{ y
}}
919 Converts logical Y coordinate to relative device coordinate, using the current
920 mapping mode but ignoring the y axis orientation.
921 Use this for converting a height, for example.
924 \membersection{wxDC::MaxX
}\label{wxdcmaxx
}
926 \func{wxCoord
}{MaxX
}{\void}
928 Gets the maximum horizontal extent used in drawing commands so far.
931 \membersection{wxDC::MaxY
}\label{wxdcmaxy
}
933 \func{wxCoord
}{MaxY
}{\void}
935 Gets the maximum vertical extent used in drawing commands so far.
938 \membersection{wxDC::MinX
}\label{wxdcminx
}
940 \func{wxCoord
}{MinX
}{\void}
942 Gets the minimum horizontal extent used in drawing commands so far.
945 \membersection{wxDC::MinY
}\label{wxdcminy
}
947 \func{wxCoord
}{MinY
}{\void}
949 Gets the minimum vertical extent used in drawing commands so far.
952 \membersection{wxDC::IsOk
}\label{wxdcisok
}
954 \func{bool
}{Ok
}{\void}
956 Returns true if the DC is ok to use.
959 \membersection{wxDC::ResetBoundingBox
}\label{wxdcresetboundingbox
}
961 \func{void
}{ResetBoundingBox
}{\void}
963 Resets the bounding box: after a call to this function, the bounding box
964 doesn't contain anything.
968 \helpref{CalcBoundingBox
}{wxdccalcboundingbox
}
971 \membersection{wxDC::SetAxisOrientation
}\label{wxdcsetaxisorientation
}
973 \func{void
}{SetAxisOrientation
}{\param{bool
}{ xLeftRight
},
974 \param{bool
}{ yBottomUp
}}
976 Sets the x and y axis orientation (i.e., the direction from lowest to
977 highest values on the axis). The default orientation is
978 x axis from left to right and y axis from top down.
980 \wxheading{Parameters
}
982 \docparam{xLeftRight
}{True to set the x axis orientation to the natural
983 left to right orientation, false to invert it.
}
985 \docparam{yBottomUp
}{True to set the y axis orientation to the natural
986 bottom up orientation, false to invert it.
}
989 \membersection{wxDC::SetBackground
}\label{wxdcsetbackground
}
991 \func{void
}{SetBackground
}{\param{const wxBrush\&
}{brush
}}
993 Sets the current background brush for the DC.
996 \membersection{wxDC::SetBackgroundMode
}\label{wxdcsetbackgroundmode
}
998 \func{void
}{SetBackgroundMode
}{\param{int
}{ mode
}}
1000 {\it mode
} may be one of wxSOLID and wxTRANSPARENT. This setting determines
1001 whether text will be drawn with a background colour or not.
1004 \membersection{wxDC::SetBrush
}\label{wxdcsetbrush
}
1006 \func{void
}{SetBrush
}{\param{const wxBrush\&
}{brush
}}
1008 Sets the current brush for the DC.
1010 If the argument is wxNullBrush, the current brush is selected out of the device
1011 context (leaving wxDC without any valid brush), allowing the current brush to
1012 be destroyed safely.
1014 See also
\helpref{wxBrush
}{wxbrush
}.
1016 See also
\helpref{wxMemoryDC
}{wxmemorydc
} for the interpretation of colours
1017 when drawing into a monochrome bitmap.
1020 \membersection{wxDC::SetClippingRegion
}\label{wxdcsetclippingregion
}
1022 \func{void
}{SetClippingRegion
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
},
\param{wxCoord
}{ width
},
\param{wxCoord
}{ height
}}
1024 \func{void
}{SetClippingRegion
}{\param{const wxPoint\&
}{pt
},
\param{const wxSize\&
}{sz
}}
1026 \func{void
}{SetClippingRegion
}{\param{const wxRect\&
}{ rect
}}
1028 \func{void
}{SetClippingRegion
}{\param{const wxRegion\&
}{ region
}}
1030 Sets the clipping region for this device context to the intersection of the
1031 given region described by the parameters of this method and the previously set
1032 clipping region. You should call
1033 \helpref{DestroyClippingRegion
}{wxdcdestroyclippingregion
} if you want to set
1034 the clipping region exactly to the region specified.
1036 The clipping region is an area to which drawing is restricted. Possible uses
1037 for the clipping region are for clipping text or for speeding up window redraws
1038 when only a known area of the screen is damaged.
1040 \wxheading{See also
}
1042 \helpref{wxDC::DestroyClippingRegion
}{wxdcdestroyclippingregion
},
\helpref{wxRegion
}{wxregion
}
1045 \membersection{wxDC::SetDeviceOrigin
}\label{wxdcsetdeviceorigin
}
1047 \func{void
}{SetDeviceOrigin
}{\param{wxCoord
}{ x
},
\param{wxCoord
}{ y
}}
1049 Sets the device origin (i.e., the origin in pixels after scaling has been
1052 This function may be useful in Windows printing
1053 operations for placing a graphic on a page.
1056 \membersection{wxDC::SetFont
}\label{wxdcsetfont
}
1058 \func{void
}{SetFont
}{\param{const wxFont\&
}{font
}}
1060 Sets the current font for the DC. It must be a valid font, in particular you
1061 should not pass
{\tt wxNullFont
} to this method.
1063 See also
\helpref{wxFont
}{wxfont
}.
1066 \membersection{wxDC::SetLayoutDirection
}\label{wxdcsetlayoutdirection
}
1068 \func{void
}{SetLayoutDirection
}{\param{wxLayoutDirection
}{ dir
}}
1070 Sets the current layout direction for the device context.
\arg{dir
} may be either
1071 \texttt{wxLayout
\_Default},
\texttt{wxLayout
\_LeftToRight} or
\texttt{wxLayout
\_RightToLeft}.
1073 \wxheading{See also
}
1075 \helpref{GetLayoutDirection
}{wxdcgetlayoutdirection
}
1078 \membersection{wxDC::SetLogicalFunction
}\label{wxdcsetlogicalfunction
}
1080 \func{void
}{SetLogicalFunction
}{\param{int
}{ function
}}
1082 Sets the current logical function for the device context. This determines how
1083 a source pixel (from a pen or brush colour, or source device context if
1084 using
\helpref{wxDC::Blit
}{wxdcblit
}) combines with a destination pixel in the
1085 current device context.
1088 and their meaning in terms of source and destination pixel values are
1093 wxAND_INVERT (NOT src) AND dst
1094 wxAND_REVERSE src AND (NOT dst)
1097 wxEQUIV (NOT src) XOR dst
1099 wxNAND (NOT src) OR (NOT dst)
1100 wxNOR (NOT src) AND (NOT dst)
1103 wxOR_INVERT (NOT src) OR dst
1104 wxOR_REVERSE src OR (NOT dst)
1106 wxSRC_INVERT NOT src
1110 The default is wxCOPY, which simply draws with the current colour.
1111 The others combine the current colour and the background using a
1112 logical operation. wxINVERT is commonly used for drawing rubber bands or
1113 moving outlines, since drawing twice reverts to the original colour.
1116 \membersection{wxDC::SetMapMode
}\label{wxdcsetmapmode
}
1118 \func{void
}{SetMapMode
}{\param{int
}{ int
}}
1120 The
{\it mapping mode
} of the device context defines the unit of
1121 measurement used to convert logical units to device units. Note that
1122 in X, text drawing isn't handled consistently with the mapping mode; a
1123 font is always specified in point size. However, setting the
{\it
1124 user scale
} (see
\helpref{wxDC::SetUserScale
}{wxdcsetuserscale
}) scales the text appropriately. In
1125 Windows, scalable TrueType fonts are always used; in X, results depend
1126 on availability of fonts, but usually a reasonable match is found.
1128 The coordinate origin is always at the top left of the screen/printer.
1130 Drawing to a Windows printer device context uses the current mapping mode,
1131 but mapping mode is currently ignored for PostScript output.
1133 The mapping mode can be one of the following:
1135 \begin{twocollist
}\itemsep=
0pt
1136 \twocolitem{wxMM
\_TWIPS}{Each logical unit is
1/
20 of a point, or
1/
1440 of
1138 \twocolitem{wxMM
\_POINTS}{Each logical unit is a point, or
1/
72 of an inch.
}
1139 \twocolitem{wxMM
\_METRIC}{Each logical unit is
1 mm.
}
1140 \twocolitem{wxMM
\_LOMETRIC}{Each logical unit is
1/
10 of a mm.
}
1141 \twocolitem{wxMM
\_TEXT}{Each logical unit is
1 pixel.
}
1145 \membersection{wxDC::SetPalette
}\label{wxdcsetpalette
}
1147 \func{void
}{SetPalette
}{\param{const wxPalette\&
}{palette
}}
1149 If this is a window DC or memory DC, assigns the given palette to the window
1150 or bitmap associated with the DC. If the argument is wxNullPalette, the current
1151 palette is selected out of the device context, and the original palette
1154 See
\helpref{wxPalette
}{wxpalette
} for further details.
1157 \membersection{wxDC::SetPen
}\label{wxdcsetpen
}
1159 \func{void
}{SetPen
}{\param{const wxPen\&
}{pen
}}
1161 Sets the current pen for the DC.
1163 If the argument is wxNullPen, the current pen is selected out of the device
1164 context (leaving wxDC without any valid pen), allowing the current brush to
1165 be destroyed safely.
1167 See also
\helpref{wxMemoryDC
}{wxmemorydc
} for the interpretation of colours
1168 when drawing into a monochrome bitmap.
1171 \membersection{wxDC::SetTextBackground
}\label{wxdcsettextbackground
}
1173 \func{void
}{SetTextBackground
}{\param{const wxColour\&
}{colour
}}
1175 Sets the current text background colour for the DC.
1178 \membersection{wxDC::SetTextForeground
}\label{wxdcsettextforeground
}
1180 \func{void
}{SetTextForeground
}{\param{const wxColour\&
}{colour
}}
1182 Sets the current text foreground colour for the DC.
1184 See also
\helpref{wxMemoryDC
}{wxmemorydc
} for the interpretation of colours
1185 when drawing into a monochrome bitmap.
1188 \membersection{wxDC::SetUserScale
}\label{wxdcsetuserscale
}
1190 \func{void
}{SetUserScale
}{\param{double
}{ xScale
},
\param{double
}{ yScale
}}
1192 Sets the user scaling factor, useful for applications which require
1196 \membersection{wxDC::StartDoc
}\label{wxdcstartdoc
}
1198 \func{bool
}{StartDoc
}{\param{const wxString\&
}{message
}}
1200 Starts a
document (only relevant when outputting to a printer).
1201 Message is a message to show while printing.
1204 \membersection{wxDC::StartPage
}\label{wxdcstartpage
}
1206 \func{bool
}{StartPage
}{\void}
1208 Starts a
document page (only relevant when outputting to a printer).
1211 \membersection{wxDC::StretchBlit
}\label{wxdcstretchblit
}
1213 \func{bool
}{StretchBlit
}{\param{wxCoord
}{ xdest
},
\param{wxCoord
}{ ydest
},
\param{wxCoord
}{ dstWidth
},
\param{wxCoord
}{ dstHeight
},
1214 \param{wxDC*
}{source
},
\param{wxCoord
}{ xsrc
},
\param{wxCoord
}{ ysrc
},
\param{wxCoord
}{ srcWidth
},
\param{wxCoord
}{ srcHeight
},
1215 \param{int
}{ logicalFunc = wxCOPY
},
\param{bool
}{useMask = false
},
\param{wxCoord
}{ xsrcMask = -
1},
\param{wxCoord
}{ ysrcMask = -
1}}
1217 Copy from a source DC to this DC, specifying the destination
1218 coordinates, destination size, source DC, source coordinates,
1219 size of source area to copy, logical function, whether to use a bitmap mask,
1220 and mask source position.
1222 \wxheading{Parameters
}
1224 \docparam{xdest
}{Destination device context x position.
}
1226 \docparam{ydest
}{Destination device context y position.
}
1228 \docparam{dstWidth
}{Width of destination area.
}
1230 \docparam{dstHeight
}{Height of destination area.
}
1232 \docparam{source
}{Source device context.
}
1234 \docparam{xsrc
}{Source device context x position.
}
1236 \docparam{ysrc
}{Source device context y position.
}
1238 \docparam{srcWidth
}{Width of source area to be copied.
}
1240 \docparam{srcHeight
}{Height of source area to be copied.
}
1242 \docparam{logicalFunc
}{Logical function to use: see
\helpref{wxDC::SetLogicalFunction
}{wxdcsetlogicalfunction
}.
}
1244 \docparam{useMask
}{If true, Blit does a transparent blit using the mask that is associated with the bitmap
1245 selected into the source device context. The Windows implementation does the following if
\texttt{MaskBlt
} cannot be used:
1248 \item Creates a temporary bitmap and copies the destination area into it.
1249 \item Copies the source area into the temporary bitmap using the specified logical function.
1250 \item Sets the masked area in the temporary bitmap to BLACK by ANDing the
1251 mask bitmap with the temp bitmap with the foreground colour set to WHITE
1252 and the background colour set to BLACK.
1253 \item Sets the unmasked area in the destination area to BLACK by ANDing the
1254 mask bitmap with the destination area with the foreground colour set to BLACK
1255 and the background colour set to WHITE.
1256 \item ORs the temporary bitmap with the destination area.
1257 \item Deletes the temporary bitmap.
1260 This sequence of operations ensures that the source's transparent area need not be black,
1261 and logical functions are supported.
1263 {\bf Note:
} on Windows, blitting with masks can be speeded up considerably by compiling
1264 wxWidgets with the
\texttt{wxUSE
\_DC\_CACHE} option enabled. You can also influence whether
\texttt{MaskBlt
}
1265 or the explicit mask blitting code above is used, by using
\helpref{wxSystemOptions
}{wxsystemoptions
} and
1266 setting the
{\bf no-maskblt
} option to
1.
1270 \docparam{xsrcMask
}{Source x position on the mask. If both xsrcMask and ysrcMask are -
1, xsrc and ysrc
1271 will be assumed for the mask source position. Currently only implemented on Windows.
}
1273 \docparam{ysrcMask
}{Source y position on the mask. If both xsrcMask and ysrcMask are -
1, xsrc and ysrc
1274 will be assumed for the mask source position. Currently only implemented on Windows.
}
1279 There is partial support for Blit in wxPostScriptDC, under X.
1281 wxDC::StretchBlit is only implemented under wxMAC and wxMSW.
1283 See
\helpref{wxMemoryDC
}{wxmemorydc
} for typical usage.
1287 \wxheading{See also
}
1289 \helpref{wxDC::Blit
}{wxdcblit
},
\helpref{wxMemoryDC
}{wxmemorydc
},
\helpref{wxBitmap
}{wxbitmap
},
\helpref{wxMask
}{wxmask
}