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     virtual bool IsOk() const;
 278
 279     /**
 280         Sets the pen cap style, which may be one of @c wxCAP_ROUND, @c wxCAP_PROJECTING
 281         and @c wxCAP_BUTT. The default is @c wxCAP_ROUND.
 282
 283         @see GetCap()
 284     */
 285     virtual void SetCap(wxPenCap capStyle);
 286
 287     //@{
 288     /**
 289         The pen's colour is changed to the given colour.
 290
 291         @see GetColour()
 292     */
 293     virtual void SetColour(wxColour& colour);
 294     virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue);
 295     //@}
 296
 297     /**
 298         Associates an array of pointers to dashes (defined as @c char in X, @c DWORD under
 299         Windows) with the pen.
 300
 301         The array is not deallocated by wxPen, but neither must it be deallocated by
 302         the calling application until the pen is deleted or this function is called
 303         with a @NULL array.
 304
 305         @see GetDashes()
 306     */
 307     virtual void SetDashes(int n, const wxDash* dash);
 308
 309     /**
 310         Sets the pen join style, which may be one of @c wxJOIN_BEVEL, @c wxJOIN_ROUND
 311         and @c wxJOIN_MITER.
 312
 313         The default is @c wxJOIN_ROUND.
 314
 315         @see GetJoin()
 316     */
 317     virtual void SetJoin(wxPenJoin join_style);
 318
 319     /**
 320         Sets the bitmap for stippling.
 321
 322         @see GetStipple()
 323     */
 324     virtual void SetStipple(const wxBitmap& stipple);
 325
 326     /**
 327         Set the pen style.
 328
 329         @see wxPen()
 330     */
 331     virtual void SetStyle(wxPenStyle style);
 332
 333     /**
 334         Sets the pen width.
 335
 336         @see GetWidth()
 337     */
 338     virtual void SetWidth(int width);
 339
 340     /**
 341         Inequality operator.
 342
 343         See @ref overview_refcount_equality "reference-counted object comparison" for
 344         more info.
 345     */
 346     bool operator!=(const wxPen& pen) const;
 347
 348     /**
 349         Assignment operator, using @ref overview_refcount.
 350     */
 351     wxPen& operator=(const wxPen& pen);
 352
 353     /**
 354         Equality operator.
 355
 356         See @ref overview_refcount_equality "reference-counted object comparison" for
 357         more info.
 358     */
 359     bool operator==(const wxPen& pen) const;
 360 };
 361
 362 /**
 363     An empty pen.
 364     wxPen::IsOk() always returns @false for this object.
 365 */
 366 wxPen wxNullPen;
 367
 368 /**
 369     Red pen.
 370     Except for the color it has all standard attributes
 371     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 372 */
 373 wxPen* wxRED_PEN;
 374
 375 /**
 376     Blue pen.
 377     Except for the color it has all standard attributes
 378     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 379 */
 380 wxPen* wxBLUE_PEN;
 381
 382 /**
 383     Cyan pen.
 384     Except for the color it has all standard attributes
 385     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 386 */
 387 wxPen* wxCYAN_PEN;
 388
 389 /**
 390     Green pen.
 391     Except for the color it has all standard attributes
 392     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 393 */
 394 wxPen* wxGREEN_PEN;
 395
 396 /**
 397     Yellow pen.
 398     Except for the color it has all standard attributes
 399     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 400 */
 401 wxPen* wxYELLOW_PEN;
 402
 403 /**
 404     Black pen.
 405     Except for the color it has all standard attributes
 406     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 407 */
 408 wxPen* wxBLACK_PEN;
 409
 410 /**
 411     White pen.
 412     Except for the color it has all standard attributes
 413     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 414 */
 415 wxPen* wxWHITE_PEN;
 416
 417 /**
 418     Transparent pen.
 419     Except for the color it has all standard attributes
 420     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 421 */
 422 wxPen* wxTRANSPARENT_PEN;
 423
 424 /**
 425     Black dashed pen.
 426     Except for the color and for the @c wxPENSTYLE_SHORT_DASH it has all standard attributes
 427     (1-pixel width, @c wxCAP_ROUND style, etc...).
 428 */
 429 wxPen* wxBLACK_DASHED_PEN;
 430
 431 /**
 432     Grey pen.
 433     Except for the color it has all standard attributes
 434     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 435 */
 436 wxPen* wxGREY_PEN;
 437
 438 /**
 439     Medium-grey pen.
 440     Except for the color it has all standard attributes
 441     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 442 */
 443 wxPen* wxMEDIUM_GREY_PEN;
 444
 445 /**
 446     Light-grey pen.
 447     Except for the color it has all standard attributes
 448     (1-pixel width, @c wxPENSTYLE_SOLID and @c wxCAP_ROUND styles, etc...).
 449 */
 450 wxPen* wxLIGHT_GREY_PEN;
 451
 452
 453
 454 /**
 455     @class wxPenList
 456
 457     There is only one instance of this class: ::wxThePenList.
 458     Use this object to search for a previously created pen of the desired
 459     type and create it if not already found. In some windowing systems,
 460     the pen may be a scarce resource, so it can pay to reuse old
 461     resources if possible. When an application finishes, all pens will
 462     be deleted and their resources freed, eliminating the possibility of
 463     'memory leaks'. However, it is best not to rely on this automatic
 464     cleanup because it can lead to double deletion in some circumstances.
 465
 466     There are two mechanisms in recent versions of wxWidgets which make the
 467     pen list less useful than it once was. Under Windows, scarce resources
 468     are cleaned up internally if they are not being used. Also, a referencing
 469     counting mechanism applied to all GDI objects means that some sharing
 470     of underlying resources is possible. You don't have to keep track of pointers,
 471     working out when it is safe delete a pen, because the referencing counting does
 472     it for you. For example, you can set a pen in a device context, and then
 473     immediately delete the pen you passed, because the pen is 'copied'.
 474
 475     So you may find it easier to ignore the pen list, and instead create
 476     and copy pens as you see fit. If your Windows resource meter suggests
 477     your application is using too many resources, you can resort to using
 478     GDI lists to share objects explicitly.
 479
 480     The only compelling use for the pen list is for wxWidgets to keep
 481     track of pens in order to clean them up on exit. It is also kept for
 482     backward compatibility with earlier versions of wxWidgets.
 483
 484     @library{wxcore}
 485     @category{gdi}
 486
 487     @stdobjects
 488     ::wxThePenList
 489
 490     @see wxPen
 491 */
 492 class wxPenList
 493 {
 494 public:
 495     /**
 496         Constructor. The application should not construct its own pen list:
 497         use the object pointer ::wxThePenList.
 498     */
 499     wxPenList();
 500
 501     /**
 502         Finds a pen with the specified attributes and returns it, else creates a
 503         new pen, adds it to the pen list, and returns it.
 504
 505         @param colour
 506             Colour object.
 507         @param width
 508             Width of pen.
 509         @param style
 510             Pen style. See ::wxPenStyle for a list of styles.
 511     */
 512     wxPen* FindOrCreatePen(const wxColour& colour,
 513                            int width = 1,
 514                            wxPenStyle style = wxPENSTYLE_SOLID);
 515 };
 516
 517 /**
 518     The global list of wxPen objects ready to be re-used (for better performances).
 519 */
 520 wxPenList* wxThePenList;
 521