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