]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/dc.h
Convert wxFSW_EVENT_{WARNING,ERROR} to string correctly.
[wxWidgets.git] / interface / wx / dc.h
index cb6031ae97248af9d92769864e0f70902de5168b..d496f73703e48f3e5c217c5fb44f3e95d914618b 100644 (file)
@@ -3,9 +3,106 @@
 // Purpose:     interface of wxDC
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+
+/**
+    Logical raster operations which can be used with wxDC::SetLogicalFunction
+    and some other wxDC functions (e.g. wxDC::Blit and wxDC::StretchBlit).
+
+    The description of the values below refer to how a generic @e src source pixel
+    and the corresponding @e dst destination pixel gets combined together to produce
+    the final pixel. E.g. @c wxCLEAR and @c wxSET completely ignore the source
+    and the destination pixel and always put zeroes or ones in the final surface.
+*/
+enum wxRasterOperationMode
+{
+    wxCLEAR,       //!< 0
+    wxXOR,         //!< @e src XOR @e dst
+    wxINVERT,      //!< NOT @e dst
+    wxOR_REVERSE,  //!< @e src OR (NOT @e dst)
+    wxAND_REVERSE, //!< @e src AND (NOT @e dst)
+    wxCOPY,        //!< @e src
+    wxAND,         //!< @e src AND @e dst
+    wxAND_INVERT,  //!< (NOT @e src) AND @e dst
+    wxNO_OP,       //!< @e dst
+    wxNOR,         //!< (NOT @e src) AND (NOT @e dst)
+    wxEQUIV,       //!< (NOT @e src) XOR @e dst
+    wxSRC_INVERT,  //!< (NOT @e src)
+    wxOR_INVERT,   //!< (NOT @e src) OR @e dst
+    wxNAND,        //!< (NOT @e src) OR (NOT @e dst)
+    wxOR,          //!< @e src OR @e dst
+    wxSET          //!< 1
+};
+
+/**
+    Flood styles used by wxDC::FloodFill.
+*/
+enum wxFloodFillStyle
+{
+    /** The flooding occurs until a colour other than the given colour is encountered. */
+    wxFLOOD_SURFACE = 1,
+
+    /** The area to be flooded is bounded by the given colour. */
+    wxFLOOD_BORDER
+};
+
+/**
+    The mapping used to transform @e logical units to @e device units.
+    See wxDC::SetMapMode.
+*/
+enum wxMappingMode
+{
+    /**
+        Each logical unit is 1 device pixel.
+        This is the default mapping mode for all wxDC-derived classes.
+    */
+    wxMM_TEXT = 1,
+
+    /** Each logical unit is 1 millimeter. */
+    wxMM_METRIC,
+
+    /** Each logical unit is 1/10 of a millimeter. */
+    wxMM_LOMETRIC,
+
+    /**
+        Each logical unit is 1/20 of a @e "printer point", or 1/1440 of an inch
+        (also known as "twip"). Equivalent to about 17.64 micrometers.
+    */
+    wxMM_TWIPS,
+
+    /**
+        Each logical unit is a @e "printer point" i.e. 1/72 of an inch.
+        Equivalent to about 353 micrometers.
+    */
+    wxMM_POINTS
+};
+
+/**
+    Simple collection of various font metrics.
+
+    This object is returned by wxDC::GetFontMetrics().
+
+    @since 2.9.2
+
+    @library{wxcore}
+    @category{dc,gdi}
+ */
+struct wxFontMetrics
+{
+    /// Constructor initializes all fields to 0.
+    wxFontMetrics();
+
+    int height,             ///< Total character height.
+        ascent,             ///< Part of the height above the baseline.
+        descent,            ///< Part of the height below the baseline.
+        internalLeading,    ///< Intra-line spacing.
+        externalLeading,    ///< Inter-line spacing.
+        averageWidth;       ///< Average font width, a.k.a. "x-width".
+};
+
+
 /**
     @class wxDC
 
     wxWidgets offers an alternative drawing API based on the modern drawing
     backends GDI+, CoreGraphics and Cairo. See wxGraphicsContext, wxGraphicsRenderer
     and related classes. There is also a wxGCDC linking the APIs by offering
-    the wxDC API ontop of a wxGraphicsContext.
+    the wxDC API on top of a wxGraphicsContext.
 
     wxDC is an abstract base class and cannot be created directly.
     Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or
     wxDCImpl class. The user-visible classes such as wxClientDC and
     wxPaintDC merely forward all calls to the backend implementation.
 
-    On Mac OS X colours with alpha channel are supported. Instances wxPen
-    or wxBrush that are built from wxColour use the colour's alpha values
-    when stroking or filling.
+
+    @section dc_units Device and logical units
+
+    In the wxDC context there is a distinction between @e logical units and @e device units.
+
+    @b Device units are the units native to the particular device; e.g. for a screen,
+    a device unit is a @e pixel. For a printer, the device unit is defined by the
+    resolution of the printer (usually given in @c DPI: dot-per-inch).
+
+    All wxDC functions use instead @b logical units, unless where explicitly
+    stated. Logical units are arbitrary units mapped to device units using
+    the current mapping mode (see wxDC::SetMapMode).
+
+    This mechanism allows to reuse the same code which prints on e.g. a window
+    on the screen to print on e.g. a paper.
+
+
+    @section dc_alpha_support Support for Transparency / Alpha Channel
+
+    In general wxDC methods don't support alpha transparency and the alpha
+    component of wxColour is simply ignored and you need to use wxGraphicsContext
+    for full transparency support. There are, however, a few exceptions: first,
+    under Mac OS X colours with alpha channel are supported in all the normal
+    wxDC-derived classes as they use wxGraphicsContext internally. Second,
+    under all platforms wxSVGFileDC also fully supports alpha channel. In both
+    of these cases the instances of wxPen or wxBrush that are built from
+    wxColour use the colour's alpha values when stroking or filling.
+
+
+    @section Support for Transformation Matrix
+
+    On some platforms (currently only under MSW and only on Windows NT, i.e.
+    not Windows 9x/ME, systems) wxDC has support for applying an arbitrary
+    affine transformation matrix to its coordinate system. Call
+    CanUseTransformMatrix() to check if this support is available and then call
+    SetTransformMatrix() if it is. If the transformation matrix is not
+    supported, SetTransformMatrix() always simply returns false and doesn't do
+    anything.
+
 
     @library{wxcore}
     @category{dc,gdi}
     @todo Precise definition of default/initial state.
     @todo Pixelwise definition of operations (e.g. last point of a line not
           drawn).
-    @todo Coordinates: state clearly which type of coordinates are returned by
-          the various Get*Point() or similar functions - often they are client
-          coordinates but not always.
 */
 class wxDC : public wxObject
 {
 public:
     /**
-        Copy from a source DC to this DC, specifying the destination
-        coordinates, size of area to copy, source DC, source coordinates,
-        logical function, whether to use a bitmap mask, and mask source
-        position.
-
-        @param xdest
-            Destination device context x position.
-        @param ydest
-            Destination device context y position.
-        @param width
-            Width of source area to be copied.
-        @param height
-            Height of source area to be copied.
-        @param source
-            Source device context.
-        @param xsrc
-            Source device context x position.
-        @param ysrc
-            Source device context y position.
-        @param logicalFunc
-            Logical function to use, see SetLogicalFunction().
-        @param useMask
-            If @true, Blit does a transparent blit using the mask that is
-            associated with the bitmap selected into the source device context.
-            The Windows implementation does the following if MaskBlt cannot be
-            used:
-            <ol>
-            <li>Creates a temporary bitmap and copies the destination area into
-                it.</li>
-            <li>Copies the source area into the temporary bitmap using the
-                specified logical function.</li>
-            <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
-                the mask bitmap with the temp bitmap with the foreground colour
-                set to WHITE and the bg colour set to BLACK.</li>
-            <li>Sets the unmasked area in the destination area to BLACK by
-                ANDing the mask bitmap with the destination area with the
-                foreground colour set to BLACK and the background colour set to
-                WHITE.</li>
-            <li>ORs the temporary bitmap with the destination area.</li>
-            <li>Deletes the temporary bitmap.</li>
-            </ol>
-            This sequence of operations ensures that the source's transparent
-            area need not be black, and logical functions are supported.
-            @n @b Note: on Windows, blitting with masks can be speeded up
-            considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
-            enabled. You can also influence whether MaskBlt or the explicit
-            mask blitting code above is used, by using wxSystemOptions and
-            setting the @c no-maskblt option to 1.
-        @param xsrcMask
-            Source x position on the mask. If both xsrcMask and ysrcMask are
-            @c -1, xsrc and ysrc will be assumed for the mask source position.
-            Currently only implemented on Windows.
-        @param ysrcMask
-            Source y position on the mask. If both xsrcMask and ysrcMask are
-            @c -1, xsrc and ysrc will be assumed for the mask source position.
-            Currently only implemented on Windows.
-
-        @remarks There is partial support for Blit() in wxPostScriptDC, under X.
-
-        @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
+        @name Coordinate conversion functions
     */
-    bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width,
-              wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc,
-              wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false,
-              wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord);
+    //@{
 
     /**
-        Adds the specified point to the bounding box which can be retrieved
-        with MinX(), MaxX() and MinY(), MaxY() functions.
-
-        @see ResetBoundingBox()
+        Convert @e device X coordinate to logical coordinate, using the current
+        mapping mode, user scale factor, device origin and axis orientation.
     */
