added a unit test for input/output file streams and fixed the problem it exposed...

[wxWidgets.git] / interface / pen.h

diff --git a/interface/pen.h b/interface/pen.h
index 9a9a2833ac41c1d4993b8fb4d286faeb37bf05b6..02368092d58559316fd74fc0de3e268b2b2abc27 100644 (file)
--- a/interface/pen.h
+++ b/interface/pen.h
@@ -1,224 +1,201 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        pen.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        pen.h

-// Purpose:     interface of wxPen
+// Purpose:     interface of wxPen* classes

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

+/**
+    The possible styles for a wxPen.
+*/
+enum wxPenStyle
+{
+    wxPENSTYLE_INVALID = -1,
+
+    wxPENSTYLE_SOLID,
+        /**< Solid style. */
+
+    wxPENSTYLE_DOT,
+        /**< Dotted style. */
+
+    wxPENSTYLE_LONG_DASH,
+        /**< Long dashed style. */
+
+    wxPENSTYLE_SHORT_DASH,
+        /**< Short dashed style. */
+
+    wxPENSTYLE_DOT_DASH,
+        /**< Dot and dash style. */
+
+    wxPENSTYLE_USER_DASH,
+        /**< Use the user dashes: see wxPen::SetDashes. */
+
+    wxPENSTYLE_TRANSPARENT,
+        /**< No pen is used. */
+
+    wxPENSTYLE_STIPPLE_MASK_OPAQUE,
+        /**< @todo WHAT's this? */
+
+    wxPENSTYLE_STIPPLE_MASK,
+        /**< @todo WHAT's this? */
+
+    wxPENSTYLE_STIPPLE,
+        /**< Use the stipple bitmap. */
+
+    wxPENSTYLE_BDIAGONAL_HATCH,
+        /**< Backward diagonal hatch. */
+
+    wxPENSTYLE_CROSSDIAG_HATCH,
+        /**< Cross-diagonal hatch. */
+
+    wxPENSTYLE_FDIAGONAL_HATCH,
+        /**< Forward diagonal hatch. */
+
+    wxPENSTYLE_CROSS_HATCH,
+        /**< Cross hatch. */
+
+    wxPENSTYLE_HORIZONTAL_HATCH,
+        /**< Horizontal hatch. */
+
+    wxPENSTYLE_VERTICAL_HATCH,
+        /**< Vertical hatch. */
+
+    wxPENSTYLE_FIRST_HATCH = wxPENSTYLE_BDIAGONAL_HATCH,
+    wxPENSTYLE_LAST_HATCH = wxPENSTYLE_VERTICAL_HATCH
+};
+
+/**
+    The possible join values of a wxPen.
+
+    @todo use wxPENJOIN_ prefix
+*/
+enum wxPenJoin
+{
+    wxJOIN_INVALID = -1,
+
+    wxJOIN_BEVEL = 120,
+    wxJOIN_MITER,
+    wxJOIN_ROUND,
+};
+
+
+/**
+    The possible cap values of a wxPen.
+
+    @todo use wxPENCAP_ prefix
+*/
+enum wxPenCap
+{
+    wxCAP_INVALID = -1,
+
+    wxCAP_ROUND = 130,
+    wxCAP_PROJECTING,
+    wxCAP_BUTT
+};
+
+
+

 /**
     @class wxPen
     @wxheader{pen.h}
 
     A pen is a drawing tool for drawing outlines. It is used for drawing
 /**
     @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. It has a
-    colour, a width and a style.
+    lines and painting the outline of rectangles, ellipses, etc.
+    It has a colour, a width and a style.
+
+    @note On a monochrome display, wxWidgets shows all non-white pens as 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 dynamically create pens with different characteristics,
+    and there is the consequent danger that a large number of duplicate pens will
+    be created. Therefore an application may wish to get a pointer to a pen by using
+    the global list of pens ::wxThePenList, and calling the member function
+    wxPenList::FindOrCreatePen().
+    See wxPenList for more info.
+
+    This class uses @ref overview_refcount "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:, ::wxNullPen, ::Pointers:, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN,
-    ::wxBLACK_PEN, ::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN, ::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN,
-
-    @see wxPenList, wxDC, wxDC::SetPen
+    @li ::wxNullPen
+    @li ::wxRED_PEN
+    @li ::wxCYAN_PEN
+    @li ::wxGREEN_PEN
+    @li ::wxBLACK_PEN
+    @li ::wxWHITE_PEN
+    @li ::wxTRANSPARENT_PEN
+    @li ::wxBLACK_DASHED_PEN
+    @li ::wxGREY_PEN
+    @li ::wxMEDIUM_GREY_PEN
+    @li ::wxLIGHT_GREY_PEN
+
+    @see wxPenList, wxDC, wxDC::SetPen()

 */
 class wxPen : public wxGDIObject
 {
 public:
 */
 class wxPen : public wxGDIObject
 {
 public:

-    //@{

     /**
     /**

-        Copy constructor, uses @ref overview_trefcount "reference counting".
-        
+        Default constructor. The pen will be uninitialised, and IsOk() will return @false.
+    */
+    wxPen();
+
+    /**
+        Constructs a pen from a colour object, pen width and style.
+

         @param colour
             A colour object.
         @param colour
             A colour object.

-        @param colourName
-            A colour name.

         @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 wxDOT, wxLONG_DASH, wxSHORT_DASH, wxDOT_DASH, or wxUSER_DASH.
-        @param stipple
-            A stipple bitmap.
-        @param pen
-            A pointer or reference to a pen to copy.
+            the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH.

         @param style
         @param style

-            The style may be one of the following:
-        
-        
-        
-        
-        
-        
-            wxSOLID
-        
-        
-        
-        
-            Solid style.
-        
-        
-        
-        
-        
-            wxTRANSPARENT
-        
-        
-        
-        
-            No pen is used.
-        
-        
-        
-        
-        
-            wxDOT
-        
-        
-        
-        
-            Dotted style.
-        
-        
-        
-        
-        
-            wxLONG_DASH
-        
-        
-        
-        
-            Long dashed style.
-        
-        
-        
-        
-        
-            wxSHORT_DASH
-        
-        
-        
-        
-            Short dashed style.
-        
-        
-        
-        
-        
-            wxDOT_DASH
-        
-        
-        
-        
-            Dot and dash style.
-        
-        
-        
-        
-        
-            wxSTIPPLE
-        
-        
-        
-        
-            Use the stipple bitmap.
-        
-        
-        
-        
-        
-            wxUSER_DASH
-        
-        
-        
-        
-            Use the user dashes: see SetDashes().
-        
-        
-        
-        
-        
-            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.
-        
+            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.
         @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.

-        
-        @see SetStyle(), SetColour(), SetWidth(), SetStipple()
+
+        @see SetStyle(), SetColour(), SetWidth()
+    */
+    wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxPENSTYLE_SOLID);
+
+    /**
+        Constructs a stippled pen from a stipple bitmap and a width.
+
+        @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.
+        @param stipple
+            A stipple bitmap.
+
+        @see SetWidth(), SetStipple()

     */
     */

-    wxPen();
-    wxPen(const wxColour& colour, int width = 1,
-          int style = wxSOLID);
-    wxPen(const wxString& colourName, int width, int style);

     wxPen(const wxBitmap& stipple, int width);
     wxPen(const wxBitmap& stipple, int width);

+
+    /**
+        Copy constructor, uses @ref overview_refcount.
+
+        @param pen
+            A pointer or reference to a pen to copy.
+    */

     wxPen(const wxPen& pen);
     wxPen(const wxPen& pen);

-    //@}

 
     /**
         Destructor.
 
     /**
         Destructor.

-        See @ref overview_refcountdestruct "reference-counted object destruction" for
-        more info.
-        
+        @see @ref overview_refcount_destruct "reference-counted object destruction"
+

         @remarks Although all remaining pens are deleted when the application
                  exits, the application should try to clean up all pens
                  itself. This is because wxWidgets cannot know if a
         @remarks Although all remaining pens are deleted when the application
                  exits, the application should try to clean up all pens
                  itself. This is because wxWidgets cannot know if a


@@ -228,60 +205,63 @@ public:
     ~wxPen();
 
     /**
     ~wxPen();
 
     /**

-        Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b
-        wxCAP_PROJECTING and
-        @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
-        
+        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.
+

         @see SetCap()
     */
         @see SetCap()
     */

-    int GetCap() const;
+    virtual wxPenCap GetCap() const;

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

-        
+

         @see SetColour()
     */
         @see SetColour()
     */

-    wxColour GetColour() const;
+    virtual wxColour GetColour() const;

 
     /**
         Gets an array of dashes (defined as char in X, DWORD under Windows).
         @a dashes is a pointer to the internal array. Do not deallocate or store this
         pointer.
 
     /**
         Gets an array of dashes (defined as char in X, DWORD under Windows).
         @a dashes is a pointer to the internal array. Do not deallocate or store this
         pointer.

-        The function returns the number of dashes associated with this pen.
-        
+
+        @return The number of dashes associated with this pen.
+

         @see SetDashes()
     */
         @see SetDashes()
     */

-    int GetDashes(wxDash** dashes) const;
+    virtual int GetDashes(wxDash** dashes) const;

 
     /**
 
     /**

-        Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b
-        wxJOIN_ROUND and
-        @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
-        
+        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.
+

         @see SetJoin()
     */
         @see SetJoin()
     */

-    int GetJoin() const;
+    virtual wxPenJoin GetJoin() const;

 
     /**
         Gets a pointer to the stipple bitmap.
 
     /**
         Gets a pointer to the stipple bitmap.

-        
+

         @see SetStipple()
     */
         @see SetStipple()
     */

-    wxBitmap* GetStipple() const;
+    virtual wxBitmap* GetStipple() const;

 
     /**
         Returns the pen style.
 
     /**
         Returns the pen style.

-        
+

         @see wxPen(), SetStyle()
     */
         @see wxPen(), SetStyle()
     */

-    int GetStyle() const;
+    virtual wxPenStyle GetStyle() const;

 
     /**
         Returns the pen width.
 
     /**
         Returns the pen width.

-        
+

         @see SetWidth()
     */
         @see SetWidth()
     */

-    int GetWidth() const;
+    virtual int GetWidth() const;

 
     /**
         Returns @true if the pen is initialised.
 
     /**
         Returns @true if the pen is initialised.


@@ -289,153 +269,211 @@ public:
     bool IsOk() const;
 
     /**
     bool IsOk() const;
 
     /**

-        Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING
-        and
-        @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
-        
+        Sets 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.
+

         @see GetCap()
     */
         @see GetCap()
     */

-    void SetCap(int capStyle);
+    virtual void SetCap(wxPenCap capStyle);

 
     //@{
     /**
         The pen's colour is changed to the given colour.
 
     //@{
     /**
         The pen's colour is changed to the given colour.

-        
+

         @see 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);

     //@}
 
     /**
         Associates an array of pointers to dashes (defined as char in X, DWORD under
     //@}
 
     /**
         Associates an array of pointers to dashes (defined as char in X, DWORD under

-        Windows)
-        with the pen. The array is not deallocated by wxPen, but neither must it be
-        deallocated by the calling application until the pen is deleted or this
-        function is called with a @NULL array.
-        
+        Windows) with the pen.
+
+        The array is not deallocated by wxPen, but neither must it be deallocated by
+        the calling application until the pen is deleted or this function is called
+        with a @NULL array.
+

         @see GetDashes()
     */
         @see GetDashes()
     */

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

 
     /**
 
     /**

-        Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND
-        and
-        @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
-        
+        Sets 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.
+

         @see GetJoin()
     */
         @see GetJoin()
     */

-    void SetJoin(int join_style);
+    virtual void SetJoin(wxPenJoin join_style);

 
     /**
         Sets the bitmap for stippling.
 
     /**
         Sets the bitmap for stippling.

-        
+

         @see GetStipple()
     */
         @see GetStipple()
     */

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

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

-        
+

         @see wxPen()
     */
         @see wxPen()
     */

-    void SetStyle(int style);
+    virtual void SetStyle(wxPenStyle style);

 
     /**
         Sets the pen width.
 
     /**
         Sets the pen width.

-        
+

         @see GetWidth()
     */
         @see GetWidth()
     */

-    void SetWidth(int width);
+    virtual void SetWidth(int width);

 
     /**
         Inequality operator.
 
     /**
         Inequality operator.

-        See @ref overview_refcountequality "reference-counted object comparison" for
+
+        See @ref overview_refcount_equality "reference-counted object comparison" for

         more info.
     */
     bool operator !=(const wxPen& pen);
 
     /**
         more info.
     */
     bool operator !=(const wxPen& pen);
 
     /**

-        Assignment operator, using @ref overview_trefcount "reference counting".
+        Assignment operator, using @ref overview_refcount.

     */
     wxPen operator =(const wxPen& pen);
 
     /**
         Equality operator.
     */
     wxPen operator =(const wxPen& pen);
 
     /**
         Equality operator.

-        See @ref overview_refcountequality "reference-counted object comparison" for
+
+        See @ref overview_refcount_equality "reference-counted object comparison" for

         more info.
     */
     bool operator ==(const wxPen& pen);
 };
 
         more info.
     */
     bool operator ==(const wxPen& pen);
 };
 

