interface/pen.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        pen.h
   3 // Purpose:     documentation for wxPen class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxPen
  11     @wxheader{pen.h}
  12
  13     A pen is a drawing tool for drawing outlines. It is used for drawing
  14     lines and painting the outline of rectangles, ellipses, etc. It has a
  15     colour, a width and a style.
  16
  17     @library{wxcore}
  18     @category{gdi}
  19
  20     @stdobjects
  21     Objects:
  22     wxNullPen
  23     Pointers:
  24     wxRED_PEN
  25
  26     wxCYAN_PEN
  27
  28     wxGREEN_PEN
  29
  30     wxBLACK_PEN
  31
  32     wxWHITE_PEN
  33
  34     wxTRANSPARENT_PEN
  35
  36     wxBLACK_DASHED_PEN
  37
  38     wxGREY_PEN
  39
  40     wxMEDIUM_GREY_PEN
  41
  42     wxLIGHT_GREY_PEN
  43
  44     @seealso
  45     wxPenList, wxDC, wxDC::SetPen
  46 */
  47 class wxPen : public wxGDIObject
  48 {
  49 public:
  50     //@{
  51     /**
  52         Copy constructor, uses @ref overview_trefcount "reference counting".
  53
  54         @param colour
  55         A colour object.
  56
  57         @param colourName
  58         A colour name.
  59
  60         @param width
  61         Pen width. Under Windows, the pen width cannot be greater than 1 if
  62         the style is wxDOT, wxLONG_DASH, wxSHORT_DASH, wxDOT_DASH, or wxUSER_DASH.
  63
  64         @param stipple
  65         A stipple bitmap.
  66
  67         @param pen
  68         A pointer or reference to a pen to copy.
  69
  70         @param style
  71         The style may be one of the following:
  72
  73         wxSOLID
  74
  75
  76         Solid style.
  77
  78         wxTRANSPARENT
  79
  80
  81         No pen is used.
  82
  83         wxDOT
  84
  85
  86         Dotted style.
  87
  88         wxLONG_DASH
  89
  90
  91         Long dashed style.
  92
  93         wxSHORT_DASH
  94
  95
  96         Short dashed style.
  97
  98         wxDOT_DASH
  99
 100
 101         Dot and dash style.
 102
 103         wxSTIPPLE
 104
 105
 106         Use the stipple bitmap.
 107
 108         wxUSER_DASH
 109
 110
 111         Use the user dashes: see SetDashes().
 112
 113         wxBDIAGONAL_HATCH
 114
 115
 116         Backward diagonal hatch.
 117
 118         wxCROSSDIAG_HATCH
 119
 120
 121         Cross-diagonal hatch.
 122
 123         wxFDIAGONAL_HATCH
 124
 125
 126         Forward diagonal hatch.
 127
 128         wxCROSS_HATCH
 129
 130
 131         Cross hatch.
 132
 133         wxHORIZONTAL_HATCH
 134
 135
 136         Horizontal hatch.
 137
 138         wxVERTICAL_HATCH
 139
 140
 141         Vertical hatch.
 142
 143         @remarks Different versions of Windows and different versions of other
 144                    platforms support very different subsets of the
 145                    styles above - there is no similarity even between
 146                    Windows95 and Windows98 - so handle with care.
 147
 148         @sa SetStyle(), SetColour(), SetWidth(), SetStipple()
 149     */
 150     wxPen();
 151     wxPen(const wxColour& colour, int width = 1,
 152           int style = wxSOLID);
 153     wxPen(const wxString& colourName, int width, int style);
 154     wxPen(const wxBitmap& stipple, int width);
 155     wxPen(const wxPen& pen);
 156     //@}
 157
 158     /**
 159         Destructor.
 160         See @ref overview_refcountdestruct "reference-counted object destruction" for
 161         more info.
 162
 163         @remarks Although all remaining pens are deleted when the application
 164                    exits, the application should try to clean up all
 165                    pens itself. This is because wxWidgets cannot know if
 166                    a pointer to the pen object is stored in an
 167                    application data structure, and there is a risk of
 168                    double deletion.
 169     */
 170     ~wxPen();
 171
 172     /**
 173         Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b
 174         wxCAP_PROJECTING and
 175         @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
 176
 177         @sa SetCap()
 178     */
 179     int GetCap();
 180
 181     /**
 182         Returns a reference to the pen colour.
 183
 184         @sa SetColour()
 185     */
 186     wxColour GetColour();
 187
 188     /**
 189         Gets an array of dashes (defined as char in X, DWORD under Windows).
 190         @e dashes is a pointer to the internal array. Do not deallocate or store this
 191         pointer.
 192         The function returns the number of dashes associated with this pen.
 193
 194         @sa SetDashes()
 195     */
 196     int GetDashes(wxDash** dashes);
 197
 198     /**
 199         Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b
 200         wxJOIN_ROUND and
 201         @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
 202
 203         @sa SetJoin()
 204     */
 205     int GetJoin();
 206
 207     /**
 208         Gets a pointer to the stipple bitmap.
 209
 210         @sa SetStipple()
 211     */
 212     wxBitmap* GetStipple();
 213
 214     /**
 215         Returns the pen style.
 216
 217         @sa wxPen(), SetStyle()
 218     */
 219     int GetStyle();
 220
 221     /**
 222         Returns the pen width.
 223
 224         @sa SetWidth()
 225     */
 226     int GetWidth();
 227
 228     /**
 229         Returns @true if the pen is initialised.
 230     */
 231 #define bool IsOk()     /* implementation is private */
 232
 233     /**
 234         Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING
 235         and
 236         @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
 237
 238         @sa GetCap()
 239     */
 240     void SetCap(int capStyle);
 241
 242     //@{
 243     /**
 244         The pen's colour is changed to the given colour.
 245
 246         @sa GetColour()
 247     */
 248     void SetColour(wxColour& colour);
 249     void SetColour(const wxString& colourName);
 250     void SetColour(unsigned char red, unsigned char green,
 251                    unsigned char blue);
 252     //@}
 253
 254     /**
 255         Associates an array of pointers to dashes (defined as char in X, DWORD under
 256         Windows)
 257         with the pen. The array is not deallocated by wxPen, but neither must it be
 258         deallocated by the calling application until the pen is deleted or this
 259         function is called with a @NULL array.
 260
 261         @sa GetDashes()
 262     */
 263     void SetDashes(int n, wxDash* dashes);
 264
 265     /**
 266         Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND
 267         and
 268         @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
 269
 270         @sa GetJoin()
 271     */
 272     void SetJoin(int join_style);
 273
 274     /**
 275         Sets the bitmap for stippling.
 276
 277         @sa GetStipple()
 278     */
 279     void SetStipple(wxBitmap* stipple);
 280
 281     /**
 282         Set the pen style.
 283
 284         @sa wxPen()
 285     */
 286     void SetStyle(int style);
 287
 288     /**
 289         Sets the pen width.
 290
 291         @sa GetWidth()
 292     */
 293     void SetWidth(int width);
 294
 295     /**
 296         Inequality operator.
 297         See @ref overview_refcountequality "reference-counted object comparison" for
 298         more info.
 299     */
 300     bool operator !=(const wxPen& pen);
 301
 302     /**
 303         Assignment operator, using @ref overview_trefcount "reference counting".
 304     */
 305     wxPen operator =(const wxPen& pen);
 306
 307     /**
 308         Equality operator.
 309         See @ref overview_refcountequality "reference-counted object comparison" for
 310         more info.
 311     */
 312     bool operator ==(const wxPen& pen);
 313 };