]> git.saurik.com Git - wxWidgets.git/blame - wxPython/src/_dc.i
Use the wx.ART_NORMAL_FILE icon
[wxWidgets.git] / wxPython / src / _dc.i
CommitLineData
d14a1e28
RD
1/////////////////////////////////////////////////////////////////////////////
2// Name: _dc.i
3// Purpose: SWIG interface defs for wxDC and releated classes
4//
5// Author: Robin Dunn
6//
7// Created: 7-July-1997
8// RCS-ID: $Id$
9// Copyright: (c) 2003 by Total Control Software
10// Licence: wxWindows license
11/////////////////////////////////////////////////////////////////////////////
12
13// Not a %module
14
15
4942342c 16
d14a1e28
RD
17//---------------------------------------------------------------------------
18
19%{
20#include "wx/wxPython/pydrawxxx.h"
21%}
22
23// TODO: 1. wrappers for wxDrawObject and wxDC::DrawObject
24
25
26//---------------------------------------------------------------------------
27
28%typemap(in) (int points, wxPoint* points_array ) {
29 $2 = wxPoint_LIST_helper($input, &$1);
30 if ($2 == NULL) SWIG_fail;
31}
32%typemap(freearg) (int points, wxPoint* points_array ) {
33 if ($2) delete [] $2;
34}
35
36
37//---------------------------------------------------------------------------
38%newgroup;
39
40
70794ec5
RD
41DocStr(wxDC,
42"A wx.DC is a device context onto which graphics and text can be
43drawn. It is intended to represent a number of output devices in a
44generic way, so a window can have a device context associated with it,
45and a printer also has a device context. In this way, the same piece
46of code may write to a number of different devices, if the device
47context is used as a parameter.
48
49Derived types of wxDC have documentation for specific features only,
50so refer to this section for most device context information.
51
52The wx.DC class is abstract and can not be instantiated, you must use
53one of the derived classes instead. Which one will depend on the
54situation in which it is used.", "");
55
d14a1e28
RD
56class wxDC : public wxObject {
57public:
58// wxDC(); **** abstract base class, can't instantiate.
59 ~wxDC();
60
61
70794ec5
RD
62 DocDeclStr(
63 virtual void , BeginDrawing(),
64 "Allows for optimization of drawing code on platforms that need it. On
65other platforms this is just an empty function and is harmless. To
66take advantage of this postential optimization simply enclose each
67group of calls to the drawing primitives within calls to
68`BeginDrawing` and `EndDrawing`.", "");
69
70 DocDeclStr(
71 virtual void , EndDrawing(),
72 "Ends the group of drawing primitives started with `BeginDrawing`, and
73invokes whatever optimization is available for this DC type on the
74current platform.", "");
75
76
77
78// TODO virtual void DrawObject(wxDrawObject* drawobject);
d14a1e28
RD
79
80
70794ec5
RD
81 DocStr(
82 FloodFill,
83 "Flood fills the device context starting from the given point, using
84the current brush colour, and using a style:
d14a1e28 85
70794ec5
RD
86 - **wxFLOOD_SURFACE**: the flooding occurs until a colour other than
87 the given colour is encountered.
d14a1e28 88
70794ec5
RD
89 - **wxFLOOD_BORDER**: the area to be flooded is bounded by the given
90 colour.
d14a1e28 91
70794ec5 92Returns False if the operation failed.
d14a1e28 93
70794ec5
RD
94Note: The present implementation for non-Windows platforms may fail to
95find colour borders if the pixels do not match the colour
96exactly. However the function will still return true.", "");
d14a1e28 97 bool FloodFill(wxCoord x, wxCoord y, const wxColour& col, int style = wxFLOOD_SURFACE);
1b8c7ba6 98 %Rename(FloodFillPoint, bool, FloodFill(const wxPoint& pt, const wxColour& col, int style = wxFLOOD_SURFACE));
dce2bd22 99
70794ec5
RD
100
101 DocStr(
102 GetPixel,
103 "Gets the colour at the specified location on the DC.","");
d14a1e28
RD
104 %extend {
105 wxColour GetPixel(wxCoord x, wxCoord y) {
106 wxColour col;
107 self->GetPixel(x, y, &col);
108 return col;
109 }
dce2bd22
RD
110 wxColour GetPixelPoint(const wxPoint& pt) {
111 wxColour col;
112 self->GetPixel(pt, &col);
113 return col;
114 }
d14a1e28 115 }
70794ec5 116
dce2bd22 117
70794ec5
RD
118 DocStr(
119 DrawLine,
120 "Draws a line from the first point to the second. The current pen is
121used for drawing the line. Note that the second point is *not* part of
122the line and is not drawn by this function (this is consistent with
123the behaviour of many other toolkits).", "");
d14a1e28 124 void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
1b8c7ba6 125 %Rename(DrawLinePoint, void, DrawLine(const wxPoint& pt1, const wxPoint& pt2));
dce2bd22 126
70794ec5
RD
127
128 DocStr(
129 CrossHair,
130 "Displays a cross hair using the current pen. This is a vertical and
131horizontal line the height and width of the window, centred on the
132given point.", "");
d14a1e28 133 void CrossHair(wxCoord x, wxCoord y);
1b8c7ba6 134 %Rename(CrossHairPoint, void, CrossHair(const wxPoint& pt));
dce2bd22 135
70794ec5
RD
136
137 DocStr(
138 DrawArc,
139 "Draws an arc of a circle, centred on the *center* point (xc, yc), from
140the first point to the second. The current pen is used for the outline
141and the current brush for filling the shape.
142
143The arc is drawn in an anticlockwise direction from the start point to
144the end point.", "");
d14a1e28 145 void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2, wxCoord xc, wxCoord yc);
1b8c7ba6 146 %Rename(DrawArcPoint, void, DrawArc(const wxPoint& pt1, const wxPoint& pt2, const wxPoint& center));
dce2bd22 147
70794ec5
RD
148
149 DocStr(
150 DrawCheckMark,
151 "Draws a check mark inside the given rectangle.", "");
d14a1e28 152 void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
1b8c7ba6 153 %Rename(DrawCheckMarkRect, void, DrawCheckMark(const wxRect& rect));
dce2bd22 154
70794ec5
RD
155 DocStr(
156 DrawEllipticArc,
157 "Draws an arc of an ellipse, with the given rectangle defining the
158bounds of the ellipse. The current pen is used for drawing the arc and
159the current brush is used for drawing the pie.
160
161The *start* and *end* parameters specify the start and end of the arc
162relative to the three-o'clock position from the center of the
163rectangle. Angles are specified in degrees (360 is a complete
164circle). Positive values mean counter-clockwise motion. If start is
165equal to end, a complete ellipse will be drawn.", "");
166 void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord w, wxCoord h, double start, double end);
1b8c7ba6 167 %Rename(DrawEllipticArcPointSize, void, DrawEllipticArc(const wxPoint& pt, const wxSize& sz, double start, double end));
70794ec5 168
dce2bd22 169
70794ec5
RD
170 DocStr(
171 DrawPoint,
172 "Draws a point using the current pen.", "");
d14a1e28 173 void DrawPoint(wxCoord x, wxCoord y);
1b8c7ba6 174 %Rename(DrawPointPoint, void, DrawPoint(const wxPoint& pt));
dce2bd22 175
70794ec5
RD
176
177 DocStr(
178 DrawRectangle,
179 "Draws a rectangle with the given top left corner, and with the given
180size. The current pen is used for the outline and the current brush
181for filling the shape.", "");
d14a1e28 182 void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
1b8c7ba6
RD
183 %Rename(DrawRectangleRect,void, DrawRectangle(const wxRect& rect));
184 %Rename(DrawRectanglePointSize, void, DrawRectangle(const wxPoint& pt, const wxSize& sz));
dce2bd22 185
70794ec5
RD
186
187 DocStr(
188 DrawRoundedRectangle,
189 "Draws a rectangle with the given top left corner, and with the given
190size. The corners are quarter-circles using the given radius. The
191current pen is used for the outline and the current brush for filling
192the shape.
193
194If radius is positive, the value is assumed to be the radius of the
195rounded corner. If radius is negative, the absolute value is assumed
196to be the proportion of the smallest dimension of the rectangle. This
197means that the corner can be a sensible size relative to the size of
198the rectangle, and also avoids the strange effects X produces when the
199corners are too big for the rectangle.", "");
d14a1e28 200 void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height, double radius);
1b8c7ba6
RD
201 %Rename(DrawRoundedRectangleRect, void, DrawRoundedRectangle(const wxRect& r, double radius));
202 %Rename(DrawRoundedRectanglePointSize, void, DrawRoundedRectangle(const wxPoint& pt, const wxSize& sz, double radius));
dce2bd22 203
70794ec5
RD
204
205 DocStr(
206 DrawCircle,
207 "Draws a circle with the given center point and radius. The current
208pen is used for the outline and the current brush for filling the
209shape.", "
210
211:see: `DrawEllipse`");
d14a1e28 212 void DrawCircle(wxCoord x, wxCoord y, wxCoord radius);
1b8c7ba6 213 %Rename(DrawCirclePoint, void, DrawCircle(const wxPoint& pt, wxCoord radius));
dce2bd22 214
70794ec5
RD
215
216 DocStr(
217 DrawEllipse,
218 "Draws an ellipse contained in the specified rectangle. The current pen
219is used for the outline and the current brush for filling the shape.", "
220
221:see: `DrawCircle`");
d14a1e28 222 void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
1b8c7ba6
RD
223 %Rename(DrawEllipseRect, void, DrawEllipse(const wxRect& rect));
224 %Rename(DrawEllipsePointSize, void, DrawEllipse(const wxPoint& pt, const wxSize& sz));
dce2bd22 225
70794ec5
RD
226
227 DocStr(
228 DrawIcon,
229 "Draw an icon on the display (does nothing if the device context is
230PostScript). This can be the simplest way of drawing bitmaps on a
231window.", "");
d14a1e28 232 void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);
1b8c7ba6 233 %Rename(DrawIconPoint, void, DrawIcon(const wxIcon& icon, const wxPoint& pt));
dce2bd22 234
d14a1e28 235
70794ec5
RD
236 DocStr(
237 DrawBitmap,
238 "Draw a bitmap on the device context at the specified point. If
239*transparent* is true and the bitmap has a transparency mask, (or
240alpha channel on the platforms that support it) then the bitmap will
241be drawn transparently.", "
4942342c 242
70794ec5
RD
243When drawing a mono-bitmap, the current text foreground colour will be
244used to draw the foreground of the bitmap (all bits set to 1), and the
245current text background colour to draw the background (all bits set to
2460).
d14a1e28 247
70794ec5 248:see: `SetTextForeground`, `SetTextBackground` and `wx.MemoryDC`");
a72f4631 249 void DrawBitmap(const wxBitmap &bmp, wxCoord x, wxCoord y, bool useMask = false);
1b8c7ba6 250 %Rename(DrawBitmapPoint, void, DrawBitmap(const wxBitmap &bmp, const wxPoint& pt, bool useMask = false));
d14a1e28 251
d14a1e28 252
70794ec5
RD
253 DocStr(
254 DrawText,
255 "Draws a text string at the specified point, using the current text
256font, and the current text foreground and background colours.
d14a1e28 257
70794ec5
RD
258The coordinates refer to the top-left corner of the rectangle bounding
259the string. See `GetTextExtent` for how to get the dimensions of a
260text string, which can be used to position the text more precisely.
d14a1e28 261
70794ec5
RD
262**NOTE**: under wxGTK the current logical function is used by this
263function but it is ignored by wxMSW. Thus, you should avoid using
264logical functions with this function in portable programs.", "
d14a1e28 265
70794ec5
RD
266:see: `DrawRotatedText`");
267 void DrawText(const wxString& text, wxCoord x, wxCoord y);
1b8c7ba6 268 %Rename(DrawTextPoint, void, DrawText(const wxString& text, const wxPoint& pt));
d14a1e28 269
d14a1e28 270
70794ec5
RD
271 DocStr(
272 DrawRotatedText,
273 "Draws the text rotated by *angle* degrees, if supported by the platform.
d14a1e28 274
70794ec5
RD
275**NOTE**: Under Win9x only TrueType fonts can be drawn by this
276function. In particular, a font different from ``wx.NORMAL_FONT``
277should be used as the it is not normally a TrueType
278font. ``wx.SWISS_FONT`` is an example of a font which is.","
d14a1e28 279
70794ec5
RD
280:see: `DrawText`");
281 void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y, double angle);
1b8c7ba6 282 %Rename(DrawRotatedTextPoint, void, DrawRotatedText(const wxString& text, const wxPoint& pt, double angle));
d14a1e28 283
d14a1e28 284
70794ec5
RD
285 DocDeclStr(
286 bool , Blit(wxCoord xdest, wxCoord ydest, wxCoord width, wxCoord height,
287 wxDC *source, wxCoord xsrc, wxCoord ysrc,
a72f4631 288 int rop = wxCOPY, bool useMask = false,
70794ec5
RD
289 wxCoord xsrcMask = -1, wxCoord ysrcMask = -1),
290 "Copy from a source DC to this DC. Parameters specify the destination
291coordinates, size of area to copy, source DC, source coordinates,
292logical function, whether to use a bitmap mask, and mask source
293position.", "
294
295 :param xdest: Destination device context x position.
296 :param ydest: Destination device context y position.
297 :param width: Width of source area to be copied.
298 :param height: Height of source area to be copied.
299 :param source: Source device context.
300 :param xsrc: Source device context x position.
301 :param ysrc: Source device context y position.
302 :param rop: Logical function to use: see `SetLogicalFunction`.
303 :param useMask: If true, Blit does a transparent blit using the mask
304 that is associated with the bitmap selected into the
305 source device context.
306 :param xsrcMask: Source x position on the mask. If both xsrcMask and
307 ysrcMask are -1, xsrc and ysrc will be assumed for
308 the mask source position.
309 :param ysrcMask: Source y position on the mask.
310");
311
312 DocDeclStrName(
313 bool , Blit(const wxPoint& destPt, const wxSize& sz,
314 wxDC *source, const wxPoint& srcPt,
a72f4631 315 int rop = wxCOPY, bool useMask = false,
70794ec5
RD
316 const wxPoint& srcPtMask = wxDefaultPosition),
317 "Copy from a source DC to this DC. Parameters specify the destination
318coordinates, size of area to copy, source DC, source coordinates,
319logical function, whether to use a bitmap mask, and mask source
320position.", "
321
322 :param destPt: Destination device context position.
323 :param sz: Size of source area to be copied.
324 :param source: Source device context.
325 :param srcPt: Source device context position.
326 :param rop: Logical function to use: see `SetLogicalFunction`.
327 :param useMask: If true, Blit does a transparent blit using the mask
328 that is associated with the bitmap selected into the
329 source device context.
330 :param srcPtMask: Source position on the mask.
331",
332 BlitPointSize);
333
d14a1e28 334
70794ec5
RD
335 DocStr(
336 SetClippingRegion,
337 "Sets the clipping region for this device context to the intersection
338of the given region described by the parameters of this method and the
339previously set clipping region. You should call `DestroyClippingRegion`
340if you want to set the clipping region exactly to the region
341specified.
4942342c 342
70794ec5
RD
343The clipping region is an area to which drawing is
344restricted. Possible uses for the clipping region are for clipping
345text or for speeding up window redraws when only a known area of the
346screen is damaged.", "
d14a1e28 347
70794ec5
RD
348:see: `DestroyClippingRegion`, `wx.Region`");
349 void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
1b8c7ba6
RD
350 %Rename(SetClippingRegionPointSize, void, SetClippingRegion(const wxPoint& pt, const wxSize& sz));
351 %Rename(SetClippingRegionAsRegion, void, SetClippingRegion(const wxRegion& region));
352 %Rename(SetClippingRect, void, SetClippingRegion(const wxRect& rect));
d7403ad2 353
4942342c 354
70794ec5
RD
355
356 DocDeclAStr(
357 void , DrawLines(int points, wxPoint* points_array,
358 wxCoord xoffset = 0, wxCoord yoffset = 0),
359 "DrawLines(self, List points, int xoffset=0, int yoffset=0)",
360 "Draws lines using a sequence of `wx.Point` objects, adding the
361optional offset coordinate. The current pen is used for drawing the
362lines.", "");
363
d14a1e28 364
70794ec5
RD
365 DocDeclAStr(
366 void , DrawPolygon(int points, wxPoint* points_array,
d14a1e28 367 wxCoord xoffset = 0, wxCoord yoffset = 0,
70794ec5
RD
368 int fillStyle = wxODDEVEN_RULE),
369 "DrawPolygon(self, List points, int xoffset=0, int yoffset=0,
370 int fillStyle=ODDEVEN_RULE)",
371 "Draws a filled polygon using a sequence of `wx.Point` objects, adding
372the optional offset coordinate. The last argument specifies the fill
373rule: ``wx.ODDEVEN_RULE`` (the default) or ``wx.WINDING_RULE``.
374
375The current pen is used for drawing the outline, and the current brush
376for filling the shape. Using a transparent brush suppresses
377filling. Note that wxWidgets automatically closes the first and last
378points.", "");
379
d14a1e28 380
86aafce3
RD
381 // TODO: Figure out a good typemap for this...
382 // Convert the first 3 args from a sequence of sequences?
383// void DrawPolyPolygon(int n, int count[], wxPoint points[],
384// wxCoord xoffset = 0, wxCoord yoffset = 0,
385// int fillStyle = wxODDEVEN_RULE);
d14a1e28 386
86aafce3 387
70794ec5
RD
388 DocDeclStr(
389 void , DrawLabel(const wxString& text, const wxRect& rect,
390 int alignment = wxALIGN_LEFT | wxALIGN_TOP,
391 int indexAccel = -1),
392 "Draw *text* within the specified rectangle, abiding by the alignment
393flags. Will additionally emphasize the character at *indexAccel* if
394it is not -1.", "
395
396:see: `DrawImageLabel`");
397
398
d14a1e28 399 %extend {
70794ec5
RD
400 DocStr(DrawImageLabel,
401 "Draw *text* and an image (which may be ``wx.NullBitmap`` to skip
402drawing it) within the specified rectangle, abiding by the alignment
403flags. Will additionally emphasize the character at *indexAccel* if
404it is not -1. Returns the bounding rectangle.", "");
d14a1e28
RD
405 wxRect DrawImageLabel(const wxString& text,
406 const wxBitmap& image,
407 const wxRect& rect,
408 int alignment = wxALIGN_LEFT | wxALIGN_TOP,
409 int indexAccel = -1) {
410 wxRect rv;
411 self->DrawLabel(text, image, rect, alignment, indexAccel, &rv);
412 return rv;
413 }
414 }
415
416
417
70794ec5
RD
418 DocDeclAStr(
419 void , DrawSpline(int points, wxPoint* points_array),
420 "DrawSpline(self, List points)",
421 "Draws a spline between all given control points, (a list of `wx.Point`
422objects) using the current pen. The spline is drawn using a series of
423lines, using an algorithm taken from the X drawing program 'XFIG'.", "");
424
d14a1e28
RD
425
426
4942342c 427
d14a1e28
RD
428 // global DC operations
429 // --------------------
430
70794ec5
RD
431 DocDeclStr(
432 virtual void , Clear(),
433 "Clears the device context using the current background brush.", "");
434
d14a1e28 435
70794ec5
RD
436 DocDeclStr(
437 virtual bool , StartDoc(const wxString& message),
438 "Starts a document (only relevant when outputting to a
439printer). *Message* is a message to show whilst printing.", "");
440
441 DocDeclStr(
442 virtual void , EndDoc(),
443 "Ends a document (only relevant when outputting to a printer).", "");
444
d14a1e28 445
70794ec5
RD
446 DocDeclStr(
447 virtual void , StartPage(),
448 "Starts a document page (only relevant when outputting to a printer).", "");
449
450 DocDeclStr(
451 virtual void , EndPage(),
452 "Ends a document page (only relevant when outputting to a printer).", "");
453
d14a1e28 454
4942342c 455
d14a1e28
RD
456 // set objects to use for drawing
457 // ------------------------------
458
70794ec5
RD
459 DocDeclStr(
460 virtual void , SetFont(const wxFont& font),
461 "Sets the current font for the DC. It must be a valid font, in
462particular you should not pass ``wx.NullFont`` to this method.","
d14a1e28 463
70794ec5
RD
464:see: `wx.Font`");
465
466 DocDeclStr(
467 virtual void , SetPen(const wxPen& pen),
468 "Sets the current pen for the DC.
4942342c 469
70794ec5
RD
470If the argument is ``wx.NullPen``, the current pen is selected out of the
471device context, and the original pen restored.", "
d14a1e28 472
70794ec5
RD
473:see: `wx.Pen`");
474
475 DocDeclStr(
476 virtual void , SetBrush(const wxBrush& brush),
477 "Sets the current brush for the DC.
478
479If the argument is ``wx.NullBrush``, the current brush is selected out
480of the device context, and the original brush restored, allowing the
481current brush to be destroyed safely.","
482
483:see: `wx.Brush`");
484
485 DocDeclStr(
486 virtual void , SetBackground(const wxBrush& brush),
487 "Sets the current background brush for the DC.", "");
488
489 DocDeclStr(
490 virtual void , SetBackgroundMode(int mode),
491 "*mode* may be one of ``wx.SOLID`` and ``wx.TRANSPARENT``. This setting
492determines whether text will be drawn with a background colour or
493not.", "");
494
495 DocDeclStr(
496 virtual void , SetPalette(const wxPalette& palette),
497 "If this is a window DC or memory DC, assigns the given palette to the
498window or bitmap associated with the DC. If the argument is
499``wx.NullPalette``, the current palette is selected out of the device
500context, and the original palette restored.", "
501
502:see: `wx.Palette`");
503
504
505
506 DocDeclStr(
507 virtual void , DestroyClippingRegion(),
508 "Destroys the current clipping region so that none of the DC is
509clipped.", "
510
511:see: `SetClippingRegion`");
512
513
514 DocDeclAStr(
322913ce 515 void, GetClippingBox(wxCoord *OUTPUT, wxCoord *OUTPUT, wxCoord *OUTPUT, wxCoord *OUTPUT) const,
70794ec5
RD
516 "GetClippingBox() -> (x, y, width, height)",
517 "Gets the rectangle surrounding the current clipping region.", "");
4942342c 518
d14a1e28 519 %extend {
70794ec5
RD
520 DocStr(
521 GetClippingRect,
522 "Gets the rectangle surrounding the current clipping region.", "");
d14a1e28
RD
523 wxRect GetClippingRect() {
524 wxRect rect;
525 self->GetClippingBox(rect);
526 return rect;
527 }
528 }
d14a1e28 529
4942342c
RD
530
531
d14a1e28
RD
532 // text extent
533 // -----------
534
70794ec5
RD
535 DocDeclStr(
536 virtual wxCoord , GetCharHeight() const,
537 "Gets the character height of the currently set font.", "");
538
539 DocDeclStr(
540 virtual wxCoord , GetCharWidth() const,
541 "Gets the average character width of the currently set font.", "");
542
d14a1e28 543
d14a1e28 544
322913ce
RD
545 DocDeclAStr(
546 void, GetTextExtent(const wxString& string, wxCoord *OUTPUT, wxCoord *OUTPUT),
547 "GetTextExtent(wxString string) -> (width, height)",
d07d2bc9
RD
548 "Get the width and height of the text using the current font. Only
549works for single line strings.", "");
550
322913ce
RD
551 DocDeclAStrName(
552 void, GetTextExtent(const wxString& string,
4942342c 553 wxCoord *OUTPUT, wxCoord *OUTPUT, wxCoord *OUTPUT, wxCoord* OUTPUT,
322913ce
RD
554 wxFont* font = NULL),
555 "GetFullTextExtent(wxString string, Font font=None) ->\n (width, height, descent, externalLeading)",
d07d2bc9
RD
556 "Get the width, height, decent and leading of the text using the
557current or specified font. Only works for single line strings.", "",
322913ce
RD
558 GetFullTextExtent);
559
4942342c 560
322913ce
RD
561 // works for single as well as multi-line strings
562 DocDeclAStr(
563 void, GetMultiLineTextExtent(const wxString& text,
564 wxCoord *OUTPUT, wxCoord *OUTPUT, wxCoord *OUTPUT,
565 wxFont *font = NULL),
566 "GetMultiLineTextExtent(wxString string, Font font=None) ->\n (width, height, descent, externalLeading)",
d07d2bc9
RD
567 "Get the width, height, decent and leading of the text using the
568current or specified font. Works for single as well as multi-line
569strings.", "");
322913ce 570
746ee6b8
RD
571
572 %extend {
70794ec5
RD
573 DocAStr(GetPartialTextExtents,
574 "GetPartialTextExtents(self, text) -> [widths]",
575 "Returns a list of integers such that each value is the distance in
576pixels from the begining of text to the coresponding character of
577*text*. The generic version simply builds a running total of the widths
578of each character using GetTextExtent, however if the various
579platforms have a native API function that is faster or more accurate
43e8916f 580than the generic implementation then it will be used instead.", "");
746ee6b8
RD
581 wxArrayInt GetPartialTextExtents(const wxString& text) {
582 wxArrayInt widths;
583 self->GetPartialTextExtents(text, widths);
584 return widths;
585 }
586 }
587
d14a1e28
RD
588
589 // size and resolution
590 // -------------------
591
70794ec5
RD
592 DocStr(
593 GetSize,
594 "This gets the horizontal and vertical resolution in device units. It
595can be used to scale graphics to fit the page. For example, if *maxX*
596and *maxY* represent the maximum horizontal and vertical 'pixel' values
597used in your application, the following code will scale the graphic to
598fit on the printer page::
599
600 w, h = dc.GetSize()
601 scaleX = maxX*1.0 / w
602 scaleY = maxY*1.0 / h
603 dc.SetUserScale(min(scaleX,scaleY),min(scaleX,scaleY))
604", "");
d14a1e28 605 wxSize GetSize();
322913ce
RD
606 DocDeclAName(
607 void, GetSize( int *OUTPUT, int *OUTPUT ),
608 "GetSizeTuple() -> (width, height)",
609 GetSizeTuple);
4942342c 610
d14a1e28 611
d07d2bc9 612 DocStr(GetSizeMM, "Get the DC size in milimeters.", "");
d14a1e28 613 wxSize GetSizeMM() const;
322913ce
RD
614 DocDeclAName(
615 void, GetSizeMM( int *OUTPUT, int *OUTPUT ) const,
616 "GetSizeMMTuple() -> (width, height)",
617 GetSizeMMTuple);
4942342c
RD
618
619
d14a1e28
RD
620
621 // coordinates conversions
622 // -----------------------
623
70794ec5
RD
624 DocDeclStr(
625 wxCoord , DeviceToLogicalX(wxCoord x) const,
626 "Convert device X coordinate to logical coordinate, using the current
627mapping mode.", "");
628
629 DocDeclStr(
630 wxCoord , DeviceToLogicalY(wxCoord y) const,
631 "Converts device Y coordinate to logical coordinate, using the current
632mapping mode.", "");
633
634 DocDeclStr(
635 wxCoord , DeviceToLogicalXRel(wxCoord x) const,
636 "Convert device X coordinate to relative logical coordinate, using the
637current mapping mode but ignoring the x axis orientation. Use this
638function for converting a width, for example.", "");
639
640 DocDeclStr(
641 wxCoord , DeviceToLogicalYRel(wxCoord y) const,
642 "Convert device Y coordinate to relative logical coordinate, using the
643current mapping mode but ignoring the y axis orientation. Use this
644function for converting a height, for example.", "");
645
646 DocDeclStr(
647 wxCoord , LogicalToDeviceX(wxCoord x) const,
648 "Converts logical X coordinate to device coordinate, using the current
649mapping mode.", "");
650
651 DocDeclStr(
652 wxCoord , LogicalToDeviceY(wxCoord y) const,
653 "Converts logical Y coordinate to device coordinate, using the current
654mapping mode.", "");
655
656 DocDeclStr(
657 wxCoord , LogicalToDeviceXRel(wxCoord x) const,
658 "Converts logical X coordinate to relative device coordinate, using the
659current mapping mode but ignoring the x axis orientation. Use this for
660converting a width, for example.", "");
661
662 DocDeclStr(
663 wxCoord , LogicalToDeviceYRel(wxCoord y) const,
664 "Converts logical Y coordinate to relative device coordinate, using the
665current mapping mode but ignoring the y axis orientation. Use this for
666converting a height, for example.", "");
667
d14a1e28 668
70794ec5 669
d14a1e28
RD
670 // query DC capabilities
671 // ---------------------
672
673 virtual bool CanDrawBitmap() const;
674 virtual bool CanGetTextExtent() const;
675
d14a1e28 676
70794ec5
RD
677 DocDeclStr(
678 virtual int , GetDepth() const,
679 "Returns the colour depth of the DC.", "");
680
d14a1e28 681
70794ec5
RD
682 DocDeclStr(
683 virtual wxSize , GetPPI() const,
684 "Resolution in Pixels per inch", "");
685
d14a1e28 686
70794ec5
RD
687 DocDeclStr(
688 virtual bool , Ok() const,
689 "Returns true if the DC is ok to use.", "");
690
4942342c 691
d14a1e28 692
70794ec5
RD
693 DocDeclStr(
694 int , GetBackgroundMode() const,
695 "Returns the current background mode, either ``wx.SOLID`` or
696``wx.TRANSPARENT``.","
d14a1e28 697
70794ec5
RD
698:see: `SetBackgroundMode`");
699
700 DocDeclStr(
701 const wxBrush& , GetBackground() const,
702 "Gets the brush used for painting the background.","
d14a1e28 703
70794ec5
RD
704:see: `SetBackground`");
705
706 DocDeclStr(
707 const wxBrush& , GetBrush() const,
708 "Gets the current brush", "");
709
710 DocDeclStr(
711 const wxFont& , GetFont() const,
712 "Gets the current font", "");
713
714 DocDeclStr(
715 const wxPen& , GetPen() const,
716 "Gets the current pen", "");
717
718 DocDeclStr(
719 const wxColour& , GetTextBackground() const,
720 "Gets the current text background colour", "");
721
722 DocDeclStr(
723 const wxColour& , GetTextForeground() const,
724 "Gets the current text foreground colour", "");
725
d14a1e28 726
70794ec5
RD
727 DocDeclStr(
728 virtual void , SetTextForeground(const wxColour& colour),
729 "Sets the current text foreground colour for the DC.", "");
730
731 DocDeclStr(
732 virtual void , SetTextBackground(const wxColour& colour),
733 "Sets the current text background colour for the DC.", "");
734
4942342c 735
70794ec5
RD
736 DocDeclStr(
737 int , GetMapMode() const,
738 "Gets the current *mapping mode* for the device context ", "");
739
740 DocDeclStr(
741 virtual void , SetMapMode(int mode),
742 "The *mapping mode* of the device context defines the unit of
743measurement used to convert logical units to device units. The
744mapping mode can be one of the following:
745
746 ================ =============================================
747 wx.MM_TWIPS Each logical unit is 1/20 of a point, or 1/1440
748 of an inch.
749 wx.MM_POINTS Each logical unit is a point, or 1/72 of an inch.
750 wx.MM_METRIC Each logical unit is 1 mm.
751 wx.MM_LOMETRIC Each logical unit is 1/10 of a mm.
752 wx.MM_TEXT Each logical unit is 1 pixel.
753 ================ =============================================
754","
755Note that in X, text drawing isn't handled consistently with the
756mapping mode; a font is always specified in point size. However,
757setting the user scale (see `SetUserScale`) scales the text
758appropriately. In Windows, scalable TrueType fonts are always used; in
759X, results depend on availability of fonts, but usually a reasonable
760match is found.
761
762The coordinate origin is always at the top left of the screen/printer.
763
764Drawing to a Windows printer device context uses the current mapping
765mode, but mapping mode is currently ignored for PostScript output.
766");
767
768
769
770 DocDeclAStr(
322913ce 771 virtual void, GetUserScale(double *OUTPUT, double *OUTPUT) const,
70794ec5
RD
772 "GetUserScale(self) -> (xScale, yScale)",
773 "Gets the current user scale factor (set by `SetUserScale`).", "");
4942342c 774
70794ec5
RD
775 DocDeclStr(
776 virtual void , SetUserScale(double x, double y),
777 "Sets the user scaling factor, useful for applications which require
778'zooming'.", "");
779
d14a1e28 780
4942342c 781
322913ce
RD
782 DocDeclA(
783 virtual void, GetLogicalScale(double *OUTPUT, double *OUTPUT),
784 "GetLogicalScale() -> (xScale, yScale)");
785
d14a1e28
RD
786 virtual void SetLogicalScale(double x, double y);
787
322913ce 788
d14a1e28 789 wxPoint GetLogicalOrigin() const;
322913ce
RD
790 DocDeclAName(
791 void, GetLogicalOrigin(wxCoord *OUTPUT, wxCoord *OUTPUT) const,
792 "GetLogicalOriginTuple() -> (x,y)",
793 GetLogicalOriginTuple);
4942342c 794
d14a1e28 795 virtual void SetLogicalOrigin(wxCoord x, wxCoord y);
d7403ad2
RD
796 %extend {
797 void SetLogicalOriginPoint(const wxPoint& point) {
798 self->SetLogicalOrigin(point.x, point.y);
799 }
800 }
d14a1e28 801
d7403ad2 802
d14a1e28 803 wxPoint GetDeviceOrigin() const;
322913ce
RD
804 DocDeclAName(
805 void, GetDeviceOrigin(wxCoord *OUTPUT, wxCoord *OUTPUT) const,
806 "GetDeviceOriginTuple() -> (x,y)",
807 GetDeviceOriginTuple);
4942342c 808
d14a1e28 809 virtual void SetDeviceOrigin(wxCoord x, wxCoord y);
d7403ad2
RD
810 %extend {
811 void SetDeviceOriginPoint(const wxPoint& point) {
812 self->SetDeviceOrigin(point.x, point.y);
813 }
814 }
d14a1e28 815
70794ec5
RD
816 DocDeclStr(
817 virtual void , SetAxisOrientation(bool xLeftRight, bool yBottomUp),
818 "Sets the x and y axis orientation (i.e., the direction from lowest to
819highest values on the axis). The default orientation is the natural
820orientation, e.g. x axis from left to right and y axis from bottom up.", "");
3350d652 821
d14a1e28 822
70794ec5
RD
823 DocDeclStr(
824 int , GetLogicalFunction() const,
825 "Gets the current logical function (set by `SetLogicalFunction`).", "");
826
827 DocDeclStr(
828 virtual void , SetLogicalFunction(int function),
829 "Sets the current logical function for the device context. This
830determines how a source pixel (from a pen or brush colour, or source
831device context if using `Blit`) combines with a destination pixel in
832the current device context.
833
834The possible values and their meaning in terms of source and
835destination pixel values are as follows:
836
837 ================ ==========================
838 wx.AND src AND dst
839 wx.AND_INVERT (NOT src) AND dst
840 wx.AND_REVERSE src AND (NOT dst)
841 wx.CLEAR 0
842 wx.COPY src
843 wx.EQUIV (NOT src) XOR dst
844 wx.INVERT NOT dst
845 wx.NAND (NOT src) OR (NOT dst)
846 wx.NOR (NOT src) AND (NOT dst)
847 wx.NO_OP dst
848 wx.OR src OR dst
849 wx.OR_INVERT (NOT src) OR dst
850 wx.OR_REVERSE src OR (NOT dst)
851 wx.SET 1
852 wx.SRC_INVERT NOT src
853 wx.XOR src XOR dst
854 ================ ==========================
855
856The default is wx.COPY, which simply draws with the current
857colour. The others combine the current colour and the background using
858a logical operation. wx.INVERT is commonly used for drawing rubber
859bands or moving outlines, since drawing twice reverts to the original
860colour.
861", "");
862
d14a1e28 863
3350d652
RD
864 DocDeclStr(
865 void , ComputeScaleAndOrigin(),
866 "Performs all necessary computations for given platform and context
867type after each change of scale and origin parameters. Usually called
868automatically internally after such changes.
869", "");
870
871
872
49e6b3c3
RD
873// DocDeclStr(
874// virtual void , SetOptimization(bool optimize),
875// "If *optimize* is true this function sets optimization mode on. This
876// currently means that under X, the device context will not try to set a
877// pen or brush property if it is known to be set already. This approach
878// can fall down if non-wxWidgets code is using the same device context
879// or window, for example when the window is a panel on which the
880// windowing system draws panel items. The wxWidgets device context
881// 'memory' will now be out of step with reality.
882
883// Setting optimization off, drawing, then setting it back on again, is a
884// trick that must occasionally be employed.", "");
885
886// DocDeclStr(
887// virtual bool , GetOptimization(),
888// "Returns true if device context optimization is on. See
889// `SetOptimization` for details.", "");
890
891 %pythoncode {
892 def SetOptimization(self, optimize):
893 pass
894 def GetOptimization(self):
895 return False
896
897 SetOptimization = wx._deprecated(SetOptimization)
898 GetOptimization = wx._deprecated(GetOptimization)
899 }
70794ec5 900
70794ec5 901
d14a1e28
RD
902 // bounding box
903 // ------------
904
70794ec5
RD
905 DocDeclStr(
906 virtual void , CalcBoundingBox(wxCoord x, wxCoord y),
907 "Adds the specified point to the bounding box which can be retrieved
908with `MinX`, `MaxX` and `MinY`, `MaxY` or `GetBoundingBox` functions.", "");
909
d7403ad2 910 %extend {
70794ec5
RD
911 DocStr(CalcBoundingBoxPoint,
912 "Adds the specified point to the bounding box which can be retrieved
913with `MinX`, `MaxX` and `MinY`, `MaxY` or `GetBoundingBox` functions.","");
d7403ad2
RD
914 void CalcBoundingBoxPoint(const wxPoint& point) {
915 self->CalcBoundingBox(point.x, point.y);
916 }
917 }
918
70794ec5
RD
919 DocDeclStr(
920 void , ResetBoundingBox(),
921 "Resets the bounding box: after a call to this function, the bounding
922box doesn't contain anything.", "");
923
d14a1e28
RD
924
925 // Get the final bounding box of the PostScript or Metafile picture.
70794ec5
RD
926 DocDeclStr(
927 wxCoord , MinX() const,
928 "Gets the minimum horizontal extent used in drawing commands so far.", "");
929
930 DocDeclStr(
931 wxCoord , MaxX() const,
932 "Gets the maximum horizontal extent used in drawing commands so far.", "");
933
934 DocDeclStr(
935 wxCoord , MinY() const,
936 "Gets the minimum vertical extent used in drawing commands so far.", "");
937
938 DocDeclStr(
939 wxCoord , MaxY() const,
940 "Gets the maximum vertical extent used in drawing commands so far.", "");
941
d14a1e28
RD
942
943
70794ec5
RD
944 DocAStr(GetBoundingBox,
945 "GetBoundingBox() -> (x1,y1, x2,y2)",
946 "Returns the min and max points used in drawing commands so far.", "");
d14a1e28
RD
947 %extend {
948 void GetBoundingBox(int* OUTPUT, int* OUTPUT, int* OUTPUT, int* OUTPUT);
949 // See below for implementation
4942342c 950 }
70794ec5 951
d14a1e28
RD
952 %pythoncode { def __nonzero__(self): return self.Ok() };
953
954
96fc3ef4
RD
955#ifdef __WXMSW__
956 long GetHDC();
957#endif
958
d14a1e28
RD
959
960 %extend { // See drawlist.cpp for impplementaion of these...
961 PyObject* _DrawPointList(PyObject* pyCoords, PyObject* pyPens, PyObject* pyBrushes)
962 {
963 return wxPyDrawXXXList(*self, wxPyDrawXXXPoint, pyCoords, pyPens, pyBrushes);
964 }
965
966 PyObject* _DrawLineList(PyObject* pyCoords, PyObject* pyPens, PyObject* pyBrushes)
967 {
968 return wxPyDrawXXXList(*self, wxPyDrawXXXLine, pyCoords, pyPens, pyBrushes);
969 }
970
971 PyObject* _DrawRectangleList(PyObject* pyCoords, PyObject* pyPens, PyObject* pyBrushes)
972 {
973 return wxPyDrawXXXList(*self, wxPyDrawXXXRectangle, pyCoords, pyPens, pyBrushes);
974 }
975
976 PyObject* _DrawEllipseList(PyObject* pyCoords, PyObject* pyPens, PyObject* pyBrushes)
977 {
978 return wxPyDrawXXXList(*self, wxPyDrawXXXEllipse, pyCoords, pyPens, pyBrushes);
979 }
980
981 PyObject* _DrawPolygonList(PyObject* pyCoords, PyObject* pyPens, PyObject* pyBrushes)
982 {
983 return wxPyDrawXXXList(*self, wxPyDrawXXXPolygon, pyCoords, pyPens, pyBrushes);
984 }
985
986 PyObject* _DrawTextList(PyObject* textList, PyObject* pyPoints,
987 PyObject* foregroundList, PyObject* backgroundList) {
988 return wxPyDrawTextList(*self, textList, pyPoints, foregroundList, backgroundList);
989 }
990 }
991
992 %pythoncode {
993 def DrawPointList(self, points, pens=None):
70794ec5
RD
994 """
995 Draw a list of points as quickly as possible.
996
997 :param points: A sequence of 2-element sequences representing
998 each point to draw, (x,y).
999 :param pens: If None, then the current pen is used. If a
1000 single pen then it will be used for all points. If
1001 a list of pens then there should be one for each point
1002 in points.
1003 """
d14a1e28
RD
1004 if pens is None:
1005 pens = []
1006 elif isinstance(pens, wx.Pen):
1007 pens = [pens]
1008 elif len(pens) != len(points):
1009 raise ValueError('points and pens must have same length')
1010 return self._DrawPointList(points, pens, [])
1011
1012
1013 def DrawLineList(self, lines, pens=None):
70794ec5
RD
1014 """
1015 Draw a list of lines as quickly as possible.
1016
1017 :param lines: A sequence of 4-element sequences representing
1018 each line to draw, (x1,y1, x2,y2).
1019 :param pens: If None, then the current pen is used. If a
1020 single pen then it will be used for all lines. If
1021 a list of pens then there should be one for each line
1022 in lines.
1023 """
d14a1e28
RD
1024 if pens is None:
1025 pens = []
1026 elif isinstance(pens, wx.Pen):
1027 pens = [pens]
1028 elif len(pens) != len(lines):
1029 raise ValueError('lines and pens must have same length')
1030 return self._DrawLineList(lines, pens, [])
1031
1032
1033 def DrawRectangleList(self, rectangles, pens=None, brushes=None):
70794ec5
RD
1034 """
1035 Draw a list of rectangles as quickly as possible.
1036
1037 :param rectangles: A sequence of 4-element sequences representing
1038 each rectangle to draw, (x,y, w,h).
1039 :param pens: If None, then the current pen is used. If a
1040 single pen then it will be used for all rectangles.
1041 If a list of pens then there should be one for each
1042 rectangle in rectangles.
1043 :param brushes: A brush or brushes to be used to fill the rectagles,
1044 with similar semantics as the pens parameter.
1045 """
d14a1e28
RD
1046 if pens is None:
1047 pens = []
1048 elif isinstance(pens, wx.Pen):
1049 pens = [pens]
1050 elif len(pens) != len(rectangles):
1051 raise ValueError('rectangles and pens must have same length')
1052 if brushes is None:
1053 brushes = []
1054 elif isinstance(brushes, wx.Brush):
1055 brushes = [brushes]
1056 elif len(brushes) != len(rectangles):
1057 raise ValueError('rectangles and brushes must have same length')
1058 return self._DrawRectangleList(rectangles, pens, brushes)
1059
1060
1061 def DrawEllipseList(self, ellipses, pens=None, brushes=None):
70794ec5
RD
1062 """
1063 Draw a list of ellipses as quickly as possible.
1064
1065 :param ellipses: A sequence of 4-element sequences representing
1066 each ellipse to draw, (x,y, w,h).
1067 :param pens: If None, then the current pen is used. If a
1068 single pen then it will be used for all ellipses.
1069 If a list of pens then there should be one for each
1070 ellipse in ellipses.
1071 :param brushes: A brush or brushes to be used to fill the ellipses,
1072 with similar semantics as the pens parameter.
1073 """
d14a1e28
RD
1074 if pens is None:
1075 pens = []
1076 elif isinstance(pens, wx.Pen):
1077 pens = [pens]
1078 elif len(pens) != len(ellipses):
1079 raise ValueError('ellipses and pens must have same length')
1080 if brushes is None:
1081 brushes = []
1082 elif isinstance(brushes, wx.Brush):
1083 brushes = [brushes]
1084 elif len(brushes) != len(ellipses):
1085 raise ValueError('ellipses and brushes must have same length')
1086 return self._DrawEllipseList(ellipses, pens, brushes)
1087
1088
1089 def DrawPolygonList(self, polygons, pens=None, brushes=None):
70794ec5
RD
1090 """
1091 Draw a list of polygons, each of which is a list of points.
1092
1093 :param polygons: A sequence of sequences of sequences.
1094 [[(x1,y1),(x2,y2),(x3,y3)...],
1095 [(x1,y1),(x2,y2),(x3,y3)...]]
1096
1097 :param pens: If None, then the current pen is used. If a
1098 single pen then it will be used for all polygons.
1099 If a list of pens then there should be one for each
1100 polygon.
1101 :param brushes: A brush or brushes to be used to fill the polygons,
1102 with similar semantics as the pens parameter.
1103 """
d14a1e28
RD
1104 if pens is None:
1105 pens = []
1106 elif isinstance(pens, wx.Pen):
1107 pens = [pens]
1108 elif len(pens) != len(polygons):
1109 raise ValueError('polygons and pens must have same length')
1110 if brushes is None:
1111 brushes = []
1112 elif isinstance(brushes, wx.Brush):
1113 brushes = [brushes]
1114 elif len(brushes) != len(polygons):
1115 raise ValueError('polygons and brushes must have same length')
1116 return self._DrawPolygonList(polygons, pens, brushes)
1117
1118
70794ec5
RD
1119 def DrawTextList(self, textList, coords, foregrounds = None, backgrounds = None):
1120 """
1121 Draw a list of strings using a list of coordinants for positioning each string.
1122
1123 :param textList: A list of strings
1124 :param coords: A list of (x,y) positions
1125 :param foregrounds: A list of `wx.Colour` objects to use for the
1126 foregrounds of the strings.
1127 :param backgrounds: A list of `wx.Colour` objects to use for the
1128 backgrounds of the strings.
1129
1130 NOTE: Make sure you set Background mode to wx.Solid (DC.SetBackgroundMode)
1131 If you want backgrounds to do anything.
1132 """
d14a1e28
RD
1133 if type(textList) == type(''):
1134 textList = [textList]
1135 elif len(textList) != len(coords):
1136 raise ValueError('textlist and coords must have same length')
1137 if foregrounds is None:
1138 foregrounds = []
fd3f2efe 1139 elif isinstance(foregrounds, wx.Colour):
d14a1e28
RD
1140 foregrounds = [foregrounds]
1141 elif len(foregrounds) != len(coords):
1142 raise ValueError('foregrounds and coords must have same length')
1143 if backgrounds is None:
1144 backgrounds = []
fd3f2efe 1145 elif isinstance(backgrounds, wx.Colour):
d14a1e28
RD
1146 backgrounds = [backgrounds]
1147 elif len(backgrounds) != len(coords):
1148 raise ValueError('backgrounds and coords must have same length')
1149 return self._DrawTextList(textList, coords, foregrounds, backgrounds)
1150 }
1151
1152};
1153
1154
1155
1156%{
1157static void wxDC_GetBoundingBox(wxDC* dc, int* x1, int* y1, int* x2, int* y2) {
1158 *x1 = dc->MinX();
1159 *y1 = dc->MinY();
1160 *x2 = dc->MaxX();
1161 *y2 = dc->MaxY();
1162}
1163%}
1164
1165
1166//---------------------------------------------------------------------------
1167%newgroup
1168
ab1f7d2a
RD
1169MustHaveApp(wxMemoryDC);
1170
70794ec5
RD
1171DocStr(wxMemoryDC,
1172"A memory device context provides a means to draw graphics onto a
1173bitmap. A bitmap must be selected into the new memory DC before it may
1174be used for anything. Typical usage is as follows::
1175
1176 dc = wx.MemoryDC()
1177 dc.SelectObject(bitmap)
1178 # draw on the dc usign any of the Draw methods
1179 dc.SelectObject(wx.NullBitmap)
1180 # the bitmap now contains wahtever was drawn upon it
1181
1182Note that the memory DC *must* be deleted (or the bitmap selected out
1183of it) before a bitmap can be reselected into another memory DC.
1184", "");
1185
d14a1e28
RD
1186class wxMemoryDC : public wxDC {
1187public:
70794ec5
RD
1188 DocCtorStr(
1189 wxMemoryDC(),
1190 "Constructs a new memory device context.
1191
1192Use the Ok member to test whether the constructor was successful in
1193creating a usable device context. Don't forget to select a bitmap into
1194the DC before drawing on it.", "
4942342c 1195
70794ec5
RD
1196:see: `MemoryDCFromDC`");
1197
1198 DocCtorStrName(
1199 wxMemoryDC(wxDC* oldDC),
1200 "Creates a DC that is compatible with the oldDC.", "",
1201 MemoryDCFromDC);
1202
1203
1204 DocDeclStr(
1205 void , SelectObject(const wxBitmap& bitmap),
1206 "Selects the bitmap into the device context, to use as the memory
1207bitmap. Selecting the bitmap into a memory DC allows you to draw into
1208the DC, and therefore the bitmap, and also to use Blit to copy the
1209bitmap to a window.
1210
1211If the argument is wx.NullBitmap (or some other uninitialised
1212`wx.Bitmap`) the current bitmap is selected out of the device context,
1213and the original bitmap restored, allowing the current bitmap to be
1214destroyed safely.", "");
1215
d14a1e28
RD
1216};
1217
1218//---------------------------------------------------------------------------
1219%newgroup
1220
b159c5c4 1221
ef22e3d3 1222%{
ef22e3d3 1223#include <wx/dcbuffer.h>
ef22e3d3
RD
1224%}
1225
67a5217c
RD
1226enum {
1227 wxBUFFER_VIRTUAL_AREA,
1228 wxBUFFER_CLIENT_AREA
1229};
ef22e3d3 1230
ab1f7d2a
RD
1231MustHaveApp(wxBufferedDC);
1232
70794ec5
RD
1233DocStr(wxBufferedDC,
1234"This simple class provides a simple way to avoid flicker: when drawing
1235on it, everything is in fact first drawn on an in-memory buffer (a
1236`wx.Bitmap`) and then copied to the screen only once, when this object
1237is destroyed.
1238
1239It can be used in the same way as any other device
1240context. wx.BufferedDC itself typically replaces `wx.ClientDC`, if you
1241want to use it in your EVT_PAINT handler, you should look at
1242`wx.BufferedPaintDC`.
1243", "");
1244
d14a1e28
RD
1245class wxBufferedDC : public wxMemoryDC
1246{
1247public:
e608d228 1248 %pythonAppend wxBufferedDC
70794ec5 1249 "self.__dc = args[0] # save a ref so the other dc will not be deleted before self";
1b8c7ba6 1250
b159c5c4 1251 %nokwargs wxBufferedDC;
d14a1e28 1252
70794ec5
RD
1253 DocStr(
1254 wxBufferedDC,
1255 "Constructs a buffered DC.", "
1256
1257 :param dc: The underlying DC: everything drawn to this object will
1258 be flushed to this DC when this object is destroyed. You may
1259 pass ``None`` in order to just initialize the buffer, and not
1260 flush it.
1261
1262 :param buffer: If a `wx.Size` object is passed as the 2nd arg then
1263 it is the size of the bitmap that will be created internally
1264 and used for an implicit buffer. If the 2nd arg is a
1265 `wx.Bitmap` then it is the explicit buffer that will be
1266 used. Using an explicit buffer is the most efficient solution
1267 as the bitmap doesn't have to be recreated each time but it
1268 also requires more memory as the bitmap is never freed. The
1269 bitmap should have appropriate size, anything drawn outside of
4a065572
RD
1270 its bounds is clipped. If wx.NullBitmap is used then a new
1271 buffer will be allocated that is the same size as the dc.
b159c5c4 1272
67a5217c
RD
1273 :param style: The style parameter indicates whether the supplied buffer is
1274 intended to cover the entire virtual size of a `wx.ScrolledWindow` or
1275 if it only covers the client area. Acceptable values are
1276 ``wx.BUFFER_VIRTUAL_AREA`` and ``wx.BUFFER_CLIENT_AREA``.
1277
1278");
4a065572
RD
1279 wxBufferedDC( wxDC* dc,
1280 const wxBitmap& buffer=wxNullBitmap,
1281 int style = wxBUFFER_CLIENT_AREA );
1282 wxBufferedDC( wxDC* dc,
1283 const wxSize& area,
1284 int style = wxBUFFER_CLIENT_AREA );
7a0b15e9 1285
70794ec5
RD
1286 DocCtorStr(
1287 ~wxBufferedDC(),
1288 "Copies everything drawn on the DC so far to the underlying DC
1289associated with this object, if any.", "");
1290
4a065572 1291
70794ec5
RD
1292 DocDeclStr(
1293 void , UnMask(),
1294 "Blits the buffer to the dc, and detaches the dc from the buffer (so it
1295can be effectively used once only). This is usually only called in
1296the destructor.", "");
e608d228 1297
d14a1e28
RD
1298};
1299
1300
7a0b15e9 1301
70794ec5 1302
ab1f7d2a 1303MustHaveApp(wxBufferedPaintDC);
7a0b15e9 1304
70794ec5
RD
1305DocStr(wxBufferedPaintDC,
1306"This is a subclass of `wx.BufferedDC` which can be used inside of an
1307EVT_PAINT event handler. Just create an object of this class instead
1308of `wx.PaintDC` and that's all you have to do to (mostly) avoid
1309flicker. The only thing to watch out for is that if you are using this
1310class together with `wx.ScrolledWindow`, you probably do **not** want
1311to call `wx.Window.PrepareDC` on it as it already does this internally
1312for the real underlying `wx.PaintDC`.
1313
1314If your window is already fully buffered in a `wx.Bitmap` then your
1315EVT_PAINT handler can be as simple as just creating a
1316``wx.BufferedPaintDC`` as it will `Blit` the buffer to the window
1317automatically when it is destroyed. For example::
1318
1319 def OnPaint(self, event):
1320 dc = wx.BufferedPaintDC(self, self.buffer)
1321
1322
67a5217c
RD
1323
1324
70794ec5
RD
1325", "");
1326
d14a1e28
RD
1327class wxBufferedPaintDC : public wxBufferedDC
1328{
1329public:
b159c5c4 1330
70794ec5 1331 DocCtorStr(
67a5217c
RD
1332 wxBufferedPaintDC( wxWindow *window,
1333 const wxBitmap &buffer = wxNullBitmap,
1334 int style = wxBUFFER_CLIENT_AREA),
70794ec5
RD
1335 "Create a buffered paint DC. As with `wx.BufferedDC`, you may either
1336provide the bitmap to be used for buffering or let this object create
1337one internally (in the latter case, the size of the client part of the
1338window is automatically used).
1339
1340", "");
b159c5c4 1341
d14a1e28
RD
1342};
1343
1344
1345//---------------------------------------------------------------------------
1346%newgroup
1347
ab1f7d2a
RD
1348MustHaveApp(wxScreenDC);
1349
70794ec5
RD
1350DocStr(wxScreenDC,
1351"A wxScreenDC can be used to paint anywhere on the screen. This should
1352normally be constructed as a temporary stack object; don't store a
1353wxScreenDC object.
1354", "");
d14a1e28
RD
1355class wxScreenDC : public wxDC {
1356public:
1357 wxScreenDC();
1358
70794ec5
RD
1359 DocDeclStrName(
1360 bool , StartDrawingOnTop(wxWindow* window),
1361 "Specify that the area of the screen to be drawn upon coincides with
1362the given window.
1363
1364:see: `EndDrawingOnTop`", "",
1365 StartDrawingOnTopWin);
1366
1367
1368 DocDeclStr(
1369 bool , StartDrawingOnTop(wxRect* rect = NULL),
1370 "Specify that the area is the given rectangle, or the whole screen if
1371``None`` is passed.
1372
1373:see: `EndDrawingOnTop`", "");
1374
1375
1376 DocDeclStr(
1377 bool , EndDrawingOnTop(),
1378 "Use this in conjunction with `StartDrawingOnTop` or
1379`StartDrawingOnTopWin` to ensure that drawing to the screen occurs on
1380top of existing windows. Without this, some window systems (such as X)
1381only allow drawing to take place underneath other windows.
1382
1383You might use this pair of functions when implementing a drag feature,
1384for example as in the `wx.SplitterWindow` implementation.
1385
1386These functions are probably obsolete since the X implementations
1387allow drawing directly on the screen now. However, the fact that this
1388function allows the screen to be refreshed afterwards may be useful
1389to some applications.", "");
1390
d14a1e28
RD
1391};
1392
1393//---------------------------------------------------------------------------
1394%newgroup
1395
ab1f7d2a
RD
1396MustHaveApp(wxClientDC);
1397
70794ec5
RD
1398DocStr(wxClientDC,
1399"A wx.ClientDC must be constructed if an application wishes to paint on
1400the client area of a window from outside an EVT_PAINT event. This should
1401normally be constructed as a temporary stack object; don't store a
1402wx.ClientDC object long term.
1403
1404To draw on a window from within an EVT_PAINT handler, construct a
1405`wx.PaintDC` object.
1406
1407To draw on the whole window including decorations, construct a
1408`wx.WindowDC` object (Windows only).
1409", "");
d14a1e28
RD
1410class wxClientDC : public wxDC {
1411public:
70794ec5
RD
1412 DocCtorStr(
1413 wxClientDC(wxWindow* win),
1414 "Constructor. Pass the window on which you wish to paint.", "");
d14a1e28
RD
1415};
1416
1417//---------------------------------------------------------------------------
1418%newgroup
1419
ab1f7d2a
RD
1420MustHaveApp(wxPaintDC);
1421
70794ec5
RD
1422DocStr(wxPaintDC,
1423"A wx.PaintDC must be constructed if an application wishes to paint on
1424the client area of a window from within an EVT_PAINT event
1425handler. This should normally be constructed as a temporary stack
1426object; don't store a wx.PaintDC object. If you have an EVT_PAINT
1427handler, you **must** create a wx.PaintDC object within it even if you
1428don't actually use it.
1429
1430Using wx.PaintDC within EVT_PAINT handlers is important because it
1431automatically sets the clipping area to the damaged area of the
1432window. Attempts to draw outside this area do not appear.
1433
1434To draw on a window from outside EVT_PAINT handlers, construct a
1435`wx.ClientDC` object.
1436","");
d14a1e28
RD
1437class wxPaintDC : public wxDC {
1438public:
70794ec5
RD
1439 DocCtorStr(
1440 wxPaintDC(wxWindow* win),
1441 "Constructor. Pass the window on which you wish to paint.", "");
d14a1e28
RD
1442};
1443
1444//---------------------------------------------------------------------------
1445%newgroup
1446
ab1f7d2a
RD
1447MustHaveApp(wxWindowDC);
1448
70794ec5
RD
1449DocStr(wxWindowDC,
1450 "A wx.WindowDC must be constructed if an application wishes to paint on
1451the whole area of a window (client and decorations). This should
1452normally be constructed as a temporary stack object; don't store a
1453wx.WindowDC object.","");
d14a1e28
RD
1454class wxWindowDC : public wxDC {
1455public:
70794ec5
RD
1456 DocCtorStr(
1457 wxWindowDC(wxWindow* win),
1458 "Constructor. Pass the window on which you wish to paint.","");
d14a1e28
RD
1459};
1460
1461//---------------------------------------------------------------------------
1462%newgroup
1463
ab1f7d2a
RD
1464MustHaveApp(wxMirrorDC);
1465
70794ec5
RD
1466DocStr(wxMirrorDC,
1467"wx.MirrorDC is a simple wrapper class which is always associated with a
1468real `wx.DC` object and either forwards all of its operations to it
1469without changes (no mirroring takes place) or exchanges x and y
1470coordinates which makes it possible to reuse the same code to draw a
1471figure and its mirror -- i.e. reflection related to the diagonal line
1472x == y.", "");
d14a1e28
RD
1473class wxMirrorDC : public wxDC
1474{
1475public:
70794ec5
RD
1476 DocCtorStr(
1477 wxMirrorDC(wxDC& dc, bool mirror),
1478 "Creates a mirrored DC associated with the real *dc*. Everything drawn
1479on the wx.MirrorDC will appear on the *dc*, and will be mirrored if
1480*mirror* is True.","");
d14a1e28
RD
1481};
1482
1483//---------------------------------------------------------------------------
1484%newgroup
1485
1486%{
1487#include <wx/dcps.h>
1488%}
1489
ab1f7d2a
RD
1490MustHaveApp(wxPostScriptDC);
1491
70794ec5
RD
1492DocStr(wxPostScriptDC,
1493"This is a `wx.DC` that can write to PostScript files on any platform.","");
1494
d14a1e28
RD
1495class wxPostScriptDC : public wxDC {
1496public:
70794ec5
RD
1497 DocCtorStr(
1498 wxPostScriptDC(const wxPrintData& printData),
1499 "Constructs a PostScript printer device context from a `wx.PrintData`
1500object.", "");
d14a1e28
RD
1501
1502 wxPrintData& GetPrintData();
1503 void SetPrintData(const wxPrintData& data);
1504
70794ec5
RD
1505 DocDeclStr(
1506 static void , SetResolution(int ppi),
1507 "Set resolution (in pixels per inch) that will be used in PostScript
1508output. Default is 720ppi.", "");
1509
1510 DocDeclStr(
1511 static int , GetResolution(),
1512 "Return resolution used in PostScript output.", "");
d14a1e28
RD
1513};
1514
1515//---------------------------------------------------------------------------
1516%newgroup
1517
1518
ab1f7d2a
RD
1519MustHaveApp(wxMetaFile);
1520MustHaveApp(wxMetaFileDC);
1521
1522
da457c1b 1523#if defined(__WXMSW__) || defined(__WXMAC__)
d14a1e28
RD
1524
1525%{
1526#include <wx/metafile.h>
1527%}
1528
1529class wxMetaFile : public wxObject {
1530public:
1531 wxMetaFile(const wxString& filename = wxPyEmptyString);
1532 ~wxMetaFile();
1533
1534 bool Ok();
1535 bool SetClipboard(int width = 0, int height = 0);
1536
1537 wxSize GetSize();
1538 int GetWidth();
1539 int GetHeight();
1540
da457c1b 1541#ifdef __WXMSW__
d14a1e28 1542 const wxString& GetFileName() const;
da457c1b
RD
1543#endif
1544
d14a1e28
RD
1545 %pythoncode { def __nonzero__(self): return self.Ok() }
1546};
1547
1548// bool wxMakeMetaFilePlaceable(const wxString& filename,
1549// int minX, int minY, int maxX, int maxY, float scale=1.0);
1550
1551
1552class wxMetaFileDC : public wxDC {
1553public:
1554 wxMetaFileDC(const wxString& filename = wxPyEmptyString,
1555 int width = 0, int height = 0,
1556 const wxString& description = wxPyEmptyString);
1557 wxMetaFile* Close();
1558};
1559
1560
1561
1562#else // Make some dummies for the other platforms
1563
1564%{
1565class wxMetaFile : public wxObject {
1566public:
1567 wxMetaFile(const wxString&)
81cfe5e1 1568 { wxPyRaiseNotImplemented(); }
d14a1e28
RD
1569};
1570
1571class wxMetaFileDC : public wxClientDC {
1572public:
1573 wxMetaFileDC(const wxString&, int, int, const wxString&)
81cfe5e1 1574 { wxPyRaiseNotImplemented(); }
d14a1e28
RD
1575};
1576
1577%}
1578
1579class wxMetaFile : public wxObject {
1580public:
1581 wxMetaFile(const wxString& filename = wxPyEmptyString);
1582};
1583
1584class wxMetaFileDC : public wxDC {
1585public:
1586 wxMetaFileDC(const wxString& filename = wxPyEmptyString,
1587 int width = 0, int height = 0,
1588 const wxString& description = wxPyEmptyString);
1589};
1590
1591
1592#endif
1593
1594
1595//---------------------------------------------------------------------------
1596
ab1f7d2a
RD
1597MustHaveApp(wxPrinterDC);
1598
d14a1e28
RD
1599#if defined(__WXMSW__) || defined(__WXMAC__)
1600
1601class wxPrinterDC : public wxDC {
1602public:
1603 wxPrinterDC(const wxPrintData& printData);
d14a1e28
RD
1604};
1605
1606#else
1607%{
1608class wxPrinterDC : public wxClientDC {
1609public:
1610 wxPrinterDC(const wxPrintData&)
81cfe5e1 1611 { wxPyRaiseNotImplemented(); }
4942342c 1612
d14a1e28
RD
1613};
1614%}
4942342c 1615
d14a1e28
RD
1616class wxPrinterDC : public wxDC {
1617public:
1618 wxPrinterDC(const wxPrintData& printData);
d14a1e28
RD
1619};
1620#endif
1621
4942342c
RD
1622//---------------------------------------------------------------------------
1623//---------------------------------------------------------------------------