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