[wxWidgets.git] / interface / pen.h

/////////////////////////////////////////////////////////////////////////////
// Name:        pen.h
// Purpose:     interface of wxPen* classes
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    The possible styles for a wxPen.
*/
enum wxPenStyle
{
    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,
    wxPENSTYLE_MAX
};

/**
    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
    lines and painting the outline of rectangles, ellipses, etc.
    It has a colour, a width and a style.

    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 the entry for wxPenList.

    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
    ::wxNullPen, ::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
*/
class wxPen : public wxGDIObject
{
public:
    /**
        Default constructor. The pen will be uninitialised, and wxPen:IsOk will return @false.
    */
    wxPen();

    /**
        Constructs a pen from a colour object, pen width and style.
    */
    wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxSOLID);

    /**
        Constructs a pen from a colour name, pen width and style.
    */
    wxPen(const wxString& colourName, int width, wxPenStyle style);

    /**
        Constructs a stippled pen from a stipple bitmap and a width.
    */
    wxPen(const wxBitmap& stipple, int width);

    /**
        Copy constructor, uses @ref overview_refcount "reference counting".

        @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
            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.
        @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.

        @see SetStyle(), SetColour(), SetWidth(), SetStipple()
    */
    wxPen(const wxPen& pen);

    /**
        Destructor.
        See @ref overview_refcountdestruct "reference-counted object destruction" for
        more info.

        @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
                 pointer to the pen object is stored in an application
                 data structure, and there is a risk of double deletion.
    */
    ~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.

        @see SetCap()
    */
    wxPenCap GetCap() const;

    /**
        Returns a reference to the pen colour.

        @see SetColour()
    */
    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.
        The function returns the number of dashes associated with this pen.

        @see SetDashes()
    */
    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.

        @see SetJoin()
    */
    wxPenJoin GetJoin() const;

    /**
        Gets a pointer to the stipple bitmap.

        @see SetStipple()
    */
    wxBitmap* GetStipple() const;

    /**
        Returns the pen style.

        @see wxPen(), SetStyle()
    */
    wxPenStyle GetStyle() const;

    /**
        Returns the pen width.

        @see SetWidth()
    */
    int GetWidth() const;

    /**
        Returns @true if the pen is initialised.
    */
    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.

        @see GetCap()
    */
    void SetCap(wxPenCap capStyle);

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

        @see GetColour()
    */
    void SetColour(wxColour& colour);
    void SetColour(const wxString& colourName);
    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
        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()
    */
    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.

        @see GetJoin()
    */
    void SetJoin(wxPenJoin join_style);

    /**
        Sets the bitmap for stippling.

        @see GetStipple()
    */
    void SetStipple(wxBitmap* stipple);

    /**
        Set the pen style.

        @see wxPen()
    */
    void SetStyle(wxPenStyle style);

    /**
        Sets the pen width.

        @see GetWidth()
    */
    void SetWidth(int width);

    /**
        Inequality operator.
        See @ref overview_refcountequality "reference-counted object comparison" for
        more info.
    */
    bool operator !=(const wxPen& pen);

    /**
        Assignment operator, using @ref overview_trefcount "reference counting".
    */
    wxPen operator =(const wxPen& pen);

    /**
        Equality operator.
        See @ref overview_refcountequality "reference-counted object comparison" for
        more info.
    */
    bool operator ==(const wxPen& pen);
};

/**
    FIXME
*/
wxPen wxNullPen;

/**
    FIXME
*/
wxPen wxRED_PEN;

/**
    FIXME
*/
wxPen wxCYAN_PEN;

/**
    FIXME
*/
wxPen wxGREEN_PEN;

/**
    FIXME
*/
wxPen wxBLACK_PEN;

/**
    FIXME
*/
wxPen wxWHITE_PEN;

/**
    FIXME
*/
wxPen wxTRANSPARENT_PEN;

/**
    FIXME
*/
wxPen wxBLACK_DASHED_PEN;

/**
    FIXME
*/
wxPen wxGREY_PEN;

/**
    FIXME
*/
wxPen wxMEDIUM_GREY_PEN;