-

 /**
 /**

-    FIXME
+    An empty pen.

 */
 */

-wxPen Objects:
-;
+wxPen wxNullPen;

 
 /**
 
 /**

-    FIXME
+    Red pen.

 */
 */

-wxPen wxNullPen;
+wxPen* wxRED_PEN;

 
 /**
 
 /**

-    FIXME
+    Cyan pen.

 */
 */

-wxPen Pointers:
-;
+wxPen* wxCYAN_PEN;

 
 /**
 
 /**

-    FIXME
+    Green pen.

 */
 */

-wxPen wxRED_PEN;
+wxPen* wxGREEN_PEN;

 
 /**
 
 /**

-    FIXME
+    Black pen.

 */
 */

-wxPen wxCYAN_PEN;
+wxPen* wxBLACK_PEN;

 
 /**
 
 /**

-    FIXME
+    White pen.

 */
 */

-wxPen wxGREEN_PEN;
+wxPen* wxWHITE_PEN;

 
 /**
 
 /**

-    FIXME
+    Transparent pen.

 */
 */

-wxPen wxBLACK_PEN;
+wxPen* wxTRANSPARENT_PEN;

 
 /**
 
 /**

-    FIXME
+    Black dashed pen.

 */
 */

-wxPen wxWHITE_PEN;
+wxPen* wxBLACK_DASHED_PEN;

 
 /**
 
 /**

-    FIXME
+    Grey pen.

 */
 */

