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