/**
    FIXME
*/
wxPen wxLIGHT_GREY_PEN;


/**
    @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
*/
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, wxPenStyle style);
};

/**
    The global list of wxPen objects ready to be re-used (for better performances).
*/
wxPenList* wxThePenList;
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
23324ae1 FM	2	// Name: pen.h
8024723d	3	// Purpose: interface of wxPen* classes
23324ae1 FM	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
8024723d FM	9	/**
	10	The possible styles for a wxPen.
	11	*/
	12	enum wxPenStyle
	13	{
	14	wxPENSTYLE_SOLID,
	15	/*< Solid style. /
	16
	17	wxPENSTYLE_DOT,
	18	/*< Dotted style. /
	19
	20	wxPENSTYLE_LONG_DASH,
	21	/*< Long dashed style. /
	22
	23	wxPENSTYLE_SHORT_DASH,
	24	/*< Short dashed style. /
	25
	26	wxPENSTYLE_DOT_DASH,
	27	/*< Dot and dash style. /
	28
	29	wxPENSTYLE_USER_DASH,
	30	/*< Use the user dashes: see wxPen::SetDashes. /
	31
	32	wxPENSTYLE_TRANSPARENT,
	33	/*< No pen is used. /
	34
	35	wxPENSTYLE_STIPPLE_MASK_OPAQUE,
	36	/*< @todo WHAT's this? /
	37
	38	wxPENSTYLE_STIPPLE_MASK,
	39	/*< @todo WHAT's this? /
	40
	41	wxPENSTYLE_STIPPLE,
	42	/*< Use the stipple bitmap. /
	43
	44	wxPENSTYLE_BDIAGONAL_HATCH,
	45	/*< Backward diagonal hatch. /
	46
	47	wxPENSTYLE_CROSSDIAG_HATCH,
	48	/*< Cross-diagonal hatch. /
	49
	50	wxPENSTYLE_FDIAGONAL_HATCH,
	51	/*< Forward diagonal hatch. /
	52
	53	wxPENSTYLE_CROSS_HATCH,
	54	/*< Cross hatch. /
	55
	56	wxPENSTYLE_HORIZONTAL_HATCH,
	57	/*< Horizontal hatch. /
	58
	59	wxPENSTYLE_VERTICAL_HATCH,
	60	/*< Vertical hatch. /
	61
	62	wxPENSTYLE_FIRST_HATCH = wxPENSTYLE_BDIAGONAL_HATCH,
	63	wxPENSTYLE_LAST_HATCH = wxPENSTYLE_VERTICAL_HATCH,
	64	wxPENSTYLE_MAX
	65	};
	66
	67	/**
	68	The possible join values of a wxPen.
	69
	70	@todo use wxPENJOIN_ prefix
	71	*/
	72	enum wxPenJoin
73	{
74	wxJOIN_INVALID = -1,
75
76	wxJOIN_BEVEL = 120,
77	wxJOIN_MITER,
78	wxJOIN_ROUND,
79	};
80
81
82	/**
83	The possible cap values of a wxPen.
84
85	@todo use wxPENCAP_ prefix
86	*/
87	enum wxPenCap
88	{
89	wxCAP_INVALID = -1,
90
91	wxCAP_ROUND = 130,
92	wxCAP_PROJECTING,
93	wxCAP_BUTT
94	};
95
96
97
23324ae1 FM	98	/**
	99	@class wxPen
	100	@wxheader{pen.h}
7c913512	101
23324ae1	102	A pen is a drawing tool for drawing outlines. It is used for drawing
8024723d FM	103	lines and painting the outline of rectangles, ellipses, etc.
	104	It has a colour, a width and a style.
	105
	106	On a monochrome display, wxWidgets shows all non-white pens as black.
	107
	108	Do not initialize objects on the stack before the program commences,
	109	since other required structures may not have been set up yet.
	110	Instead, define global pointers to objects and create them in wxApp::OnInit
	111	or when required.
	112
	113	An application may wish to dynamically create pens with different characteristics,
	114	and there is the consequent danger that a large number of duplicate pens will
	115	be created. Therefore an application may wish to get a pointer to a pen by using
	116	the global list of pens wxThePenList, and calling the member function
	117	wxPenList::FindOrCreatePen().
	118	See the entry for wxPenList.
	119
	120	This class uses reference counting and copy-on-write internally so that
	121	assignments between two instances of this class are very cheap.
	122	You can therefore use actual objects instead of pointers without efficiency problems.
	123	If an instance of this class is changed it will create its own data internally
	124	so that other instances, which previously shared the data using the reference
	125	counting, are not affected.
7c913512	126
23324ae1 FM	127	@library{wxcore}
23324ae1 FM	128	@category{gdi}
7c913512	129
23324ae1	130	@stdobjects
8024723d FM	131	::wxNullPen, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN, ::wxBLACK_PEN,
	132	::wxWHITE_PEN, ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN,
	133	::wxMEDIUM_GREY_PEN, ::wxLIGHT_GREY_PEN
7c913512	134
e54c96f1	135	@see wxPenList, wxDC, wxDC::SetPen
23324ae1 FM	136	*/
	137	class wxPen : public wxGDIObject
	138	{
	139	public:
23324ae1	140	/**
8024723d FM	141	Default constructor. The pen will be uninitialised, and wxPen:IsOk will return @false.
	142	*/
	143	wxPen();
	144
	145	/**
	146	Constructs a pen from a colour object, pen width and style.
	147	*/
	148	wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxSOLID);
	149
	150	/**
	151	Constructs a pen from a colour name, pen width and style.
	152	*/
	153	wxPen(const wxString& colourName, int width, wxPenStyle style);
	154
	155	/**
	156	Constructs a stippled pen from a stipple bitmap and a width.
	157	*/
	158	wxPen(const wxBitmap& stipple, int width);
	159
	160	/**
	161	Copy constructor, uses @ref overview_refcount "reference counting".
	162
7c913512	163	@param colour
4cc4bfaf	164	A colour object.
7c913512	165	@param colourName
4cc4bfaf	166	A colour name.
7c913512	167	@param width
4cc4bfaf FM	168	Pen width. Under Windows, the pen width cannot be greater than 1 if
4cc4bfaf FM	169	the style is wxDOT, wxLONG_DASH, wxSHORT_DASH, wxDOT_DASH, or wxUSER_DASH.
7c913512	170	@param stipple
4cc4bfaf	171	A stipple bitmap.
7c913512	172	@param pen
4cc4bfaf	173	A pointer or reference to a pen to copy.
7c913512	174	@param style
8024723d FM	175	The style may be one of the ::wxPenStyle values.
8024723d FM	176
23324ae1	177	@remarks Different versions of Windows and different versions of other
4cc4bfaf FM	178	platforms support very different subsets of the styles
	179	above - there is no similarity even between Windows95
	180	and Windows98 - so handle with care.
8024723d	181
4cc4bfaf	182	@see SetStyle(), SetColour(), SetWidth(), SetStipple()
23324ae1	183	*/
7c913512	184	wxPen(const wxPen& pen);
23324ae1 FM	185
	186	/**
	187	Destructor.
	188	See @ref overview_refcountdestruct "reference-counted object destruction" for
	189	more info.
8024723d	190
23324ae1	191	@remarks Although all remaining pens are deleted when the application
4cc4bfaf FM	192	exits, the application should try to clean up all pens
	193	itself. This is because wxWidgets cannot know if a
	194	pointer to the pen object is stored in an application
	195	data structure, and there is a risk of double deletion.
23324ae1 FM	196	*/
	197	~wxPen();
	198
	199	/**
	200	Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b
	201	wxCAP_PROJECTING and
	202	@b wxCAP_BUTT. The default is @b wxCAP_ROUND.
8024723d	203
4cc4bfaf	204	@see SetCap()
23324ae1	205	*/
8024723d	206	wxPenCap GetCap() const;
23324ae1 FM	207
	208	/**
	209	Returns a reference to the pen colour.
8024723d	210
4cc4bfaf	211	@see SetColour()
23324ae1	212	*/
328f5751	213	wxColour GetColour() const;
23324ae1 FM	214
	215	/**
	216	Gets an array of dashes (defined as char in X, DWORD under Windows).
4cc4bfaf	217	@a dashes is a pointer to the internal array. Do not deallocate or store this
23324ae1 FM	218	pointer.
23324ae1 FM	219	The function returns the number of dashes associated with this pen.
8024723d	220
4cc4bfaf	221	@see SetDashes()
23324ae1	222	*/
328f5751	223	int GetDashes(wxDash** dashes) const;
23324ae1 FM	224
	225	/**
	226	Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b
	227	wxJOIN_ROUND and
	228	@b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
8024723d	229
4cc4bfaf	230	@see SetJoin()
23324ae1	231	*/
8024723d	232	wxPenJoin GetJoin() const;
23324ae1 FM	233
	234	/**
	235	Gets a pointer to the stipple bitmap.
8024723d	236
4cc4bfaf	237	@see SetStipple()
23324ae1	238	*/
328f5751	239	wxBitmap* GetStipple() const;
23324ae1 FM	240
	241	/**
	242	Returns the pen style.
8024723d	243
4cc4bfaf	244	@see wxPen(), SetStyle()
23324ae1	245	*/
8024723d	246	wxPenStyle GetStyle() const;
23324ae1 FM	247
	248	/**
	249	Returns the pen width.
8024723d	250
4cc4bfaf	251	@see SetWidth()
23324ae1	252	*/
328f5751	253	int GetWidth() const;
23324ae1 FM	254
	255	/**
	256	Returns @true if the pen is initialised.
	257	*/
328f5751	258	bool IsOk() const;
23324ae1 FM	259
	260	/**
	261	Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING
	262	and
	263	@b wxCAP_BUTT. The default is @b wxCAP_ROUND.
8024723d	264
4cc4bfaf	265	@see GetCap()
23324ae1	266	*/
8024723d	267	void SetCap(wxPenCap capStyle);
23324ae1 FM	268
	269	//@{
	270	/**
	271	The pen's colour is changed to the given colour.
8024723d	272
4cc4bfaf	273	@see GetColour()
23324ae1 FM	274	*/
23324ae1 FM	275	void SetColour(wxColour& colour);
7c913512 FM	276	void SetColour(const wxString& colourName);
	277	void SetColour(unsigned char red, unsigned char green,
	278	unsigned char blue);
23324ae1 FM	279	//@}
	280
	281	/**
	282	Associates an array of pointers to dashes (defined as char in X, DWORD under
	283	Windows)
	284	with the pen. The array is not deallocated by wxPen, but neither must it be
	285	deallocated by the calling application until the pen is deleted or this
	286	function is called with a @NULL array.
8024723d	287
4cc4bfaf	288	@see GetDashes()
23324ae1 FM	289	*/
	290	void SetDashes(int n, wxDash* dashes);
	291
	292	/**
	293	Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND
	294	and
	295	@b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
8024723d	296
4cc4bfaf	297	@see GetJoin()
23324ae1	298	*/
8024723d	299	void SetJoin(wxPenJoin join_style);
23324ae1 FM	300
	301	/**
	302	Sets the bitmap for stippling.
8024723d	303
4cc4bfaf	304	@see GetStipple()
23324ae1 FM	305	*/
	306	void SetStipple(wxBitmap* stipple);
	307
	308	/**
	309	Set the pen style.
8024723d	310
4cc4bfaf	311	@see wxPen()
23324ae1	312	*/
8024723d	313	void SetStyle(wxPenStyle style);
23324ae1 FM	314
	315	/**
	316	Sets the pen width.
8024723d	317
4cc4bfaf	318	@see GetWidth()
23324ae1 FM	319	*/
	320	void SetWidth(int width);
	321
	322	/**
	323	Inequality operator.
	324	See @ref overview_refcountequality "reference-counted object comparison" for
	325	more info.
	326	*/
	327	bool operator !=(const wxPen& pen);
	328
	329	/**
	330	Assignment operator, using @ref overview_trefcount "reference counting".
	331	*/
	332	wxPen operator =(const wxPen& pen);
	333
	334	/**
	335	Equality operator.
	336	See @ref overview_refcountequality "reference-counted object comparison" for
	337	more info.
	338	*/
	339	bool operator ==(const wxPen& pen);
	340	};