-    void CalcBoundingBox(wxCoord x, wxCoord y);
+    wxCoord DeviceToLogicalX(wxCoord x) const;
 
     /**
-        Clears the device context using the current background brush.
+        Convert @e device X coordinate to relative logical coordinate, using the
+        current mapping mode and user scale factor but ignoring the
+        axis orientation. Use this for converting a width, for example.
     */
-    void Clear();
+    wxCoord DeviceToLogicalXRel(wxCoord x) const;
 
     /**
-        Displays a cross hair using the current pen. This is a vertical and
-        horizontal line the height and width of the window, centred on the
-        given point.
+        Converts @e device Y coordinate to logical coordinate, using the current
+        mapping mode, user scale factor, device origin and axis orientation.
     */
-    void CrossHair(wxCoord x, wxCoord y);
+    wxCoord DeviceToLogicalY(wxCoord y) const;
 
     /**
-        Destroys the current clipping region so that none of the DC is clipped.
-
-        @see SetClippingRegion()
+        Convert @e device Y coordinate to relative logical coordinate, using the
+        current mapping mode and user scale factor but ignoring the
+        axis orientation. Use this for converting a height, for example.
     */
-    void DestroyClippingRegion();
+    wxCoord DeviceToLogicalYRel(wxCoord y) const;
 
     /**
-        Convert device X coordinate to logical coordinate, using the current
+        Converts logical X coordinate to device coordinate, using the current
         mapping mode, user scale factor, device origin and axis orientation.
     */
-    wxCoord DeviceToLogicalX(wxCoord x) const;
+    wxCoord LogicalToDeviceX(wxCoord x) const;
 
     /**
-        Convert device X coordinate to relative logical coordinate, using the
+        Converts logical X coordinate to relative device coordinate, using the
         current mapping mode and user scale factor but ignoring the
         axis orientation. Use this for converting a width, for example.
     */
-    wxCoord DeviceToLogicalXRel(wxCoord x) const;
+    wxCoord LogicalToDeviceXRel(wxCoord x) const;
 
     /**
-        Converts device Y coordinate to logical coordinate, using the current
+        Converts logical Y coordinate to device coordinate, using the current
         mapping mode, user scale factor, device origin and axis orientation.
     */
-    wxCoord DeviceToLogicalY(wxCoord y) const;
+    wxCoord LogicalToDeviceY(wxCoord y) const;
 
     /**
-        Convert device Y coordinate to relative logical coordinate, using the
+        Converts logical Y coordinate to relative device coordinate, using the
         current mapping mode and user scale factor but ignoring the
         axis orientation. Use this for converting a height, for example.
     */
-    wxCoord DeviceToLogicalYRel(wxCoord y) const;
+    wxCoord LogicalToDeviceYRel(wxCoord y) const;
+
+    //@}
+
+
+
+    /**
+        @name Drawing functions
+    */
+    //@{
+
+    /**
+        Clears the device context using the current background brush.
+    */
+    void Clear();
 
     /**
         Draws an arc of a circle, centred on (@a xc, @a yc), with starting
-        point (@a x1, @a y1) and ending at (@a x2, @a y2). The current pen is
-        used for the outline and the current brush for filling the shape.
+        point (@a xStart, @a yStart) and ending at (@a xEnd, @a yEnd). 
+        The current pen is used for the outline and the current brush for 
+        filling the shape.
 
         The arc is drawn in a counter-clockwise direction from the start point
         to the end point.
     */
