synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / dc.h

diff --git a/interface/wx/dc.h b/interface/wx/dc.h
index 67542826eefda3c09d2112bde7db8d6251a1846b..e8e54c4526b5ed802068857c390996dff24d4248 100644 (file)
--- a/interface/wx/dc.h
+++ b/interface/wx/dc.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxDC
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxDC
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -79,6 +79,28 @@ enum wxMappingMode
     wxMM_POINTS
 };
 
     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".
+};

 
 
 /**
 
 
 /**


@@ -91,7 +113,7 @@ enum wxMappingMode
     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
     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
 
     wxDC is an abstract base class and cannot be created directly.
     Use wxPaintDC, wxClientDC, wxWindowDC, wxScreenDC, wxMemoryDC or


@@ -121,7 +143,7 @@ enum wxMappingMode
     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).
 
     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 explicitely
+    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).
 
     stated. Logical units are arbitrary units mapped to device units using
     the current mapping mode (see wxDC::SetMapMode).
 


@@ -131,9 +153,25 @@ enum wxMappingMode
 
     @section dc_alpha_support Support for Transparency / Alpha Channel
 
 
     @section dc_alpha_support Support for Transparency / Alpha Channel
 

-    On Mac OS X colours with alpha channel are supported. Instances of wxPen
-    or wxBrush that are built from wxColour use the colour's alpha values
-    when stroking or filling.
+    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}
 
 
     @library{wxcore}


@@ -222,15 +260,21 @@ public:
 
     /**
         Draws an arc of a circle, centred on (@a xc, @a yc), with starting
 
     /**
         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.
     */
 
         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,
+    void DrawArc(wxCoord xStart, wxCoord yStart, wxCoord xEnd, wxCoord yEnd,

                  wxCoord xc, wxCoord yc);
 
                  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
         @a transparent is @true and the bitmap has a transparency mask, the
     /**
         Draw a bitmap on the device context at the specified point. If
         @a transparent is @true and the bitmap has a transparency mask, the


@@ -246,6 +290,12 @@ public:
     void DrawBitmap(const wxBitmap& bitmap, wxCoord x, wxCoord y,
                     bool useMask = false);
 
     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.
     */
     /**
         Draws a check mark inside the given rectangle.
     */


@@ -306,6 +356,12 @@ public:
     void DrawEllipticArc(wxCoord x, wxCoord y, wxCoord width, wxCoord height,
                           double start, double end);
 
     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
     /**
         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


@@ -313,13 +369,18 @@ public:
     */
     void DrawIcon(const wxIcon& icon, wxCoord x, wxCoord y);
 
     */
     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.
     */
     /**
         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);
                    const wxRect& rect,
                    int alignment = wxALIGN_LEFT | wxALIGN_TOP,
                    int indexAccel = -1, wxRect* rectBounding = NULL);


@@ -339,14 +400,18 @@ public:
     */
     void DrawLine(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2);
 
     */
     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.
 
     /**
         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);
     */
     void DrawLines(int n, wxPoint points[], wxCoord xoffset = 0,
                    wxCoord yoffset = 0);


@@ -355,10 +420,11 @@ public:
         coordinate. The programmer is responsible for deleting the list of
         points.
 
         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);
     */
     void DrawLines(const wxPointList* points,
                    wxCoord xoffset = 0, wxCoord yoffset = 0);


