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