-    void DrawArc(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
-                  wxCoord xc, wxCoord yc);
+    void DrawArc(wxCoord xStart, wxCoord yStart, wxCoord xEnd, wxCoord yEnd,
+                 wxCoord xc, wxCoord yc);
+
+    /**
+        @overload
+    */
+    void DrawArc(const wxPoint& ptStart, const wxPoint& ptEnd, const wxPoint& centre);
 
     /**
         Draw a bitmap on the device context at the specified point. If
@@ -203,25 +290,34 @@ public:
     void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y,
                     bool useMask = false);
 
-    //@{
+    /**
+        @overload
+    */
+    void DrawBitmap(const wxBitmap &bmp, const wxPoint& pt,
+                    bool useMask = false);
+
     /**
         Draws a check mark inside the given rectangle.
     */
     void DrawCheckMark(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
+
+    /**
+        @overload
+    */
     void DrawCheckMark(const wxRect& rect);
-    //@}
 
-    //@{
     /**
         Draws a circle with the given centre and radius.
 
         @see DrawEllipse()
     */
     void DrawCircle(wxCoord x, wxCoord y, wxCoord radius);
+
+    /**
+        @overload
+    */
     void DrawCircle(const wxPoint& pt, wxCoord radius);
-    //@}
 
-    //@{
     /**
         Draws an ellipse contained in the rectangle specified either with the
         given top left corner and the given size or directly. The current pen
@@ -230,9 +326,16 @@ public:
         @see DrawCircle()
     */
     void DrawEllipse(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
+
+    /**
+        @overload
+    */
     void DrawEllipse(const wxPoint& pt, const wxSize& size);
+
+    /**
+        @overload
+    */
     void DrawEllipse(const wxRect& rect);
-    //@}
 
     /**
         Draws an arc of an ellipse. The current pen is used for drawing the arc
@@ -253,6 +356,12 @@ public:
     void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height,
                           double start, double end);
 
+    /**
+        @overload
+    */
+    void DrawEllipticArc(const wxPoint& pt, const wxSize& sz,
+                         double sa, double ea);
+
     /**
         Draw an icon on the display (does nothing if the device context is
         PostScript). This can be the simplest way of drawing bitmaps on a
@@ -260,21 +369,28 @@ public:
     */
     void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);
 
-    //@{
+    /**
+        @overload
+    */
+    void DrawIcon(const wxIcon& icon, const wxPoint& pt);
+
     /**
         Draw optional bitmap and the text into the given rectangle and aligns
         it as specified by alignment parameter; it also will emphasize the
         character with the given index if it is != -1 and return the bounding
         rectangle if required.
     */
-    void DrawLabel(const wxString& text, const wxBitmap& image,
+    void DrawLabel(const wxString& text, const wxBitmap& bitmap,
                    const wxRect& rect,
                    int alignment = wxALIGN_LEFT | wxALIGN_TOP,
                    int indexAccel = -1, wxRect* rectBounding = NULL);
+
+    /**
+        @overload
+    */
     void DrawLabel(const wxString& text, const wxRect& rect,
                    int alignment = wxALIGN_LEFT | wxALIGN_TOP,
                    int indexAccel = -1);
-    //@}
 
     /**
         Draws a line from the first point to the second. The current pen is
@@ -284,14 +400,18 @@ public:
     */
     void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
 
+    /**
+        @overload
+    */
+    void DrawLine(const wxPoint& pt1, const wxPoint& pt2);
+
     /**
         Draws lines using an array of points of size @a n adding the optional
         offset coordinate. The current pen is used for drawing the lines.
 
-        @beginWxPythonOnly
-        The wxPython version of this method accepts a Python list of wxPoint
-        objects.
-        @endWxPythonOnly
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly
     */
     void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0,
                    wxCoord yoffset = 0);
@@ -300,10 +420,11 @@ public:
         coordinate. The programmer is responsible for deleting the list of
         points.
 
-        @beginWxPythonOnly
-        The wxPython version of this method accepts a Python list of wxPoint
-        objects.
-        @endWxPythonOnly
+        @beginWxPerlOnly
+        The wxPerl version of this method accepts
+        as its first parameter a reference to an array
+        of wxPoint objects.
+        @endWxPerlOnly
     */
     void DrawLines(const wxPointList* points,
                    wxCoord xoffset = 0, wxCoord yoffset = 0);
@@ -314,6 +435,11 @@ public:
     */
     void DrawPoint(wxCoord x, wxCoord y);
 
+    /**
+        @overload
+    */
+    void DrawPoint(const wxPoint& pt);
+
     /**
         Draws a filled polygon using an array of points of size @a n, adding
         the optional offset coordinate. The first and last points are
@@ -324,6 +450,10 @@ public:
 
         The current pen is used for drawing the outline, and the current brush
         for filling the shape. Using a transparent brush suppresses filling.
+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly
     */
     void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0,
                      wxCoord yoffset = 0,
@@ -341,10 +471,11 @@ public:
 
         The programmer is responsible for deleting the list of points.
 
-        @beginWxPythonOnly
-        The wxPython version of this method accepts a Python list of wxPoint
-        objects.
-        @endWxPythonOnly
+        @beginWxPerlOnly
+        The wxPerl version of this method accepts
+        as its first parameter a reference to an array
+        of wxPoint objects.
+        @endWxPerlOnly
     */
     void DrawPolygon(const wxPointList* points,
                      wxCoord xoffset = 0, wxCoord yoffset = 0,
@@ -372,10 +503,6 @@ public:
         call to DrawPolyPolygon() must be closed. Unlike polygons created by
         the DrawPolygon() member function, the polygons created by this
         method are not closed automatically.
-
-        @beginWxPythonOnly
-        Not implemented yet.
-        @endWxPythonOnly
     */
     void DrawPolyPolygon(int n, int count[], wxPoint points[],
                          wxCoord xoffset = 0, wxCoord yoffset = 0,
@@ -389,7 +516,18 @@ public:
     void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 
     /**
-        Draws the text rotated by @a angle degrees.
+        @overload
+    */
+    void DrawRectangle(const wxPoint& pt, const wxSize& sz);
+
+    /**
+        @overload
+    */
+    void DrawRectangle(const wxRect& rect);
+
+    /**
+        Draws the text rotated by @a angle degrees 
+        (positive angles are counterclockwise; the full angle is 360 degrees).
 
         @note Under Win9x only TrueType fonts can be drawn by this function. In
               particular, a font different from @c wxNORMAL_FONT should be used
@@ -401,6 +539,12 @@ public:
     void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y,
                          double angle);
 
+    /**
+        @overload
+    */
+    void DrawRotatedText(const wxString& text, const wxPoint& point,
+                         double angle);
+
     /**
         Draws a rectangle with the given top left corner, and with the given
         size. The corners are quarter-circles using the given radius. The
@@ -417,20 +561,48 @@ public:
     void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width,
                               wxCoord height, double radius);
 
-    //@{
+    /**
+        @overload
+    */
+    void DrawRoundedRectangle(const wxPoint& pt, const wxSize& sz,
+                              double radius);
+
+    /**
+        @overload
+    */
+    void DrawRoundedRectangle(const wxRect& rect, double radius);
+
     /**
         Draws a spline between all given points using the current pen.
 
-        @beginWxPythonOnly
-        The wxPython version of this method accepts a Python list of wxPoint
-        objects.
-        @endWxPythonOnly
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly
     */
     void DrawSpline(int n, wxPoint points[]);
+
+    /**
+        @overload
+
+
+        @beginWxPerlOnly
+        The wxPerl version of this method accepts
+        as its first parameter a reference to an array
+        of wxPoint objects.
+        @endWxPerlOnly
+    */
     void DrawSpline(const wxPointList* points);
+
+    /**
+        @overload
+
+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly
+    */
     void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
                     wxCoord x3, wxCoord y3);
-    //@}
 
     /**
         Draws a text string at the specified point, using the current text
@@ -438,7 +610,12 @@ public:
 
         The coordinates refer to the top-left corner of the rectangle bounding
         the string. See GetTextExtent() for how to get the dimensions of a text
-        string, which can be used to position the text more precisely.
+        string, which can be used to position the text more precisely and
+        DrawLabel() if you need to align the string differently.
+
+        Starting from wxWidgets 2.9.2 @a text parameter can be a multi-line
+        string, i.e. contain new line characters, and will be rendered
+        correctly.
 
         @note The current @ref GetLogicalFunction() "logical function" is
               ignored by this function.
@@ -446,112 +623,186 @@ public:
     void DrawText(const wxString& text, wxCoord x, wxCoord y);
 
     /**
-        Ends a document (only relevant when outputting to a printer).
+        @overload
     */
-    void EndDoc();
+    void DrawText(const wxString& text, const wxPoint& pt);
 
     /**
-        Ends a document page (only relevant when outputting to a printer).
+        Fill the area specified by rect with a radial gradient, starting from
+        @a initialColour at the centre of the circle and fading to
+        @a destColour on the circle outside.
+
+        The circle is placed at the centre of @a rect.
+
+        @note Currently this function is very slow, don't use it for real-time
+              drawing.
     */
-    void EndPage();
+    void GradientFillConcentric(const wxRect& rect,
+                                const wxColour& initialColour,
+                                const wxColour& destColour);
 
     /**
-        Flood fills the device context starting from the given point, using
-        the current brush colour, and using a style:
+        Fill the area specified by rect with a radial gradient, starting from
+        @a initialColour at the centre of the circle and fading to
+        @a destColour on the circle outside.
 
-        - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
-          given colour is encountered.
-        - wxFLOOD_BORDER: The area to be flooded is bounded by the given
-          colour.
+        @a circleCenter are the relative coordinates of centre of the circle in
+        the specified @a rect.
+
+        @note Currently this function is very slow, don't use it for real-time
+              drawing.
+    */
+    void GradientFillConcentric(const wxRect& rect,
+                                const wxColour& initialColour,
+                                const wxColour& destColour,
+                                const wxPoint& circleCenter);
+
+    /**
+        Fill the area specified by @a rect with a linear gradient, starting
+        from @a initialColour and eventually fading to @e destColour.
+
+        The @a nDirection specifies the direction of the colour change, default is
+        to use @a initialColour on the left part of the rectangle and
+        @a destColour on the right one.
+    */
+    void GradientFillLinear(const wxRect& rect, const wxColour& initialColour,
+                            const wxColour& destColour,
+                            wxDirection nDirection = wxRIGHT);
+
+    /**
+        Flood fills the device context starting from the given point, using
+        the current brush colour, and using a style:
+
+        - wxFLOOD_SURFACE: The flooding occurs until a colour other than the
+          given colour is encountered.
+        - wxFLOOD_BORDER: The area to be flooded is bounded by the given
+          colour.
 
         @return @false if the operation failed.
 
         @note The present implementation for non-Windows platforms may fail to
               find colour borders if the pixels do not match the colour
               exactly. However the function will still return @true.
+
+        @note This method shouldn't be used with wxPaintDC under non-Windows
+              platforms as it uses GetPixel() internally and this may give
+              wrong results, notably in wxGTK. If you need to flood fill
+              wxPaintDC, create a temporary wxMemoryDC, flood fill it and then
+              blit it to, or draw as a bitmap on, wxPaintDC. See the example of
+              doing this in the drawing sample and wxBufferedPaintDC class.
     */
     bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
                    wxFloodFillStyle style = wxFLOOD_SURFACE);
 
     /**
-        Gets the brush used for painting the background.
-
-        @see wxDC::SetBackground()
+        @overload
     */
-    const wxBrush& GetBackground() const;
+    bool FloodFill(const wxPoint& pt, const wxColour& col,
+                   wxFloodFillStyle style = wxFLOOD_SURFACE);
 
     /**
-        Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
-
-        @see SetBackgroundMode()
+        Displays a cross hair using the current pen. This is a vertical and
+        horizontal line the height and width of the window, centred on the
+        given point.
     */
-    int GetBackgroundMode() const;
+    void CrossHair(wxCoord x, wxCoord y);
 
     /**
-        Gets the current brush.
-
-        @see wxDC::SetBrush()
+        @overload
     */
-    const wxBrush& GetBrush() const;
+    void CrossHair(const wxPoint& pt);
+
+    //@}
+
 
     /**
-        Gets the character height of the currently set font.
+        @name Clipping region functions
     */
-    wxCoord GetCharHeight() const;
+    //@{
 
     /**
-        Gets the average character width of the currently set font.
+        Destroys the current clipping region so that none of the DC is clipped.
+
+        @see SetClippingRegion()
     */
-    wxCoord GetCharWidth() const;
+    void DestroyClippingRegion();
 
     /**
         Gets the rectangle surrounding the current clipping region.
-
-        @beginWxPythonOnly
-        No arguments are required and the four values defining the rectangle
-        are returned as a tuple.
-        @endWxPythonOnly
     */
     void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const;
 
     /**
-        Returns the depth (number of bits/pixel) of this DC.
+        Sets the clipping region for this device context to the intersection of
+        the given region described by the parameters of this method and the
+        previously set clipping region.
 
-        @see wxDisplayDepth()
+        The clipping region is an area to which drawing is restricted. Possible
+        uses for the clipping region are for clipping text or for speeding up
+        window redraws when only a known area of the screen is damaged.
+
+        Notice that you need to call DestroyClippingRegion() if you want to set
+        the clipping region exactly to the region specified.
+
+        Also note that if the clipping region is empty, any previously set
+        clipping region is destroyed, i.e. it is equivalent to calling
+        DestroyClippingRegion(), and not to clipping out all drawing on the DC
+        as might be expected.
+
+        @see DestroyClippingRegion(), wxRegion
     */
-    int GetDepth() const;
+    void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 
     /**
-        Gets the current font. Notice that even although each device context
-        object has some default font after creation, this method would return a
-        wxNullFont initially and only after calling SetFont() a valid font is
-        returned.
+        @overload
     */
-    const wxFont& GetFont() const;
+    void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
 
     /**
-        Gets the current layout direction of the device context. On platforms
-        where RTL layout is supported, the return value will either be
-        @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
-        not supported, the return value will be @c wxLayout_Default.
-
-        @see SetLayoutDirection()
+        @overload
     */
-    wxLayoutDirection GetLayoutDirection() const;
+    void SetClippingRegion(const wxRect& rect);
 
     /**
-        Gets the current logical function.
+        Sets the clipping region for this device context.
 
-        @see SetLogicalFunction()
+        Unlike SetClippingRegion(), this function works with physical
+        coordinates and not with the logical ones.
+     */
+    void SetDeviceClippingRegion(const wxRegion& region);
+
+    //@}
+
+
+    /**
+        @name Text/character extent functions
     */
-    wxRasterOperationMode GetLogicalFunction() const;
+    //@{
 
     /**
-        Gets the mapping mode for the device context.
+        Gets the character height of the currently set font.
+    */
+    wxCoord GetCharHeight() const;
 
-        @see SetMapMode()
+    /**
+        Gets the average character width of the currently set font.
     */
-    wxMappingMode GetMapMode() const;
+    wxCoord GetCharWidth() const;
+
+    /**
+        Returns the various font characteristics.
+
+        This method allows to retrieve some of the font characteristics not
+        returned by GetTextExtent(), notably internal leading and average
+        character width.
+
+        Currently this method returns correct results only under wxMSW, in the
+        other ports the internal leading will always be 0 and the average
+        character width will be computed as the width of the character 'x'.
+
+        @since 2.9.2
+     */
+    wxFontMetrics GetFontMetrics() const;
 
     /**
         Gets the dimensions of the string using the currently selected font.
@@ -566,6 +817,12 @@ public:
 
         @note This function works with both single-line and multi-line strings.
 
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as
+        GetMultiLineTextExtent(string, font = undef) returning a
+        3-element list (width, height, line_height)
+        @endWxPerlOnly
+
         @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
     */
     void GetMultiLineTextExtent(const wxString& string, wxCoord* w,
@@ -581,6 +838,10 @@ public:
 
         @note This function works with both single-line and multi-line strings.
 
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly
+
         @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
     */
     wxSize GetMultiLineTextExtent(const wxString& string) const;
@@ -593,10 +854,10 @@ public:
         function that is faster or more accurate than the generic
         implementation then it should be used instead.
 
-        @beginWxPythonOnly
-        This method only takes the @a text parameter and returns a Python list
-        of integers.
-        @endWxPythonOnly
+        @beginWxPerlOnly
+        In wxPerl this method only takes the @a text parameter and
+        returns the widths as a list of integers.
+        @endWxPerlOnly
 
         @see GetMultiLineTextExtent(), GetTextExtent()
     */
@@ -604,64 +865,78 @@ public:
                                wxArrayInt& widths) const;
 
     /**
-        Gets the current pen.
+        Gets the dimensions of the string using the currently selected font.
+        @a string is the text string to measure, @a descent is the dimension
+        from the baseline of the font to the bottom of the descender, and
+        @a externalLeading is any extra vertical space added to the font by the
+        font designer (usually is zero).
 
-        @see SetPen()
+        The text extent is returned in @a w and @a h pointers or as a wxSize
+        object depending on which version of this function is used.
+
+        If the optional parameter @a font is specified and valid, then it is
+        used for the text extent calculation. Otherwise the currently selected
+        font is.
+
+        @note This function only works with single-line strings.
+
+        @beginWxPerlOnly
+        In wxPerl this method is implemented as GetTextExtent(string,
+        font = undef) returning a 4-element list (width, height,
+        descent, externalLeading)
+        @endWxPerlOnly
+
+        @see wxFont, SetFont(), GetPartialTextExtents(),
+             GetMultiLineTextExtent()
     */
-    const wxPen& GetPen() const;
+    void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
+                       wxCoord* descent = NULL,
+                       wxCoord* externalLeading = NULL,
+                       const wxFont* font = NULL) const;
 
     /**
-        Gets in @a colour the colour at the specified location. Not available
-        for wxPostScriptDC or wxMetafileDC.
+        @overload
 
-        @note Setting a pixel can be done using DrawPoint().
 
-        @beginWxPythonOnly
-        The wxColour value is returned and is not required as a parameter.
-        @endWxPythonOnly
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly
     */
