interface/pen.h

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