@@ -369,6 +435,11 @@ public:
     */
     void DrawPoint(wxCoord x, wxCoord y);
 
     */
     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
     /**
         Draws a filled polygon using an array of points of size @a n, adding
         the optional offset coordinate. The first and last points are


@@ -379,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.
 
         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,
     */
     void DrawPolygon(int n, wxPoint points[], wxCoord xoffset = 0,
                      wxCoord yoffset = 0,


@@ -396,10 +471,11 @@ public:
 
         The programmer is responsible for deleting the list of points.
 
 
         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,
     */
     void DrawPolygon(const wxPointList* points,
                      wxCoord xoffset = 0, wxCoord yoffset = 0,


@@ -427,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.
         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,
     */
     void DrawPolyPolygon(int n, int count[], wxPoint points[],
                          wxCoord xoffset = 0, wxCoord yoffset = 0,


@@ -443,6 +515,16 @@ public:
     */
     void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 
     */
     void DrawRectangle(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
 

+    /**
+        @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).
     /**
         Draws the text rotated by @a angle degrees 
         (positive angles are counterclockwise; the full angle is 360 degrees).


@@ -457,6 +539,12 @@ public:
     void DrawRotatedText(const wxString& text, wxCoord x, wxCoord y,
                          double angle);
 
     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
     /**
         Draws a rectangle with the given top left corner, and with the given
         size. The corners are quarter-circles using the given radius. The


@@ -473,23 +561,45 @@ public:
     void DrawRoundedRectangle(wxCoord x, wxCoord y, wxCoord width,
                               wxCoord height, double radius);
 
     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.
 
     /**
         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
     */
     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
     */
     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);
     */
     void DrawSpline(wxCoord x1, wxCoord y1, wxCoord x2, wxCoord y2,
                     wxCoord x3, wxCoord y3);


@@ -500,13 +610,23 @@ 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
 
         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.
     */
     void DrawText(const wxString& text, wxCoord x, wxCoord y);
 
 
         @note The current @ref GetLogicalFunction() "logical function" is
               ignored by this function.
     */
     void DrawText(const wxString& text, wxCoord x, wxCoord y);
 

+    /**
+        @overload
+    */
+    void DrawText(const wxString& text, const wxPoint& pt);
+

     /**
         Fill the area specified by rect with a radial gradient, starting from
         @a initialColour at the centre of the circle and fading to
     /**
         Fill the area specified by rect with a radial gradient, starting from
         @a initialColour at the centre of the circle and fading to


@@ -563,10 +683,23 @@ public:
         @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 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);
 
     */
     bool FloodFill(wxCoord x, wxCoord y, const wxColour& colour,
                    wxFloodFillStyle style = wxFLOOD_SURFACE);
 

+    /**
+        @overload
+    */
+    bool FloodFill(const wxPoint& pt, const wxColour& col,
+                   wxFloodFillStyle style = wxFLOOD_SURFACE);
+

     /**
         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
     /**
         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


@@ -574,6 +707,11 @@ public:
     */
     void CrossHair(wxCoord x, wxCoord y);
 
     */
     void CrossHair(wxCoord x, wxCoord y);
 

+    /**
+        @overload
+    */
+    void CrossHair(const wxPoint& pt);
+

     //@}
 
 
     //@}
 
 


@@ -591,24 +729,26 @@ public:
 
     /**
         Gets the rectangle surrounding the current clipping region.
 
     /**
         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;
 
     /**
         Sets the clipping region for this device context to the intersection of
         the given region described by the parameters of this method and the
     */
     void GetClippingBox(wxCoord *x, wxCoord *y, wxCoord *width, wxCoord *height) const;
 
     /**
         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.
+        previously set clipping region.

 
         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.
 
 
         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
     */
     void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);
         @see DestroyClippingRegion(), wxRegion
     */
     void SetClippingRegion(wxCoord x, wxCoord y, wxCoord width, wxCoord height);


@@ -649,6 +789,21 @@ public:
     */
     wxCoord GetCharWidth() 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.
         @a string is the text string to measure, @e heightLine, if non @NULL,
     /**
         Gets the dimensions of the string using the currently selected font.
         @a string is the text string to measure, @e heightLine, if non @NULL,


@@ -662,6 +817,12 @@ public:
 
         @note This function works with both single-line and multi-line strings.
 
 
         @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,
         @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
     */
     void GetMultiLineTextExtent(const wxString& string, wxCoord* w,


@@ -677,6 +838,10 @@ public:
 
         @note This function works with both single-line and multi-line strings.
 
 
         @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;
         @see wxFont, SetFont(), GetPartialTextExtents(), GetTextExtent()
     */
     wxSize GetMultiLineTextExtent(const wxString& string) const;


@@ -689,10 +854,10 @@ public:
         function that is faster or more accurate than the generic
         implementation then it should be used instead.
 
         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()
     */
 
         @see GetMultiLineTextExtent(), GetTextExtent()
     */


@@ -715,12 +880,11 @@ public:
 
         @note This function only works with single-line strings.
 
 
         @note This function only works with single-line strings.
 

-        @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
+        @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()
 
         @see wxFont, SetFont(), GetPartialTextExtents(),
              GetMultiLineTextExtent()


@@ -732,6 +896,11 @@ public:
 
     /**
         @overload
 
     /**
         @overload

+
+
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly

     */
     wxSize GetTextExtent(const wxString& string) const;
 
     */
     wxSize GetTextExtent(const wxString& string) const;
 


@@ -751,10 +920,11 @@ public:
     int GetBackgroundMode() const;
 
     /**
     int GetBackgroundMode() const;
 
     /**

-        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.
+        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.

     */
     const wxFont& GetFont() const;
 
     */
     const wxFont& GetFont() const;
 


@@ -783,14 +953,19 @@ public:
     const wxColour& GetTextForeground() const;
 
     /**
     const wxColour& GetTextForeground() const;
 
     /**

-        @a mode may be one of wxSOLID and wxTRANSPARENT. This setting
-        determines whether text will be drawn with a background colour or not.
+        @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);
 
     /**
     */
     void SetBackgroundMode(int mode);
 
     /**

-        Sets the current font for the DC. It must be a valid font, in
-        particular you should not pass wxNullFont to this method.
+        Sets the current font for the DC. 
+
+        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
     */
 
         @see wxFont
     */


@@ -810,9 +985,11 @@ public:
     void SetTextForeground(const wxColour& colour);
 
     /**
     void SetTextForeground(const wxColour& colour);
 
     /**

-        Sets the current layout direction for the device context. @a dir may be
-        either @c wxLayout_Default, @c wxLayout_LeftToRight or
-        @c wxLayout_RightToLeft.
+        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 GetLayoutDirection()
     */
 
         @see GetLayoutDirection()
     */


@@ -900,10 +1077,17 @@ 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.
+        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 xdest
             Destination device context x position.


@@ -944,7 +1128,7 @@ public:
             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
             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
+            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.
             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.


@@ -967,10 +1151,18 @@ public:
               wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord);
 
     /**
               wxCoord xsrcMask = wxDefaultCoord, wxCoord ysrcMask = wxDefaultCoord);
 
     /**

-        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.
+        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 xdest
             Destination device context x position.


@@ -1015,7 +1207,7 @@ public:
             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
             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
+            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.
             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.


@@ -1030,8 +1222,6 @@ public:
 
         There is partial support for Blit() in wxPostScriptDC, under X.
 
 
         There is partial support for Blit() in wxPostScriptDC, under X.
 

-        StretchBlit() is only implemented under wxMAC and wxMSW.
-

         See wxMemoryDC for typical usage.
 
         @since 2.9.0
         See wxMemoryDC for typical usage.
 
         @since 2.9.0


@@ -1083,9 +1273,9 @@ public:
     /**
         Sets the current brush for the DC.
 
     /**
         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.
+        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)
 
         @see wxBrush, wxMemoryDC (for the interpretation of colours when
              drawing into a monochrome bitmap)


@@ -1093,9 +1283,11 @@ public:
     void SetBrush(const wxBrush& brush);
 
     /**
     void SetBrush(const wxBrush& brush);
 
     /**

-        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 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.
 
         @see wxMemoryDC for the interpretation of colours when drawing into a
              monochrome bitmap.


@@ -1105,6 +1297,19 @@ public:
     //@}
 
 
     //@}
 
 

+    /**
+        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.
 
     /**
         Returns the depth (number of bits/pixel) of this DC.


@@ -1140,9 +1345,8 @@ public:
 
         @note Setting a pixel can be done using DrawPoint().
 
 
         @note Setting a pixel can be done using DrawPoint().
 

-        @beginWxPythonOnly
-        The wxColour value is returned and is not required as a parameter.
-        @endWxPythonOnly
+        @note This method shouldn't be used with wxPaintDC as accessing the DC
+        while drawing can result in unexpected results, notably in wxGTK.

     */
     bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
 
     */
     bool GetPixel(wxCoord x, wxCoord y, wxColour* colour) const;
 


@@ -1167,12 +1371,12 @@ public:
         dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
         @endcode
 
         dc.SetUserScale(min(scaleX, scaleY),min(scaleX, scaleY));
         @endcode
 

-        @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
+        @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

     */
     void GetSize(wxCoord* width, wxCoord* height) const;
 
     */
     void GetSize(wxCoord* width, wxCoord* height) const;
 


@@ -1194,6 +1398,11 @@ public:
     /**
         Gets the current user scale factor.
 
     /**
         Gets the current user scale factor.
 

+        @beginWxPerlOnly
+        In wxPerl this method takes no arguments and return a two
+        element array (x, y).
+        @endWxPerlOnly
+

         @see SetUserScale()
     */
     void GetUserScale(double* x, double* y) const;
         @see SetUserScale()
     */
     void GetUserScale(double* x, double* y) const;


@@ -1272,6 +1481,66 @@ public:
         'zooming'.
     */
     void SetUserScale(double xScale, double yScale);
         'zooming'.
     */
     void SetUserScale(double xScale, double yScale);

+
+
+    /**
+        @name Transformation matrix
+
+        See the notes about the availability of these functions in the class
+        documentation.
+    */
+    //@{
+
+    /**
+        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
+    */
+    bool CanUseTransformMatrix() const;
+
+    /**
+        Set the transformation matrix.
+
+        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
+    */
+    bool SetTransformMatrix(const wxAffineMatrix2D& matrix);
+
+    /**
+        Return the transformation matrix used by this device context.
+
+        By default the transformation matrix is the identity matrix.
+
+        @since 2.9.2
+    */
+    wxAffineMatrix2D GetTransformMatrix() const;
+
+    /**
+        Revert the transformation matrix to identity matrix.
+
+        @since 2.9.2
+    */
+    void ResetTransformMatrix();
+
+    //@}
+
+
+    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;
+    

 };
 
 
 };
 
 


