]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/brush.h
projects / wxWidgets.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
non-pch build fix
[wxWidgets.git] / interface / brush.h
diff --git a/interface/brush.h b/interface/brush.h
index d644b1e19b5bdfc1136be43b48797c356ae12b87..3b4e63d63d4424fae3234863608fcd0e5bb9e357 100644 (file)
--- a/interface/brush.h
+++ b/interface/brush.h
@@ -6,234 +6,168 @@
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
+/**
+    The possible brush styles.
+*/
+enum wxBrushStyle
+{
+    wxBRUSHSTYLE_SOLID = wxSOLID,
+        /**< Solid. */
+
+    wxBRUSHSTYLE_TRANSPARENT = wxTRANSPARENT,
+        /**< Transparent (no fill). */
+
+    wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE = wxSTIPPLE_MASK_OPAQUE,
+        /**< @todo WHAT's THIS?? */
+
+    wxBRUSHSTYLE_STIPPLE_MASK = wxSTIPPLE_MASK,
+        /**< @todo WHAT's THIS?? */
+
+    wxBRUSHSTYLE_STIPPLE = wxSTIPPLE,
+        /**< Uses a bitmap as a stipple. */
+
+    wxBRUSHSTYLE_BDIAGONAL_HATCH = wxBDIAGONAL_HATCH,
+        /**< Backward diagonal hatch. */
+
+    wxBRUSHSTYLE_CROSSDIAG_HATCH = wxCROSSDIAG_HATCH,
+        /**< Cross-diagonal hatch. */
+
+    wxBRUSHSTYLE_FDIAGONAL_HATCH = wxFDIAGONAL_HATCH,
+        /**< Forward diagonal hatch. */
+
+    wxBRUSHSTYLE_CROSS_HATCH = wxCROSS_HATCH,
+        /**< Cross hatch. */
+
+    wxBRUSHSTYLE_HORIZONTAL_HATCH = wxHORIZONTAL_HATCH,
+        /**< Horizontal hatch. */
+
+    wxBRUSHSTYLE_VERTICAL_HATCH = wxVERTICAL_HATCH,
+        /**< Vertical hatch. */
+
+    wxBRUSHSTYLE_FIRST_HATCH = wxFIRST_HATCH,
+    wxBRUSHSTYLE_LAST_HATCH = wxLAST_HATCH,
+    wxBRUSHSTYLE_MAX
+};
+
+
+
 /**
     @class wxBrush
     @wxheader{brush.h}
 
     A brush is a drawing tool for filling in areas. It is used for painting
 /**
     @class wxBrush
     @wxheader{brush.h}
 
     A brush is a drawing tool for filling in areas. It is used for painting
-    the background of rectangles, ellipses, etc. It has a colour and a
-    style.
+    the background of rectangles, ellipses, etc. It has a colour and a style.
+
+    On a monochrome display, wxWidgets shows all brushes as white unless the
+    colour is really black.
+
+    Do not initialize objects on the stack before the program commences, since
+    other required structures may not have been set up yet. Instead, define
+    global pointers to objects and create them in wxApp::OnInit or when required.
+
+    An application may wish to create brushes with different characteristics
+    dynamically, and there is the consequent danger that a large number of
+    duplicate brushes will be created. Therefore an application may wish to
+    get a pointer to a brush by using the global list of brushes ::wxTheBrushList,
+    and calling the member function wxBrushList::FindOrCreateBrush().
+
+    This class uses reference counting and copy-on-write internally so that
+    assignments between two instances of this class are very cheap.
+    You can therefore use actual objects instead of pointers without efficiency problems.
+    If an instance of this class is changed it will create its own data internally
+    so that other instances, which previously shared the data using the reference
+    counting, are not affected.
 
     @library{wxcore}
     @category{gdi}
 
     @stdobjects
 
     @library{wxcore}
     @category{gdi}
 
     @stdobjects
-    ::Objects:, ::wxNullBrush, ::Pointers:, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH,
-    ::wxWHITE_BRUSH, ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH, ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_BRUSH,
+    ::wxNullBrush, ::wxBLUE_BRUSH, ::wxGREEN_BRUSH, ::wxWHITE_BRUSH,
+    ::wxBLACK_BRUSH, ::wxGREY_BRUSH, ::wxMEDIUM_GREY_BRUSH, ::wxLIGHT_GREY_BRUSH,
+    ::wxTRANSPARENT_BRUSH, ::wxCYAN_BRUSH, ::wxRED_BRUSH
 
     @see wxBrushList, wxDC, wxDC::SetBrush
 */
 class wxBrush : public wxGDIObject
 {
 public:
 
     @see wxBrushList, wxDC, wxDC::SetBrush
 */
 class wxBrush : public wxGDIObject
 {
 public:
-    //@{
     /**
     /**
-        Copy constructor, uses @ref overview_trefcount "reference counting".
-        
+        Default constructor.
+        The brush will be uninitialised, and wxBrush:IsOk() will return @false.
+    */
+    wxBrush();
+
+    /**
+        Constructs a brush from a colour object and @a style.
+
         @param colour
             Colour object.
         @param colour
             Colour object.
+        @param style
+            One of the ::wxBrushStyle enumeration values.
+    */
+    wxBrush(const wxColour& colour, wxBrushStyle style = wxSOLID);
+
+    /**
+        Constructs a brush from a colour name and @a style.
+
         @param colourName
             Colour name. The name will be looked up in the colour database.
         @param style
         @param colourName
             Colour name. The name will be looked up in the colour database.
         @param style
-            One of:
-        
-        
-        
-        
-        
-        
-            wxTRANSPARENT
-        
-        
-        
-        
-            Transparent (no fill).
-        
-        
-        
-        
-        
-            wxSOLID
-        
-        
-        
-        
-            Solid.
-        
-        
-        
-        
-        
-            wxSTIPPLE
-        
-        
-        
-        
-            Uses a bitmap as a stipple.
-        
-        
-        
-        
-        
-            wxBDIAGONAL_HATCH
-        
-        
-        
-        
-            Backward diagonal hatch.
-        
-        
-        
-        
-        
-            wxCROSSDIAG_HATCH
-        
-        
-        
-        
-            Cross-diagonal hatch.
-        
-        
-        
-        
-        
-            wxFDIAGONAL_HATCH
-        
-        
-        
-        
-            Forward diagonal hatch.
-        
-        
-        
-        
-        
-            wxCROSS_HATCH
-        
-        
-        
-        
-            Cross hatch.
-        
-        
-        
-        
-        
-            wxHORIZONTAL_HATCH
-        
-        
-        
-        
-            Horizontal hatch.
-        
-        
-        
-        
-        
-            wxVERTICAL_HATCH
-        
-        
-        
-        
-            Vertical hatch.
-        @param brush
-            Pointer or reference to a brush to copy.
-        @param stippleBitmap
-            A bitmap to use for stippling.
-        
-        @remarks If a stipple brush is created, the brush style will be set to
-                 wxSTIPPLE.
-        
-        @see wxBrushList, wxColour, wxColourDatabase
+            One of the ::wxBrushStyle enumeration values.
+
+        @see wxColourDatabase
+    */
+    wxBrush(const wxString& colourName, wxBrushStyle style);
+
+    /**
+        Constructs a stippled brush using a bitmap.
+        The brush style will be set to wxBRUSHSTYLE_STIPPLE.
     */
     */
-    wxBrush();
-    wxBrush(const wxColour& colour, int style = wxSOLID);
-    wxBrush(const wxString& colourName, int style);
     wxBrush(const wxBitmap& stippleBitmap);
     wxBrush(const wxBitmap& stippleBitmap);
+
+    /**
+        Copy constructor, uses @ref overview_refcount "reference counting".
+    */
     wxBrush(const wxBrush& brush);
     wxBrush(const wxBrush& brush);
-    //@}
 
     /**
         Destructor.
 
     /**
         Destructor.
-        See @ref overview_refcountdestruct "reference-counted object destruction" for
-        more info.
-        
+
+        See @ref overview_refcount_destruct for more info.
+
         @remarks Although all remaining brushes are deleted when the application
         @remarks Although all remaining brushes are deleted when the application
-                 exits, the application should try to clean up all
-                 brushes itself. This is because wxWidgets cannot know
-                 if a pointer to the brush object is stored in an
-                 application data structure, and there is a risk of
-                 double deletion.
+                 exits, the application should try to clean up all brushes itself.
+                 This is because wxWidgets cannot know if a pointer to the brush
+                 object is stored in an application data structure, and there is
+                 a risk of double deletion.
     */
     ~wxBrush();
 
     /**
         Returns a reference to the brush colour.
     */
     ~wxBrush();
 
     /**
         Returns a reference to the brush colour.
-        
+
         @see SetColour()
     */
     wxColour GetColour() const;
 
     /**
         @see SetColour()
     */
     wxColour GetColour() const;
 
     /**
-        Gets a pointer to the stipple bitmap. If the brush does not have a wxSTIPPLE
-        style,
-        this bitmap may be non-@NULL but uninitialised (@ref wxBitmap::isok
-        wxBitmap:IsOk returns @false).
-        
+        Gets a pointer to the stipple bitmap. If the brush does not have a wxBRUSHSTYLE_STIPPLE
+        style, this bitmap may be non-@NULL but uninitialised (i.e. wxBitmap:IsOk() returns @false).
+
         @see SetStipple()
     */
     wxBitmap* GetStipple() const;
 
     /**
         @see SetStipple()
     */
     wxBitmap* GetStipple() const;
 
     /**
-        Returns the brush style, one of:
-        
-        @b wxTRANSPARENT
-        
-        Transparent (no fill).
-        
-        @b wxSOLID
-        
-        Solid.
-        
-        @b wxBDIAGONAL_HATCH
-        
-        Backward diagonal hatch.
-        
-        @b wxCROSSDIAG_HATCH
-        
-        Cross-diagonal hatch.
-        
-        @b wxFDIAGONAL_HATCH
-        
-        Forward diagonal hatch.
-        
-        @b wxCROSS_HATCH
-        
-        Cross hatch.
-        
-        @b wxHORIZONTAL_HATCH
-        
-        Horizontal hatch.
-        
-        @b wxVERTICAL_HATCH
-        
-        Vertical hatch.
-        
-        @b wxSTIPPLE
-        
-        Stippled using a bitmap.
-        
-        @b wxSTIPPLE_MASK_OPAQUE
-        
-        Stippled using a bitmap's mask.
-        
+        Returns the brush style, one of the ::wxBrushStyle values.
+
         @see SetStyle(), SetColour(), SetStipple()
     */
         @see SetStyle(), SetColour(), SetStipple()
     */
-    int GetStyle() const;
+    wxBrushStyle GetStyle() const;
 
     /**
         Returns @true if the style of the brush is any of hatched fills.
 
     /**
         Returns @true if the style of the brush is any of hatched fills.
-        
+
         @see GetStyle()
     */
     bool IsHatch() const;
         @see GetStyle()
     */
     bool IsHatch() const;
@@ -248,7 +182,7 @@ public:
     //@{
     /**
         Sets the brush colour using red, green and blue values.
     //@{
     /**
         Sets the brush colour using red, green and blue values.
-        
+
         @see GetColour()
     */
     void SetColour(wxColour& colour);
         @see GetColour()
     */
     void SetColour(wxColour& colour);
@@ -259,225 +193,137 @@ public:
 
     /**
         Sets the stipple bitmap.
 
     /**
         Sets the stipple bitmap.
-        
+
         @param bitmap
             The bitmap to use for stippling.
         @param bitmap
             The bitmap to use for stippling.
-        
-        @remarks The style will be set to wxSTIPPLE, unless the bitmap has a mask
-                 associated to it, in which case the style will be set
-                 to wxSTIPPLE_MASK_OPAQUE.
-        
+
+        @remarks The style will be set to wxBRUSHSTYLE_STIPPLE, unless the bitmap
+                 has a mask associated to it, in which case the style will be set
+                 to wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE.
+
         @see wxBitmap
     */
     void SetStipple(const wxBitmap& bitmap);
 
     /**
         Sets the brush style.
         @see wxBitmap
     */
     void SetStipple(const wxBitmap& bitmap);
 
     /**
         Sets the brush style.
-        
+
         @param style
         @param style
-            One of:
-        
-        
-        
-        
-        
-        
-            wxTRANSPARENT
-        
-        
-        
-        
-            Transparent (no fill).
-        
-        
-        
-        
-        
-            wxSOLID
-        
-        
-        
-        
-            Solid.
-        
-        
-        
-        
-        
-            wxBDIAGONAL_HATCH
-        
-        
-        
-        
-            Backward diagonal hatch.
-        
-        
-        
-        
-        
-            wxCROSSDIAG_HATCH
-        
-        
-        
-        
-            Cross-diagonal hatch.
-        
-        
-        
-        
-        
-            wxFDIAGONAL_HATCH
-        
-        
-        
-        
-            Forward diagonal hatch.
-        
-        
-        
-        
-        
-            wxCROSS_HATCH
-        
-        
-        
-        
-            Cross hatch.
-        
-        
-        
-        
-        
-            wxHORIZONTAL_HATCH
-        
-        
-        
-        
-            Horizontal hatch.
-        
-        
-        
-        
-        
-            wxVERTICAL_HATCH
-        
-        
-        
-        
-            Vertical hatch.
-        
-        
-        
-        
-        
-            wxSTIPPLE
-        
-        
-        
-        
-            Stippled using a bitmap.
-        
-        
-        
-        
-        
-            wxSTIPPLE_MASK_OPAQUE
-        
-        
-        
-        
-            Stippled using a bitmap's mask.
-        
+            One of the ::wxBrushStyle values.
+
         @see GetStyle()
     */
         @see GetStyle()
     */
-    void SetStyle(int style);
+    void SetStyle(wxBrushStyle style);
 
     /**
         Inequality operator.
 
     /**
         Inequality operator.
-        See @ref overview_refcountequality "reference-counted object comparison" for
-        more info.
+        See @ref overview_refcount_equality for more info.
     */
     bool operator !=(const wxBrush& brush);
 
     /**
     */
     bool operator !=(const wxBrush& brush);
 
     /**
-        Assignment operator, using @ref overview_trefcount "reference counting".
+        Assignment operator, using @ref overview_refcount "reference counting".
     */
     wxBrush operator =(const wxBrush& brush);
 
     /**
         Equality operator.
     */
     wxBrush operator =(const wxBrush& brush);
 
     /**
         Equality operator.
-        See @ref overview_refcountequality "reference-counted object comparison" for
-        more info.
+        See @ref overview_refcount_equality for more info.
     */
     bool operator ==(const wxBrush& brush);
 };
 
     */
     bool operator ==(const wxBrush& brush);
 };
 
