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     wxPenCap GetCap() const;
 203
 204     /**
 205         Returns a reference to the pen colour.
 206
 207         @see SetColour()
 208     */
 209     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     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     wxPenJoin GetJoin() const;
 229
 230     /**
 231         Gets a pointer to the stipple bitmap.
 232
 233         @see SetStipple()
 234     */
 235     wxBitmap* GetStipple() const;
 236
 237     /**
 238         Returns the pen style.
 239
 240         @see wxPen(), SetStyle()
 241     */
 242     wxPenStyle GetStyle() const;
 243
 244     /**
 245         Returns the pen width.
 246
 247         @see SetWidth()
 248     */
 249     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     void SetCap(wxPenCap capStyle);
 264
 265     //@{
 266     /**
 267         The pen's colour is changed to the given colour.
 268
 269         @see GetColour()
 270     */
 271     void SetColour(wxColour& colour);
 272     void SetColour(const wxString& colourName);
 273     void SetColour(unsigned char red, unsigned char green,
 274                    unsigned char blue);
 275     //@}
 276
 277     /**
 278         Associates an array of pointers to dashes (defined as char in X, DWORD under
 279         Windows)
 280         with the pen. The array is not deallocated by wxPen, but neither must it be
 281         deallocated by the calling application until the pen is deleted or this
 282         function is called with a @NULL array.
 283
 284         @see GetDashes()
 285     */
 286     void SetDashes(int n, wxDash* dashes);
 287
 288     /**
 289         Sets the pen join style, which may be one of @b wxJOIN_BEVEL, @b wxJOIN_ROUND
 290         and
 291         @b wxJOIN_MITER. The default is @b wxJOIN_ROUND.
 292
 293         @see GetJoin()
 294     */
 295     void SetJoin(wxPenJoin join_style);
 296
 297     /**
 298         Sets the bitmap for stippling.
 299
 300         @see GetStipple()
 301     */
 302     void SetStipple(wxBitmap* stipple);
 303
 304     /**
 305         Set the pen style.
 306
 307         @see wxPen()
 308     */
 309     void SetStyle(wxPenStyle style);
 310
 311     /**
 312         Sets the pen width.
 313
 314         @see GetWidth()
 315     */
 316     void SetWidth(int width);
 317
 318     /**
 319         Inequality operator.
 320         See @ref overview_refcountequality "reference-counted object comparison" for
 321         more info.
 322     */
 323     bool operator !=(const wxPen& pen);
 324
 325     /**
 326         Assignment operator, using @ref overview_trefcount "reference counting".
 327     */
 328     wxPen operator =(const wxPen& pen);
 329
 330     /**
 331         Equality operator.
 332         See @ref overview_refcountequality "reference-counted object comparison" for
 333         more info.
 334     */
 335     bool operator ==(const wxPen& pen);
 336 };
 337
 338 /**
 339     FIXME
 340 */
 341 wxPen wxNullPen;
 342
 343 /**
 344     FIXME
 345 */
 346 wxPen wxRED_PEN;
 347
 348 /**
 349     FIXME
 350 */
 351 wxPen wxCYAN_PEN;
 352
 353 /**
 354     FIXME
 355 */
 356 wxPen wxGREEN_PEN;
 357
 358 /**
 359     FIXME
 360 */
 361 wxPen wxBLACK_PEN;
 362
 363 /**
 364     FIXME
 365 */
 366 wxPen wxWHITE_PEN;
 367
 368 /**
 369     FIXME
 370 */
 371 wxPen wxTRANSPARENT_PEN;
 372
 373 /**
 374     FIXME
 375 */
 376 wxPen wxBLACK_DASHED_PEN;
 377
 378 /**
 379     FIXME
 380 */
 381 wxPen wxGREY_PEN;
 382
 383 /**
 384     FIXME
 385 */
 386 wxPen wxMEDIUM_GREY_PEN;
 387
 388 /**
 389     FIXME
 390 */
 391 wxPen wxLIGHT_GREY_PEN;
 392
 393
 394
 395 /**
 396     @class wxPenList
 397     @wxheader{gdicmn.h}
 398
 399     There is only one instance of this class: ::wxThePenList.
 400     Use this object to search for a previously created pen of the desired
 401     type and create it if not already found. In some windowing systems,
 402     the pen may be a scarce resource, so it can pay to reuse old
 403     resources if possible. When an application finishes, all pens will
 404     be deleted and their resources freed, eliminating the possibility of
 405     'memory leaks'. However, it is best not to rely on this automatic
 406     cleanup because it can lead to double deletion in some circumstances.
 407
 408     There are two mechanisms in recent versions of wxWidgets which make the
 409     pen list less useful than it once was. Under Windows, scarce resources
 410     are cleaned up internally if they are not being used. Also, a referencing
 411     counting mechanism applied to all GDI objects means that some sharing
 412     of underlying resources is possible. You don't have to keep track of pointers,
 413     working out when it is safe delete a pen, because the referencing counting does
 414     it for you. For example, you can set a pen in a device context, and then
 415     immediately delete the pen you passed, because the pen is 'copied'.
 416
 417     So you may find it easier to ignore the pen list, and instead create
 418     and copy pens as you see fit. If your Windows resource meter suggests
 419     your application is using too many resources, you can resort to using
 420     GDI lists to share objects explicitly.
 421
 422     The only compelling use for the pen list is for wxWidgets to keep
 423     track of pens in order to clean them up on exit. It is also kept for
 424     backward compatibility with earlier versions of wxWidgets.
 425
 426     @library{wxcore}
 427     @category{gdi}
 428
 429     @stdobjects
 430     ::wxThePenList
 431
 432     @see wxPen
 433 */
 434 class wxPenList
 435 {
 436 public:
 437     /**
 438         Constructor. The application should not construct its own pen list:
 439         use the object pointer ::wxThePenList.
 440     */
 441     wxPenList();
 442
 443     /**
 444         Finds a pen with the specified attributes and returns it, else creates a
 445         new pen, adds it to the pen list, and returns it.
 446
 447         @param colour
 448             Colour object.
 449         @param width
 450             Width of pen.
 451         @param style
 452             Pen style. See ::wxPenStyle for a list of styles.
 453     */
 454     wxPen* FindOrCreatePen(const wxColour& colour,
 455                            int width = 1,
 456                            wxPenStyle style = wxPENSTYLE_SOLID);
 457 };
 458
 459 /**
 460     The global list of wxPen objects ready to be re-used (for better performances).
 461 */
 462 wxPenList* wxThePenList;
 463