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