Interface fixes for Phoenix

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

diff --git a/interface/wx/region.h b/interface/wx/region.h
index 5d190a430d3fbca841e009c0c7670cf983c68a79..bdf25ba38469c00461ba47d69444c4c8ac8e6004 100644 (file)
--- a/interface/wx/region.h
+++ b/interface/wx/region.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxRegionIterator
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxRegionIterator
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -115,12 +115,8 @@ public:
 
     /**
         Increment operator. Increments the iterator to the next region.
 
     /**
         Increment operator. Increments the iterator to the next region.

-
-        @beginWxPythonOnly
-        A wxPython alias for this operator is called Next.
-        @endWxPythonOnly

     */
     */

-    void operator ++();
+    wxRegionIterator& operator ++();

 
     /**
         Returns @true if there are still some rectangles; otherwise returns @false.
 
     /**
         Returns @true if there are still some rectangles; otherwise returns @false.


@@ -157,6 +153,9 @@ class wxRegion : public wxGDIObject
 public:
     /**
         Default constructor.
 public:
     /**
         Default constructor.

+
+        This constructor creates an invalid, or null, object, i.e. calling
+        IsOk() on it returns @false and IsEmpty() returns @true.

     */
     wxRegion();
     /**
     */
     wxRegion();
     /**


@@ -181,7 +180,7 @@ public:
         in the provided array.
         @a fillStyle parameter may have values @c wxWINDING_RULE or @c wxODDEVEN_RULE.
     */
         in the provided array.
         @a fillStyle parameter may have values @c wxWINDING_RULE or @c wxODDEVEN_RULE.
     */

-    wxRegion(size_t n, const wxPoint* points, int fillStyle = wxWINDING_RULE);
+    wxRegion(size_t n, const wxPoint* points, wxPolygonFillMode fillStyle = wxODDEVEN_RULE);

     /**
         Constructs a region using a bitmap. See Union() for more details.
     */
     /**
         Constructs a region using a bitmap. See Union() for more details.
     */


@@ -202,18 +201,26 @@ public:
 
     /**
         Clears the current region.
 
     /**
         Clears the current region.

+
+        The object becomes invalid, or null, after being cleared.

     */
     virtual void Clear();
 
     /**
         Returns a value indicating whether the given point is contained within the region.
 
     */
     virtual void Clear();
 
     /**
         Returns a value indicating whether the given point is contained within the region.
 

+        This method always returns @c wxOutRegion for an invalid region but
+        may, nevertheless, be safely called in this case.
+

         @return The return value is one of @c wxOutRegion and @c wxInRegion.
     */
         @return The return value is one of @c wxOutRegion and @c wxInRegion.
     */

-    wxRegionContain Contains(long& x, long& y) const;
+    wxRegionContain Contains(wxCoord x, wxCoord y) const;

     /**
         Returns a value indicating whether the given point is contained within the region.
 
     /**
         Returns a value indicating whether the given point is contained within the region.
 

+        This method always returns @c wxOutRegion for an invalid region but
+        may, nevertheless, be safely called in this case.
+

         @return The return value is one of @c wxOutRegion and @c wxInRegion.
     */
     wxRegionContain Contains(const wxPoint& pt) const;
         @return The return value is one of @c wxOutRegion and @c wxInRegion.
     */
     wxRegionContain Contains(const wxPoint& pt) const;


@@ -221,17 +228,23 @@ public:
         Returns a value indicating whether the given rectangle is contained within the
         region.
 
         Returns a value indicating whether the given rectangle is contained within the
         region.
 

+        This method always returns @c wxOutRegion for an invalid region but
+        may, nevertheless, be safely called in this case.
+

         @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
 
         @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value
               ::wxInRegion then indicates that all or some part of the region is
               contained in this region.
     */
         @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
 
         @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value
               ::wxInRegion then indicates that all or some part of the region is
               contained in this region.
     */

-    wxRegionContain Contains(long& x, long& y, long& width, long& height) const;
+    wxRegionContain Contains(wxCoord x, wxCoord y, wxCoord width, wxCoord height) const;

     /**
         Returns a value indicating whether the given rectangle is contained within the
         region.
 
     /**
         Returns a value indicating whether the given rectangle is contained within the
         region.
 

+        This method always returns @c wxOutRegion for an invalid region but
+        may, nevertheless, be safely called in this case.
+

         @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
 
         @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value
         @return One of ::wxOutRegion, ::wxPartRegion or ::wxInRegion.
 
         @note On Windows, only ::wxOutRegion and ::wxInRegion are returned; a value


@@ -243,22 +256,29 @@ public:
     /**
         Convert the region to a black and white bitmap with the white pixels
         being inside the region.
     /**
         Convert the region to a black and white bitmap with the white pixels
         being inside the region.

+
+        This method can't be used for invalid region.

     */
     wxBitmap ConvertToBitmap() const;
 
     //@{
     /**
         Returns the outer bounds of the region.
     */
     wxBitmap ConvertToBitmap() const;
 
     //@{
     /**
         Returns the outer bounds of the region.

+
+        This method returns 0-sized bounding box for invalid regions.

     */
     void GetBox(wxCoord& x, wxCoord& y, wxCoord& width,
                 wxCoord& height) const;
     */
     void GetBox(wxCoord& x, wxCoord& y, wxCoord& width,
                 wxCoord& height) const;