-    bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
+    wxSize GetTextExtent(const wxString& string) const;
+
+    //@}
+
 
     /**
-        Returns the resolution of the device in pixels per inch.
+        @name Text properties functions
     */
-    wxSize GetPPI() const;
-
     //@{
-    /**
-        This gets the horizontal and vertical resolution in device units. It
-        can be used to scale graphics to fit the page.
 
-        For example, if @e maxX and @e maxY represent the maximum horizontal
-        and vertical 'pixel' values used in your application, the following
-        code will scale the graphic to fit on the printer page:
+    /**
+        Returns the current background mode: @c wxSOLID or @c wxTRANSPARENT.
 
-        @code
-        wxCoord w, h;
-        dc.GetSize(&w, &h);
-        double scaleX = (double)(maxX / w);
-        double scaleY = (double)(maxY / h);
-        dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
-        @endcode
+        @see SetBackgroundMode()
+    */
+    int GetBackgroundMode() const;
 
-        @beginWxPythonOnly
-        In place of a single overloaded method name, wxPython implements the
-        following methods:
-        - GetSize() - Returns a wxSize.
-        - GetSizeWH() - Returns a 2-tuple (width, height).
-        @endWxPythonOnly
+    /**
+        Gets the current font. 
+        
+        Notice that even although each device context object has some default font 
+        after creation, this method would return a ::wxNullFont initially and only 
+        after calling SetFont() a valid font is returned.
     */
-    void GetSize(wxCoord* width, wxCoord* height) const;
-    wxSize GetSize() const;
-    //@}
+    const wxFont& GetFont() const;
 
-    //@{
     /**
-        Returns the horizontal and vertical resolution in millimetres.
+        Gets the current layout direction of the device context. On platforms
+        where RTL layout is supported, the return value will either be
+        @c wxLayout_LeftToRight or @c wxLayout_RightToLeft. If RTL layout is
+        not supported, the return value will be @c wxLayout_Default.
+
+        @see SetLayoutDirection()
     */
-    void GetSizeMM(wxCoord* width, wxCoord* height) const;
-    wxSize GetSizeMM() const;
-    //@}
+    wxLayoutDirection GetLayoutDirection() const;
 
     /**
         Gets the current text background colour.
@@ -670,145 +945,472 @@ public:
     */
     const wxColour& GetTextBackground() const;
 
-    //@{
     /**
-        Gets the dimensions of the string using the currently selected font.
-        @a string is the text string to measure, @a descent is the dimension
-        from the baseline of the font to the bottom of the descender, and
-        @a externalLeading is any extra vertical space added to the font by the
-        font designer (usually is zero).
+        Gets the current text foreground colour.
 
-        The text extent is returned in @a w and @a h pointers or as a wxSize
-        object depending on which version of this function is used.
+        @see SetTextForeground()
+    */
+    const wxColour& GetTextForeground() const;
 
