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