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