-        If the optional parameter @a font is specified and valid, then it is
-        used for the text extent calculation. Otherwise the currently selected
-        font is.
+    /**
+        @a mode may be one of @c wxSOLID and @c wxTRANSPARENT. 
+        
+        This setting determines whether text will be drawn with a background 
+        colour or not.
+    */
+    void SetBackgroundMode(int mode);
 
-        @note This function only works with single-line strings.
+    /**
+        Sets the current font for the DC. 
 
-        @beginWxPythonOnly
-        The following methods are implemented in wxPython:
-        - GetTextExtent(string) - Returns a 2-tuple, (width, height).
-        - GetFullTextExtent(string, font=NULL) -
-            Returns a 4-tuple, (width, height, descent, externalLeading).
-        @endWxPythonOnly
+        If the argument is ::wxNullFont (or another invalid font; see wxFont::IsOk), 
+        the current font is selected out of the device context (leaving wxDC without 
+        any valid font), allowing the current font to be destroyed safely.
 
-        @see wxFont, SetFont(), GetPartialTextExtents(),
-             GetMultiLineTextExtent()
+        @see wxFont
     */
-    void GetTextExtent(const wxString& string, wxCoord* w, wxCoord* h,
-                       wxCoord* descent = NULL,
-                       wxCoord* externalLeading = NULL,
-                       const wxFont* font = NULL) const;
-    wxSize GetTextExtent(const wxString& string) const;
-    //@}
+    void SetFont(const wxFont& font);
 
     /**
-        Gets the current text foreground colour.
+        Sets the current text background colour for the DC.
+    */
+    void SetTextBackground(const wxColour& colour);
 
-        @see SetTextForeground()
+    /**
+        Sets the current text foreground colour for the DC.
+
+        @see wxMemoryDC for the interpretation of colours when drawing into a
+             monochrome bitmap.
     */
-    const wxColour& GetTextForeground() const;
+    void SetTextForeground(const wxColour& colour);
 
     /**
-        Gets the current user scale factor.
+        Sets the current layout direction for the device context. 
+        
+        @param dir 
+           May be either @c wxLayout_Default, @c wxLayout_LeftToRight or
+           @c wxLayout_RightToLeft.
 
-        @see SetUserScale()
+        @see GetLayoutDirection()
     */
-    void GetUserScale(double* x, double* y) const;
+    void SetLayoutDirection(wxLayoutDirection dir);
+
+    //@}
+
 
-    //@{
     /**
-        Fill the area specified by rect with a radial gradient, starting from
-        @a initialColour at the centre of the circle and fading to
-        @a destColour on the circle outside.
+        @name Bounding box functions
+    */
+    //@{
 
-        @a circleCenter are the relative coordinates of centre of the circle in
-        the specified @e rect. If not specified, the circle is placed at the
-        centre of rect.
+    /**
+        Adds the specified point to the bounding box which can be retrieved
+        with MinX(), MaxX() and MinY(), MaxY() functions.
 
-        @note Currently this function is very slow, don't use it for real-time
-              drawing.
+        @see ResetBoundingBox()
     */
-    void GradientFillConcentric(const wxRect& rect,
-                                const wxColour& initialColour,
-                                const wxColour& destColour);
-    void GradientFillConcentric(const wxRect& rect,
-                                const wxColour& initialColour,
-                                const wxColour& destColour,
-                                const wxPoint& circleCenter);
-    //@}
+    void CalcBoundingBox(wxCoord x, wxCoord y);
 
     /**
-        Fill the area specified by @a rect with a linear gradient, starting
-        from @a initialColour and eventually fading to @e destColour. The
-        @a nDirection specifies the direction of the colour change, default is
-        to use @a initialColour on the left part of the rectangle and
-        @a destColour on the right one.
+        Gets the maximum horizontal extent used in drawing commands so far.
     */
