]>
Commit | Line | Data |
---|---|---|
a660d684 KB |
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, | |
fe604ccd | 5 | so a window can have a device context associated with it, and a printer also has a device context. |
a660d684 KB |
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 | ||
954b8ae6 JS |
16 | \wxheading{Include files} |
17 | ||
18 | <wx/dc.h> | |
19 | ||
a660d684 KB |
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 | ||
1f897d25 VZ |
55 | \func{bool}{Blit}{\param{wxCoord}{ xdest}, \param{wxCoord}{ ydest}, \param{wxCoord}{ width}, \param{wxCoord}{ height}, |
56 | \param{wxDC* }{source}, \param{wxCoord}{ xsrc}, \param{wxCoord}{ ysrc}, \param{int}{ logicalFunc = wxCOPY}, | |
ac1edf35 | 57 | \param{bool }{useMask = FALSE}} |
a660d684 KB |
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 | ||
ac1edf35 | 107 | \wxheading{See also} |
a660d684 KB |
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 | ||
1f897d25 | 119 | \func{void}{CrossHair}{\param{wxCoord}{ x}, \param{wxCoord}{ y}} |
a660d684 KB |
120 | |
121 | Displays a cross hair using the current pen. This is a vertical | |
fe604ccd | 122 | and horizontal line the height and width of the window, centred |
a660d684 KB |
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 | ||
1f897d25 | 134 | \func{wxCoord}{DeviceToLogicalX}{\param{wxCoord}{ x}} |
a660d684 KB |
135 | |
136 | Convert device X coordinate to logical coordinate, using the current | |
137 | mapping mode. | |
138 | ||
139 | \membersection{wxDC::DeviceToLogicalXRel}\label{wxdcdevicetologicalxrel} | |
140 | ||
1f897d25 | 141 | \func{wxCoord}{DeviceToLogicalXRel}{\param{wxCoord}{ x}} |
a660d684 KB |
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 | ||
1f897d25 | 148 | \func{wxCoord}{DeviceToLogicalY}{\param{wxCoord}{ y}} |
a660d684 KB |
149 | |
150 | Converts device Y coordinate to logical coordinate, using the current | |
151 | mapping mode. | |
152 | ||
153 | \membersection{wxDC::DeviceToLogicalYRel}\label{wxdcdevicetologicalyrel} | |
154 | ||
1f897d25 | 155 | \func{wxCoord}{DeviceToLogicalYRel}{\param{wxCoord}{ y}} |
a660d684 KB |
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 | ||
1f897d25 | 162 | \func{void}{DrawArc}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}, \param{double}{ xc}, \param{double}{ yc}} |
a660d684 | 163 | |
b8de493f | 164 | Draws an arc of a circle, centred on ({\it xc, yc}), with starting point ({\it x1, y1}) |
a660d684 KB |
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 | ||
b8de493f JS |
168 | The arc is drawn in an anticlockwise direction from the start point to the end point. |
169 | ||
72fd19a1 JS |
170 | \membersection{wxDC::DrawBitmap}\label{wxdcdrawbitmap} |
171 | ||
1f897d25 | 172 | \func{void}{DrawBitmap}{\param{const wxBitmap\&}{ bitmap}, \param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{bool}{ transparent}} |
72fd19a1 JS |
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 | ||
41fbc841 | 177 | When drawing a mono-bitmap, the current text foreground colour will be used to draw the foreground |
9000c624 RR |
178 | of the bitmap (all bits set to 1), and the current text background colour to draw the background |
179 | (all bits set to 0). See also \helpref{SetTextForeground}{wxdcsettextforeground}, | |
180 | \helpref{SetTextBackground}{wxdcsettextbackground} and \helpref{wxMemoryDC}{wxmemorydc}. | |
41fbc841 | 181 | |
a660d684 KB |
182 | \membersection{wxDC::DrawEllipse}\label{wxdcdrawellipse} |
183 | ||
1f897d25 | 184 | \func{void}{DrawEllipse}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}} |
a660d684 KB |
185 | |
186 | Draws an ellipse contained in the rectangle with the given top left corner, and with the | |
187 | given size. The current pen is used for the outline and the current brush for | |
188 | filling the shape. | |
189 | ||
190 | \membersection{wxDC::DrawEllipticArc}\label{wxdcdrawellipticarc} | |
191 | ||
1f897d25 | 192 | \func{void}{DrawEllipticArc}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}, |
a660d684 KB |
193 | \param{double}{ start}, \param{double}{ end}} |
194 | ||
06d20283 | 195 | Draws an arc of an ellipse. The current pen is used for drawing the arc and |
a660d684 | 196 | the current brush is used for drawing the pie. This function is currently only available for |
fe604ccd | 197 | X window and PostScript device contexts. |
a660d684 KB |
198 | |
199 | {\it x} and {\it y} specify the x and y coordinates of the upper-left corner of the rectangle that contains | |
200 | the ellipse. | |
201 | ||
06d20283 | 202 | {\it width} and {\it height} specify the width and height of the rectangle that contains |
a660d684 KB |
203 | the ellipse. |
204 | ||
205 | {\it start} and {\it end} specify the start and end of the arc relative to the three-o'clock | |
206 | position from the center of the rectangle. Angles are specified | |
207 | in degrees (360 is a complete circle). Positive values mean | |
208 | counter-clockwise motion. If {\it start} is equal to {\it end}, a | |
209 | complete ellipse will be drawn. | |
210 | ||
211 | \membersection{wxDC::DrawIcon}\label{wxdcdrawicon} | |
212 | ||
1f897d25 | 213 | \func{void}{DrawIcon}{\param{const wxIcon\&}{ icon}, \param{wxCoord}{ x}, \param{wxCoord}{ y}} |
a660d684 KB |
214 | |
215 | Draw an icon on the display (does nothing if the device context is PostScript). | |
fe604ccd | 216 | This can be the simplest way of drawing bitmaps on a window. |
a660d684 KB |
217 | |
218 | \membersection{wxDC::DrawLine}\label{wxdcdrawline} | |
219 | ||
1f897d25 | 220 | \func{void}{DrawLine}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}} |
a660d684 KB |
221 | |
222 | Draws a line from the first point to the second. The current pen is used | |
223 | for drawing the line. | |
224 | ||
225 | \membersection{wxDC::DrawLines}\label{wxdcdrawlines} | |
226 | ||
1f897d25 | 227 | \func{void}{DrawLines}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0}} |
a660d684 | 228 | |
1f897d25 | 229 | \func{void}{DrawLines}{\param{wxList *}{points}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0}} |
a660d684 KB |
230 | |
231 | Draws lines using an array of {\it points} of size {\it n}, or list of | |
232 | pointers to points, adding the optional offset coordinate. The current | |
233 | pen is used for drawing the lines. The programmer is responsible for | |
234 | deleting the list of points. | |
235 | ||
06d20283 RD |
236 | \pythonnote{The wxPython version of this method accepts a Python list |
237 | of wxPoint objects.} | |
238 | ||
a660d684 KB |
239 | \membersection{wxDC::DrawPolygon}\label{wxdcdrawpolygon} |
240 | ||
1f897d25 | 241 | \func{void}{DrawPolygon}{\param{int}{ n}, \param{wxPoint}{ points[]}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0},\\ |
a660d684 KB |
242 | \param{int }{fill\_style = wxODDEVEN\_RULE}} |
243 | ||
1f897d25 | 244 | \func{void}{DrawPolygon}{\param{wxList *}{points}, \param{wxCoord}{ xoffset = 0}, \param{wxCoord}{ yoffset = 0},\\ |
a660d684 KB |
245 | \param{int }{fill\_style = wxODDEVEN\_RULE}} |
246 | ||
247 | Draws a filled polygon using an array of {\it points} of size {\it n}, | |
248 | or list of pointers to points, adding the optional offset coordinate. | |
249 | ||
250 | The last argument specifies the fill rule: {\bf wxODDEVEN\_RULE} (the | |
251 | default) or {\bf wxWINDING\_RULE}. | |
252 | ||
253 | The current pen is used for drawing the outline, and the current brush | |
254 | for filling the shape. Using a transparent brush suppresses filling. | |
255 | The programmer is responsible for deleting the list of points. | |
256 | ||
257 | Note that wxWindows automatically closes the first and last points. | |
258 | ||
06d20283 RD |
259 | \pythonnote{The wxPython version of this method accepts a Python list |
260 | of wxPoint objects.} | |
261 | ||
a660d684 KB |
262 | \membersection{wxDC::DrawPoint}\label{wxdcdrawpoint} |
263 | ||
1f897d25 | 264 | \func{void}{DrawPoint}{\param{wxCoord}{ x}, \param{wxCoord}{ y}} |
a660d684 KB |
265 | |
266 | Draws a point using the current pen. | |
267 | ||
268 | \membersection{wxDC::DrawRectangle}\label{wxdcdrawrectangle} | |
269 | ||
1f897d25 | 270 | \func{void}{DrawRectangle}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}} |
a660d684 KB |
271 | |
272 | Draws a rectangle with the given top left corner, and with the given | |
273 | size. The current pen is used for the outline and the current brush | |
274 | for filling the shape. | |
275 | ||
1f897d25 VZ |
276 | \membersection{wxDC::DrawRotatedText}\label{wxdcdrawrotatedtext} |
277 | ||
278 | \func{void}{DrawRotatedText}{\param{const wxString\& }{text}, \param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{double}{ angle}} | |
279 | ||
280 | Draws the text rotated by {\it angle} degrees. | |
281 | ||
282 | \wxheading{See also} | |
283 | ||
284 | \helpref{DrawText}{wxdcdrawtext} | |
285 | ||
a660d684 KB |
286 | \membersection{wxDC::DrawRoundedRectangle}\label{wxdcdrawroundedrectangle} |
287 | ||
1f897d25 | 288 | \func{void}{DrawRoundedRectangle}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}, \param{double}{ radius = 20}} |
a660d684 KB |
289 | |
290 | Draws a rectangle with the given top left corner, and with the given | |
291 | size. The corners are quarter-circles using the given radius. The | |
292 | current pen is used for the outline and the current brush for filling | |
293 | the shape. | |
294 | ||
295 | If {\it radius} is positive, the value is assumed to be the | |
296 | radius of the rounded corner. If {\it radius} is negative, | |
297 | the absolute value is assumed to be the {\it proportion} of the smallest | |
298 | dimension of the rectangle. This means that the corner can be | |
299 | a sensible size relative to the size of the rectangle, and also avoids | |
300 | the strange effects X produces when the corners are too big for | |
301 | the rectangle. | |
302 | ||
303 | \membersection{wxDC::DrawSpline}\label{wxdcdrawspline} | |
304 | ||
305 | \func{void}{DrawSpline}{\param{wxList *}{points}} | |
306 | ||
307 | Draws a spline between all given control points, using the current | |
308 | pen. Doesn't delete the wxList and contents. The spline is drawn | |
309 | using a series of lines, using an algorithm taken from the X drawing | |
310 | program `XFIG'. | |
311 | ||
1f897d25 | 312 | \func{void}{DrawSpline}{\param{wxCoord}{ x1}, \param{wxCoord}{ y1}, \param{wxCoord}{ x2}, \param{wxCoord}{ y2}, \param{wxCoord}{ x3}, \param{wxCoord}{ y3}} |
a660d684 KB |
313 | |
314 | Draws a three-point spline using the current pen. | |
315 | ||
06d20283 RD |
316 | \pythonnote{The wxPython version of this method accepts a Python list |
317 | of wxPoint objects.} | |
318 | ||
a660d684 KB |
319 | \membersection{wxDC::DrawText}\label{wxdcdrawtext} |
320 | ||
1f897d25 | 321 | \func{void}{DrawText}{\param{const wxString\& }{text}, \param{wxCoord}{ x}, \param{wxCoord}{ y}} |
a660d684 KB |
322 | |
323 | Draws a text string at the specified point, using the current text font, | |
324 | and the current text foreground and background colours. | |
325 | ||
326 | The coordinates refer to the top-left corner of the rectangle bounding | |
327 | the string. See \helpref{wxDC::GetTextExtent}{wxdcgettextextent} for how | |
328 | to get the dimensions of a text string, which can be used to position the | |
329 | text more precisely. | |
330 | ||
331 | \membersection{wxDC::EndDoc}\label{wxdcenddoc} | |
332 | ||
333 | \func{void}{EndDoc}{\void} | |
334 | ||
335 | Ends a document (only relevant when outputting to a printer). | |
336 | ||
337 | \membersection{wxDC::EndDrawing}\label{wxdcenddrawing} | |
338 | ||
339 | \func{void}{EndDrawing}{\void} | |
340 | ||
341 | Allows optimization of drawing code under MS Windows. Enclose | |
342 | drawing primitives between {\bf BeginDrawing} and {\bf EndDrawing}\rtfsp | |
343 | calls. | |
344 | ||
345 | \membersection{wxDC::EndPage}\label{wxdcendpage} | |
346 | ||
347 | \func{void}{EndPage}{\void} | |
348 | ||
349 | Ends a document page (only relevant when outputting to a printer). | |
350 | ||
351 | \membersection{wxDC::FloodFill}\label{wxdcfloodfill} | |
352 | ||
1f897d25 | 353 | \func{void}{FloodFill}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxColour *}{colour}, \param{int}{ style=wxFLOOD\_SURFACE}} |
a660d684 KB |
354 | |
355 | Flood fills the device context starting from the given point, in the given colour, | |
356 | and using a style: | |
357 | ||
358 | \begin{itemize}\itemsep=0pt | |
359 | \item wxFLOOD\_SURFACE: the flooding occurs until a colour other than the given colour is encountered. | |
360 | \item wxFLOOD\_BORDER: the area to be flooded is bounded by the given colour. | |
361 | \end{itemize} | |
362 | ||
363 | {\it Note:} this function is available in MS Windows only. | |
364 | ||
365 | \membersection{wxDC::GetBackground}\label{wxdcgetbackground} | |
366 | ||
c0ed460c | 367 | \func{wxBrush\&}{GetBackground}{\void} |
a660d684 KB |
368 | |
369 | Gets the brush used for painting the background (see \helpref{wxDC::SetBackground}{wxdcsetbackground}). | |
370 | ||
371 | \membersection{wxDC::GetBrush}\label{wxdcgetbrush} | |
372 | ||
c0ed460c | 373 | \func{wxBrush\&}{GetBrush}{\void} |
a660d684 KB |
374 | |
375 | Gets the current brush (see \helpref{wxDC::SetBrush}{wxdcsetbrush}). | |
376 | ||
377 | \membersection{wxDC::GetCharHeight}\label{wxdcgetcharheight} | |
378 | ||
1f897d25 | 379 | \func{wxCoord}{GetCharHeight}{\void} |
a660d684 KB |
380 | |
381 | Gets the character height of the currently set font. | |
382 | ||
383 | \membersection{wxDC::GetCharWidth}\label{wxdcgetcharwidth} | |
384 | ||
1f897d25 | 385 | \func{wxCoord}{GetCharWidth}{\void} |
a660d684 KB |
386 | |
387 | Gets the average character width of the currently set font. | |
388 | ||
fe604ccd | 389 | \membersection{wxDC::GetClippingBox}\label{wxdcgetclippingbox} |
a660d684 | 390 | |
1f897d25 | 391 | \func{void}{GetClippingBox}{\param{wxCoord}{ *x}, \param{wxCoord}{ *y}, \param{wxCoord}{ *width}, \param{wxCoord}{ *height}} |
a660d684 KB |
392 | |
393 | Gets the rectangle surrounding the current clipping region. | |
394 | ||
06d20283 RD |
395 | \pythonnote{No arguments are required and the four values defining the |
396 | rectangle are returned as a tuple.} | |
397 | ||
a660d684 KB |
398 | \membersection{wxDC::GetFont}\label{wxdcgetfont} |
399 | ||
c0ed460c | 400 | \func{wxFont\&}{GetFont}{\void} |
a660d684 KB |
401 | |
402 | Gets the current font (see \helpref{wxDC::SetFont}{wxdcsetfont}). | |
403 | ||
404 | \membersection{wxDC::GetLogicalFunction}\label{wxdcgetlogicalfunction} | |
405 | ||
406 | \func{int}{GetLogicalFunction}{\void} | |
407 | ||
408 | Gets the current logical function (see \helpref{wxDC::SetLogicalFunction}{wxdcsetlogicalfunction}). | |
409 | ||
410 | \membersection{wxDC::GetMapMode}\label{wxdcgetmapmode} | |
411 | ||
412 | \func{int}{GetMapMode}{\void} | |
413 | ||
414 | Gets the {\it mapping mode} for the device context (see \helpref{wxDC::SetMapMode}{wxdcsetmapmode}). | |
415 | ||
416 | \membersection{wxDC::GetOptimization}\label{wxdcgetoptimization} | |
417 | ||
418 | \func{bool}{GetOptimization}{\void} | |
419 | ||
420 | Returns TRUE if device context optimization is on. | |
421 | See \helpref{wxDC::SetOptimization}{wxsetoptimization} for details. | |
422 | ||
423 | \membersection{wxDC::GetPen}\label{wxdcgetpen} | |
424 | ||
c0ed460c | 425 | \func{wxPen\&}{GetPen}{\void} |
a660d684 KB |
426 | |
427 | Gets the current pen (see \helpref{wxDC::SetPen}{wxdcsetpen}). | |
428 | ||
429 | \membersection{wxDC::GetPixel}\label{wxdcgetpixel} | |
430 | ||
1f897d25 | 431 | \func{bool}{GetPixel}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxColour *}{colour}} |
a660d684 KB |
432 | |
433 | Sets {\it colour} to the colour at the specified location. Windows only; an X implementation | |
e2a6f233 | 434 | is being worked on. Not available for wxPostScriptDC or wxMetafileDC. |
a660d684 | 435 | |
86e78222 RD |
436 | \pythonnote{For wxPython the wxColour value is returned and is not |
437 | required as a parameter.} | |
438 | ||
a660d684 KB |
439 | \membersection{wxDC::GetSize}\label{wxdcgetsize} |
440 | ||
1f897d25 | 441 | \func{void}{GetSize}{\param{wxCoord *}{width}, \param{wxCoord *}{height}} |
a660d684 KB |
442 | |
443 | For a PostScript device context, this gets the maximum size of graphics | |
444 | drawn so far on the device context. | |
445 | ||
446 | For a Windows printer device context, this gets the horizontal and vertical | |
447 | resolution. It can be used to scale graphics to fit the page when using | |
448 | a Windows printer device context. For example, if {\it maxX} and {\it maxY}\rtfsp | |
449 | represent the maximum horizontal and vertical `pixel' values used in your | |
450 | application, the following code will scale the graphic to fit on the | |
451 | printer page: | |
452 | ||
453 | \begin{verbatim} | |
1f897d25 | 454 | wxCoord w, h; |
a660d684 KB |
455 | dc.GetSize(&w, &h); |
456 | double scaleX=(double)(maxX/w); | |
457 | double scaleY=(double)(maxY/h); | |
458 | dc.SetUserScale(min(scaleX,scaleY),min(scaleX,scaleY)); | |
459 | \end{verbatim} | |
460 | ||
2233e5b8 RD |
461 | \pythonnote{In place of a single overloaded method name, wxPython |
462 | implements the following methods:\par | |
463 | \indented{2cm}{\begin{twocollist} | |
c9110876 VS |
464 | \twocolitem{{\bf GetSize()}}{Returns a wxSize} |
465 | \twocolitem{{\bf GetSizeTuple()}}{Returns a 2-tuple (width, height)} | |
2233e5b8 RD |
466 | \end{twocollist}} |
467 | } | |
06d20283 | 468 | |
a660d684 KB |
469 | \membersection{wxDC::GetTextBackground}\label{wxdcgettextbackground} |
470 | ||
471 | \func{wxColour\&}{GetTextBackground}{\void} | |
472 | ||
473 | Gets the current text background colour (see \helpref{wxDC::SetTextBackground}{wxdcsettextbackground}). | |
474 | ||
475 | \membersection{wxDC::GetTextExtent}\label{wxdcgettextextent} | |
476 | ||
1f897d25 VZ |
477 | \func{void}{GetTextExtent}{\param{const wxString\& }{string}, \param{wxCoord *}{w}, \param{wxCoord *}{h},\\ |
478 | \param{wxCoord *}{descent = NULL}, \param{wxCoord *}{externalLeading = NULL}, \param{wxFont *}{font = NULL}} | |
a660d684 KB |
479 | |
480 | Gets the dimensions of the string using the currently selected font. | |
481 | \rtfsp{\it string} is the text string to measure, {\it w} and {\it h} are | |
482 | the total width and height respectively, {\it descent} is the | |
483 | dimension from the baseline of the font to the bottom of the | |
484 | descender, and {\it externalLeading} is any extra vertical space added | |
485 | to the font by the font designer (usually is zero). | |
486 | ||
487 | The optional parameter {\it font} specifies an alternative | |
488 | to the currently selected font: but note that this does not | |
489 | yet work under Windows, so you need to set a font for | |
490 | the device context first. | |
491 | ||
492 | See also \helpref{wxFont}{wxfont}, \helpref{wxDC::SetFont}{wxdcsetfont}. | |
493 | ||
06d20283 RD |
494 | \pythonnote{The following methods are implemented in wxPython:\par |
495 | \indented{2cm}{\begin{twocollist} | |
c9110876 VS |
496 | \twocolitem{{\bf GetTextExtent(string)}}{Returns a 2-tuple, (width, height)} |
497 | \twocolitem{{\bf GetFullTextExtent(string, font=NULL)}}{Returns a | |
06d20283 RD |
498 | 4-tuple, (width, height, descent, externalLeading) } |
499 | \end{twocollist}} | |
500 | } | |
501 | ||
a660d684 KB |
502 | \membersection{wxDC::GetTextForeground}\label{wxdcgettextforeground} |
503 | ||
504 | \func{wxColour\&}{GetTextForeground}{\void} | |
505 | ||
506 | Gets the current text foreground colour (see \helpref{wxDC::SetTextForeground}{wxdcsettextforeground}). | |
507 | ||
16964b5e VS |
508 | |
509 | \membersection{wxDC::GetUserScale}\label{wxdcgetuserscale} | |
510 | ||
511 | \func{void}{GetUserScale}{\param{double}{ *x}, \param{double}{ *y}} | |
512 | ||
513 | Gets the current user scale factor (set by \helpref{SetUserScale}{wxdcsetuserscale}). | |
514 | ||
515 | ||
a660d684 KB |
516 | \membersection{wxDC::LogicalToDeviceX}\label{wxdclogicaltodevicex} |
517 | ||
1f897d25 | 518 | \func{wxCoord}{LogicalToDeviceX}{\param{wxCoord}{ x}} |
a660d684 KB |
519 | |
520 | Converts logical X coordinate to device coordinate, using the current | |
521 | mapping mode. | |
522 | ||
523 | \membersection{wxDC::LogicalToDeviceXRel}\label{wxdclogicaltodevicexrel} | |
524 | ||
1f897d25 | 525 | \func{wxCoord}{LogicalToDeviceXRel}{\param{wxCoord}{ x}} |
a660d684 KB |
526 | |
527 | Converts logical X coordinate to relative device coordinate, using the current | |
528 | mapping mode. Use this for converting a width, for example. | |
529 | ||
530 | \membersection{wxDC::LogicalToDeviceY}\label{wxdclogicaltodevicey} | |
531 | ||
1f897d25 | 532 | \func{wxCoord}{LogicalToDeviceY}{\param{wxCoord}{ y}} |
a660d684 KB |
533 | |
534 | Converts logical Y coordinate to device coordinate, using the current | |
535 | mapping mode. | |
536 | ||
537 | \membersection{wxDC::LogicalToDeviceYRel}\label{wxdclogicaltodeviceyrel} | |
538 | ||
1f897d25 | 539 | \func{wxCoord}{LogicalToDeviceYRel}{\param{wxCoord}{ y}} |
a660d684 KB |
540 | |
541 | Converts logical Y coordinate to relative device coordinate, using the current | |
542 | mapping mode. Use this for converting a height, for example. | |
543 | ||
544 | \membersection{wxDC::MaxX}\label{wxdcmaxx} | |
545 | ||
1f897d25 | 546 | \func{wxCoord}{MaxX}{\void} |
a660d684 KB |
547 | |
548 | Gets the maximum horizontal extent used in drawing commands so far. | |
549 | ||
550 | \membersection{wxDC::MaxY}\label{wxdcmaxy} | |
551 | ||
1f897d25 | 552 | \func{wxCoord}{MaxY}{\void} |
a660d684 KB |
553 | |
554 | Gets the maximum vertical extent used in drawing commands so far. | |
555 | ||
556 | \membersection{wxDC::MinX}\label{wxdcminx} | |
557 | ||
1f897d25 | 558 | \func{wxCoord}{MinX}{\void} |
a660d684 KB |
559 | |
560 | Gets the minimum horizontal extent used in drawing commands so far. | |
561 | ||
562 | \membersection{wxDC::MinY}\label{wxdcminy} | |
563 | ||
1f897d25 | 564 | \func{wxCoord}{MinY}{\void} |
a660d684 KB |
565 | |
566 | Gets the minimum vertical extent used in drawing commands so far. | |
567 | ||
568 | \membersection{wxDC::Ok}\label{wxdcok} | |
569 | ||
570 | \func{bool}{Ok}{\void} | |
571 | ||
572 | Returns TRUE if the DC is ok to use. | |
573 | ||
574 | \membersection{wxDC::SetDeviceOrigin}\label{wxdcsetdeviceorigin} | |
575 | ||
1f897d25 | 576 | \func{void}{SetDeviceOrigin}{\param{wxCoord}{ x}, \param{wxCoord}{ y}} |
a660d684 KB |
577 | |
578 | Sets the device origin (i.e., the origin in pixels after scaling has been | |
579 | applied). | |
580 | ||
581 | This function may be useful in Windows printing | |
582 | operations for placing a graphic on a page. | |
583 | ||
584 | \membersection{wxDC::SetBackground}\label{wxdcsetbackground} | |
585 | ||
586 | \func{void}{SetBackground}{\param{const wxBrush\& }{brush}} | |
587 | ||
588 | Sets the current background brush for the DC. | |
589 | ||
590 | \membersection{wxDC::SetBackgroundMode}\label{wxdcsetbackgroundmode} | |
591 | ||
592 | \func{void}{SetBackgroundMode}{\param{int}{ mode}} | |
593 | ||
594 | {\it mode} may be one of wxSOLID and wxTRANSPARENT. This setting determines | |
595 | whether text will be drawn with a background colour or not. | |
596 | ||
597 | \membersection{wxDC::SetClippingRegion}\label{wxdcsetclippingregion} | |
598 | ||
1f897d25 | 599 | \func{void}{SetClippingRegion}{\param{wxCoord}{ x}, \param{wxCoord}{ y}, \param{wxCoord}{ width}, \param{wxCoord}{ height}} |
a660d684 | 600 | |
a724d789 JS |
601 | \func{void}{SetClippingRegion}{\param{const wxRegion\&}{ region}} |
602 | ||
603 | Sets the clipping region for the DC. The clipping region is an area | |
604 | to which drawing is restricted. Possible uses for the clipping region are for clipping text | |
fe604ccd | 605 | or for speeding up window redraws when only a known area of the screen is damaged. |
a660d684 | 606 | |
a724d789 JS |
607 | \wxheading{See also} |
608 | ||
609 | \helpref{wxDC::DestroyClippingRegion}{wxdcdestroyclippingregion}, \helpref{wxRegion}{wxregion} | |
a660d684 KB |
610 | |
611 | \membersection{wxDC::SetPalette}\label{wxdcsetpalette} | |
612 | ||
613 | \func{void}{SetPalette}{\param{const wxPalette\& }{palette}} | |
614 | ||
fe604ccd | 615 | If this is a window DC or memory DC, assigns the given palette to the window |
a660d684 KB |
616 | or bitmap associated with the DC. If the argument is wxNullPalette, the current |
617 | palette is selected out of the device context, and the original palette | |
618 | restored. | |
619 | ||
620 | See \helpref{wxPalette}{wxpalette} for further details. | |
621 | ||
622 | \membersection{wxDC::SetBrush}\label{wxdcsetbrush} | |
623 | ||
624 | \func{void}{SetBrush}{\param{const wxBrush\& }{brush}} | |
625 | ||
626 | Sets the current brush for the DC. | |
627 | ||
628 | If the argument is wxNullBrush, the current brush is selected out of the device | |
629 | context, and the original brush restored, allowing the current brush to | |
630 | be destroyed safely. | |
631 | ||
632 | See also \helpref{wxBrush}{wxbrush}. | |
633 | ||
9000c624 RR |
634 | See also \helpref{wxMemoryDC}{wxmemorydc} for the interpretation of colours |
635 | when drawing into a monochrome bitmap. | |
636 | ||
a660d684 KB |
637 | \membersection{wxDC::SetFont}\label{wxdcsetfont} |
638 | ||
639 | \func{void}{SetFont}{\param{const wxFont\& }{font}} | |
640 | ||
641 | Sets the current font for the DC. | |
642 | ||
643 | If the argument is wxNullFont, the current font is selected out of the device | |
644 | context, and the original font restored, allowing the current font to | |
645 | be destroyed safely. | |
646 | ||
647 | See also \helpref{wxFont}{wxfont}. | |
648 | ||
649 | \membersection{wxDC::SetLogicalFunction}\label{wxdcsetlogicalfunction} | |
650 | ||
651 | \func{void}{SetLogicalFunction}{\param{int}{ function}} | |
652 | ||
fe604ccd | 653 | Sets the current logical function for the device context. This determines how |
a660d684 KB |
654 | a source pixel (from a pen or brush colour, or source device context if |
655 | using \helpref{wxDC::Blit}{wxdcblit}) combines with a destination pixel in the | |
656 | current device context. | |
657 | ||
658 | The possible values | |
659 | and their meaning in terms of source and destination pixel values are | |
660 | as follows: | |
661 | ||
662 | \begin{verbatim} | |
663 | wxAND src AND dst | |
664 | wxAND_INVERT (NOT src) AND dst | |
665 | wxAND_REVERSE src AND (NOT dst) | |
666 | wxCLEAR 0 | |
667 | wxCOPY src | |
668 | wxEQUIV (NOT src) XOR dst | |
669 | wxINVERT NOT dst | |
670 | wxNAND (NOT src) OR (NOT dst) | |
671 | wxNOR (NOT src) AND (NOT dst) | |
672 | wxNO_OP dst | |
673 | wxOR src OR dst | |
674 | wxOR_INVERT (NOT src) OR dst | |
675 | wxOR_REVERSE src OR (NOT dst) | |
676 | wxSET 1 | |
677 | wxSRC_INVERT NOT src | |
678 | wxXOR src XOR dst | |
679 | \end{verbatim} | |
680 | ||
681 | The default is wxCOPY, which simply draws with the current colour. | |
682 | The others combine the current colour and the background using a | |
6453876e | 683 | logical operation. wxINVERT is commonly used for drawing rubber bands or |
a660d684 KB |
684 | moving outlines, since drawing twice reverts to the original colour. |
685 | ||
686 | \membersection{wxDC::SetMapMode}\label{wxdcsetmapmode} | |
687 | ||
688 | \func{void}{SetMapMode}{\param{int}{ int}} | |
689 | ||
690 | The {\it mapping mode} of the device context defines the unit of | |
691 | measurement used to convert logical units to device units. Note that | |
692 | in X, text drawing isn't handled consistently with the mapping mode; a | |
693 | font is always specified in point size. However, setting the {\it | |
694 | user scale} (see \helpref{wxDC::SetUserScale}{wxdcsetuserscale}) scales the text appropriately. In | |
695 | Windows, scaleable TrueType fonts are always used; in X, results depend | |
696 | on availability of fonts, but usually a reasonable match is found. | |
697 | ||
698 | Note that the coordinate origin should ideally be selectable, but for | |
699 | now is always at the top left of the screen/printer. | |
700 | ||
701 | Drawing to a Windows printer device context under UNIX | |
702 | uses the current mapping mode, but mapping mode is currently ignored for | |
703 | PostScript output. | |
704 | ||
705 | The mapping mode can be one of the following: | |
706 | ||
707 | \begin{twocollist}\itemsep=0pt | |
e3065973 | 708 | \twocolitem{wxMM\_TWIPS}{Each logical unit is 1/20 of a point, or 1/1440 of |
a660d684 | 709 | an inch.} |
e3065973 JS |
710 | \twocolitem{wxMM\_POINTS}{Each logical unit is a point, or 1/72 of an inch.} |
711 | \twocolitem{wxMM\_METRIC}{Each logical unit is 1 mm.} | |
712 | \twocolitem{wxMM\_LOMETRIC}{Each logical unit is 1/10 of a mm.} | |
713 | \twocolitem{wxMM\_TEXT}{Each logical unit is 1 pixel.} | |
a660d684 KB |
714 | \end{twocollist} |
715 | ||
716 | \membersection{wxDC::SetOptimization}\label{wxsetoptimization} | |
717 | ||
718 | \func{void}{SetOptimization}{\param{bool }{optimize}} | |
719 | ||
720 | If {\it optimize} is TRUE (the default), this function sets optimization mode on. | |
721 | This currently means that under X, the device context will not try to set a pen or brush | |
722 | property if it is known to be set already. This approach can fall down | |
723 | if non-wxWindows code is using the same device context or window, for example | |
724 | when the window is a panel on which the windowing system draws panel items. | |
725 | The wxWindows device context 'memory' will now be out of step with reality. | |
726 | ||
727 | Setting optimization off, drawing, then setting it back on again, is a trick | |
728 | that must occasionally be employed. | |
729 | ||
730 | \membersection{wxDC::SetPen}\label{wxdcsetpen} | |
731 | ||
732 | \func{void}{SetPen}{\param{const wxPen\& }{pen}} | |
733 | ||
734 | Sets the current pen for the DC. | |
735 | ||
736 | If the argument is wxNullPen, the current pen is selected out of the device | |
737 | context, and the original pen restored. | |
738 | ||
9000c624 RR |
739 | See also \helpref{wxMemoryDC}{wxmemorydc} for the interpretation of colours |
740 | when drawing into a monochrome bitmap. | |
741 | ||
a660d684 KB |
742 | \membersection{wxDC::SetTextBackground}\label{wxdcsettextbackground} |
743 | ||
744 | \func{void}{SetTextBackground}{\param{const wxColour\& }{colour}} | |
745 | ||
746 | Sets the current text background colour for the DC. | |
747 | ||
748 | \membersection{wxDC::SetTextForeground}\label{wxdcsettextforeground} | |
749 | ||
750 | \func{void}{SetTextForeground}{\param{const wxColour\& }{colour}} | |
751 | ||
752 | Sets the current text foreground colour for the DC. | |
753 | ||
9000c624 RR |
754 | See also \helpref{wxMemoryDC}{wxmemorydc} for the interpretation of colours |
755 | when drawing into a monochrome bitmap. | |
756 | ||
a660d684 KB |
757 | \membersection{wxDC::SetUserScale}\label{wxdcsetuserscale} |
758 | ||
759 | \func{void}{SetUserScale}{\param{double}{ xScale}, \param{double}{ yScale}} | |
760 | ||
761 | Sets the user scaling factor, useful for applications which require | |
762 | `zooming'. | |
763 | ||
764 | \membersection{wxDC::StartDoc}\label{wxdcstartdoc} | |
765 | ||
766 | \func{bool}{StartDoc}{\param{const wxString\& }{message}} | |
767 | ||
768 | Starts a document (only relevant when outputting to a printer). | |
769 | Message is a message to show whilst printing. | |
770 | ||
771 | \membersection{wxDC::StartPage}\label{wxdcstartpage} | |
772 | ||
773 | \func{bool}{StartPage}{\void} | |
774 | ||
775 | Starts a document page (only relevant when outputting to a printer). | |
776 |