-    const wxRect  GetBox() const;
+    wxRect GetBox() const;

     //@}
 
     /**
         Finds the intersection of this region and another, rectangular region,
         specified using position and size.
 
     //@}
 
     /**
         Finds the intersection of this region and another, rectangular region,
         specified using position and size.
 

+        This method always fails, i.e. returns @false, if this region is
+        invalid but may nevertheless be safely used even in this case.
+

         @return @true if successful, @false otherwise.
 
         @remarks Creates the intersection of the two regions, that is, the parts
         @return @true if successful, @false otherwise.
 
         @remarks Creates the intersection of the two regions, that is, the parts


@@ -270,6 +290,9 @@ public:
     /**
         Finds the intersection of this region and another, rectangular region.
 
     /**
         Finds the intersection of this region and another, rectangular region.
 

+        This method always fails, i.e. returns @false, if this region is
+        invalid but may nevertheless be safely used even in this case.
+

         @return @true if successful, @false otherwise.
 
         @remarks Creates the intersection of the two regions, that is, the parts
         @return @true if successful, @false otherwise.
 
         @remarks Creates the intersection of the two regions, that is, the parts


@@ -280,6 +303,9 @@ public:
     /**
         Finds the intersection of this region and another region.
 
     /**
         Finds the intersection of this region and another region.
 

+        This method always fails, i.e. returns @false, if this region is
+        invalid but may nevertheless be safely used even in this case.
+

         @return @true if successful, @false otherwise.
 
         @remarks Creates the intersection of the two regions, that is, the parts
         @return @true if successful, @false otherwise.
 
         @remarks Creates the intersection of the two regions, that is, the parts


@@ -290,6 +316,8 @@ public:
 
     /**
         Returns @true if the region is empty, @false otherwise.
 
     /**
         Returns @true if the region is empty, @false otherwise.

+
+        Always returns @true if the region is invalid.

     */
     virtual bool IsEmpty() const;
 
     */
     virtual bool IsEmpty() const;
 


@@ -297,8 +325,8 @@ public:
         Returns @true if the region is equal to, i.e. covers the same area as,
         another one.
 
         Returns @true if the region is equal to, i.e. covers the same area as,
         another one.
 

-        @note If both this region and @a region are invalid, they are
-              considered to be equal.
+        If both this region and @a region are both invalid, they are considered
+        to be equal.

     */
     bool IsEqual(const wxRegion& region) const;
 
     */
     bool IsEqual(const wxRegion& region) const;
 


@@ -307,6 +335,10 @@ public:
         Moves the region by the specified offsets in horizontal and vertical
         directions.
 
         Moves the region by the specified offsets in horizontal and vertical
         directions.
 

+        This method can't be called if the region is invalid as it doesn't make
+        sense to offset it then. Attempts to do it will result in assert
+        failure.
+

         @return @true if successful, @false otherwise (the region is unchanged
                  then).
     */
         @return @true if successful, @false otherwise (the region is unchanged
                  then).
     */


@@ -317,6 +349,9 @@ public:
     /**
         Subtracts a rectangular region from this region.
 
     /**
         Subtracts a rectangular region from this region.
 

+        This method always fails, i.e. returns @false, if this region is
+        invalid but may nevertheless be safely used even in this case.
+

         @return @true if successful, @false otherwise.
 
         @remarks This operation combines the parts of 'this' region that are not
         @return @true if successful, @false otherwise.
 
         @remarks This operation combines the parts of 'this' region that are not


@@ -327,6 +362,9 @@ public:
     /**
         Subtracts a region from this region.
 
     /**
         Subtracts a region from this region.
 

+        This method always fails, i.e. returns @false, if this region is
+        invalid but may nevertheless be safely used even in this case.
+

         @return @true if successful, @false otherwise.
 
         @remarks This operation combines the parts of 'this' region that are not
         @return @true if successful, @false otherwise.
 
         @remarks This operation combines the parts of 'this' region that are not


@@ -339,6 +377,10 @@ public:
         Finds the union of this region and another, rectangular region, specified using
         position and size.
 
         Finds the union of this region and another, rectangular region, specified using
         position and size.
 

+        This method can be used even if this region is invalid and has the
+        natural behaviour in this case, i.e. makes this region equal to the
+        given rectangle.
+

         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region
         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region


@@ -349,6 +391,10 @@ public:
     /**
         Finds the union of this region and another, rectangular region.
 
     /**
         Finds the union of this region and another, rectangular region.
 

+        This method can be used even if this region is invalid and has the
+        natural behaviour in this case, i.e. makes this region equal to the
+        given rectangle.
+

         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region
         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region


@@ -359,6 +405,10 @@ public:
     /**
         Finds the union of this region and another region.
 
     /**
         Finds the union of this region and another region.
 

+        This method can be used even if this region is invalid and has the
+        natural behaviour in this case, i.e. makes this region equal to the
+        given @a region.
+

         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region
         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region


@@ -396,6 +446,10 @@ public:
         Finds the Xor of this region and another, rectangular region, specified using
         position and size.
 
         Finds the Xor of this region and another, rectangular region, specified using
         position and size.
 

+        This method can be used even if this region is invalid and has the
+        natural behaviour in this case, i.e. makes this region equal to the
+        given rectangle.
+

         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region
         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region


@@ -406,6 +460,10 @@ public:
     /**
         Finds the Xor of this region and another, rectangular region.
 
     /**
         Finds the Xor of this region and another, rectangular region.
 

+        This method can be used even if this region is invalid and has the
+        natural behaviour in this case, i.e. makes this region equal to the
+        given rectangle.
+

         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region
         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region


@@ -416,6 +474,10 @@ public:
     /**
         Finds the Xor of this region and another region.
 
     /**
         Finds the Xor of this region and another region.
 

+        This method can be used even if this region is invalid and has the
+        natural behaviour in this case, i.e. makes this region equal to the
+        given @a region.
+

         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region
         @return @true if successful, @false otherwise.
 
         @remarks This operation creates a region that combines all of this region