update minimum GTK2 version requirement to 2.6

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

diff --git a/interface/wx/brush.h b/interface/wx/brush.h
index 512b7f00ebaf07eb2c3c6ff0f0dbe397f7259947..24db3e93a298d9e6de199f749f3360f9fe8930f7 100644 (file)
--- a/interface/wx/brush.h
+++ b/interface/wx/brush.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxBrush
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxBrush
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

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


@@ -20,34 +20,39 @@ enum wxBrushStyle
         /**< Transparent (no fill). */
 
     wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE = wxSTIPPLE_MASK_OPAQUE,
         /**< Transparent (no fill). */
 
     wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE = wxSTIPPLE_MASK_OPAQUE,

-        /**< @todo WHAT's THIS?? */
+        /**< Uses a bitmap as a stipple; the mask is used for blitting monochrome
+             using text foreground and background colors. */

 
     wxBRUSHSTYLE_STIPPLE_MASK = wxSTIPPLE_MASK,
 
     wxBRUSHSTYLE_STIPPLE_MASK = wxSTIPPLE_MASK,

-        /**< @todo WHAT's THIS?? */
+        /**< Uses a bitmap as a stipple; mask is used for masking areas in the
+             stipple bitmap. */

 
     wxBRUSHSTYLE_STIPPLE = wxSTIPPLE,
         /**< Uses a bitmap as a stipple. */
 
 
     wxBRUSHSTYLE_STIPPLE = wxSTIPPLE,
         /**< Uses a bitmap as a stipple. */
 

-    wxBRUSHSTYLE_BDIAGONAL_HATCH = wxBDIAGONAL_HATCH,
+    wxBRUSHSTYLE_BDIAGONAL_HATCH,

         /**< Backward diagonal hatch. */
 
         /**< Backward diagonal hatch. */
 

-    wxBRUSHSTYLE_CROSSDIAG_HATCH = wxCROSSDIAG_HATCH,
+    wxBRUSHSTYLE_CROSSDIAG_HATCH,

         /**< Cross-diagonal hatch. */
 
         /**< Cross-diagonal hatch. */
 

-    wxBRUSHSTYLE_FDIAGONAL_HATCH = wxFDIAGONAL_HATCH,
+    wxBRUSHSTYLE_FDIAGONAL_HATCH,

         /**< Forward diagonal hatch. */
 
         /**< Forward diagonal hatch. */
 

-    wxBRUSHSTYLE_CROSS_HATCH = wxCROSS_HATCH,
+    wxBRUSHSTYLE_CROSS_HATCH,

         /**< Cross hatch. */
 
         /**< Cross hatch. */
 

-    wxBRUSHSTYLE_HORIZONTAL_HATCH = wxHORIZONTAL_HATCH,
+    wxBRUSHSTYLE_HORIZONTAL_HATCH,

         /**< Horizontal hatch. */
 
         /**< Horizontal hatch. */
 

-    wxBRUSHSTYLE_VERTICAL_HATCH = wxVERTICAL_HATCH,
+    wxBRUSHSTYLE_VERTICAL_HATCH,

         /**< Vertical hatch. */
 
         /**< Vertical hatch. */
 

-    wxBRUSHSTYLE_FIRST_HATCH = wxFIRST_HATCH,
-    wxBRUSHSTYLE_LAST_HATCH = wxLAST_HATCH,
+    wxBRUSHSTYLE_FIRST_HATCH,
+        /**< First of the hatch styles (inclusive). */
+
+    wxBRUSHSTYLE_LAST_HATCH
+        /**< Last of the hatch styles (inclusive). */

 };
 
 
 };
 
 


@@ -82,9 +87,18 @@ enum wxBrushStyle
     @category{gdi}
 
     @stdobjects
     @category{gdi}
 
     @stdobjects

-    ::wxNullBrush, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH, ::wxWHITE_BRUSH,
-    ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH,
-    ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_BRUSH
+    @li ::wxNullBrush
+    @li ::wxBLACK_BRUSH
+    @li ::wxBLUE_BRUSH
+    @li ::wxCYAN_BRUSH
+    @li ::wxGREEN_BRUSH
+    @li ::wxYELLOW_BRUSH
+    @li ::wxGREY_BRUSH
+    @li ::wxLIGHT_GREY_BRUSH
+    @li ::wxMEDIUM_GREY_BRUSH
+    @li ::wxRED_BRUSH
+    @li ::wxTRANSPARENT_BRUSH
+    @li ::wxWHITE_BRUSH

 
     @see wxBrushList, wxDC, wxDC::SetBrush
 */
 
     @see wxBrushList, wxDC, wxDC::SetBrush
 */


@@ -109,7 +123,7 @@ public:
 
     /**
         Constructs a stippled brush using a bitmap.
 
     /**
         Constructs a stippled brush using a bitmap.

-        The brush style will be set to wxBRUSHSTYLE_STIPPLE.
+        The brush style will be set to @c wxBRUSHSTYLE_STIPPLE.

     */
     wxBrush(const wxBitmap& stippleBitmap);
 
     */
     wxBrush(const wxBitmap& stippleBitmap);
 


