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