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     ::wxNullPen, ::wxRED_PEN, ::wxCYAN_PEN, ::wxGREEN_PEN, ::wxBLACK_PEN, ::wxWHITE_PEN,
 133     ::wxTRANSPARENT_PEN, ::wxBLACK_DASHED_PEN, ::wxGREY_PEN, ::wxMEDIUM_GREY_PEN,
 134     ::wxLIGHT_GREY_PEN
 135
 136     @see wxPenList, wxDC, wxDC::SetPen()
 137 */
 138 class wxPen : public wxGDIObject
 139 {
 140 public:
 141     /**
 142         Default constructor. The pen will be uninitialised, and IsOk() will return @false.
 143     */
 144     wxPen();
 145
 146     /**
 147         Constructs a pen from a colour object, pen width and style.
 148
 149         @param colour
 150             A colour object.
 151         @param width
 152             Pen width. Under Windows, the pen width cannot be greater than 1 if
 153             the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH.
 154         @param style
 155             The style may be one of the ::wxPenStyle values.
 156
 157         @remarks Different versions of Windows and different versions of other
 158                  platforms support very different subsets of the styles
 159                  above - there is no similarity even between Windows95
 160                  and Windows98 - so handle with care.
 161
 162         @see SetStyle(), SetColour(), SetWidth()
 163     */
 164     wxPen(const wxColour& colour, int width = 1, wxPenStyle style = wxPENSTYLE_SOLID);
 165
 166     /**
 167         Constructs a stippled pen from a stipple bitmap and a width.
 168
 169         @param width
 170             Pen width. Under Windows, the pen width cannot be greater than 1 if
 171             the style is @c wxDOT, @c wxLONG_DASH, @c wxSHORT_DASH, @c wxDOT_DASH, or @c wxUSER_DASH.
 172         @param stipple
 173             A stipple bitmap.
 174
 175         @see SetWidth(), SetStipple()
 176     */
 177     wxPen(const wxBitmap& stipple, int width);
 178
 179     /**
 180         Copy constructor, uses @ref overview_refcount.
 181
 182         @param pen
 183             A pointer or reference to a pen to copy.
 184     */
 185     wxPen(const wxPen& pen);
 186
 187     /**
 188         Destructor.
 189         @see @ref overview_refcount_destruct "reference-counted object destruction"
 190
 191         @remarks Although all remaining pens are deleted when the application
 192                  exits, the application should try to clean up all pens
 193                  itself. This is because wxWidgets cannot know if a
 194                  pointer to the pen object is stored in an application
 195                  data structure, and there is a risk of double deletion.
 196     */
 197     ~wxPen();
 198
 199     /**
 200         Returns the pen cap style, which may be one of @c wxCAP_ROUND, @c
 201         wxCAP_PROJECTING and @c wxCAP_BUTT.
 202
 203         The default is @c wxCAP_ROUND.
 204
 205         @see SetCap()
 206     */
 207     virtual wxPenCap GetCap() const;
 208
 209     /**
 210         Returns a reference to the pen colour.
 211
 212         @see SetColour()
 213     */
 214     virtual wxColour GetColour() const;
 215
 216     /**
 217         Gets an array of dashes (defined as char in X, DWORD under Windows).
 218         @a dashes is a pointer to the internal array. Do not deallocate or store this
 219         pointer.
 220
 221         @return The number of dashes associated with this pen.
 222
 223         @see SetDashes()
 224     */
 225     virtual int GetDashes(wxDash** dashes) const;
 226
 227     /**
 228         Returns the pen join style, which may be one of @c wxJOIN_BEVEL, @c
 229         wxJOIN_ROUND and @c wxJOIN_MITER.
 230
 231         The default is @c wxJOIN_ROUND.
 232
 233         @see SetJoin()
 234     */
 235     virtual wxPenJoin GetJoin() const;
 236
 237     /**
 238         Gets a pointer to the stipple bitmap.
 239
 240         @see SetStipple()
 241     */
 242     virtual wxBitmap* GetStipple() const;
 243
 244     /**
 245         Returns the pen style.
 246
 247         @see wxPen(), SetStyle()
 248     */
 249     virtual wxPenStyle GetStyle() const;
 250
 251     /**
 252         Returns the pen width.
 253
 254         @see SetWidth()
 255     */
 256     virtual int GetWidth() const;
 257
 258     /**
 259         Returns @true if the pen is initialised.
 260     */
 261     bool IsOk() const;
 262
 263     /**
 264         Sets the pen cap style, which may be one of @c wxCAP_ROUND, @c wxCAP_PROJECTING
 265         and @c wxCAP_BUTT. The default is @c wxCAP_ROUND.
 266
 267         @see GetCap()
 268     */
 269     virtual void SetCap(wxPenCap capStyle);
 270
 271     //@{
 272     /**
 273         The pen's colour is changed to the given colour.
 274
 275         @see GetColour()
 276     */
 277     virtual void SetColour(wxColour& colour);
 278     virtual void SetColour(unsigned char red, unsigned char green, unsigned char blue);
 279     //@}
 280
 281     /**
 282         Associates an array of pointers to dashes (defined as char in X, DWORD under
 283         Windows) with the pen.
 284
 285         The array is not deallocated by wxPen, but neither must it be deallocated by
 286         the calling application until the pen is deleted or this function is called
 287         with a @NULL array.
 288
 289         @see GetDashes()
 290     */
 291     virtual void SetDashes(int n, wxDash* dashes);
 292
 293     /**
 294         Sets the pen join style, which may be one of @c wxJOIN_BEVEL, @c wxJOIN_ROUND
 295         and @c wxJOIN_MITER.
 296
 297         The default is @c wxJOIN_ROUND.
 298
 299         @see GetJoin()
 300     */
 301     virtual void SetJoin(wxPenJoin join_style);
 302
 303     /**
 304         Sets the bitmap for stippling.
 305
 306         @see GetStipple()
 307     */
 308     virtual void SetStipple(wxBitmap* stipple);
 309
 310     /**
 311         Set the pen style.
 312
 313         @see wxPen()
 314     */
 315     virtual void SetStyle(wxPenStyle style);
 316
 317     /**
 318         Sets the pen width.
 319
 320         @see GetWidth()
 321     */
 322     virtual void SetWidth(int width);
 323
 324     /**
 325         Inequality operator.
 326
 327         See @ref overview_refcount_equality "reference-counted object comparison" for
 328         more info.
 329     */
 330     bool operator !=(const wxPen& pen);
 331
 332     /**
 333         Assignment operator, using @ref overview_refcount.
 334     */
 335     wxPen operator =(const wxPen& pen);
 336
 337     /**
 338         Equality operator.
 339
 340         See @ref overview_refcount_equality "reference-counted object comparison" for
 341         more info.
 342     */
 343     bool operator ==(const wxPen& pen);
 344 };
 345
 346 /**
 347     An empty pen.
 348 */
 349 wxPen wxNullPen;
 350
 351 /**
 352     Red pen.
 353 */
 354 wxPen* wxRED_PEN;
 355
 356 /**
 357     Cyan pen.
 358 */
 359 wxPen* wxCYAN_PEN;
 360
 361 /**
 362     Green pen.
 363 */
 364 wxPen* wxGREEN_PEN;
 365
 366 /**
 367     Black pen.
 368 */
 369 wxPen* wxBLACK_PEN;
 370
 371 /**
 372     White pen.
 373 */
 374 wxPen* wxWHITE_PEN;
 375
 376 /**
 377     Transparent pen.
 378 */
 379 wxPen* wxTRANSPARENT_PEN;
 380
 381 /**
 382     Black dashed pen.
 383 */
 384 wxPen* wxBLACK_DASHED_PEN;
 385
 386 /**
 387     Grey pen.
 388 */
 389 wxPen* wxGREY_PEN;
 390
 391 /**
 392     Medium-grey pen.
 393 */
 394 wxPen* wxMEDIUM_GREY_PEN;
 395
 396 /**
 397     Light-grey pen.
 398 */
 399 wxPen* wxLIGHT_GREY_PEN;
 400
 401
 402
 403 /**
 404     @class wxPenList
 405     @wxheader{gdicmn.h}
 406
 407     There is only one instance of this class: ::wxThePenList.
 408     Use this object to search for a previously created pen of the desired
 409     type and create it if not already found. In some windowing systems,
 410     the pen may be a scarce resource, so it can pay to reuse old
 411     resources if possible. When an application finishes, all pens will
 412     be deleted and their resources freed, eliminating the possibility of
 413     'memory leaks'. However, it is best not to rely on this automatic
 414     cleanup because it can lead to double deletion in some circumstances.
 415
 416     There are two mechanisms in recent versions of wxWidgets which make the
 417     pen list less useful than it once was. Under Windows, scarce resources
 418     are cleaned up internally if they are not being used. Also, a referencing
 419     counting mechanism applied to all GDI objects means that some sharing
 420     of underlying resources is possible. You don't have to keep track of pointers,
 421     working out when it is safe delete a pen, because the referencing counting does
 422     it for you. For example, you can set a pen in a device context, and then
 423     immediately delete the pen you passed, because the pen is 'copied'.
 424
 425     So you may find it easier to ignore the pen list, and instead create
 426     and copy pens as you see fit. If your Windows resource meter suggests
 427     your application is using too many resources, you can resort to using
 428     GDI lists to share objects explicitly.
 429
 430     The only compelling use for the pen list is for wxWidgets to keep
 431     track of pens in order to clean them up on exit. It is also kept for
 432     backward compatibility with earlier versions of wxWidgets.
 433
 434     @library{wxcore}
 435     @category{gdi}
 436
 437     @stdobjects
 438     ::wxThePenList
 439
 440     @see wxPen
 441 */
 442 class wxPenList
 443 {
 444 public:
 445     /**
 446         Constructor. The application should not construct its own pen list:
 447         use the object pointer ::wxThePenList.
 448     */
 449     wxPenList();
 450
 451     /**
 452         Finds a pen with the specified attributes and returns it, else creates a
 453         new pen, adds it to the pen list, and returns it.
 454
 455         @param colour
 456             Colour object.
 457         @param width
 458             Width of pen.
 459         @param style
 460             Pen style. See ::wxPenStyle for a list of styles.
 461     */
 462     wxPen* FindOrCreatePen(const wxColour& colour,
 463                            int width = 1,
 464                            wxPenStyle style = wxPENSTYLE_SOLID);
 465 };
 466
 467 /**
 468     The global list of wxPen objects ready to be re-used (for better performances).
 469 */
 470 wxPenList* wxThePenList;
 471