mac paths updated

[wxWidgets.git] / interface / brush.h

diff --git a/interface/brush.h b/interface/brush.h
index f4752aa3e7d3531c2ab3c8ddbdff610c2f9fc935..f98b98525fbde881f3116ced1c753581a45dd6b1 100644 (file)
--- a/interface/brush.h
+++ b/interface/brush.h
@@ -1,333 +1,308 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        brush.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        brush.h

-// Purpose:     documentation for wxBrush class
+// Purpose:     interface of wxBrush

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 /**
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 /**

-    @class wxBrush
-    @wxheader{brush.h}
+    The possible brush styles.
+*/
+enum wxBrushStyle
+{
+    wxBRUSHSTYLE_INVALID = -1,

 
 

-    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.
+    wxBRUSHSTYLE_SOLID = wxSOLID,
+        /**< Solid. */

 
 

-    @library{wxcore}
-    @category{gdi}
+    wxBRUSHSTYLE_TRANSPARENT = wxTRANSPARENT,
+        /**< Transparent (no fill). */

 
 

-    @stdobjects
-    Objects:
-    wxNullBrush
-    Pointers:
-    wxBLUE_BRUSH
+    wxBRUSHSTYLE_STIPPLE_MASK_OPAQUE = wxSTIPPLE_MASK_OPAQUE,
+        /**< @todo WHAT's THIS?? */
+
+    wxBRUSHSTYLE_STIPPLE_MASK = wxSTIPPLE_MASK,
+        /**< @todo WHAT's THIS?? */

 
 

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

 
 

-    wxWHITE_BRUSH
+    wxBRUSHSTYLE_BDIAGONAL_HATCH = wxBDIAGONAL_HATCH,
+        /**< Backward diagonal hatch. */

 
 

-    wxBLACK_BRUSH
+    wxBRUSHSTYLE_CROSSDIAG_HATCH = wxCROSSDIAG_HATCH,
+        /**< Cross-diagonal hatch. */

 
 

-    wxGREY_BRUSH
+    wxBRUSHSTYLE_FDIAGONAL_HATCH = wxFDIAGONAL_HATCH,
+        /**< Forward diagonal hatch. */

 
 

-    wxMEDIUM_GREY_BRUSH
+    wxBRUSHSTYLE_CROSS_HATCH = wxCROSS_HATCH,
+        /**< Cross hatch. */

 
 

-    wxLIGHT_GREY_BRUSH
+    wxBRUSHSTYLE_HORIZONTAL_HATCH = wxHORIZONTAL_HATCH,
+        /**< Horizontal hatch. */

 
 

-    wxTRANSPARENT_BRUSH
+    wxBRUSHSTYLE_VERTICAL_HATCH = wxVERTICAL_HATCH,
+        /**< Vertical hatch. */
+
+    wxBRUSHSTYLE_FIRST_HATCH = wxFIRST_HATCH,
+    wxBRUSHSTYLE_LAST_HATCH = wxLAST_HATCH,
+};

 
 

-    wxCYAN_BRUSH

 
 

-    wxRED_BRUSH

 
 

-    @seealso
-    wxBrushList, wxDC, wxDC::SetBrush
+/**
+    @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.
+
+    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
+    ::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:
 */
 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
         @param colour

-        Colour object.
-        
-        @param colourName
-        Colour name. The name will be looked up in the colour database.
-        
+            Colour object.

         @param style
         @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.
-        
-        @sa wxBrushList, wxColour, wxColourDatabase
+            One of the ::wxBrushStyle enumeration values.
+    */
+    wxBrush(const wxColour& colour, wxBrushStyle style = wxBRUSHSTYLE_SOLID);
+
+    /**
+        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();
+    virtual ~wxBrush();

 
     /**
         Returns a reference to the brush colour.
 
     /**
         Returns a reference to the brush colour.

-        
-        @sa SetColour()
+
+        @see SetColour()

     */
     */