-wxPen wxTRANSPARENT_PEN;
+wxPen* wxGREY_PEN;

 
 /**
 
 /**

-    FIXME
+    Medium-grey pen.

 */
 */

-wxPen wxBLACK_DASHED_PEN;
+wxPen* wxMEDIUM_GREY_PEN;

 
 /**
 
 /**

-    FIXME
+    Light-grey pen.

 */
 */

-wxPen wxGREY_PEN;
+wxPen* wxLIGHT_GREY_PEN;
+
+

 
 /**
 
 /**

-    FIXME
+    @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
+    type and create it if not already found. In some windowing systems,
+    the pen may be a scarce resource, so it can pay to reuse old
+    resources if possible. When an application finishes, all pens will
+    be deleted and their resources freed, eliminating the possibility of
+    'memory leaks'. However, it is best not to rely on this automatic
+    cleanup because it can lead to double deletion in some circumstances.
+
+    There are two mechanisms in recent versions of wxWidgets which make the
+    pen list less useful than it once was. Under Windows, scarce resources
+    are cleaned up internally if they are not being used. Also, a referencing
+    counting mechanism applied to all GDI objects means that some sharing
+    of underlying resources is possible. You don't have to keep track of pointers,
+    working out when it is safe delete a pen, because the referencing counting does
+    it for you. For example, you can set a pen in a device context, and then
+    immediately delete the pen you passed, because the pen is 'copied'.
+
+    So you may find it easier to ignore the pen list, and instead create
+    and copy pens as you see fit. If your Windows resource meter suggests
+    your application is using too many resources, you can resort to using
+    GDI lists to share objects explicitly.
+
+    The only compelling use for the pen list is for wxWidgets to keep
+    track of pens in order to clean them up on exit. It is also kept for
+    backward compatibility with earlier versions of wxWidgets.
+
+    @library{wxcore}
+    @category{gdi}
+
+    @stdobjects
+    ::wxThePenList
+
+    @see wxPen

 */
 */

-wxPen wxMEDIUM_GREY_PEN;
+class wxPenList
+{
+public:
+    /**
+        Constructor. The application should not construct its own pen list:
+        use the object pointer ::wxThePenList.
+    */
+    wxPenList();
+
+    /**
+        Finds a pen with the specified attributes and returns it, else creates a
+        new pen, adds it to the pen list, and returns it.
+
+        @param colour
+            Colour object.
+        @param width
+            Width of pen.
+        @param style
+            Pen style. See ::wxPenStyle for a list of styles.
+    */
+    wxPen* FindOrCreatePen(const wxColour& colour,
+                           int width = 1,
+                           wxPenStyle style = wxPENSTYLE_SOLID);
+};

 
 /**
 
 /**

-    FIXME
+    The global list of wxPen objects ready to be re-used (for better performances).

 */
 */

-wxPen wxLIGHT_GREY_PEN;
-
+wxPenList* wxThePenList;