Make storing non-trivial data in wxThreadSpecificInfo possible.

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

diff --git a/interface/wx/pen.h b/interface/wx/pen.h
index 02368092d58559316fd74fc0de3e268b2b2abc27..2cfc12f5b92c997ef90931f48fc88fcce89b2311 100644 (file)
--- a/interface/wx/pen.h
+++ b/interface/wx/pen.h
@@ -2,12 +2,14 @@
 // Name:        pen.h
 // Purpose:     interface of wxPen* classes
 // Author:      wxWidgets team
 // Name:        pen.h
 // Purpose:     interface of wxPen* classes
 // Author:      wxWidgets team

-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     The possible styles for a wxPen.
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     The possible styles for a wxPen.

+
+    Note that hatched pen styles are not supported by X11-based ports,
+    including wxGTK.

 */
 enum wxPenStyle
 {
 */
 enum wxPenStyle
 {


@@ -61,8 +63,11 @@ enum wxPenStyle
     wxPENSTYLE_VERTICAL_HATCH,
         /**< Vertical hatch. */
 
     wxPENSTYLE_VERTICAL_HATCH,
         /**< Vertical hatch. */
 

-    wxPENSTYLE_FIRST_HATCH = wxPENSTYLE_BDIAGONAL_HATCH,
-    wxPENSTYLE_LAST_HATCH = wxPENSTYLE_VERTICAL_HATCH
+    wxPENSTYLE_FIRST_HATCH,
+        /**< First of the hatch styles (inclusive). */
+
+    wxPENSTYLE_LAST_HATCH
+        /**< Last of the hatch styles (inclusive). */

 };
 
 /**
 };
 
 /**


@@ -98,7 +103,6 @@ enum wxPenCap
 
 /**
     @class wxPen
 
 /**
     @class wxPen

-    @wxheader{pen.h}

 
     A pen is a drawing tool for drawing outlines. It is used for drawing
     lines and painting the outline of rectangles, ellipses, etc.
 
     A pen is a drawing tool for drawing outlines. It is used for drawing
     lines and painting the outline of rectangles, ellipses, etc.


@@ -130,16 +134,18 @@ enum wxPenCap
 
     @stdobjects
     @li ::wxNullPen
 
     @stdobjects
     @li ::wxNullPen

-    @li ::wxRED_PEN
+    @li ::wxBLACK_DASHED_PEN
+    @li ::wxBLACK_PEN
+    @li ::wxBLUE_PEN

     @li ::wxCYAN_PEN
     @li ::wxGREEN_PEN
     @li ::wxCYAN_PEN
     @li ::wxGREEN_PEN

-    @li ::wxBLACK_PEN
-    @li ::wxWHITE_PEN
-    @li ::wxTRANSPARENT_PEN
-    @li ::wxBLACK_DASHED_PEN
+    @li ::wxYELLOW_PEN

     @li ::wxGREY_PEN
     @li ::wxGREY_PEN

-    @li ::wxMEDIUM_GREY_PEN

     @li ::wxLIGHT_GREY_PEN
     @li ::wxLIGHT_GREY_PEN

+    @li ::wxMEDIUM_GREY_PEN
+    @li ::wxRED_PEN
+    @li ::wxTRANSPARENT_PEN
+    @li ::wxWHITE_PEN

 
     @see wxPenList, wxDC, wxDC::SetPen()
 */
 
     @see wxPenList, wxDC, wxDC::SetPen()
 */


@@ -158,14 +164,15 @@ public:
             A colour object.
         @param width
             Pen width. Under Windows, the pen width cannot be greater than 1 if
             A colour object.
         @param width
             Pen width. Under Windows, the pen width cannot be greater than 1 if

-            the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH.
+            the style is @c wxPENSTYLE_DOT, @c wxPENSTYLE_LONG_DASH, @c wxPENSTYLE_SHORT_DASH,
+            @c wxPENSTYLE_DOT_DASH, or @c wxPENSTYLE_USER_DASH.

         @param style
             The style may be one of the ::wxPenStyle values.
 
         @remarks Different versions of Windows and different versions of other
         @param style
             The style may be one of the ::wxPenStyle values.
 
         @remarks Different versions of Windows and different versions of other

-                 platforms support very different subsets of the styles
-                 above - there is no similarity even between Windows95
-                 and Windows98 - so handle with care.
+                 platforms support very different subsets of the styles above
+                 - there is no similarity even between Windows95 and Windows98 -
+                 so handle with care.

 
         @see SetStyle(), SetColour(), SetWidth()
     */
 
         @see SetStyle(), SetColour(), SetWidth()
     */


@@ -176,10 +183,13 @@ public:
 
         @param width
             Pen width. Under Windows, the pen width cannot be greater than 1 if
 
         @param width
             Pen width. Under Windows, the pen width cannot be greater than 1 if

-            the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH.
+            the style is @c wxPENSTYLE_DOT, @c wxPENSTYLE_LONG_DASH, @c wxPENSTYLE_SHORT_DASH,
+            @c wxPENSTYLE_DOT_DASH, or @c wxPENSTYLE_USER_DASH.

         @param stipple
             A stipple bitmap.
 
         @param stipple
             A stipple bitmap.
 

+        @onlyfor{wxmsw,wxosx}
+

         @see SetWidth(), SetStipple()
     */
     wxPen(const wxBitmap& stipple, int width);
         @see SetWidth(), SetStipple()
     */
     wxPen(const wxBitmap& stipple, int width);


@@ -202,11 +212,11 @@ public:
                  pointer to the pen object is stored in an application
                  data structure, and there is a risk of double deletion.
     */
                  pointer to the pen object is stored in an application
                  data structure, and there is a risk of double deletion.
     */

-    ~wxPen();
+    virtual ~wxPen();

 
     /**
 
     /**

-        Returns the pen cap style, which may be one of @c wxCAP_ROUND, @c
-        wxCAP_PROJECTING and @c wxCAP_BUTT.
+        Returns the pen cap style, which may be one of @c wxCAP_ROUND,
+        @c wxCAP_PROJECTING and @c wxCAP_BUTT.

 
         The default is @c wxCAP_ROUND.
 
 
         The default is @c wxCAP_ROUND.
 


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

-        Gets an array of dashes (defined as char in X, DWORD under Windows).
+        Gets an array of dashes (defined as @c char in X, @c DWORD under Windows).

         @a dashes is a pointer to the internal array. Do not deallocate or store this
         pointer.
 
         @a dashes is a pointer to the internal array. Do not deallocate or store this
         pointer.
 


@@ -233,8 +243,8 @@ public:
     virtual int GetDashes(wxDash** dashes) const;
 
     /**
     virtual int GetDashes(wxDash** dashes) const;
 
     /**

-        Returns the pen join style, which may be one of @c wxJOIN_BEVEL, @c
-        wxJOIN_ROUND and @c wxJOIN_MITER.
+        Returns the pen join style, which may be one of @c wxJOIN_BEVEL,
+        @c wxJOIN_ROUND and @c wxJOIN_MITER.

 
         The default is @c wxJOIN_ROUND.
 
 
         The default is @c wxJOIN_ROUND.
 


@@ -265,8 +275,42 @@ public:
 
     /**
         Returns @true if the pen is initialised.
 
     /**
         Returns @true if the pen is initialised.

+
+        Notice that an uninitialized pen object can't be queried for any pen
+        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 pen is a valid non-transparent pen.
+
+        This method returns @true if the pen 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
+        wxPENSTYLE_TRANSPARENT if the pen may be invalid as GetStyle() would
+        assert in this case.
+
+        @see IsTransparent()
+
+        @since 2.9.2.
+     */
+    bool IsNonTransparent() const;
+
+    /**
+        Returns @true if the pen is transparent.
+
+        A transparent pen is simply a pen with wxPENSTYLE_TRANSPARENT style.
+
+        Notice that this function works even for non-initialized pens (for
+        which it returns @false) unlike tests of the form <code>GetStyle() ==
+        wxPENSTYLE_TRANSPARENT</code> which would assert if the pen is invalid.
+
+        @see IsNonTransparent()
+
+        @since 2.9.2.
+     */
+    bool IsTransparent() const;

 
     /**
         Sets the pen cap style, which may be one of @c wxCAP_ROUND, @c wxCAP_PROJECTING
 
     /**
         Sets the pen cap style, which may be one of @c wxCAP_ROUND, @c wxCAP_PROJECTING


@@ -287,7 +331,7 @@ public:
     //@}
 
     /**
     //@}
 
     /**

-        Associates an array of pointers to dashes (defined as char in X, DWORD under
+        Associates an array of dash values (defined as @c char in X, @c DWORD under

         Windows) with the pen.
 
         The array is not deallocated by wxPen, but neither must it be deallocated by
         Windows) with the pen.
 
         The array is not deallocated by wxPen, but neither must it be deallocated by


@@ -296,7 +340,7 @@ public:
 
         @see GetDashes()
     */
 
         @see GetDashes()
     */

-    virtual void SetDashes(int n, wxDash* dashes);
+    virtual void SetDashes(int n, const wxDash* dash);

 
     /**
         Sets the pen join style, which may be one of @c wxJOIN_BEVEL, @c wxJOIN_ROUND
 
     /**
         Sets the pen join style, which may be one of @c wxJOIN_BEVEL, @c wxJOIN_ROUND


@@ -313,7 +357,7 @@ public:
 
         @see GetStipple()
     */
 
         @see GetStipple()
     */

-    virtual void SetStipple(wxBitmap* stipple);
+    virtual void SetStipple(const wxBitmap& stipple);

 
     /**
         Set the pen style.
 
     /**
         Set the pen style.


@@ -335,12 +379,12 @@ public:
         See @ref overview_refcount_equality "reference-counted object comparison" for
         more info.
     */
         See @ref overview_refcount_equality "reference-counted object comparison" for
         more info.
     */

-    bool operator !=(const wxPen& pen);
+    bool operator!=(const wxPen& pen) const;

 
     /**
         Assignment operator, using @ref overview_refcount.
     */
 
     /**
         Assignment operator, using @ref overview_refcount.
     */

-    wxPen operator =(const wxPen& pen);
+    wxPen& operator=(const wxPen& pen);

 
     /**
         Equality operator.
 
     /**
         Equality operator.


@@ -348,61 +392,96 @@ public:
         See @ref overview_refcount_equality "reference-counted object comparison" for
         more info.
     */
         See @ref overview_refcount_equality "reference-counted object comparison" for
         more info.
     */

-    bool operator ==(const wxPen& pen);
+    bool operator==(const wxPen& pen) const;

 };
 
 /**
     An empty pen.
 };
 
 /**
     An empty pen.

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

 */
 wxPen wxNullPen;
 
 /**
     Red pen.
 */
 wxPen wxNullPen;
 
 /**
     Red pen.

+    Except for the color it has all standard attributes
+    (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).

 */
 wxPen* wxRED_PEN;
 
 */
 wxPen* wxRED_PEN;
 