-    wxColour GetColour();
+    virtual 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).
-        
-        @sa SetStipple()
+        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();
+    virtual 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.
-        
-        
-        @sa SetStyle(), SetColour(), SetStipple()
+        Returns the brush style, one of the ::wxBrushStyle values.
+
+        @see SetStyle(), SetColour(), SetStipple()

     */
     */

-    int GetStyle();
+    virtual 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.

-        
-        @sa GetStyle()
+
+        @see GetStyle()

     */
     */

-    bool IsHatch();
+    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. 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).
     */

-#define bool IsOk()     /* implementation is private */
+    bool IsOk() const;

 
     //@{
     /**
         Sets the brush colour using red, green and blue values.
 
     //@{
     /**
         Sets the brush colour using red, green and blue values.

-        
-        @sa GetColour()
+
+        @see GetColour()

     */
     */

-    void SetColour(wxColour& colour);
-    void SetColour(const wxString& colourName);
-    void SetColour(unsigned char red, unsigned char green,
-                   unsigned char blue);
+    virtual void SetColour(wxColour& colour);
+    virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue);

     //@}
 
     /**
         Sets the stipple bitmap.
     //@}
 
     /**
         Sets the stipple bitmap.

-        
+

         @param bitmap
         @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.
-        
-        @sa wxBitmap
+            The bitmap to use for stippling.
+
+        @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);
+    virtual void SetStipple(const wxBitmap& bitmap);

 
     /**
         Sets the brush style.
 
     /**
         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.
-        
-        @sa GetStyle()
+            One of the ::wxBrushStyle values.
+
+        @see GetStyle()

     */
     */

-    void SetStyle(int style);
+    virtual 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) const;

 
     /**
 
     /**

-        Assignment operator, using @ref overview_trefcount "reference counting".
+        Equality operator.
+        See @ref overview_refcount_equality for more info.

     */
     */

-    wxBrush operator =(const wxBrush& brush);
+    bool operator ==(const wxBrush& brush) const;
+};
+
+/**
+    An empty brush.
+*/
+wxBrush wxNullBrush;
+
+/**
+    Blue brush.
+*/
+wxBrush* wxBLUE_BRUSH;

 
 

+/**
+    Green brush.
+*/
+wxBrush* wxGREEN_BRUSH;
+
+/**
+    White brush.
+*/
+wxBrush* wxWHITE_BRUSH;
+
+/**
+    Black brush.
+*/
+wxBrush* wxBLACK_BRUSH;
+
+/**
+    Grey brush.
+*/
+wxBrush* wxGREY_BRUSH;
+
+/**
+    Medium grey brush.
+*/
+wxBrush* wxMEDIUM_GREY_BRUSH;
+
+/**
+    Light grey brush.
+*/
+wxBrush* wxLIGHT_GREY_BRUSH;
+
+/**
+    Transparent brush.
+*/
+wxBrush* wxTRANSPARENT_BRUSH;
+
+/**
+    Cyan brush.
+*/
+wxBrush* wxCYAN_BRUSH;
+
+/**
+    Red brush.
+*/
+wxBrush* wxRED_BRUSH;
+
+
+
+/**
+    @class wxBrushList
+    @wxheader{gdicmn.h}
+
+    A brush list is a list containing all brushes which have been created.
+
+    The application should not construct its own brush list: it should use the
+    object pointer ::wxTheBrushList.
+
+    @library{wxcore}
+    @category{gdi}
+
+    @see wxBrush
+*/
+class wxBrushList : public wxList
+{
+public:

     /**
     /**

-        Equality operator.
-        See @ref overview_refcountequality "reference-counted object comparison" for
-        more info.
+        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.

     */
     */

-    bool operator ==(const wxBrush& brush);
+    wxBrush* FindOrCreateBrush(const wxColour& colour,
+                               wxBrushStyle style = wxBRUSHSTYLE_SOLID);

 };
 };

+
+/**
+    The global wxBrushList instance.
+*/
+wxBrushList* wxTheBrushList;