interface/wx/pen.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        pen.h
   3 // Purpose:     interface of wxPen* classes
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     The possible styles for a wxPen.
  11
  12     Note that hatched pen styles are not supported by X11-based ports,
  13     including wxGTK.
  14 */
  15 enum wxPenStyle
  16 {
  17     wxPENSTYLE_INVALID = -1,
  18
  19     wxPENSTYLE_SOLID,
  20         /**< Solid style. */
  21
  22     wxPENSTYLE_DOT,
  23         /**< Dotted style. */
  24
  25     wxPENSTYLE_LONG_DASH,
  26         /**< Long dashed style. */
  27
  28     wxPENSTYLE_SHORT_DASH,
  29         /**< Short dashed style. */
  30
  31     wxPENSTYLE_DOT_DASH,
  32         /**< Dot and dash style. */
  33
  34     wxPENSTYLE_USER_DASH,
  35         /**< Use the user dashes: see wxPen::SetDashes. */
  36
  37     wxPENSTYLE_TRANSPARENT,
  38         /**< No pen is used. */
  39
  40     wxPENSTYLE_STIPPLE_MASK_OPAQUE,
  41         /**< @todo WHAT's this? */
  42
  43     wxPENSTYLE_STIPPLE_MASK,
  44         /**< @todo WHAT's this? */
  45
  46     wxPENSTYLE_STIPPLE,
  47         /**< Use the stipple bitmap. */
  48
  49     wxPENSTYLE_BDIAGONAL_HATCH,
  50         /**< Backward diagonal hatch. */
  51
  52     wxPENSTYLE_CROSSDIAG_HATCH,
  53         /**< Cross-diagonal hatch. */
  54
  55     wxPENSTYLE_FDIAGONAL_HATCH,
  56         /**< Forward diagonal hatch. */
  57
  58     wxPENSTYLE_CROSS_HATCH,
  59         /**< Cross hatch. */
  60
  61     wxPENSTYLE_HORIZONTAL_HATCH,
  62         /**< Horizontal hatch. */
  63
  64     wxPENSTYLE_VERTICAL_HATCH,
  65         /**< Vertical hatch. */
  66
  67     wxPENSTYLE_FIRST_HATCH,
  68         /**< First of the hatch styles (inclusive). */
  69
  70     wxPENSTYLE_LAST_HATCH
  71         /**< Last of the hatch styles (inclusive). */
  72 };
  73
  74 /**
  75     The possible join values of a wxPen.
  76
  77     @todo use wxPENJOIN_ prefix
  78 */
  79 enum wxPenJoin
  80 {
  81     wxJOIN_INVALID = -1,
  82
  83     wxJOIN_BEVEL = 120,
  84     wxJOIN_MITER,
  85     wxJOIN_ROUND,
  86 };
  87
  88
  89 /**
  90     The possible cap values of a wxPen.
  91
  92     @todo use wxPENCAP_ prefix
  93 */
  94 enum wxPenCap
  95 {
  96     wxCAP_INVALID = -1,
  97
  98     wxCAP_ROUND = 130,
  99     wxCAP_PROJECTING,
 100     wxCAP_BUTT
 101 };
 102
 103
 104
 105 /**
 106     @class wxPen
 107
 108     A pen is a drawing tool for drawing outlines. It is used for drawing
 109     lines and painting the outline of rectangles, ellipses, etc.
 110     It has a colour, a width and a style.
 111
 112     @note On a monochrome display, wxWidgets shows all non-white pens as black.
 113
 114     Do not initialize objects on the stack before the program commences,
 115     since other required structures may not have been set up yet.
 116     Instead, define global pointers to objects and create them in wxApp::OnInit()
 117     or when required.
 118
 119     An application may wish to dynamically create pens with different characteristics,
 120     and there is the consequent danger that a large number of duplicate pens will
 121     be created. Therefore an application may wish to get a pointer to a pen by using
 122     the global list of pens ::wxThePenList, and calling the member function
 123     wxPenList::FindOrCreatePen().
 124     See wxPenList for more info.
 125
 126     This class uses @ref overview_refcount "reference counting and copy-on-write" internally
 127     so that assignments between two instances of this class are very cheap.
 128     You can therefore use actual objects instead of pointers without efficiency problems.
 129     If an instance of this class is changed it will create its own data internally
 130     so that other instances, which previously shared the data using the reference
 131     counting, are not affected.
 132
 133     @library{wxcore}
 134     @category{gdi}
 135
 136     @stdobjects
 137     @li ::wxNullPen
 138     @li ::wxBLACK_DASHED_PEN
 139     @li ::wxBLACK_PEN
 140     @li ::wxBLUE_PEN
 141     @li ::wxCYAN_PEN
 142     @li ::wxGREEN_PEN
 143     @li ::wxYELLOW_PEN
 144     @li ::wxGREY_PEN
 145     @li ::wxLIGHT_GREY_PEN
 146     @li ::wxMEDIUM_GREY_PEN
 147     @li ::wxRED_PEN
 148     @li ::wxTRANSPARENT_PEN
 149     @li ::wxWHITE_PEN
 150
 151     @see wxPenList, wxDC, wxDC::SetPen()
 152 */
 153 class wxPen : public wxGDIObject
 154 {
 155 public:
 156     /**
 157         Default constructor. The pen will be uninitialised, and IsOk() will return @false.
 158     */
 159     wxPen();
 160
 161     /**
 162         Constructs a pen from a colour object, pen width and style.
 163
 164         @param colour
 165             A colour object.
 166         @param width
 167             Pen width. Under Windows, the pen width cannot be greater than 1 if
 168             the style is @c wxPENSTYLE_DOT, @c wxPENSTYLE_LONG_DASH, @c wxPENSTYLE_SHORT_DASH,
 169             @c wxPENSTYLE_DOT_DASH, or @c wxPENSTYLE_USER_DASH.
 170         @param style
 171             The style may be one of the ::wxPenStyle values.
 172
 173         @remarks Different versions of Windows and different versions of other
 174                  platforms support very different subsets of the styles above
 175                  - there is no similarity even between Windows95 and Windows98 -
 176                  so handle with care.
 177
 178         @see SetStyle(), SetColour(), SetWidth()
 179     */
 180     wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxPENSTYLE_SOLID);
 181
 182     /**
 183         Constructs a stippled pen from a stipple bitmap and a width.
 184
 185         @param width
 186             Pen width. Under Windows, the pen width cannot be greater than 1 if
 187             the style is @c wxPENSTYLE_DOT, @c wxPENSTYLE_LONG_DASH, @c wxPENSTYLE_SHORT_DASH,
 188             @c wxPENSTYLE_DOT_DASH, or @c wxPENSTYLE_USER_DASH.
 189         @param stipple
 190             A stipple bitmap.
 191
 192         @onlyfor{wxmsw,wxosx}
 193
 194         @see SetWidth(), SetStipple()
 195     */
 196     wxPen(const wxBitmap& stipple, int width);
 197
 198     /**
 199         Copy constructor, uses @ref overview_refcount.
 200
 201         @param pen
 202             A pointer or reference to a pen to copy.
 203     */
 204     wxPen(const wxPen& pen);
 205
 206     /**
 207         Destructor.
 208         @see @ref overview_refcount_destruct "reference-counted object destruction"
 209
 210         @remarks Although all remaining pens are deleted when the application
 211                  exits, the application should try to clean up all pens
 212                  itself. This is because wxWidgets cannot know if a
 213                  pointer to the pen object is stored in an application
 214                  data structure, and there is a risk of double deletion.
 215     */
 216     virtual ~wxPen();
 217
 218     /**
 219         Returns the pen cap style, which may be one of @c wxCAP_ROUND,
 220         @c wxCAP_PROJECTING and @c wxCAP_BUTT.
 221
 222         The default is @c wxCAP_ROUND.
 223
 224         @see SetCap()
 225     */
 226     virtual wxPenCap GetCap() const;
 227
 228     /**
 229         Returns a reference to the pen colour.
 230
 231         @see SetColour()
 232     */
 233     virtual wxColour GetColour() const;
 234
 235     /**
 236         Gets an array of dashes (defined as @c char in X, @c DWORD under Windows).
 237         @a dashes is a pointer to the internal array. Do not deallocate or store this
 238         pointer.
 239
 240         @return The number of dashes associated with this pen.
 241
 242         @see SetDashes()
 243     */
 244     virtual int GetDashes(wxDash** dashes) const;
 245
 246     /**
 247         Returns the pen join style, which may be one of @c wxJOIN_BEVEL,
 248         @c wxJOIN_ROUND and @c wxJOIN_MITER.
 249
 250         The default is @c wxJOIN_ROUND.
 251
 252         @see SetJoin()
 253     */
 254     virtual wxPenJoin GetJoin() const;
 255
 256     /**
 257         Gets a pointer to the stipple bitmap.
 258
 259         @see SetStipple()
 260     */
 261     virtual wxBitmap* GetStipple() const;
 262
 263     /**
 264         Returns the pen style.
 265
 266         @see wxPen(), SetStyle()
 267     */
 268     virtual wxPenStyle GetStyle() const;
 269
 270     /**
 271         Returns the pen width.
 272
 273         @see SetWidth()
 274     */
 275     virtual int GetWidth() const;
 276
 277     /**
 278         Returns @true if the pen is initialised.
 279
 280         Notice that an uninitialized pen object can't be queried for any pen
 281         properties and all calls to the accessor methods on it will result in
 282         an assert failure.
 283     */
 284     virtual bool IsOk() const;
 285
 286     /**
 287         Returns @true if the pen is a valid non-transparent pen.
 288
 289         This method returns @true if the pen object is initialized and has a
 290         non-transparent style. Notice that this should be used instead of
 291         simply testing whether GetStyle() returns a style different from
 292         wxPENSTYLE_TRANSPARENT if the pen may be invalid as GetStyle() would
 293         assert in this case.
 294
 295         @see IsTransparent()
 296
 297         @since 2.9.2.
 298      */
 299     bool IsNonTransparent() const;
 300
 301     /**
 302         Returns @true if the pen is transparent.
 303
 304         A transparent pen is simply a pen with wxPENSTYLE_TRANSPARENT style.
 305
 306         Notice that this function works even for non-initialized pens (for
 307         which it returns @false) unlike tests of the form <code>GetStyle() ==
 308         wxPENSTYLE_TRANSPARENT</code> which would assert if the pen is invalid.
 309
 310         @see IsNonTransparent()
 311
 312         @since 2.9.2.
 313      */
 314     bool IsTransparent() const;
 315
 316     /**
 317         Sets the pen cap style, which may be one of @c wxCAP_ROUND, @c wxCAP_PROJECTING
 318         and @c wxCAP_BUTT. The default is @c wxCAP_ROUND.
 319
 320         @see GetCap()
 321     */
 322     virtual void SetCap(wxPenCap capStyle);
 323
 324     //@{
 325     /**
 326         The pen's colour is changed to the given colour.
 327
 328         @see GetColour()
 329     */
 330     virtual void SetColour(wxColour& colour);
 331     virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue);
 332     //@}
 333
 334     /**
 335         Associates an array of dash values (defined as @c char in X, @c DWORD under
 336         Windows) with the pen.
 337
 338         The array is not deallocated by wxPen, but neither must it be deallocated by
 339         the calling application until the pen is deleted or this function is called
 340         with a @NULL array.
 341
 342         @see GetDashes()
 343     */
 344     virtual void SetDashes(int n, const wxDash* dash);
 345
 346     /**
 347         Sets the pen join style, which may be one of @c wxJOIN_BEVEL, @c wxJOIN_ROUND
 348         and @c wxJOIN_MITER.
 349
 350         The default is @c wxJOIN_ROUND.
 351
 352         @see GetJoin()
 353     */
 354     virtual void SetJoin(wxPenJoin join_style);
 355
 356     /**
 357         Sets the bitmap for stippling.
 358
 359         @see GetStipple()
 360     */
 361     virtual void SetStipple(const wxBitmap& stipple);
 362
 363     /**
 364         Set the pen style.
 365
 366         @see wxPen()
 367     */
 368     virtual void SetStyle(wxPenStyle style);
 369
 370     /**
 371         Sets the pen width.
 372
 373         @see GetWidth()
 374     */
 375     virtual void SetWidth(int width);
 376
 377     /**
 378         Inequality operator.
 379
 380         See @ref overview_refcount_equality "reference-counted object comparison" for
 381         more info.
 382     */
 383     bool operator!=(const wxPen& pen) const;
 384
 385     /**
 386         Assignment operator, using @ref overview_refcount.
 387     */
 388     wxPen& operator=(const wxPen& pen);
 389
 390     /**
 391         Equality operator.
 392
 393         See @ref overview_refcount_equality "reference-counted object comparison" for
 394         more info.
 395     */
 396     bool operator==(const wxPen& pen) const;
 397 };
 398
 399 /**
 400     An empty pen.
 401     wxPen::IsOk() always returns @false for this object.
 402 */
 403 wxPen wxNullPen;
 404
 405 /**
 406     Red pen.
 407     Except for the color it has all standard attributes
 408     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 409 */
 410 wxPen* wxRED_PEN;
 411
 412 /**
 413     Blue pen.
 414     Except for the color it has all standard attributes
 415     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 416 */
 417 wxPen* wxBLUE_PEN;
 418
 419 /**
 420     Cyan pen.
 421     Except for the color it has all standard attributes
 422     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 423 */
 424 wxPen* wxCYAN_PEN;
 425
 426 /**
 427     Green pen.
 428     Except for the color it has all standard attributes
 429     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 430 */
 431 wxPen* wxGREEN_PEN;
 432
 433 /**
 434     Yellow pen.
 435     Except for the color it has all standard attributes
 436     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 437 */
 438 wxPen* wxYELLOW_PEN;
 439
 440 /**
 441     Black pen.
 442     Except for the color it has all standard attributes
 443     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 444 */
 445 wxPen* wxBLACK_PEN;
 446
 447 /**
 448     White pen.
 449     Except for the color it has all standard attributes
 450     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 451 */
 452 wxPen* wxWHITE_PEN;
 453
 454 /**
 455     Transparent pen.
 456     Except for the color it has all standard attributes
 457     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 458 */
 459 wxPen* wxTRANSPARENT_PEN;
 460
 461 /**
 462     Black dashed pen.
 463     Except for the color and for the @c wxPENSTYLE_SHORT_DASH it has all standard attributes
 464     (1-pixel width, @c wxCAP_ROUND style, etc...).
 465 */
 466 wxPen* wxBLACK_DASHED_PEN;
 467
 468 /**
 469     Grey pen.
 470     Except for the color it has all standard attributes
 471     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 472 */
 473 wxPen* wxGREY_PEN;
 474
 475 /**
 476     Medium-grey pen.
 477     Except for the color it has all standard attributes
 478     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 479 */
 480 wxPen* wxMEDIUM_GREY_PEN;
 481
 482 /**
 483     Light-grey pen.
 484     Except for the color it has all standard attributes
 485     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 486 */
 487 wxPen* wxLIGHT_GREY_PEN;
 488
 489
 490
 491 /**
 492     @class wxPenList
 493
 494     There is only one instance of this class: ::wxThePenList.
 495     Use this object to search for a previously created pen of the desired
 496     type and create it if not already found. In some windowing systems,
 497     the pen may be a scarce resource, so it can pay to reuse old
 498     resources if possible. When an application finishes, all pens will
 499     be deleted and their resources freed, eliminating the possibility of
 500     'memory leaks'. However, it is best not to rely on this automatic
 501     cleanup because it can lead to double deletion in some circumstances.
 502
 503     There are two mechanisms in recent versions of wxWidgets which make the
 504     pen list less useful than it once was. Under Windows, scarce resources
 505     are cleaned up internally if they are not being used. Also, a referencing
 506     counting mechanism applied to all GDI objects means that some sharing
 507     of underlying resources is possible. You don't have to keep track of pointers,
 508     working out when it is safe delete a pen, because the referencing counting does
 509     it for you. For example, you can set a pen in a device context, and then
 510     immediately delete the pen you passed, because the pen is 'copied'.
 511
 512     So you may find it easier to ignore the pen list, and instead create
 513     and copy pens as you see fit. If your Windows resource meter suggests
 514     your application is using too many resources, you can resort to using
 515     GDI lists to share objects explicitly.
 516
 517     The only compelling use for the pen list is for wxWidgets to keep
 518     track of pens in order to clean them up on exit. It is also kept for
 519     backward compatibility with earlier versions of wxWidgets.
 520
 521     @library{wxcore}
 522     @category{gdi}
 523
 524     @stdobjects
 525     ::wxThePenList
 526
 527     @see wxPen
 528 */
 529 class wxPenList
 530 {
 531 public:
 532     /**
 533         Constructor. The application should not construct its own pen list:
 534         use the object pointer ::wxThePenList.
 535     */
 536     wxPenList();
 537
 538     /**
 539         Finds a pen with the specified attributes and returns it, else creates a
 540         new pen, adds it to the pen list, and returns it.
 541
 542         @param colour
 543             Colour object.
 544         @param width
 545             Width of pen.
 546         @param style
 547             Pen style. See ::wxPenStyle for a list of styles.
 548     */
 549     wxPen* FindOrCreatePen(const wxColour& colour,
 550                            int width = 1,
 551                            wxPenStyle style = wxPENSTYLE_SOLID);
 552 };
 553
 554 /**
 555     The global list of wxPen objects ready to be re-used (for better performances).
 556 */
 557 wxPenList* wxThePenList;
 558