+/**
+    Blue pen.
+    Except for the color it has all standard attributes
+    (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
+*/
+wxPen* wxBLUE_PEN;
+

 /**
     Cyan pen.
 /**
     Cyan pen.

+    Except for the color it has all standard attributes
+    (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).

 */
 wxPen* wxCYAN_PEN;
 
 /**
     Green pen.
 */
 wxPen* wxCYAN_PEN;
 
 /**
     Green pen.

+    Except for the color it has all standard attributes
+    (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).

 */
 wxPen* wxGREEN_PEN;
 
 */
 wxPen* wxGREEN_PEN;
 

+/**
+    Yellow pen.
+    Except for the color it has all standard attributes
+    (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
+*/
+wxPen* wxYELLOW_PEN;
+

 /**
     Black pen.
 /**
     Black pen.

+    Except for the color it has all standard attributes
+    (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).

 */
 wxPen* wxBLACK_PEN;
 
 /**
     White pen.
 */
 wxPen* wxBLACK_PEN;
 
 /**
     White pen.

+    Except for the color it has all standard attributes
+    (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).

 */
 wxPen* wxWHITE_PEN;
 
 /**
     Transparent pen.
 */
 wxPen* wxWHITE_PEN;
 
 /**
     Transparent pen.

+    Except for the color it has all standard attributes
+    (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).

 */
 wxPen* wxTRANSPARENT_PEN;
 
 /**
     Black dashed pen.
 */
 wxPen* wxTRANSPARENT_PEN;
 
 /**
     Black dashed pen.

+    Except for the color and for the @c wxPENSTYLE_SHORT_DASH it has all standard attributes
+    (1-pixel width, @c wxCAP_ROUND style, etc...).

 */
 wxPen* wxBLACK_DASHED_PEN;
 
 /**
     Grey pen.
 */
 wxPen* wxBLACK_DASHED_PEN;
 
 /**
     Grey pen.

+    Except for the color it has all standard attributes
+    (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).

 */
 wxPen* wxGREY_PEN;
 
 /**
     Medium-grey pen.
 */
 wxPen* wxGREY_PEN;
 
 /**
     Medium-grey pen.

+    Except for the color it has all standard attributes
+    (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).

 */
 wxPen* wxMEDIUM_GREY_PEN;
 
 /**
     Light-grey pen.
 */
 wxPen* wxMEDIUM_GREY_PEN;
 
 /**
     Light-grey pen.

+    Except for the color it has all standard attributes
+    (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).

 */
 wxPen* wxLIGHT_GREY_PEN;
 
 */
 wxPen* wxLIGHT_GREY_PEN;
 


@@ -410,7 +489,6 @@ wxPen* wxLIGHT_GREY_PEN;
 
 /**
     @class wxPenList
 
 /**
     @class wxPenList

-    @wxheader{gdicmn.h}

 
     There is only one instance of this class: ::wxThePenList.
     Use this object to search for a previously created pen of the desired
 
     There is only one instance of this class: ::wxThePenList.
     Use this object to search for a previously created pen of the desired