-    void GradientFillLinear(const wxRect& rect, const wxColour& initialColour,
-                            const wxColour& destColour,
-                            wxDirection nDirection = wxRIGHT);
+    wxCoord MaxX() const;
+
+    /**
+        Gets the maximum vertical extent used in drawing commands so far.
+    */
+    wxCoord MaxY() const;
+
+    /**
+        Gets the minimum horizontal extent used in drawing commands so far.
+    */
+    wxCoord MinX() const;
+
+    /**
+        Gets the minimum vertical extent used in drawing commands so far.
+    */
+    wxCoord MinY() const;
+
+    /**
+        Resets the bounding box: after a call to this function, the bounding
+        box doesn't contain anything.
+
+        @see CalcBoundingBox()
+    */
+    void ResetBoundingBox();
+
+    //@}
+
+
+    /**
+        @name Page and document start/end functions
+    */
+    //@{
+
+    /**
+        Starts a document (only relevant when outputting to a printer).
+        @a message is a message to show while printing.
+    */
+    bool StartDoc(const wxString& message);
+
+    /**
+        Starts a document page (only relevant when outputting to a printer).
+    */
+    void StartPage();
+
+    /**
+        Ends a document (only relevant when outputting to a printer).
+    */
+    void EndDoc();
+
+    /**
+        Ends a document page (only relevant when outputting to a printer).
+    */
+    void EndPage();
+
+    //@}
+
+
+    /**
+        @name Bit-Block Transfer operations (blit)
+    */
+    //@{
+
+    /**
+        Copy from a source DC to this DC.
+
+        With this method you can specify the destination coordinates and the
+        size of area to copy which will be the same for both the source and
+        target DCs. If you need to apply scaling while copying, use
+        StretchBlit().
+
+        Notice that source DC coordinates @a xsrc and @a ysrc are interpreted
+        using the current source DC coordinate system, i.e. the scale, origin
+        position and axis directions are taken into account when transforming
+        them to physical (pixel) coordinates.
+
+        @param xdest
+            Destination device context x position.
+        @param ydest
+            Destination device context y position.
+        @param width
+            Width of source area to be copied.
+        @param height
+            Height of source area to be copied.
+        @param source
+            Source device context.
+        @param xsrc
+            Source device context x position.
+        @param ysrc
+            Source device context y position.
+        @param logicalFunc
+            Logical function to use, see SetLogicalFunction().
+        @param useMask
+            If @true, Blit does a transparent blit using the mask that is
+            associated with the bitmap selected into the source device context.
+            The Windows implementation does the following if MaskBlt cannot be
+            used:
+            <ol>
+            <li>Creates a temporary bitmap and copies the destination area into
+                it.</li>
+            <li>Copies the source area into the temporary bitmap using the
+                specified logical function.</li>
+            <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
+                the mask bitmap with the temp bitmap with the foreground colour
+                set to WHITE and the bg colour set to BLACK.</li>
+            <li>Sets the unmasked area in the destination area to BLACK by
+                ANDing the mask bitmap with the destination area with the
+                foreground colour set to BLACK and the background colour set to
+                WHITE.</li>
+            <li>ORs the temporary bitmap with the destination area.</li>
+            <li>Deletes the temporary bitmap.</li>
+            </ol>
+            This sequence of operations ensures that the source's transparent
+            area need not be black, and logical functions are supported.
+            @n @b Note: on Windows, blitting with masks can be speeded up
+            considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
+            enabled. You can also influence whether MaskBlt or the explicit
+            mask blitting code above is used, by using wxSystemOptions and
+            setting the @c no-maskblt option to 1.
+        @param xsrcMask
+            Source x position on the mask. If both xsrcMask and ysrcMask are
+            @c -1, xsrc and ysrc will be assumed for the mask source position.
+            Currently only implemented on Windows.
+        @param ysrcMask
+            Source y position on the mask. If both xsrcMask and ysrcMask are
+            @c -1, xsrc and ysrc will be assumed for the mask source position.
+            Currently only implemented on Windows.
+
+        @remarks There is partial support for Blit() in wxPostScriptDC, under X.
+
+        @see StretchBlit(), wxMemoryDC, wxBitmap, wxMask
+    */
+    bool Blit(wxCoord xdest, wxCoord ydest, wxCoord width,
+              wxCoord height, wxDC* source, wxCoord xsrc, wxCoord ysrc,
+              wxRasterOperationMode logicalFunc = wxCOPY, bool useMask = false,
+              wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord);
+
+    /**
+        Copy from a source DC to this DC possibly changing the scale.
+
+        Unlike Blit(), this method allows to specify different source and
+        destination region sizes, meaning that it can stretch or shrink it
+        while copying. The same can be achieved by changing the scale of the
+        source or target DC but calling this method is simpler and can also be
+        more efficient if the platform provides a native implementation of it.
+
+        The meaning of its other parameters is the same as with Blit(), in
+        particular all source coordinates are interpreted using the source DC
+        coordinate system, i.e. are affected by its scale, origin translation
+        and axis direction.
+
+        @param xdest
+            Destination device context x position.
+        @param ydest
+            Destination device context y position.
+        @param dstWidth
+            Width of destination area.
+        @param dstHeight
+            Height of destination area.
+        @param source
+            Source device context.
+        @param xsrc
+            Source device context x position.
+        @param ysrc
+            Source device context y position.
+        @param srcWidth
+            Width of source area to be copied.
+        @param srcHeight
+            Height of source area to be copied.
+        @param logicalFunc
+            Logical function to use, see SetLogicalFunction().
+        @param useMask
+            If @true, Blit does a transparent blit using the mask that is
+            associated with the bitmap selected into the source device context.
+            The Windows implementation does the following if MaskBlt cannot be
+            used:
+            <ol>
+            <li>Creates a temporary bitmap and copies the destination area into
+                it.</li>
+            <li>Copies the source area into the temporary bitmap using the
+                specified logical function.</li>
+            <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
+                the mask bitmap with the temp bitmap with the foreground colour
+                set to WHITE and the bg colour set to BLACK.</li>
+            <li>Sets the unmasked area in the destination area to BLACK by
+                ANDing the mask bitmap with the destination area with the
+                foreground colour set to BLACK and the background colour set to
+                WHITE.</li>
+            <li>ORs the temporary bitmap with the destination area.</li>
+            <li>Deletes the temporary bitmap.</li>
+            </ol>
+            This sequence of operations ensures that the source's transparent
+            area need not be black, and logical functions are supported.
+            @n @b Note: on Windows, blitting with masks can be speeded up
+            considerably by compiling wxWidgets with the wxUSE_DC_CACHEING option
+            enabled. You can also influence whether MaskBlt or the explicit
+            mask blitting code above is used, by using wxSystemOptions and
+            setting the @c no-maskblt option to 1.
+        @param xsrcMask
+            Source x position on the mask. If both xsrcMask and ysrcMask are
+            wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
+            source position. Currently only implemented on Windows.
+        @param ysrcMask
+            Source y position on the mask. If both xsrcMask and ysrcMask are
+            wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
+            source position. Currently only implemented on Windows.
+
+        There is partial support for Blit() in wxPostScriptDC, under X.
+
+        See wxMemoryDC for typical usage.
+
+        @since 2.9.0
+
+        @see Blit(), wxMemoryDC, wxBitmap, wxMask
+    */
+    bool StretchBlit(wxCoord xdest, wxCoord ydest,
+                     wxCoord dstWidth, wxCoord dstHeight,
+                     wxDC* source, wxCoord xsrc, wxCoord ysrc,
+                     wxCoord srcWidth, wxCoord srcHeight,
+                     wxRasterOperationMode logicalFunc = wxCOPY,
+                     bool useMask = false,
+                     wxCoord xsrcMask = wxDefaultCoord,
+                     wxCoord ysrcMask = wxDefaultCoord);
+    //@}
+
+
+    /**
+        @name Background/foreground brush and pen
+    */
+    //@{
+
+    /**
+        Gets the brush used for painting the background.
+
+        @see wxDC::SetBackground()
+    */
+    const wxBrush& GetBackground() const;
+
+    /**
+        Gets the current brush.
+
+        @see wxDC::SetBrush()
+    */
+    const wxBrush& GetBrush() const;
+
+    /**
+        Gets the current pen.
+
+        @see SetPen()
+    */
+    const wxPen& GetPen() const;
+
+    /**
+        Sets the current background brush for the DC.
+    */
+    void SetBackground(const wxBrush& brush);
+
+    /**
+        Sets the current brush for the DC.
+
+        If the argument is ::wxNullBrush (or another invalid brush; see wxBrush::IsOk), 
+        the current brush is selected out of the device context (leaving wxDC without 
+        any valid brush), allowing the current brush to be destroyed safely.
+
+        @see wxBrush, wxMemoryDC (for the interpretation of colours when
+             drawing into a monochrome bitmap)
+    */
+    void SetBrush(const wxBrush& brush);
+
+    /**
+        Sets the current pen for the DC. 
+
+        If the argument is ::wxNullPen (or another invalid pen; see wxPen::IsOk), 
+        the current pen is selected out of the device context (leaving wxDC without any 
+        valid pen), allowing the current pen to be destroyed safely.
+
+        @see wxMemoryDC for the interpretation of colours when drawing into a
+             monochrome bitmap.
+    */
+    void SetPen(const wxPen& pen);
+
+    //@}
+
+
+    /**
+        Copy attributes from another DC.
+
+        The copied attributes currently are:
+            - Font
+            - Text foreground and background colours
+            - Background brush
+            - Layout direction
+
+        @param dc
+            A valid (i.e. its IsOk() must return @true) source device context.
+     */
+    void CopyAttributes(const wxDC& dc);
+
+    /**
+        Returns the depth (number of bits/pixel) of this DC.
+
+        @see wxDisplayDepth()
+    */
+    int GetDepth() const;
 
     /**
-        Returns @true if the DC is ok to use.
+        Returns the current device origin.
+
+        @see SetDeviceOrigin()
     */
-    bool IsOk() const;
+    wxPoint GetDeviceOrigin() const;
 
     /**
-        Converts logical X coordinate to device coordinate, using the current
-        mapping mode, user scale factor, device origin and axis orientation.
+        Gets the current logical function.
+
+        @see SetLogicalFunction()
     */
-    wxCoord LogicalToDeviceX(wxCoord x) const;
+    wxRasterOperationMode GetLogicalFunction() const;
 
     /**
-        Converts logical X coordinate to relative device coordinate, using the
-        current mapping mode and user scale factor but ignoring the
-        axis orientation. Use this for converting a width, for example.
+        Gets the current mapping mode for the device context.
+
+        @see SetMapMode()
     */
-    wxCoord LogicalToDeviceXRel(wxCoord x) const;
+    wxMappingMode GetMapMode() const;
 
     /**
-        Converts logical Y coordinate to device coordinate, using the current
-        mapping mode, user scale factor, device origin and axis orientation.
+        Gets in @a colour the colour at the specified location. Not available
+        for wxPostScriptDC or wxMetafileDC.
+
+        @note Setting a pixel can be done using DrawPoint().
+
+        @note This method shouldn't be used with wxPaintDC as accessing the DC
+        while drawing can result in unexpected results, notably in wxGTK.
     */
-    wxCoord LogicalToDeviceY(wxCoord y) const;
+    bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
 
     /**
-        Converts logical Y coordinate to relative device coordinate, using the
-        current mapping mode and user scale factor but ignoring the
-        axis orientation. Use this for converting a height, for example.
+        Returns the resolution of the device in pixels per inch.
     */
-    wxCoord LogicalToDeviceYRel(wxCoord y) const;
+    wxSize GetPPI() const;
 
     /**
-        Gets the maximum horizontal extent used in drawing commands so far.
+        Gets the horizontal and vertical extent of this device context in @e device units.
+        It can be used to scale graphics to fit the page.
+
+        For example, if @e maxX and @e maxY represent the maximum horizontal
+        and vertical 'pixel' values used in your application, the following
+        code will scale the graphic to fit on the printer page:
+
+        @code
+        wxCoord w, h;
+        dc.GetSize(&w, &h);
+        double scaleX = (double)(maxX / w);
+        double scaleY = (double)(maxY / h);
+        dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
+        @endcode
+
+        @beginWxPerlOnly
+        In wxPerl there are two methods instead of a single overloaded
+        method:
+        - GetSize(): returns a Wx::Size object.
+        - GetSizeWH(): returns a 2-element list (width, height).
+        @endWxPerlOnly
     */
-    wxCoord MaxX() const;
+    void GetSize(wxCoord* width, wxCoord* height) const;
 
     /**
-        Gets the maximum vertical extent used in drawing commands so far.
+        @overload
     */
-    wxCoord MaxY() const;
+    wxSize GetSize() const;
 
     /**
-        Gets the minimum horizontal extent used in drawing commands so far.
+        Returns the horizontal and vertical resolution in millimetres.
     */
-    wxCoord MinX() const;
+    void GetSizeMM(wxCoord* width, wxCoord* height) const;
 
     /**
-        Gets the minimum vertical extent used in drawing commands so far.
+        @overload
     */
-    wxCoord MinY() const;
+    wxSize GetSizeMM() const;
 
     /**
-        Resets the bounding box: after a call to this function, the bounding
-        box doesn't contain anything.
+        Gets the current user scale factor.
 
-        @see CalcBoundingBox()
+        @beginWxPerlOnly
+        In wxPerl this method takes no arguments and return a two
+        element array (x, y).
+        @endWxPerlOnly
+
+        @see SetUserScale()
     */
