Extensive documentation typo patch (closes #13063).

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

diff --git a/interface/wx/dc.h b/interface/wx/dc.h
index 704e5b06a4c1521bb4de88ea0efa8e1b53b31174..3c0b009072a99a422a63760608e1cf13b99ea1ea 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".
+};

 
 
 /**
 
 
 /**


@@ -222,15 +244,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 +274,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 +340,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,6 +353,11 @@ 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
     /**
         Draw optional bitmap and the text into the given rectangle and aligns
         it as specified by alignment parameter; it also will emphasize the


@@ -339,6 +384,11 @@ 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.


@@ -347,6 +397,10 @@ public:
         The wxPython version of this method accepts a Python list of wxPoint
         objects.
         @endWxPythonOnly
         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);


@@ -359,6 +413,12 @@ public:
         The wxPython version of this method accepts a Python list of wxPoint
         objects.
         @endWxPythonOnly
         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 +429,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 +444,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,


@@ -400,6 +469,12 @@ public:
         The wxPython version of this method accepts a Python list of wxPoint
         objects.
         @endWxPythonOnly
         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,


@@ -443,6 +518,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 +542,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&,
+                         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,6 +564,17 @@ 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.
 


@@ -480,16 +582,32 @@ public:
         The wxPython version of this method accepts a Python list of wxPoint
         objects.
         @endWxPythonOnly
         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 +618,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


@@ -567,6 +695,12 @@ public:
     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,
+                   int 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 +708,11 @@ public:
     */
     void CrossHair(wxCoord x, wxCoord y);
 
     */
     void CrossHair(wxCoord x, wxCoord y);
 

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

     //@}
 
 
     //@}
 
 


@@ -656,6 +795,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,


@@ -669,6 +823,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,


@@ -684,6 +844,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;


@@ -701,6 +865,11 @@ public:
         of integers.
         @endWxPythonOnly
 
         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()
     */
     bool GetPartialTextExtents(const wxString& text,
         @see GetMultiLineTextExtent(), GetTextExtent()
     */
     bool GetPartialTextExtents(const wxString& text,


@@ -729,6 +898,12 @@ public:
             Returns a 4-tuple, (width, height, descent, externalLeading).
         @endWxPythonOnly
 
             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()
     */


@@ -739,6 +914,11 @@ public:
 
     /**
         @overload
 
     /**
         @overload

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

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


@@ -959,7 +1139,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,7 +1210,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.


@@ -1203,6 +1383,13 @@ public:
         - GetSize() - Returns a wxSize.
         - GetSizeWH() - Returns a 2-tuple (width, height).
         @endWxPythonOnly
         - 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;
 


@@ -1224,6 +1411,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;


@@ -1493,6 +1685,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.
 


@@ -1504,7 +1708,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();
 };