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         @param colourName
  57             A colour name.
  58         @param width
  59             Pen width. Under Windows, the pen width cannot be greater than 1 if
  60             the style is wxDOT, wxLONG_DASH, wxSHORT_DASH, wxDOT_DASH, or wxUSER_DASH.
  61         @param stipple
  62             A stipple bitmap.
  63         @param pen
  64             A pointer or reference to a pen to copy.
  65         @param style
  66             The style may be one of the following:
  67
  68
  69
  70
  71
  72
  73             wxSOLID
  74
  75
  76
  77
  78             Solid style.
  79
  80
  81
  82
  83
  84             wxTRANSPARENT
  85
  86
  87
  88
  89             No pen is used.
  90
  91
  92
  93
  94
  95             wxDOT
  96
  97
  98
  99
 100             Dotted style.
 101
 102
 103
 104
 105
 106             wxLONG_DASH
 107
 108
 109
 110
 111             Long dashed style.
 112
 113
 114
 115
 116
 117             wxSHORT_DASH
 118
 119
 120
 121
 122             Short dashed style.
 123
 124
 125
 126
 127
 128             wxDOT_DASH
 129
 130
 131
 132
 133             Dot and dash style.
 134
 135
 136
 137
 138
 139             wxSTIPPLE
 140
 141
 142
 143
 144             Use the stipple bitmap.
 145
 146
 147
 148
 149
 150             wxUSER_DASH
 151
 152
 153
 154
 155             Use the user dashes: see SetDashes().
 156
 157
 158
 159
 160
 161             wxBDIAGONAL_HATCH
 162
 163
 164
 165
 166             Backward diagonal hatch.
 167
 168
 169
 170
 171
 172             wxCROSSDIAG_HATCH
 173
 174
 175
 176
 177             Cross-diagonal hatch.
 178
 179
 180
 181
 182
 183             wxFDIAGONAL_HATCH
 184
 185
 186
 187
 188             Forward diagonal hatch.
 189
 190
 191
 192
 193
 194             wxCROSS_HATCH
 195
 196
 197
 198
 199             Cross hatch.
 200
 201
 202
 203
 204
 205             wxHORIZONTAL_HATCH
 206
 207
 208
 209
 210             Horizontal hatch.
 211
 212
 213
 214
 215
 216             wxVERTICAL_HATCH
 217
 218
 219
 220
 221             Vertical hatch.
 222
 223         @remarks Different versions of Windows and different versions of other
 224                  platforms support very different subsets of the styles
 225                  above - there is no similarity even between Windows95
 226                  and Windows98 - so handle with care.
 227
 228         @see SetStyle(), SetColour(), SetWidth(), SetStipple()
 229     */
 230     wxPen();
 231     wxPen(const wxColour& colour, int width = 1,
 232           int style = wxSOLID);
 233     wxPen(const wxString& colourName, int width, int style);
 234     wxPen(const wxBitmap& stipple, int width);
 235     wxPen(const wxPen& pen);
 236     //@}
 237
 238     /**
 239         Destructor.
 240         See @ref overview_refcountdestruct "reference-counted object destruction" for
 241         more info.
 242
 243         @remarks Although all remaining pens are deleted when the application
 244                  exits, the application should try to clean up all pens
 245                  itself. This is because wxWidgets cannot know if a
 246                  pointer to the pen object is stored in an application
 247                  data structure, and there is a risk of double deletion.
 248     */
 249     ~wxPen();
 250
 251     /**
 252         Returns the pen cap style, which may be one of @b wxCAP_ROUND, @b
 253         wxCAP_PROJECTING and
 254         @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
 255
 256         @see SetCap()
 257     */
 258     int GetCap() const;
 259
 260     /**
 261         Returns a reference to the pen colour.
 262
 263         @see SetColour()
 264     */
 265     wxColour GetColour() const;
 266
 267     /**
 268         Gets an array of dashes (defined as char in X, DWORD under Windows).
 269         @a dashes is a pointer to the internal array. Do not deallocate or store this
 270         pointer.
 271         The function returns the number of dashes associated with this pen.
 272
 273         @see SetDashes()
 274     */
 275     int GetDashes(wxDash** dashes) const;
 276
 277     /**
 278         Returns the pen join style, which may be one of @b wxJOIN_BEVEL, @b
 279         wxJOIN_ROUND and
 280         @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
 281
 282         @see SetJoin()
 283     */
 284     int GetJoin() const;
 285
 286     /**
 287         Gets a pointer to the stipple bitmap.
 288
 289         @see SetStipple()
 290     */
 291     wxBitmap* GetStipple() const;
 292
 293     /**
 294         Returns the pen style.
 295
 296         @see wxPen(), SetStyle()
 297     */
 298     int GetStyle() const;
 299
 300     /**
 301         Returns the pen width.
 302
 303         @see SetWidth()
 304     */
 305     int GetWidth() const;
 306
 307     /**
 308         Returns @true if the pen is initialised.
 309     */
 310     bool IsOk() const;
 311
 312     /**
 313         Sets the pen cap style, which may be one of @b wxCAP_ROUND, @b wxCAP_PROJECTING
 314         and
 315         @b wxCAP_BUTT. The default is @b wxCAP_ROUND.
 316
 317         @see GetCap()
 318     */
 319     void SetCap(int capStyle);
 320
 321     //@{
 322     /**
 323         The pen's colour is changed to the given colour.
 324
 325         @see GetColour()
 326     */
 327     void SetColour(wxColour& colour);
 328     void SetColour(const wxString& colourName);
 329     void SetColour(unsigned char red, unsigned char green,
 330                    unsigned char blue);
 331     //@}
 332
 333     /**
 334         Associates an array of pointers to dashes (defined as char in X, DWORD under
 335         Windows)
 336         with the pen. The array is not deallocated by wxPen, but neither must it be
 337         deallocated by the calling application until the pen is deleted or this
 338         function is called with a @NULL array.
 339
 340         @see GetDashes()
 341     */
 342     void SetDashes(int n, wxDash* dashes);
 343
 344     /**
 345         Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND
 346         and
 347         @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
 348
 349         @see GetJoin()
 350     */
 351     void SetJoin(int join_style);
 352
 353     /**
 354         Sets the bitmap for stippling.
 355
 356         @see GetStipple()
 357     */
 358     void SetStipple(wxBitmap* stipple);
 359
 360     /**
 361         Set the pen style.
 362
 363         @see wxPen()
 364     */
 365     void SetStyle(int style);
 366
 367     /**
 368         Sets the pen width.
 369
 370         @see GetWidth()
 371     */
 372     void SetWidth(int width);
 373
 374     /**
 375         Inequality operator.
 376         See @ref overview_refcountequality "reference-counted object comparison" for
 377         more info.
 378     */
 379     bool operator !=(const wxPen& pen);
 380
 381     /**
 382         Assignment operator, using @ref overview_trefcount "reference counting".
 383     */
 384     wxPen operator =(const wxPen& pen);
 385
 386     /**
 387         Equality operator.
 388         See @ref overview_refcountequality "reference-counted object comparison" for
 389         more info.
 390     */
 391     bool operator ==(const wxPen& pen);
 392 };