-    void ResetBoundingBox();
+    void GetUserScale(double* x, double* y) const;
+
+    /**
+        Returns @true if the DC is ok to use.
+    */
+    bool IsOk() const;
 
     /**
         Sets the x and y axis orientation (i.e., the direction from lowest to
@@ -824,56 +1426,6 @@ public:
     */
     void SetAxisOrientation(bool xLeftRight, bool yBottomUp);
 
-    /**
-        Sets the current background brush for the DC.
-    */
-    void SetBackground(const wxBrush& brush);
-
-    /**
-        @a mode may be one of wxSOLID and wxTRANSPARENT. This setting
-        determines whether text will be drawn with a background colour or not.
-    */
-    void SetBackgroundMode(int mode);
-
-    /**
-        Sets the current brush for the DC.
-
-        If the argument is wxNullBrush, the current brush is selected out of
-        the device context (leaving wxDC without any valid brush), allowing the
-        current brush to be destroyed safely.
-
-        @see wxBrush, wxMemoryDC (for the interpretation of colours when
-             drawing into a monochrome bitmap)
-    */
-    void SetBrush(const wxBrush& brush);
-
-    //@{
-    /**
-        Sets the clipping region for this device context to the intersection of
-        the given region described by the parameters of this method and the
-        previously set clipping region. You should call DestroyClippingRegion()
-        if you want to set the clipping region exactly to the region specified.
-
-        The clipping region is an area to which drawing is restricted. Possible
-        uses for the clipping region are for clipping text or for speeding up
-        window redraws when only a known area of the screen is damaged.
-
-        @see DestroyClippingRegion(), wxRegion
-    */
-    void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width,
-                           wxCoord height);
-    void SetClippingRegion(const wxPoint& pt, const wxSize& sz);
-    void SetClippingRegion(const wxRect& rect);
-    //@}
-
-    /**
-        Sets the clipping region for this device context.
-
-        Unlike SetClippingRegion(), this function works with physical
-        coordinates and not with the logical ones.
-     */
-    void SetDeviceClippingRegion(const wxRegion& region);
-
     /**
         Sets the device origin (i.e., the origin in pixels after scaling has
         been applied). This function may be useful in Windows printing
@@ -882,63 +1434,27 @@ public:
     void SetDeviceOrigin(wxCoord x, wxCoord y);
 
     /**
-        Sets the current font for the DC. It must be a valid font, in
-        particular you should not pass wxNullFont to this method.
-
-        @see wxFont
-    */
-    void SetFont(const wxFont& font);
-
-    /**
-        Sets the current layout direction for the device context. @a dir may be
-        either @c wxLayout_Default, @c wxLayout_LeftToRight or
-        @c wxLayout_RightToLeft.
-
-        @see GetLayoutDirection()
-    */
-    void SetLayoutDirection(wxLayoutDirection dir);
-
-    /**
-        Sets the current logical function for the device context. This
-        determines how a source pixel (from a pen or brush colour, or source
-        device context if using Blit()) combines with a destination pixel in
+        Sets the current logical function for the device context.
+        It determines how a @e source pixel (from a pen or brush colour, or source
+        device context if using Blit()) combines with a @e destination pixel in
         the current device context.
         Text drawing is not affected by this function.
 
-        The possible values and their meaning in terms of source and
-        destination pixel values are as follows:
-
-        @verbatim
-        wxAND           src AND dst
-        wxAND_INVERT    (NOT src) AND dst
-        wxAND_REVERSE   src AND (NOT dst)
-        wxCLEAR         0
-        wxCOPY          src
-        wxEQUIV         (NOT src) XOR dst
-        wxINVERT        NOT dst
-        wxNAND          (NOT src) OR (NOT dst)
-        wxNOR           (NOT src) AND (NOT dst)
-        wxNO_OP         dst
-        wxOR            src OR dst
-        wxOR_INVERT     (NOT src) OR dst
-        wxOR_REVERSE    src OR (NOT dst)
-        wxSET           1
-        wxSRC_INVERT    NOT src
-        wxXOR           src XOR dst
-        @endverbatim
-
-        The default is wxCOPY, which simply draws with the current colour. The
-        others combine the current colour and the background using a logical
-        operation. wxINVERT is commonly used for drawing rubber bands or moving
+        See ::wxRasterOperationMode enumeration values for more info.
+
+        The default is @c wxCOPY, which simply draws with the current colour.
+        The others combine the current colour and the background using a logical
+        operation. @c wxINVERT is commonly used for drawing rubber bands or moving
         outlines, since drawing twice reverts to the original colour.
     */
     void SetLogicalFunction(wxRasterOperationMode function);
 
     /**
         The mapping mode of the device context defines the unit of measurement
-        used to convert logical units to device units. Note that in X, text
-        drawing isn't handled consistently with the mapping mode; a font is
-        always specified in point size. However, setting the user scale (see
+        used to convert @e logical units to @e device units.
+
+        Note that in X, text drawing isn't handled consistently with the mapping mode;
+        a font is always specified in point size. However, setting the user scale (see
         SetUserScale()) scales the text appropriately. In Windows, scalable
         TrueType fonts are always used; in X, results depend on availability of
         fonts, but usually a reasonable match is found.
@@ -947,21 +1463,13 @@ public:
 
         Drawing to a Windows printer device context uses the current mapping
         mode, but mapping mode is currently ignored for PostScript output.
-
-        The mapping mode can be one of the following:
-        - wxMM_TWIPS: Each logical unit is 1/20 of a point, or 1/1440 of an
-          inch.
-        - wxMM_POINTS: Each logical unit is a point, or 1/72 of an inch.
-        - wxMM_METRIC: Each logical unit is 1 mm.
-        - wxMM_LOMETRIC: Each logical unit is 1/10 of a mm.
-        - wxMM_TEXT: Each logical unit is 1 device pixel.
     */
     void SetMapMode(wxMappingMode mode);
 
     /**
         If this is a window DC or memory DC, assigns the given palette to the
         window or bitmap associated with the DC. If the argument is
-        wxNullPalette, the current palette is selected out of the device
+        ::wxNullPalette, the current palette is selected out of the device
         context, and the original palette restored.
 
         @see wxPalette
@@ -969,125 +1477,109 @@ public:
     void SetPalette(const wxPalette& palette);
 
     /**
-        Sets the current pen for the DC. If the argument is wxNullPen, the
-        current pen is selected out of the device context (leaving wxDC without
-        any valid pen), allowing the current brush to be destroyed safely.
+        Sets the user scaling factor, useful for applications which require
+        'zooming'.
+    */
+    void SetUserScale(double xScale, double yScale);
+
+
+    /**
+        @name Transformation matrix
 
-        @see wxMemoryDC for the interpretation of colours when drawing into a
-             monochrome bitmap.
+        See the notes about the availability of these functions in the class
+        documentation.
     */
-    void SetPen(const wxPen& pen);
+    //@{
 
     /**
-        Sets the current text background colour for the DC.
+        Check if the use of transformation matrix is supported by the current
+        system.
+
+        Currently this function always returns @false for non-MSW platforms and
+        may return @false for old (Windows 9x/ME) Windows systems. Normally
+        support for the transformation matrix is always available in any
+        relatively recent Windows versions.
+
+        @since 2.9.2
     */
-    void SetTextBackground(const wxColour& colour);
+    bool CanUseTransformMatrix() const;
 
     /**
-        Sets the current text foreground colour for the DC.
+        Set the transformation matrix.
 
-        @see wxMemoryDC for the interpretation of colours when drawing into a
-             monochrome bitmap.
+        If transformation matrix is supported on the current system, the
+        specified @a matrix will be used to transform between wxDC and physical
+        coordinates. Otherwise the function returns @false and doesn't change
+        the coordinate mapping.
+
+        @since 2.9.2
     */
-    void SetTextForeground(const wxColour& colour);
+    bool SetTransformMatrix(const wxAffineMatrix2D& matrix);
 
     /**
-        Sets the user scaling factor, useful for applications which require
-        'zooming'.
+        Return the transformation matrix used by this device context.
+
+        By default the transformation matrix is the identity matrix.
+
+        @since 2.9.2
     */
-    void SetUserScale(double xScale, double yScale);
+    wxAffineMatrix2D GetTransformMatrix() const;
 
     /**
-        Starts a document (only relevant when outputting to a printer).
-        @a message is a message to show while printing.
+        Revert the transformation matrix to identity matrix.
+
+        @since 2.9.2
     */