e54c96f1	341
e54c96f1 FM	342	/**
	343	FIXME
	344	*/
	345	wxPen wxNullPen;
	346
e54c96f1 FM	347	/**
	348	FIXME
	349	*/
	350	wxPen wxRED_PEN;
	351
	352	/**
	353	FIXME
	354	*/
	355	wxPen wxCYAN_PEN;
	356
	357	/**
	358	FIXME
	359	*/
	360	wxPen wxGREEN_PEN;
	361
	362	/**
	363	FIXME
	364	*/
	365	wxPen wxBLACK_PEN;
	366
	367	/**
	368	FIXME
	369	*/
	370	wxPen wxWHITE_PEN;
	371
	372	/**
	373	FIXME
	374	*/
	375	wxPen wxTRANSPARENT_PEN;
	376
	377	/**
	378	FIXME
	379	*/
	380	wxPen wxBLACK_DASHED_PEN;
	381
	382	/**
	383	FIXME
	384	*/
	385	wxPen wxGREY_PEN;
	386
	387	/**
	388	FIXME
	389	*/
	390	wxPen wxMEDIUM_GREY_PEN;
	391
	392	/**
	393	FIXME
	394	*/
	395	wxPen wxLIGHT_GREY_PEN;
	396
	397
8024723d FM	398
	399	/**
	400	@class wxPenList
	401	@wxheader{gdicmn.h}
	402
	403	There is only one instance of this class: ::wxThePenList.
	404	Use this object to search for a previously created pen of the desired
	405	type and create it if not already found. In some windowing systems,
	406	the pen may be a scarce resource, so it can pay to reuse old
	407	resources if possible. When an application finishes, all pens will
	408	be deleted and their resources freed, eliminating the possibility of
	409	'memory leaks'. However, it is best not to rely on this automatic
	410	cleanup because it can lead to double deletion in some circumstances.
	411
	412	There are two mechanisms in recent versions of wxWidgets which make the
	413	pen list less useful than it once was. Under Windows, scarce resources
	414	are cleaned up internally if they are not being used. Also, a referencing
	415	counting mechanism applied to all GDI objects means that some sharing
	416	of underlying resources is possible. You don't have to keep track of pointers,
	417	working out when it is safe delete a pen, because the referencing counting does
	418	it for you. For example, you can set a pen in a device context, and then
	419	immediately delete the pen you passed, because the pen is 'copied'.
	420
	421	So you may find it easier to ignore the pen list, and instead create
	422	and copy pens as you see fit. If your Windows resource meter suggests
	423	your application is using too many resources, you can resort to using
	424	GDI lists to share objects explicitly.
	425
	426	The only compelling use for the pen list is for wxWidgets to keep
	427	track of pens in order to clean them up on exit. It is also kept for
	428	backward compatibility with earlier versions of wxWidgets.
	429
	430	@library{wxcore}
	431	@category{gdi}
	432
	433	@stdobjects
	434	::wxThePenList
	435
	436	@see wxPen
	437	*/
	438	class wxPenList
	439	{
	440	public:
	441	/**
	442	Constructor. The application should not construct its own pen list:
	443	use the object pointer ::wxThePenList.
	444	*/
	445	wxPenList();
	446
	447	/**
	448	Finds a pen with the specified attributes and returns it, else creates a
	449	new pen, adds it to the pen list, and returns it.
	450
	451	@param colour
	452	Colour object.
	453	@param width
	454	Width of pen.
	455	@param style
	456	Pen style. See ::wxPenStyle for a list of styles.
	457	*/
	458	wxPen* FindOrCreatePen(const wxColour& colour, int width, wxPenStyle style);
	459	};
	460
	461	/**
462	The global list of wxPen objects ready to be re-used (for better performances).
463	*/
464	wxPenList* wxThePenList;
465