interface/pen.h

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