@@ -139,7 +153,7 @@ public:
     virtual wxColour GetColour() const;
 
     /**
     virtual wxColour GetColour() const;
 
     /**

-        Gets a pointer to the stipple bitmap. If the brush does not have a wxBRUSHSTYLE_STIPPLE
+        Gets a pointer to the stipple bitmap. If the brush does not have a @c wxBRUSHSTYLE_STIPPLE

         style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false).
 
         @see SetStipple()
         style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false).
 
         @see SetStipple()


@@ -161,11 +175,46 @@ public:
     virtual bool IsHatch() const;
 
     /**
     virtual bool IsHatch() const;
 
     /**

-        Returns @true if the brush is initialised. It will return @false if the default
-        constructor has been used (for example, the brush is a member of a class, or
-        @NULL has been assigned to it).
+        Returns @true if the brush is initialised.
+
+        Notice that an uninitialized brush object can't be queried for any
+        brush properties and all calls to the accessor methods on it will
+        result in an assert failure.

     */
     */

-    bool IsOk() const;
+    virtual bool IsOk() const;
+
+    /**
+        Returns @true if the brush is a valid non-transparent brush.
+
+        This method returns @true if the brush object is initialized and has a
+        non-transparent style. Notice that this should be used instead of
+        simply testing whether GetStyle() returns a style different from
+        wxBRUSHSTYLE_TRANSPARENT if the brush may be invalid as GetStyle()
+        would assert in this case.
+
+        @see IsTransparent()
+
+        @since 2.9.2.
+     */
+    bool IsNonTransparent() const;
+
+    /**
+        Returns @true if the brush is transparent.
+
+        A transparent brush is simply a brush with wxBRUSHSTYLE_TRANSPARENT
+        style.
+
+        Notice that this function works even for non-initialized brushes (for
+        which it returns @false) unlike tests of the form <code>GetStyle() ==
+        wxBRUSHSTYLE_TRANSPARENT</code> which would assert if the brush is
+        invalid.
+
+        @see IsNonTransparent()
+
+        @since 2.9.2.
+     */
+    bool IsTransparent() const;
+

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


@@ -173,7 +222,7 @@ public:
 
         @see GetColour()
     */
 
         @see GetColour()
     */

-    virtual void SetColour(wxColour& colour);
+    virtual void SetColour(const wxColour& colour);

     virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue);
     //@}
 
     virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue);
     //@}
 


@@ -183,9 +232,9 @@ public:
         @param bitmap
             The bitmap to use for stippling.
 
         @param bitmap
             The bitmap to use for stippling.
 

-        @remarks The style will be set to wxBRUSHSTYLE_STIPPLE, unless the bitmap
+        @remarks The style will be set to @c wxBRUSHSTYLE_STIPPLE, unless the bitmap

                  has a mask associated to it, in which case the style will be set
                  has a mask associated to it, in which case the style will be set

-                 to wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE.
+                 to @c wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE.

 
         @see wxBitmap
     */
 
         @see wxBitmap
     */


@@ -216,56 +265,84 @@ public:
 
 /**
     An empty brush.
 
 /**
     An empty brush.

+    wxBrush::IsOk() always returns @false for this object.

 */
 wxBrush wxNullBrush;
 
 /**
     Blue brush.
 */
 wxBrush wxNullBrush;
 
 /**
     Blue brush.

+    Except for the color it has all standard attributes
+    (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).

 */
 wxBrush* wxBLUE_BRUSH;
 
 /**
     Green brush.
 */
 wxBrush* wxBLUE_BRUSH;
 
 /**
     Green brush.

+    Except for the color it has all standard attributes
+    (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).

 */
 wxBrush* wxGREEN_BRUSH;
 
 */
 wxBrush* wxGREEN_BRUSH;
 

+/**
+    Yellow brush.
+    Except for the color it has all standard attributes
+    (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).
+*/
+wxBrush* wxYELLOW_BRUSH;
+

 /**
     White brush.
 /**
     White brush.

+    Except for the color it has all standard attributes
+    (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).

 */
 wxBrush* wxWHITE_BRUSH;
 
 /**
     Black brush.
 */
 wxBrush* wxWHITE_BRUSH;
 
 /**
     Black brush.

+    Except for the color it has all standard attributes
+    (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).

 */
 wxBrush* wxBLACK_BRUSH;
 
 /**
     Grey brush.
 */
 wxBrush* wxBLACK_BRUSH;
 
 /**
     Grey brush.

+    Except for the color it has all standard attributes
+    (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).

 */
 wxBrush* wxGREY_BRUSH;
 
 /**
     Medium grey brush.
 */
 wxBrush* wxGREY_BRUSH;
 
 /**
     Medium grey brush.

+    Except for the color it has all standard attributes
+    (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).

 */
 wxBrush* wxMEDIUM_GREY_BRUSH;
 
 /**
     Light grey brush.
 */
 wxBrush* wxMEDIUM_GREY_BRUSH;
 
 /**
     Light grey brush.

+    Except for the color it has all standard attributes
+    (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).

 */
 wxBrush* wxLIGHT_GREY_BRUSH;
 
 /**
     Transparent brush.
 */
 wxBrush* wxLIGHT_GREY_BRUSH;
 
 /**
     Transparent brush.

+    Except for the color it has all standard attributes
+    (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).

 */
 wxBrush* wxTRANSPARENT_BRUSH;
 
 /**
     Cyan brush.
 */
 wxBrush* wxTRANSPARENT_BRUSH;
 
 /**
     Cyan brush.

+    Except for the color it has all standard attributes
+    (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).

 */
 wxBrush* wxCYAN_BRUSH;
 
 /**
     Red brush.
 */
 wxBrush* wxCYAN_BRUSH;
 
 /**
     Red brush.

+    Except for the color it has all standard attributes
+    (@c wxBRUSHSTYLE_SOLID, no stipple bitmap, etc...).

 */
 wxBrush* wxRED_BRUSH;
 
 */
 wxBrush* wxRED_BRUSH;