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