interface/wx/pen.h

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