synchronize GTK2 minimum version in docs

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

diff --git a/interface/wx/gdicmn.h b/interface/wx/gdicmn.h
index b06c7a331eedba52e5bf29fa4e718a7e57fbc8a4..f043636096873fd3d79d3d638acd9dda67be251e 100644 (file)
--- a/interface/wx/gdicmn.h
+++ b/interface/wx/gdicmn.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxRealPoint
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxRealPoint
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

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


@@ -24,8 +24,10 @@ enum wxBitmapType
     wxBITMAP_TYPE_XBM_DATA,
     wxBITMAP_TYPE_XPM,
     wxBITMAP_TYPE_XPM_DATA,
     wxBITMAP_TYPE_XBM_DATA,
     wxBITMAP_TYPE_XPM,
     wxBITMAP_TYPE_XPM_DATA,

-    wxBITMAP_TYPE_TIF,
-    wxBITMAP_TYPE_TIF_RESOURCE,
+    wxBITMAP_TYPE_TIFF,
+    wxBITMAP_TYPE_TIF = wxBITMAP_TYPE_TIFF,
+    wxBITMAP_TYPE_TIFF_RESOURCE,
+    wxBITMAP_TYPE_TIF_RESOURCE = wxBITMAP_TYPE_TIFF_RESOURCE,

     wxBITMAP_TYPE_GIF,
     wxBITMAP_TYPE_GIF_RESOURCE,
     wxBITMAP_TYPE_PNG,
     wxBITMAP_TYPE_GIF,
     wxBITMAP_TYPE_GIF_RESOURCE,
     wxBITMAP_TYPE_PNG,


