// 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.
+
+ Note that hatched pen styles are not supported by X11-based ports,
+ including wxGTK.
*/
enum wxPenStyle
{
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). */
};
/**
@stdobjects
@li ::wxNullPen
- @li ::wxRED_PEN
+ @li ::wxBLACK_DASHED_PEN
+ @li ::wxBLACK_PEN
+ @li ::wxBLUE_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 ::wxMEDIUM_GREY_PEN
@li ::wxLIGHT_GREY_PEN
+ @li ::wxMEDIUM_GREY_PEN
+ @li ::wxRED_PEN
+ @li ::wxTRANSPARENT_PEN
+ @li ::wxWHITE_PEN
@see wxPenList, wxDC, wxDC::SetPen()
*/
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
- 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()
*/
@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.
+ @onlyfor{wxmsw,wxosx}
+
@see SetWidth(), SetStipple()
*/
wxPen(const wxBitmap& stipple, int width);
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.
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.
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.
/**
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.
*/
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
and @c wxCAP_BUTT. The default is @c wxCAP_ROUND.
//@}
/**
- 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
/**
An empty pen.
+ wxPen::IsOk() always returns @false for this object.
*/
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;
+/**
+ 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.
+ 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.
+ Except for the color it has all standard attributes
+ (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
*/
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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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.
+ 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;
projects / wxWidgets.git / blobdiff