-
 /**
 /**
-    FIXME
-*/
-wxBrush Objects:
-;
-
-/**
-    FIXME
+    An empty brush.
 */
 wxBrush wxNullBrush;
 
 /**
 */
 wxBrush wxNullBrush;
 
 /**
-    FIXME
+    Blue brush.
 */
 */
-wxBrush Pointers:
-;
+wxBrush* wxBLUE_BRUSH;
 
 /**
 
 /**
-    FIXME
+    Green brush.
 */
 */
-wxBrush wxBLUE_BRUSH;
+wxBrush* wxGREEN_BRUSH;
 
 /**
 
 /**
-    FIXME
+    White brush.
 */
 */
-wxBrush wxGREEN_BRUSH;
+wxBrush* wxWHITE_BRUSH;
 
 /**
 
 /**
-    FIXME
+    Black brush.
 */
 */
-wxBrush wxWHITE_BRUSH;
+wxBrush* wxBLACK_BRUSH;
 
 /**
 
 /**
-    FIXME
+    Grey brush.
 */
 */
-wxBrush wxBLACK_BRUSH;
+wxBrush* wxGREY_BRUSH;
 
 /**
 
 /**
-    FIXME
+    Medium grey brush.
 */
 */
-wxBrush wxGREY_BRUSH;
+wxBrush* wxMEDIUM_GREY_BRUSH;
 
 /**
 
 /**
-    FIXME
+    Light grey brush.
 */
 */