@@ -49,7 +51,23 @@ enum wxBitmapType
 };
 
 /**
 };
 
 /**

-    Standard cursors. See wxCursor.
+    Polygon filling mode. See wxDC::DrawPolygon.
+*/
+enum wxPolygonFillMode
+{
+    wxODDEVEN_RULE = 1,
+    wxWINDING_RULE
+};
+
+/**
+    Standard cursors.
+
+    Notice that under wxMSW some of these cursors are defined in @c wx.rc file
+    and not by the system itself so you should include this file from your own
+    resource file (possibly creating a trivial resource file just containing a
+    single include line if you don't need it otherwise) to be able to use them.
+
+    See wxCursor.

 */
 enum wxStockCursor
 {
 */
 enum wxStockCursor
 {


@@ -97,8 +115,11 @@ enum wxStockCursor
 
     A wxRealPoint is a useful data structure for graphics operations.
 
 
     A wxRealPoint is a useful data structure for graphics operations.
 

-    It contains floating point @e x and @e y members. See wxPoint for an
-    integer version.
+    It contains floating point @e x and @e y members.
+    See wxPoint for an integer version.
+
+    Note that the coordinates stored inside a wxRealPoint object may be negative
+    and that wxRealPoint functions do not perform any check against negative values.

 
     @library{wxcore}
     @category{data}
 
     @library{wxcore}
     @category{data}


@@ -108,6 +129,9 @@ enum wxStockCursor
 class wxRealPoint
 {
 public:
 class wxRealPoint
 {
 public:

+    /**
+        Initializes to zero the x and y members.
+    */

     wxRealPoint();
 
     /**
     wxRealPoint();
 
     /**


@@ -115,6 +139,48 @@ public:
     */
     wxRealPoint(double x, double y);
 
     */
     wxRealPoint(double x, double y);
 

+    /**
+        Converts the given wxPoint (with integer coordinates) to a wxRealPoint.
+    */
+    wxRealPoint(const wxPoint& pt);
+
+    /**
+        @name Miscellaneous operators
+
+        Note that these operators are documented as class members
+        (to make them easier to find) but, as their prototype shows,
+        they are implemented as global operators; note that this is
+        transparent to the user but it helps to understand why the
+        following functions are documented to take the wxPoint they
+        operate on as an explicit argument.
+    */
+    //@{
+    wxRealPoint& operator=(const wxRealPoint& pt);
+
+    bool operator ==(const wxRealPoint& p1, const wxRealPoint& p2);
+    bool operator !=(const wxRealPoint& p1, const wxRealPoint& p2);
+
+    wxRealPoint operator +(const wxRealPoint& p1, const wxRealPoint& p2);
+    wxRealPoint operator -(const wxRealPoint& p1, const wxRealPoint& p2);
+
+    wxRealPoint& operator +=(const wxRealPoint& pt);
+    wxRealPoint& operator -=(const wxRealPoint& pt);
+
+    wxRealPoint operator +(const wxRealPoint& pt, const wxSize& sz);
+    wxRealPoint operator -(const wxRealPoint& pt, const wxSize& sz);
+    wxRealPoint operator +(const wxSize& sz, const wxRealPoint& pt);
+    wxRealPoint operator -(const wxSize& sz, const wxRealPoint& pt);
+
+    wxRealPoint& operator +=(const wxSize& sz);
+    wxRealPoint& operator -=(const wxSize& sz);
+
+    wxSize operator /(const wxRealPoint& sz, int factor);
+    wxSize operator *(const wxRealPoint& sz, int factor);
+    wxSize operator *(int factor, const wxSize& sz);
+    wxSize& operator /=(int factor);
+    wxSize& operator *=(int factor);
+    //@}
+

     /**
         X coordinate of this point.
     */
     /**
         X coordinate of this point.
     */


@@ -133,6 +199,10 @@ public:
 
     A class for manipulating rectangles.
 
 
     A class for manipulating rectangles.
 

+    Note that the x, y coordinates and the width and height stored inside a wxRect
+    object may be negative and that wxRect functions do not perform any check against
+    negative values.
+

     @library{wxcore}
     @category{data}
 
     @library{wxcore}
     @category{data}
 


@@ -143,6 +213,7 @@ class wxRect
 public:
     /**
         Default constructor.
 public:
     /**
         Default constructor.

+        Initializes to zero the internal @a x, @a y, @a width and @a height members.

     */
     wxRect();
     /**
     */
     wxRect();
     /**


@@ -154,7 +225,7 @@ public:
     */
     wxRect(const wxPoint& topLeft, const wxPoint& bottomRight);
     /**
     */
     wxRect(const wxPoint& topLeft, const wxPoint& bottomRight);
     /**

-        Creates a wxRect object from position and @a size values.
+        Creates a wxRect object from position @a pos and @a size values.

     */
     wxRect(const wxPoint& pos, const wxSize& size);
     /**
     */
     wxRect(const wxPoint& pos, const wxSize& size);
     /**


@@ -197,10 +268,10 @@ public:
         This method is the opposite from Inflate(): Deflate(a, b) is equivalent
         to Inflate(-a, -b). Please refer to Inflate() for full description.
     */
         This method is the opposite from Inflate(): Deflate(a, b) is equivalent
         to Inflate(-a, -b). Please refer to Inflate() for full description.
     */

-    void Deflate(wxCoord dx, wxCoord dy);
-    void Deflate(const wxSize& diff);
-    void Deflate(wxCoord diff);
-    wxRect Deflate(wxCoord dx, wxCoord dy) const;
+    wxRect& Deflate(wxCoord dx, wxCoord dy);
+    wxRect& Deflate(const wxSize& diff);
+    wxRect& Deflate(wxCoord diff);
+    wxRect  Deflate(wxCoord dx, wxCoord dy) const;

     //@}
 
     /**
     //@}
 
     /**


@@ -282,7 +353,7 @@ public:
 
         The left border is moved farther left and the right border is moved
         farther right by @a dx. The upper border is moved farther up and the
 
         The left border is moved farther left and the right border is moved
         farther right by @a dx. The upper border is moved farther up and the

-        bottom border is moved farther down by @a dy. (Note the the width and
+        bottom border is moved farther down by @a dy. (Note that the width and

         height of the rectangle thus change by 2*dx and 2*dy, respectively.) If
         one or both of @a dx and @a dy are negative, the opposite happens: the
         rectangle size decreases in the respective direction.
         height of the rectangle thus change by 2*dx and 2*dy, respectively.) If
         one or both of @a dx and @a dy are negative, the opposite happens: the
         rectangle size decreases in the respective direction.


@@ -305,9 +376,9 @@ public:
 
         @see Deflate()
     */
 
         @see Deflate()
     */

-    void Inflate(wxCoord dx, wxCoord dy);
-    void Inflate(const wxSize& diff);
-    void Inflate(wxCoord diff);
+    wxRect& Inflate(wxCoord dx, wxCoord dy);
+    wxRect& Inflate(const wxSize& diff);
+    wxRect& Inflate(wxCoord diff);

     wxRect Inflate(wxCoord dx, wxCoord dy) const;
     //@}
 
     wxRect Inflate(wxCoord dx, wxCoord dy) const;
     //@}
 


@@ -374,6 +445,47 @@ public:
     */
     void SetY(int y);
 
     */
     void SetY(int y);
 

+    /**
+       Set the left side of the rectangle.
+    */
+    void SetLeft(int left);
+
+    /**
+       Set the right side of the rectangle.
+     */
+    void SetRight(int right);
+
+    /**
+       Set the top edge of the rectangle.
+     */
+    void SetTop(int top);
+
+    /**
+       Set the bottome edge of th rectangle.
+     */
+    void SetBottom(int bottom);
+
+    /**
+       Set the top-left point of the rectangle.
+     */
+    void SetTopLeft(const wxPoint &p);
+
+    /**
+       Set the bottom-right point of the rectangle.
+     */
+    void SetBottomRight(const wxPoint &p);
+
+    /**
+       Set the top-right point of the rectangle.
+     */
+    void SetTopRight(const wxPoint &p);
+
+    /**
+       Set the bottom-left point of the rectangle.
+     */
+    void SetBottomLeft(const wxPoint &p);
+
+    

     //@{
     /**
         Modifies the rectangle to contain the bounding box of this rectangle
     //@{
     /**
         Modifies the rectangle to contain the bounding box of this rectangle


@@ -442,8 +554,12 @@ public:
 
     A wxPoint is a useful data structure for graphics operations.
 
 
     A wxPoint is a useful data structure for graphics operations.
 

-    It contains integer @e x and @e y members. See wxRealPoint for a floating
-    point version.
+    It contains integer @e x and @e y members.
+    See wxRealPoint for a floating point version.
+
+    Note that the width and height stored inside a wxPoint object may be negative
+    and that wxPoint functions do not perform any check against negative values
+    (this is used to e.g. store the special -1 value in ::wxDefaultPosition instance).

 
     @library{wxcore}
     @category{data}
 
     @library{wxcore}
     @category{data}


@@ -456,17 +572,34 @@ public:
 class wxPoint
 {
 public:
 class wxPoint
 {
 public:

-    //@{

     /**
         Constructs a point.
     /**
         Constructs a point.

+        Initializes the internal x and y coordinates to zero.

     */
     wxPoint();
     */
     wxPoint();

+
+    /**
+        Initializes the point object with the given @a x and @a y coordinates.
+    */

     wxPoint(int x, int y);
     wxPoint(int x, int y);

-    //@}

 
     /**
 
     /**

-        Assignment operator.
+        Converts the given wxRealPoint (with floating point coordinates) to a
+        wxPoint instance.

     */
     */

+    wxPoint(const wxRealPoint& pt);
+
+    /**
+        @name Miscellaneous operators
+
+        Note that these operators are documented as class members
+        (to make them easier to find) but, as their prototype shows,
+        they are implemented as global operators; note that this is
+        transparent to the user but it helps to understand why the
+        following functions are documented to take the wxPoint they
+        operate on as an explicit argument.
+    */
+    //@{

     wxPoint& operator=(const wxPoint& pt);
 
     bool operator ==(const wxPoint& p1, const wxPoint& p2);
     wxPoint& operator=(const wxPoint& pt);
 
     bool operator ==(const wxPoint& p1, const wxPoint& p2);


@@ -486,6 +619,56 @@ public:
     wxPoint& operator +=(const wxSize& sz);
     wxPoint& operator -=(const wxSize& sz);
 
     wxPoint& operator +=(const wxSize& sz);
     wxPoint& operator -=(const wxSize& sz);
 

+    wxSize operator /(const wxPoint& sz, int factor);
+    wxSize operator *(const wxPoint& sz, int factor);
+    wxSize operator *(int factor, const wxSize& sz);
+    wxSize& operator /=(int factor);
+    wxSize& operator *=(int factor);
+    //@}
+
+
+    /**
+        @name Defaults handling.
+
+        Test for and set non-specified wxPoint components.
+
+        Although a wxPoint is always initialized to (0, 0), wxWidgets commonly
+        uses wxDefaultCoord (defined as @c -1) to indicate that a point hasn't
+        been initialized or specified. In particular, ::wxDefaultPosition is
+        used in many places with this meaning.
+     */
+    //@{
+
+    /**
+        Returns @true if neither of the point components is equal to
+        wxDefaultCoord.
+
+        This method is typically used before calling SetDefaults().
+
+        @since 2.9.2
+    */
+    bool IsFullySpecified() const;
+
+    /**
+        Combine this object with another one replacing the uninitialized
+        values.
+
+        It is typically used like this:
+
+        @code
+        if ( !pos.IsFullySpecified() )
+        {
+            pos.SetDefaults(GetDefaultPosition());
+        }
+        @endcode
+
+        @see IsFullySpecified()
+
+        @since 2.9.2
+    */
+    void SetDefaults(const wxPoint& pt);
+    //@}
+

     /**
         x member.
     */
     /**
         x member.
     */


@@ -498,9 +681,9 @@ public:
 };
 
 /**
 };
 
 /**

-    Global istance of a wxPoint initialized with values (-1,-1).
+    Global instance of a wxPoint initialized with values (-1,-1).

 */
 */

-wxPoint wxDefaultPosition;
+const wxPoint wxDefaultPosition;

 
 
 /**
 
 
 /**


@@ -627,21 +810,28 @@ public:
 };
 
 
 };
 
 

+/**
+    Global instance of a wxColourDatabase.
+*/
+wxColourDatabase* wxTheColourDatabase;
+
+

 /**
     @class wxSize
 
 /**
     @class wxSize
 

-    A wxSize is a useful data structure for graphics operations. It simply
-    contains integer @e width and @e height members.
+    A wxSize is a useful data structure for graphics operations.
+    It simply contains integer @e width and @e height members.
+
+    Note that the width and height stored inside a wxSize object may be negative
+    and that wxSize functions do not perform any check against negative values
+    (this is used to e.g. store the special -1 value in ::wxDefaultSize instance).
+    See also IsFullySpecified() and SetDefaults() for utility functions regarding
+    the special -1 value.

 
     wxSize is used throughout wxWidgets as well as wxPoint which, although
     almost equivalent to wxSize, has a different meaning: wxPoint represents a
     position while wxSize represents the size.
 
 
     wxSize is used throughout wxWidgets as well as wxPoint which, although
     almost equivalent to wxSize, has a different meaning: wxPoint represents a
     position while wxSize represents the size.
 

-    @beginWxPythonOnly
-    wxPython defines aliases for the @e x and @e y members named @e width and
-    @e height since it makes much more sense for sizes.
-    @endWxPythonOnly
-

     @library{wxcore}
     @category{data}
 
     @library{wxcore}
     @category{data}
 


@@ -653,13 +843,15 @@ public:
 class wxSize
 {
 public:
 class wxSize
 {
 public:

-    //@{

     /**
     /**

-        Creates a size object.
+        Initializes this size object with zero width and height.

     */
     wxSize();
     */
     wxSize();

+
+    /**
+        Initializes this size object with the given @a width and @a height.
+    */

     wxSize(int width, int height);
     wxSize(int width, int height);

-    //@}

 
     //@{
     /**
 
     //@{
     /**


@@ -667,6 +859,7 @@ public:
 
         @see IncBy()
     */
 
         @see IncBy()
     */

+    void DecBy(const wxPoint& pt);

     void DecBy(const wxSize& size);
     void DecBy(int dx, int dy);
     void DecBy(int d);
     void DecBy(const wxSize& size);
     void DecBy(int dx, int dy);
     void DecBy(int d);


@@ -696,6 +889,7 @@ public:
 
         @see DecBy()
     */
 
         @see DecBy()
     */

+    void IncBy(const wxPoint& pt);

     void IncBy(const wxSize& size);
     void IncBy(int dx, int dy);
     void IncBy(int d);
     void IncBy(const wxSize& size);
     void IncBy(int dx, int dy);
     void IncBy(int d);


@@ -759,9 +953,18 @@ public:
     */
     void SetWidth(int width);
 
     */
     void SetWidth(int width);
 

+

     /**
     /**

-        Assignment operator.
+        @name Miscellaneous operators
+
+        Note that these operators are documented as class members
+        (to make them easier to find) but, as their prototype shows,
+        they are implemented as global operators; note that this is
+        transparent to the user but it helps to understand why the
+        following functions are documented to take the wxSize they
+        operate on as an explicit argument.

     */
     */

+    //@{

     wxSize& operator=(const wxSize& sz);
 
     bool operator ==(const wxSize& s1, const wxSize& s2);
     wxSize& operator=(const wxSize& sz);
 
     bool operator ==(const wxSize& s1, const wxSize& s2);


@@ -777,12 +980,13 @@ public:
     wxSize operator *(int factor, const wxSize& sz);
     wxSize& operator /=(int factor);
     wxSize& operator *=(int factor);
     wxSize operator *(int factor, const wxSize& sz);
     wxSize& operator /=(int factor);
     wxSize& operator *=(int factor);

+    //@}

 };
 
 /**
     Global instance of a wxSize object initialized to (-1,-1).
 */
 };
 
 /**
     Global instance of a wxSize object initialized to (-1,-1).
 */

-wxSize wxDefaultSize;
+const wxSize wxDefaultSize;

 
 
 
 
 
 


@@ -791,7 +995,7 @@ wxSize wxDefaultSize;
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/** @ingroup group_funcmacro_gdi */
+/** @addtogroup group_funcmacro_gdi */

 //@{
 
 /**
 //@{
 
 /**


@@ -814,7 +1018,7 @@ wxSize wxDefaultSize;
 
     @header{wx/gdicmn.h}
 */
 
     @header{wx/gdicmn.h}
 */

-wxICON();
+#define wxICON(iconName)

 
 /**
     Returns @true if the display is colour, @false otherwise.
 
 /**
     Returns @true if the display is colour, @false otherwise.


@@ -843,7 +1047,7 @@ void wxSetCursor(const wxCursor& cursor);
 
 //@}
 
 
 //@}
 

-/** @ingroup group_funcmacro_gdi */
+/** @addtogroup group_funcmacro_gdi */

 //@{
 /**
     Returns the dimensions of the work area on the display. On Windows this
 //@{
 /**
     Returns the dimensions of the work area on the display. On Windows this


@@ -857,7 +1061,7 @@ void wxClientDisplayRect(int* x, int* y, int* width, int* height);
 wxRect wxGetClientDisplayRect();
 //@}
 
 wxRect wxGetClientDisplayRect();
 //@}
 

-/** @ingroup group_funcmacro_gdi */
+/** @addtogroup group_funcmacro_gdi */

 //@{
 /**
     Returns the display resolution in pixels per inch.
 //@{
 /**
     Returns the display resolution in pixels per inch.


@@ -872,7 +1076,7 @@ wxRect wxGetClientDisplayRect();
 wxSize wxGetDisplayPPI();
 //@}
 
 wxSize wxGetDisplayPPI();
 //@}
 

-/** @ingroup group_funcmacro_gdi */
+/** @addtogroup group_funcmacro_gdi */

 //@{
 /**
     Returns the display size in pixels.
 //@{
 /**
     Returns the display size in pixels.


@@ -886,7 +1090,7 @@ void wxDisplaySize(int* width, int* height);
 wxSize wxGetDisplaySize();
 //@}
 
 wxSize wxGetDisplaySize();
 //@}
 

-/** @ingroup group_funcmacro_gdi */
+/** @addtogroup group_funcmacro_gdi */

 //@{
 /**
     Returns the display size in millimeters.
 //@{
 /**
     Returns the display size in millimeters.