-    bool StartDoc(const wxString& message);
+    void ResetTransformMatrix();
 
+    //@}
+
+    
     /**
-        Starts a document page (only relevant when outputting to a printer).
+        @name query capabilities
     */
-    void StartPage();
+    //@{
 
     /**
-        Copy from a source DC to this DC, specifying the destination
-        coordinates, destination size, source DC, source coordinates, size of
-        source area to copy, logical function, whether to use a bitmap mask,
-        and mask source position.
+       Does the DC support drawing bitmaps?
+    */
+    bool CanDrawBitmap() const;
 
-        @param xdest
-            Destination device context x position.
-        @param ydest
-            Destination device context y position.
-        @param dstWidth
-            Width of destination area.
-        @param dstHeight
-            Height of destination area.
-        @param source
-            Source device context.
-        @param xsrc
-            Source device context x position.
-        @param ysrc
-            Source device context y position.
-        @param srcWidth
-            Width of source area to be copied.
-        @param srcHeight
-            Height of source area to be copied.
-        @param logicalFunc
-            Logical function to use, see SetLogicalFunction().
-        @param useMask
-            If @true, Blit does a transparent blit using the mask that is
-            associated with the bitmap selected into the source device context.
-            The Windows implementation does the following if MaskBlt cannot be
-            used:
-            <ol>
-            <li>Creates a temporary bitmap and copies the destination area into
-                it.</li>
-            <li>Copies the source area into the temporary bitmap using the
-                specified logical function.</li>
-            <li>Sets the masked area in the temporary bitmap to BLACK by ANDing
-                the mask bitmap with the temp bitmap with the foreground colour
-                set to WHITE and the bg colour set to BLACK.</li>
-            <li>Sets the unmasked area in the destination area to BLACK by
-                ANDing the mask bitmap with the destination area with the
-                foreground colour set to BLACK and the background colour set to
-                WHITE.</li>
-            <li>ORs the temporary bitmap with the destination area.</li>
-            <li>Deletes the temporary bitmap.</li>
-            </ol>
-            This sequence of operations ensures that the source's transparent
-            area need not be black, and logical functions are supported.
-            @n @b Note: on Windows, blitting with masks can be speeded up
-            considerably by compiling wxWidgets with the wxUSE_DC_CACHE option
-            enabled. You can also influence whether MaskBlt or the explicit
-            mask blitting code above is used, by using wxSystemOptions and
-            setting the @c no-maskblt option to 1.
-        @param xsrcMask
-            Source x position on the mask. If both xsrcMask and ysrcMask are
-            wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
-            source position. Currently only implemented on Windows.
-        @param ysrcMask
-            Source y position on the mask. If both xsrcMask and ysrcMask are
-            wxDefaultCoord, @a xsrc and @a ysrc will be assumed for the mask
-            source position. Currently only implemented on Windows.
+    /**
+       Does the DC supoprt calculating the size required to draw text?
+    */
+    bool CanGetTextExtent() const;
+    
+    //@}
 
-        There is partial support for Blit() in wxPostScriptDC, under X.
+    /**
+       Returns a value that can be used as a handle to the native drawing
+       context, if this wxDC has something that could be thought of in that
+       way.  (Not all of them do.)
 
-        StretchBlit() is only implemented under wxMAC and wxMSW.
+       For example, on Windows the return value is an HDC, on OSX it is a
+       CGContextRef and on wxGTK it will be a GdkDrawable.  If the DC is a
+       wxGCDC then the return value will be the value returned from
+       wxGraphicsContext::GetNativeContext.  A value of NULL is returned if
+       the DC does not have anything that fits the handle concept.
+       
+       @since 2.9.5
+     */
+    void* GetHandle() const;
 
-        See wxMemoryDC for typical usage.
+    
+    /**
+       If supported by the platform and the type of DC, fetch the contents of the DC, or a subset of it, as a bitmap.
+    */
+    wxBitmap GetAsBitmap(const wxRect *subrect = NULL) const;
 
-        @since 2.9.0
 
-        @see Blit(), wxMemoryDC, wxBitmap, wxMask
-    */
-    bool StretchBlit(wxCoord xdest, wxCoord ydest,
-                     wxCoord dstWidth, wxCoord dstHeight,
-                     wxDC* source, wxCoord xsrc, wxCoord ysrc,
-                     wxCoord srcWidth, wxCoord srcHeight,
-                     wxRasterOperationMode logicalFunc = wxCOPY,
-                     bool useMask = false,
-                     wxCoord xsrcMask = wxDefaultCoord,
-                     wxCoord ysrcMask = wxDefaultCoord);
+    void SetLogicalScale(double x, double y);
+    void GetLogicalScale(double *x, double *y) const;
+    void SetLogicalOrigin(wxCoord x, wxCoord y);
+    void GetLogicalOrigin(wxCoord *x, wxCoord *y) const;
+    wxPoint GetLogicalOrigin() const;
+    
 };
 
 
@@ -1095,10 +1587,12 @@ public:
 /**
     @class wxDCClipper
 
-    wxDCClipper is a small helper class for setting a clipping region on a wxDC
-    and unsetting it automatically. An object of wxDCClipper class is typically
-    created on the stack so that it is automatically destroyed when the object
-    goes out of scope. A typical usage example:
+    wxDCClipper is a helper class for setting a clipping region on a wxDC
+    during its lifetime.
+
+    An object of wxDCClipper class is typically created on the stack so that it
+    is automatically destroyed when the object goes out of scope. A typical
+    usage example:
 
     @code
     void MyFunction(wxDC& dc)
@@ -1115,6 +1609,12 @@ public:
     }
     @endcode
 
+    @note Unlike other similar classes such as wxDCFontChanger, wxDCClipper
+        currently doesn't restore the previously active clipping region when it
+        is destroyed but simply resets clipping on the associated wxDC. This
+        may be changed in the future wxWidgets versions but has to be taken
+        into account explicitly in the current one.
+
     @library{wxcore}
     @category{gdi}
 
@@ -1130,7 +1630,7 @@ public:
 
         The clipping region is automatically unset when this object is destroyed.
     */
-    wxDCClipper(wxDC& dc, const wxRegion& r);
+    wxDCClipper(wxDC& dc, const wxRegion& region);
     wxDCClipper(wxDC& dc, const wxRect& rect);
     wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h);
     //@}
@@ -1223,6 +1723,16 @@ public:
 class wxDCTextColourChanger
 {
 public:
+    /**
+        Trivial constructor not changing anything.
+
+        This constructor is useful if you don't know beforehand if the colour
+        needs to be changed or not. It simply creates the object which won't do
+        anything in its destructor unless Set() is called -- in which case it
+        would reset the previous colour.
+     */
+    wxDCTextColourChanger(wxDC& dc);
+
     /**
         Sets @a col on the given @a dc, storing the old one.
 
@@ -1233,6 +1743,17 @@ public:
     */
     wxDCTextColourChanger(wxDC& dc, const wxColour& col);
 
+    /**
+        Set the colour to use.
+
+        This method is meant to be called once only and only on the objects
+        created with the constructor overload not taking wxColour argument and
+        has the same effect as the other constructor, i.e. sets the colour to
+        the given @a col and ensures that the old value is restored when this
+        object is destroyed.
+     */
+    void Set(const wxColour& col);
+
     /**
         Restores the colour originally selected in the DC passed to the ctor.
     */
@@ -1258,6 +1779,18 @@ public:
 class wxDCFontChanger
 {
 public:
+    /**
+        Trivial constructor not changing anything.
+
+        This constructor is useful if you don't know beforehand if the font
+        needs to be changed or not. It simply creates the object which won't do
+        anything in its destructor unless Set() is called -- in which case it
+        would reset the previous font.
+
+        @since 2.9.1
+     */
+    wxDCFontChanger(wxDC& dc);
+
     /**
         Sets @a font on the given @a dc, storing the old one.
 
@@ -1269,7 +1802,18 @@ public:
     wxDCFontChanger(wxDC& dc, const wxFont& font);
 
     /**
-        Restores the colour originally selected in the DC passed to the ctor.
+        Set the font to use.
+
+        This method is meant to be called once only and only on the objects
+        created with the constructor overload not taking wxColour argument and
+        has the same effect as the other constructor, i.e. sets the font to
+        the given @a font and ensures that the old value is restored when this
+        object is destroyed.
+     */
+    void Set(const wxFont& font);
+
+    /**
+        Restores the font originally selected in the DC passed to the ctor.
     */
     ~wxDCFontChanger();
 };