-wxBrush wxMEDIUM_GREY_BRUSH;
+wxBrush* wxLIGHT_GREY_BRUSH;
 
 /**
 
 /**
-    FIXME
+    Transparent brush.
 */
 */
-wxBrush wxLIGHT_GREY_BRUSH;
+wxBrush* wxTRANSPARENT_BRUSH;
 
 /**
 
 /**
-    FIXME
+    Cyan brush.
 */
 */
-wxBrush wxTRANSPARENT_BRUSH;
+wxBrush* wxCYAN_BRUSH;
 
 /**
 
 /**
-    FIXME
+    Red brush.
 */
 */
-wxBrush wxCYAN_BRUSH;
+wxBrush* wxRED_BRUSH;
+
+
 
 /**
 
 /**
-    FIXME
+    @class wxBrushList
+    @wxheader{gdicmn.h}
+
+    A brush list is a list containing all brushes which have been created.
+
+    @library{wxcore}
+    @category{gdi}
+
+    @see wxBrush
 */
 */
-wxBrush wxRED_BRUSH;
+class wxBrushList : public wxList
+{
+public:
+    /**
+        Constructor. The application should not construct its own brush list:
+        use the object pointer ::wxTheBrushList.
+    */
+    wxBrushList();
 
 
+    /**
+        Finds a brush with the specified attributes and returns it, else creates a new
+        brush, adds it to the brush list, and returns it.
 
 
+        @param colour
+            Colour object.
+        @param style
+            Brush style. See ::wxBrushStyle for a list of styles.
+    */
+    wxBrush* FindOrCreateBrush(const wxColour& colour,
+                               wxBrushStyle style = wxBRUSHSTYLE_SOLID);
+};
+
+/**
+    The global wxBrushList instance.
+*/
+wxBrushList* wxTheBrushList;
wxWidgets (Impactor)