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