@@ -1279,10 +1548,12 @@ public:
 /**
     @class wxDCClipper
 
 /**
     @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)
 
     @code
     void MyFunction(wxDC& dc)


@@ -1299,6 +1570,12 @@ public:
     }
     @endcode
 
     }
     @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}
 
     @library{wxcore}
     @category{gdi}
 


@@ -1314,7 +1591,7 @@ public:
 
         The clipping region is automatically unset when this object is destroyed.
     */
 
         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);
     //@}
     wxDCClipper(wxDC& dc, const wxRect& rect);
     wxDCClipper(wxDC& dc, wxCoord x, wxCoord y, wxCoord w, wxCoord h);
     //@}


@@ -1407,6 +1684,16 @@ public:
 class wxDCTextColourChanger
 {
 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.
 
     /**
         Sets @a col on the given @a dc, storing the old one.
 


@@ -1417,6 +1704,17 @@ public:
     */
     wxDCTextColourChanger(wxDC& dc, const wxColour& col);
 
     */
     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.
     */
     /**
         Restores the colour originally selected in the DC passed to the ctor.
     */


@@ -1442,6 +1740,18 @@ public:
 class wxDCFontChanger
 {
 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.
 
     /**
         Sets @a font on the given @a dc, storing the old one.
 


@@ -1453,7 +1763,18 @@ public:
     wxDCFontChanger(wxDC& dc, const wxFont& font);
 
     /**
     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();
 };
     */
     ~wxDCFontChanger();
 };