interface/gdicmn.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        gdicmn.h
   3 // Purpose:     interface of wxRealPoint
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9
  10 /**
  11     Bitmap flags.
  12 */
  13 enum wxBitmapType
  14 {
  15     wxBITMAP_TYPE_INVALID,
  16     wxBITMAP_TYPE_BMP,
  17     wxBITMAP_TYPE_BMP_RESOURCE,
  18     wxBITMAP_TYPE_RESOURCE = wxBITMAP_TYPE_BMP_RESOURCE,
  19     wxBITMAP_TYPE_ICO,
  20     wxBITMAP_TYPE_ICO_RESOURCE,
  21     wxBITMAP_TYPE_CUR,
  22     wxBITMAP_TYPE_CUR_RESOURCE,
  23     wxBITMAP_TYPE_XBM,
  24     wxBITMAP_TYPE_XBM_DATA,
  25     wxBITMAP_TYPE_XPM,
  26     wxBITMAP_TYPE_XPM_DATA,
  27     wxBITMAP_TYPE_TIF,
  28     wxBITMAP_TYPE_TIF_RESOURCE,
  29     wxBITMAP_TYPE_GIF,
  30     wxBITMAP_TYPE_GIF_RESOURCE,
  31     wxBITMAP_TYPE_PNG,
  32     wxBITMAP_TYPE_PNG_RESOURCE,
  33     wxBITMAP_TYPE_JPEG,
  34     wxBITMAP_TYPE_JPEG_RESOURCE,
  35     wxBITMAP_TYPE_PNM,
  36     wxBITMAP_TYPE_PNM_RESOURCE,
  37     wxBITMAP_TYPE_PCX,
  38     wxBITMAP_TYPE_PCX_RESOURCE,
  39     wxBITMAP_TYPE_PICT,
  40     wxBITMAP_TYPE_PICT_RESOURCE,
  41     wxBITMAP_TYPE_ICON,
  42     wxBITMAP_TYPE_ICON_RESOURCE,
  43     wxBITMAP_TYPE_ANI,
  44     wxBITMAP_TYPE_IFF,
  45     wxBITMAP_TYPE_TGA,
  46     wxBITMAP_TYPE_MACCURSOR,
  47     wxBITMAP_TYPE_MACCURSOR_RESOURCE,
  48     wxBITMAP_TYPE_ANY = 50
  49 };
  50
  51 /**
  52     Standard cursors.
  53 */
  54 enum wxStockCursor
  55 {
  56     wxCURSOR_NONE,
  57     wxCURSOR_ARROW,
  58     wxCURSOR_RIGHT_ARROW,
  59     wxCURSOR_BULLSEYE,
  60     wxCURSOR_CHAR,
  61     wxCURSOR_CROSS,
  62     wxCURSOR_HAND,
  63     wxCURSOR_IBEAM,
  64     wxCURSOR_LEFT_BUTTON,
  65     wxCURSOR_MAGNIFIER,
  66     wxCURSOR_MIDDLE_BUTTON,
  67     wxCURSOR_NO_ENTRY,
  68     wxCURSOR_PAINT_BRUSH,
  69     wxCURSOR_PENCIL,
  70     wxCURSOR_POINT_LEFT,
  71     wxCURSOR_POINT_RIGHT,
  72     wxCURSOR_QUESTION_ARROW,
  73     wxCURSOR_RIGHT_BUTTON,
  74     wxCURSOR_SIZENESW,
  75     wxCURSOR_SIZENS,
  76     wxCURSOR_SIZENWSE,
  77     wxCURSOR_SIZEWE,
  78     wxCURSOR_SIZING,
  79     wxCURSOR_SPRAYCAN,
  80     wxCURSOR_WAIT,
  81     wxCURSOR_WATCH,
  82     wxCURSOR_BLANK,
  83     wxCURSOR_DEFAULT,       //!< standard X11 cursor
  84     wxCURSOR_COPY_ARROW ,   //!< MacOS Theme Plus arrow
  85     // Not yet implemented for Windows
  86     wxCURSOR_CROSS_REVERSE,
  87     wxCURSOR_DOUBLE_ARROW,
  88     wxCURSOR_BASED_ARROW_UP,
  89     wxCURSOR_BASED_ARROW_DOWN,
  90     wxCURSOR_ARROWWAIT,
  91     wxCURSOR_MAX
  92 };
  93
  94
  95
  96 /**
  97     @class wxRealPoint
  98     @wxheader{gdicmn.h}
  99
 100     A @b wxRealPoint is a useful data structure for graphics operations.
 101     It contains floating point @e x and @e y members.
 102     See also wxPoint for an integer version.
 103
 104     @library{wxcore}
 105     @category{data}
 106
 107     @see wxPoint
 108 */
 109 class wxRealPoint
 110 {
 111 public:
 112     //@{
 113     /**
 114         Create a point.
 115         double  x
 116         double  y
 117         Members of the @b wxRealPoint object.
 118     */
 119     wxRealPoint();
 120     wxRealPoint(double x, double y);
 121     //@}
 122 };
 123
 124
 125
 126 /**
 127     @class wxRect
 128     @wxheader{gdicmn.h}
 129
 130     A class for manipulating rectangles.
 131
 132     @library{wxcore}
 133     @category{data}
 134
 135     @see wxPoint, wxSize
 136 */
 137 class wxRect
 138 {
 139 public:
 140     //@{
 141     /**
 142         Creates a wxRect object from size values at the origin.
 143     */
 144     wxRect();
 145     wxRect(int x, int y, int width, int height);
 146     wxRect(const wxPoint& topLeft, const wxPoint& bottomRight);
 147     wxRect(const wxPoint& pos, const wxSize& size);
 148     wxRect(const wxSize& size);
 149     //@}
 150
 151     //@{
 152     /**
 153         Returns the rectangle having the same size as this one but centered relatively
 154         to the given rectangle @e r. By default, rectangle is centred in both
 155         directions but if @a dir includes only @c wxVERTICAL or only
 156         @c wxHORIZONTAL flag, then it is only centered in this direction while
 157         the other component of its position remains unchanged.
 158     */
 159     wxRect CentreIn(const wxRect& r, int dir = wxBOTH) const;
 160     const wxRect  CenterIn(const wxRect& r, int dir = wxBOTH) const;
 161     //@}
 162
 163     //@{
 164     /**
 165         Returns @true if the given rectangle is completely inside this rectangle
 166         (or touches its boundary) and @false otherwise.
 167     */
 168     bool Contains(int x, int y) const;
 169     const bool Contains(const wxPoint& pt) const;
 170     const bool Contains(const wxRect& rect) const;
 171     //@}
 172
 173     //@{
 174     /**
 175         Decrease the rectangle size.
 176         This method is the opposite from Inflate():
 177         Deflate(a, b) is equivalent to Inflate(-a, -b).
 178         Please refer to Inflate() for full description.
 179
 180         @see Inflate()
 181     */
 182     void Deflate(wxCoord dx, wxCoord dy) const;
 183     void Deflate(const wxSize& diff) const;
 184     void Deflate(wxCoord diff) const;
 185     wxRect Deflate(wxCoord dx, wxCoord dy) const;
 186     //@}
 187
 188     /**
 189         Gets the bottom point of the rectangle.
 190     */
 191     int GetBottom() const;
 192
 193     /**
 194         Gets the position of the bottom left corner.
 195     */
 196     wxPoint GetBottomLeft() const;
 197
 198     /**
 199         Gets the position of the bottom right corner.
 200     */
 201     wxPoint GetBottomRight() const;
 202
 203     /**
 204         Gets the height member.
 205     */
 206     int GetHeight() const;
 207
 208     /**
 209         Gets the left point of the rectangle (the same as wxRect::GetX).
 210     */
 211     int GetLeft() const;
 212
 213     /**
 214         Gets the position.
 215     */
 216     wxPoint GetPosition() const;
 217
 218     /**
 219         Gets the right point of the rectangle.
 220     */
 221     int GetRight() const;
 222
 223     /**
 224         Gets the size.
 225
 226         @see SetSize()
 227     */
 228     wxSize GetSize() const;
 229
 230     /**
 231         Gets the top point of the rectangle (the same as wxRect::GetY).
 232     */
 233     int GetTop() const;
 234
 235     /**
 236         Gets the position of the top left corner of the rectangle, same as
 237         GetPosition().
 238     */
 239     wxPoint GetTopLeft() const;
 240
 241     /**
 242         Gets the position of the top right corner.
 243     */
 244     wxPoint GetTopRight() const;
 245
 246     /**
 247         Gets the width member.
 248     */
 249     int GetWidth() const;
 250
 251     /**
 252         Gets the x member.
 253     */
 254     int GetX() const;
 255
 256     /**
 257         Gets the y member.
 258     */
 259     int GetY() const;
 260
 261     //@{
 262     /**
 263         Increases the size of the rectangle.
 264         The second form uses the same @a diff for both @a dx and @e dy.
 265         The first two versions modify the rectangle in place, the last one returns a
 266         new rectangle leaving this one unchanged.
 267         The left border is moved farther left and the right border is moved farther
 268         right by @e dx. The upper border is moved farther up and the bottom border
 269         is moved farther down by @e dy. (Note the the width and height of the
 270         rectangle thus change by 2*@a dx and 2*@e dy, respectively.) If one or
 271         both of @a dx and @a dy are negative, the opposite happens: the rectangle
 272         size decreases in the respective direction.
 273         Inflating and deflating behaves "naturally''. Defined more precisely, that
 274         means:
 275              "Real'' inflates (that is, @a dx and/or @a dy = 0) are not
 276                 constrained. Thus inflating a rectangle can cause its upper left corner
 277                 to move into the negative numbers. (the versions prior to 2.5.4 forced
 278                 the top left coordinate to not fall below (0, 0), which implied a
 279                 forced move of the rectangle.)
 280              Deflates are clamped to not reduce the width or height of the
 281                 rectangle below zero. In such cases, the top-left corner is nonetheless
 282                 handled properly. For example, a rectangle at (10, 10) with size (20,
 283                 40) that is inflated by (-15, -15) will become located at (20, 25) at
 284                 size (0, 10). Finally, observe that the width and height are treated
 285                 independently. In the above example, the width is reduced by 20,
 286                 whereas the height is reduced by the full 30 (rather than also stopping
 287                 at 20, when the width reached zero).
 288
 289         @see Deflate()
 290     */
 291     void Inflate(wxCoord dx, wxCoord dy) const;
 292     void Inflate(const wxSize& diff) const;
 293     void Inflate(wxCoord diff) const;
 294     wxRect Inflate(wxCoord dx, wxCoord dy) const;
 295     //@}
 296
 297     //@{
 298     /**
 299         Modifies the rectangle to contain the overlapping box of this rectangle and the
 300         one passed in as parameter. The const version returns the new rectangle, the
 301         other one modifies this rectangle in place.
 302     */
 303     wxRect Intersect(const wxRect& rect);
 304     const wxRect&  Intersect(const wxRect& rect);
 305     //@}
 306
 307     /**
 308         Returns @true if this rectangle has a non-empty intersection with the
 309         rectangle @a rect and @false otherwise.
 310     */
 311     bool Intersects(const wxRect& rect) const;
 312
 313     /**
 314         Returns @true if this rectangle has a width or height less than or equal to
 315         0 and @false otherwise.
 316     */
 317     bool IsEmpty() const;
 318
 319     //@{
 320     /**
 321         Moves the rectangle by the specified offset. If @a dx is positive, the
 322         rectangle is moved to the right, if @a dy is positive, it is moved to the
 323         bottom, otherwise it is moved to the left or top respectively.
 324     */
 325     void Offset(wxCoord dx, wxCoord dy);
 326     void Offset(const wxPoint& pt);
 327     //@}
 328
 329     /**
 330         Sets the height.
 331     */
 332     void SetHeight(int height);
 333
 334     /**
 335         Sets the size.
 336
 337         @see GetSize()
 338     */
 339     void SetSize(const wxSize& s);
 340
 341     /**
 342         Sets the width.
 343     */
 344     void SetWidth(int width);
 345
 346     /**
 347         Sets the x position.
 348     */
 349     void SetX(int x);
 350
 351     /**
 352         Sets the y position.
 353     */
 354     void SetY(int y);
 355
 356     //@{
 357     /**
 358         Modifies the rectangle to contain the bounding box of this rectangle and the
 359         one passed in as parameter. The const version returns the new rectangle, the
 360         other one modifies this rectangle in place.
 361     */
 362     wxRect Union(const wxRect& rect);
 363     const wxRect&  Union(const wxRect& rect);
 364     //@}
 365
 366     /**
 367         int height
 368         Height member.
 369     */
 370
 371
 372     //@{
 373     /**
 374         Returns the intersection of two rectangles (which may be empty).
 375     */
 376     bool operator !=(const wxRect& r1, const wxRect& r2);
 377     wxRect operator +(const wxRect& r1, const wxRect& r2);
 378     wxRect operator +=(const wxRect& r);
 379     See also wxRect  operator *(const wxRect& r1,
 380                                 const wxRect& r2);
 381     wxRect operator *=(const wxRect& r);
 382     //@}
 383
 384     /**
 385         Assignment operator.
 386     */
 387     void operator =(const wxRect& rect);
 388
 389     /**
 390         Equality operator.
 391     */
 392     bool operator ==(const wxRect& r1, const wxRect& r2);
 393
 394     /**
 395         int width
 396         Width member.
 397     */
 398
 399
 400     /**
 401         int x
 402         x coordinate of the top-level corner of the rectangle.
 403     */
 404
 405
 406     /**
 407         int y
 408         y coordinate of the top-level corner of the rectangle.
 409     */
 410 };
 411
 412
 413
 414 /**
 415     @class wxBrushList
 416     @wxheader{gdicmn.h}
 417
 418     A brush list is a list containing all brushes which have been created.
 419
 420     @library{wxcore}
 421     @category{gdi}
 422
 423     @see wxBrush
 424 */
 425 class wxBrushList : public wxList
 426 {
 427 public:
 428     /**
 429         Constructor. The application should not construct its own brush list:
 430         use the object pointer @b wxTheBrushList.
 431     */
 432     wxBrushList();
 433
 434     /**
 435         Finds a brush with the specified attributes and returns it, else creates a new
 436         brush, adds it
 437         to the brush list, and returns it.
 438
 439         @param colour
 440             Colour object.
 441         @param style
 442             Brush style. See wxBrush::SetStyle for a list of styles.
 443     */
 444     wxBrush* FindOrCreateBrush(const wxColour& colour,
 445                                int style = wxSOLID);
 446 };
 447
 448
 449
 450 /**
 451     @class wxPoint
 452     @wxheader{gdicmn.h}
 453
 454     A @b wxPoint is a useful data structure for graphics operations.
 455     It simply contains integer @e x and @e y members.
 456
 457     See also wxRealPoint for a floating point version.
 458
 459     @library{wxcore}
 460     @category{data}
 461
 462     @see wxRealPoint
 463 */
 464 class wxPoint
 465 {
 466 public:
 467     //@{
 468     /**
 469         Create a point.
 470     */
 471     wxPoint();
 472     wxPoint(int x, int y);
 473     //@}
 474
 475     //@{
 476     /**
 477         Operators for sum and subtraction between a wxPoint object and a
 478         wxSize object.
 479     */
 480     void operator =(const wxPoint& pt);
 481     bool operator ==(const wxPoint& p1, const wxPoint& p2);
 482     bool operator !=(const wxPoint& p1, const wxPoint& p2);
 483     wxPoint operator +(const wxPoint& p1, const wxPoint& p2);
 484     wxPoint operator -(const wxPoint& p1, const wxPoint& p2);
 485     wxPoint operator +=(const wxPoint& pt);
 486     wxPoint operator -=(const wxPoint& pt);
 487     wxPoint operator +(const wxPoint& pt, const wxSize& sz);
 488     wxPoint operator -(const wxPoint& pt, const wxSize& sz);
 489     wxPoint operator +(const wxSize& sz, const wxPoint& pt);
 490     wxPoint operator -(const wxSize& sz, const wxPoint& pt);
 491     wxPoint operator +=(const wxSize& sz);
 492     wxPoint operator -=(const wxSize& sz);
 493     //@}
 494
 495     /**
 496         int x
 497         x member.
 498     */
 499
 500
 501     /**
 502         int  y
 503         y member.
 504     */
 505 };
 506
 507
 508
 509 /**
 510     @class wxColourDatabase
 511     @wxheader{gdicmn.h}
 512
 513     wxWidgets maintains a database of standard RGB colours for a predefined
 514     set of named colours (such as "BLACK'', "LIGHT GREY''). The
 515     application may add to this set if desired by using
 516     wxColourDatabase::AddColour and may use it to look up
 517     colours by names using wxColourDatabase::Find or find the names
 518     for the standard colour suing wxColourDatabase::FindName.
 519
 520     There is one predefined instance of this class called
 521     @b wxTheColourDatabase.
 522
 523     @library{wxcore}
 524     @category{FIXME}
 525
 526     @see wxColour
 527 */
 528 class wxColourDatabase
 529 {
 530 public:
 531     /**
 532         Constructs the colour database. It will be initialized at the first use.
 533     */
 534     wxColourDatabase();
 535
 536     //@{
 537     /**
 538         Adds a colour to the database. If a colour with the same name already exists,
 539         it is replaced.
 540         Please note that the overload taking a pointer is deprecated and will be
 541         removed in the next wxWidgets version, please don't use it.
 542     */
 543     void AddColour(const wxString& colourName,
 544                    const wxColour& colour);
 545     void AddColour(const wxString& colourName, wxColour* colour);
 546     //@}
 547
 548     /**
 549         Finds a colour given the name. Returns an invalid colour object (that is, such
 550         that its @ref wxColour::isok Ok method returns @false) if the colour wasn't
 551         found in the database.
 552     */
 553     wxColour Find(const wxString& colourName);
 554
 555     /**
 556         Finds a colour name given the colour. Returns an empty string if the colour is
 557         not found in the database.
 558     */
 559     wxString FindName(const wxColour& colour) const;
 560 };
 561
 562
 563
 564 /**
 565     @class wxFontList
 566     @wxheader{gdicmn.h}
 567
 568     A font list is a list containing all fonts which have been created. There
 569     is only one instance of this class: @b wxTheFontList.  Use this object to search
 570     for a previously created font of the desired type and create it if not already
 571     found.
 572     In some windowing systems, the font may be a scarce resource, so it is best to
 573     reuse old resources if possible.  When an application finishes, all fonts will
 574     be
 575     deleted and their resources freed, eliminating the possibility of 'memory
 576     leaks'.
 577
 578     @library{wxcore}
 579     @category{gdi}
 580
 581     @see wxFont
 582 */
 583 class wxFontList : public wxList
 584 {
 585 public:
 586     /**
 587         Constructor. The application should not construct its own font list:
 588         use the object pointer @b wxTheFontList.
 589     */
 590     wxFontList();
 591
 592     /**
 593         Finds a font of the given specification, or creates one and adds it to the
 594         list. See the @ref wxFont::ctor "wxFont constructor" for
 595         details of the arguments.
 596     */
 597     wxFont* FindOrCreateFont(int point_size, int family, int style,
 598                              int weight,
 599                              bool underline = false,
 600                              const wxString& facename = NULL,
 601                              wxFontEncoding encoding = wxFONTENCODING_DEFAULT);
 602 };
 603
 604
 605
 606 /**
 607     @class wxSize
 608     @wxheader{gdicmn.h}
 609
 610     A @b wxSize is a useful data structure for graphics operations.
 611     It simply contains integer @e width and @e height members.
 612
 613     wxSize is used throughout wxWidgets as well as wxPoint which, although almost
 614     equivalent to wxSize, has a different meaning: wxPoint represents a position
 615     while wxSize - the size.
 616
 617     @b wxPython note: wxPython defines aliases for the @c x and @c y members
 618     named @c width and @c height since it makes much more sense for
 619     sizes.
 620
 621
 622     @library{wxcore}
 623     @category{data}
 624
 625     @see wxPoint, wxRealPoint
 626 */
 627 class wxSize
 628 {
 629 public:
 630     //@{
 631     /**
 632         Creates a size object.
 633     */
 634     wxSize();
 635     wxSize(int width, int height);
 636     //@}
 637
 638     //@{
 639     /**
 640         Decreases the size in x- and y- directions
 641              By @e size.x and @e size.y for the first overload
 642              By @a dx and @a dy for the second one
 643              By @a d and @a d for the third one
 644
 645         @see IncBy()
 646     */
 647     void DecBy(const wxSize& size);
 648     void DecBy(int dx, int dy);
 649     void DecBy(int d);
 650     //@}
 651
 652     /**
 653         Decrements this object so that both of its dimensions are not greater than the
 654         corresponding dimensions of the @e size.
 655
 656         @see IncTo()
 657     */
 658     void DecTo(const wxSize& size);
 659
 660     /**
 661         Gets the height member.
 662     */
 663     int GetHeight() const;
 664
 665     /**
 666         Gets the width member.
 667     */
 668     int GetWidth() const;
 669
 670     //@{
 671     /**
 672         Increases the size in x- and y- directions
 673              By @e size.x and @e size.y for the first overload
 674              By @a dx and @a dy for the second one
 675              By @a d and @a d for the third one
 676
 677         @see DecBy()
 678     */
 679     void IncBy(const wxSize& size);
 680     void IncBy(int dx, int dy);
 681     void IncBy(int d);
 682     //@}
 683
 684     /**
 685         Increments this object so that both of its dimensions are not less than the
 686         corresponding dimensions of the @e size.
 687
 688         @see DecTo()
 689     */
 690     void IncTo(const wxSize& size);
 691
 692     /**
 693         Returns @true if neither of the size object components is equal to -1, which
 694         is used as default for the size values in wxWidgets (hence the predefined
 695         @c wxDefaultSize has both of its components equal to -1).
 696         This method is typically used before calling
 697         SetDefaults().
 698     */
 699     bool IsFullySpecified() const;
 700
 701     //@{
 702     /**
 703         Operators for division and multiplication between a wxSize object and an
 704         integer.
 705     */
 706     void operator =(const wxSize& sz);
 707     bool operator ==(const wxSize& s1, const wxSize& s2);
 708     bool operator !=(const wxSize& s1, const wxSize& s2);
 709     wxSize operator +(const wxSize& s1, const wxSize& s2);
 710     wxSize operator -(const wxSize& s1, const wxSize& s2);
 711     wxSize operator +=(const wxSize& sz);
 712     wxSize operator -=(const wxSize& sz);
 713     wxSize operator /(const wxSize& sz, int factor);
 714     wxSize operator *(const wxSize& sz, int factor);
 715     wxSize operator *(int factor, const wxSize& sz);
 716     wxSize operator /=(int factor);
 717     wxSize operator *=(int factor);
 718     //@}
 719
 720     /**
 721         Scales the dimensions of this object by the given factors.
 722         If you want to scale both dimensions by the same factor you can also use
 723         the @ref operators() "operator *="
 724         Returns a reference to this object (so that you can concatenate other
 725         operations in the same line).
 726     */
 727     wxSize Scale(float xscale, float yscale);
 728
 729     /**
 730         Sets the width and height members.
 731     */
 732     void Set(int width, int height);
 733
 734     /**
 735         Combine this size object with another one replacing the default (i.e. equal
 736         to -1) components of this object with those of the other. It is typically
 737         used like this:
 738
 739         @see IsFullySpecified()
 740     */
 741     void SetDefaults(const wxSize& sizeDefault);
 742
 743     /**
 744         Sets the height.
 745     */
 746     void SetHeight(int height);
 747
 748     /**
 749         Sets the width.
 750     */
 751     void SetWidth(int width);
 752 };
 753
 754
 755
 756 /**
 757     @class wxPenList
 758     @wxheader{gdicmn.h}
 759
 760     There is only one instance of this class: @b wxThePenList.  Use
 761     this object to search for a previously created pen of the desired
 762     type and create it if not already found. In some windowing systems,
 763     the pen may be a scarce resource, so it can pay to reuse old
 764     resources if possible. When an application finishes, all pens will
 765     be deleted and their resources freed, eliminating the possibility of
 766     'memory leaks'. However, it is best not to rely on this automatic
 767     cleanup because it can lead to double deletion in some circumstances.
 768
 769     There are two mechanisms in recent versions of wxWidgets which make the
 770     pen list less useful than it once was. Under Windows, scarce resources
 771     are cleaned up internally if they are not being used. Also, a referencing
 772     counting mechanism applied to all GDI objects means that some sharing
 773     of underlying resources is possible. You don't have to keep track of pointers,
 774     working out when it is safe delete a pen, because the referencing counting does
 775     it for you. For example, you can set a pen in a device context, and then
 776     immediately delete the pen you passed, because the pen is 'copied'.
 777
 778     So you may find it easier to ignore the pen list, and instead create
 779     and copy pens as you see fit. If your Windows resource meter suggests
 780     your application is using too many resources, you can resort to using
 781     GDI lists to share objects explicitly.
 782
 783     The only compelling use for the pen list is for wxWidgets to keep
 784     track of pens in order to clean them up on exit. It is also kept for
 785     backward compatibility with earlier versions of wxWidgets.
 786
 787     @library{wxcore}
 788     @category{gdi}
 789
 790     @see wxPen
 791 */
 792 class wxPenList
 793 {
 794 public:
 795     /**
 796         Constructor. The application should not construct its own pen list:
 797         use the object pointer @b wxThePenList.
 798     */
 799     wxPenList();
 800
 801     //@{
 802     /**
 803         Finds a pen with the specified attributes and returns it, else creates a new
 804         pen, adds it
 805         to the pen list, and returns it.
 806
 807         @param colour
 808             Colour object.
 809         @param colourName
 810             Colour name, which should be in the colour database.
 811         @param width
 812             Width of pen.
 813         @param style
 814             Pen style. See wxPen::wxPen for a list of styles.
 815     */
 816     wxPen* FindOrCreatePen(const wxColour& colour, int width,
 817                            int style);
 818     wxPen* FindOrCreatePen(const wxString& colourName, int width,
 819                            int style);
 820     //@}
 821 };
 822
 823
 824
 825 // ============================================================================
 826 // Global functions/macros
 827 // ============================================================================
 828
 829 /** @ingroup group_funcmacro_gdi */
 830 //@{
 831
 832 /**
 833     Returns the dimensions of the work area on the display.  On Windows
 834     this means the area not covered by the taskbar, etc.  Other platforms
 835     are currently defaulting to the whole display until a way is found to
 836     provide this info for all window managers, etc.
 837 */
 838 void wxClientDisplayRect(int* x, int* y, int* width,
 839                          int* height);
 840 wxRect wxGetClientDisplayRect();
 841
 842 /**
 843     Returns the display size in pixels.
 844 */
 845 void wxDisplaySize(int* width, int* height);
 846 wxSize wxGetDisplaySize();
 847
 848 /**
 849     Returns the display size in millimeters.
 850 */
 851 void wxDisplaySizeMM(int* width, int* height);
 852 wxSize wxGetDisplaySizeMM();
 853
 854 /**
 855     This macro loads an icon from either application resources (on the platforms
 856     for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
 857     avoid using @c #ifdefs when creating icons.
 858
 859     @see @ref overview_wxbitmapoverview, wxBITMAP()
 860 */
 861 wxICON();
 862
 863 /**
 864     Returns @true if the display is colour, @false otherwise.
 865 */
 866 bool wxColourDisplay();
 867
 868 /**
 869     This macro loads a bitmap from either application resources (on the platforms
 870     for which they exist, i.e. Windows and OS2) or from an XPM file. It allows to
 871     avoid using @c #ifdefs when creating bitmaps.
 872
 873     @see @ref overview_wxbitmapoverview, wxICON()
 874 */
 875 #define wxBITMAP() /* implementation is private */
 876
 877 /**
 878     Returns the depth of the display (a value of 1 denotes a monochrome display).
 879 */
 880 int wxDisplayDepth();
 881
 882 //@}
 883