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