interface/wx/gdicmn.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        gdicmn.h
   3 // Purpose:     interface of wxRealPoint
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8
   9 /**
  10     Bitmap type flags. See wxBitmap and wxImage classes.
  11 */
  12 enum wxBitmapType
  13 {
  14     wxBITMAP_TYPE_INVALID,
  15     wxBITMAP_TYPE_BMP,
  16     wxBITMAP_TYPE_BMP_RESOURCE,
  17     wxBITMAP_TYPE_RESOURCE = wxBITMAP_TYPE_BMP_RESOURCE,
  18     wxBITMAP_TYPE_ICO,
  19     wxBITMAP_TYPE_ICO_RESOURCE,
  20     wxBITMAP_TYPE_CUR,
  21     wxBITMAP_TYPE_CUR_RESOURCE,
  22     wxBITMAP_TYPE_XBM,
  23     wxBITMAP_TYPE_XBM_DATA,
  24     wxBITMAP_TYPE_XPM,
  25     wxBITMAP_TYPE_XPM_DATA,
  26     wxBITMAP_TYPE_TIFF,
  27     wxBITMAP_TYPE_TIF = wxBITMAP_TYPE_TIFF,
  28     wxBITMAP_TYPE_TIFF_RESOURCE,
  29     wxBITMAP_TYPE_TIF_RESOURCE = wxBITMAP_TYPE_TIFF_RESOURCE,
  30     wxBITMAP_TYPE_GIF,
  31     wxBITMAP_TYPE_GIF_RESOURCE,
  32     wxBITMAP_TYPE_PNG,
  33     wxBITMAP_TYPE_PNG_RESOURCE,
  34     wxBITMAP_TYPE_JPEG,
  35     wxBITMAP_TYPE_JPEG_RESOURCE,
  36     wxBITMAP_TYPE_PNM,
  37     wxBITMAP_TYPE_PNM_RESOURCE,
  38     wxBITMAP_TYPE_PCX,
  39     wxBITMAP_TYPE_PCX_RESOURCE,
  40     wxBITMAP_TYPE_PICT,
  41     wxBITMAP_TYPE_PICT_RESOURCE,
  42     wxBITMAP_TYPE_ICON,
  43     wxBITMAP_TYPE_ICON_RESOURCE,
  44     wxBITMAP_TYPE_ANI,
  45     wxBITMAP_TYPE_IFF,
  46     wxBITMAP_TYPE_TGA,
  47     wxBITMAP_TYPE_MACCURSOR,
  48     wxBITMAP_TYPE_MACCURSOR_RESOURCE,
  49     wxBITMAP_TYPE_ANY = 50
  50 };
  51
  52 /**
  53     Polygon filling mode. See wxDC::DrawPolygon.
  54 */
  55 enum wxPolygonFillMode
  56 {
  57     wxODDEVEN_RULE = 1,
  58     wxWINDING_RULE
  59 };
  60
  61 /**
  62     Standard cursors.
  63
  64     Notice that under wxMSW some of these cursors are defined in @c wx.rc file
  65     and not by the system itself so you should include this file from your own
  66     resource file (possibly creating a trivial resource file just containing a
  67     single include line if you don't need it otherwise) to be able to use them.
  68
  69     See wxCursor.
  70 */
  71 enum wxStockCursor
  72 {
  73     wxCURSOR_NONE,
  74     wxCURSOR_ARROW,             ///< A standard arrow cursor.
  75     wxCURSOR_RIGHT_ARROW,       ///< A standard arrow cursor pointing to the right.
  76     wxCURSOR_BULLSEYE,          ///< Bullseye cursor.
  77     wxCURSOR_CHAR,              ///< Rectangular character cursor.
  78     wxCURSOR_CROSS,             ///< A cross cursor.
  79     wxCURSOR_HAND,              ///< A hand cursor.
  80     wxCURSOR_IBEAM,             ///< An I-beam cursor (vertical line).
  81     wxCURSOR_LEFT_BUTTON,       ///< Represents a mouse with the left button depressed.
  82     wxCURSOR_MAGNIFIER,         ///< A magnifier icon.
  83     wxCURSOR_MIDDLE_BUTTON,     ///< Represents a mouse with the middle button depressed.
  84     wxCURSOR_NO_ENTRY,          ///< A no-entry sign cursor.
  85     wxCURSOR_PAINT_BRUSH,       ///< A paintbrush cursor.
  86     wxCURSOR_PENCIL,            ///< A pencil cursor.
  87     wxCURSOR_POINT_LEFT,        ///< A cursor that points left.
  88     wxCURSOR_POINT_RIGHT,       ///< A cursor that points right.
  89     wxCURSOR_QUESTION_ARROW,    ///< An arrow and question mark.
  90     wxCURSOR_RIGHT_BUTTON,      ///< Represents a mouse with the right button depressed.
  91     wxCURSOR_SIZENESW,          ///< A sizing cursor pointing NE-SW.
  92     wxCURSOR_SIZENS,            ///< A sizing cursor pointing N-S.
  93     wxCURSOR_SIZENWSE,          ///< A sizing cursor pointing NW-SE.
  94     wxCURSOR_SIZEWE,            ///< A sizing cursor pointing W-E.
  95     wxCURSOR_SIZING,            ///< A general sizing cursor.
  96     wxCURSOR_SPRAYCAN,          ///< A spraycan cursor.
  97     wxCURSOR_WAIT,              ///< A wait cursor.
  98     wxCURSOR_WATCH,             ///< A watch cursor.
  99     wxCURSOR_BLANK,             ///< Transparent cursor.
 100     wxCURSOR_DEFAULT,           ///< Standard X11 cursor (only in wxGTK).
 101     wxCURSOR_COPY_ARROW ,       ///< MacOS Theme Plus arrow (only in wxMac).
 102     wxCURSOR_CROSS_REVERSE,     ///< Only available on wxX11.
 103     wxCURSOR_DOUBLE_ARROW,      ///< Only available on wxX11.
 104     wxCURSOR_BASED_ARROW_UP,    ///< Only available on wxX11.
 105     wxCURSOR_BASED_ARROW_DOWN,  ///< Only available on wxX11.
 106     wxCURSOR_ARROWWAIT,         ///< A wait cursor with a standard arrow.
 107     wxCURSOR_MAX
 108 };
 109
 110
 111
 112 /**
 113     @class wxRealPoint
 114
 115     A wxRealPoint is a useful data structure for graphics operations.
 116
 117     It contains floating point @e x and @e y members.
 118     See wxPoint for an integer version.
 119
 120     Note that the coordinates stored inside a wxRealPoint object may be negative
 121     and that wxRealPoint functions do not perform any check against negative values.
 122
 123     @library{wxcore}
 124     @category{data}
 125
 126     @see wxPoint
 127 */
 128 class wxRealPoint
 129 {
 130 public:
 131     /**
 132         Initializes to zero the x and y members.
 133     */
 134     wxRealPoint();
 135
 136     /**
 137         Initializes the point with the given coordinates.
 138     */
 139     wxRealPoint(double x, double y);
 140
 141     /**
 142         Converts the given wxPoint (with integer coordinates) to a wxRealPoint.
 143     */
 144     wxRealPoint(const wxPoint& pt);
 145
 146     /**
 147         @name Miscellaneous operators
 148
 149         Note that these operators are documented as class members
 150         (to make them easier to find) but, as their prototype shows,
 151         they are implemented as global operators; note that this is
 152         transparent to the user but it helps to understand why the
 153         following functions are documented to take the wxPoint they
 154         operate on as an explicit argument.
 155     */
 156     //@{
 157     wxRealPoint& operator=(const wxRealPoint& pt);
 158
 159     bool operator ==(const wxRealPoint& p1, const wxRealPoint& p2);
 160     bool operator !=(const wxRealPoint& p1, const wxRealPoint& p2);
 161
 162     wxRealPoint operator +(const wxRealPoint& p1, const wxRealPoint& p2);
 163     wxRealPoint operator -(const wxRealPoint& p1, const wxRealPoint& p2);
 164
 165     wxRealPoint& operator +=(const wxRealPoint& pt);
 166     wxRealPoint& operator -=(const wxRealPoint& pt);
 167
 168     wxRealPoint operator +(const wxRealPoint& pt, const wxSize& sz);
 169     wxRealPoint operator -(const wxRealPoint& pt, const wxSize& sz);
 170     wxRealPoint operator +(const wxSize& sz, const wxRealPoint& pt);
 171     wxRealPoint operator -(const wxSize& sz, const wxRealPoint& pt);
 172
 173     wxRealPoint& operator +=(const wxSize& sz);
 174     wxRealPoint& operator -=(const wxSize& sz);
 175
 176     wxSize operator /(const wxRealPoint& sz, int factor);
 177     wxSize operator *(const wxRealPoint& sz, int factor);
 178     wxSize operator *(int factor, const wxSize& sz);
 179     wxSize& operator /=(int factor);
 180     wxSize& operator *=(int factor);
 181     //@}
 182
 183     /**
 184         X coordinate of this point.
 185     */
 186     double x;
 187
 188     /**
 189         Y coordinate of this point.
 190     */
 191     double y;
 192 };
 193
 194
 195
 196 /**
 197     @class wxRect
 198
 199     A class for manipulating rectangles.
 200
 201     Note that the x, y coordinates and the width and height stored inside a wxRect
 202     object may be negative and that wxRect functions do not perform any check against
 203     negative values.
 204
 205     @library{wxcore}
 206     @category{data}
 207
 208     @see wxPoint, wxSize
 209 */
 210 class wxRect
 211 {
 212 public:
 213     /**
 214         Default constructor.
 215         Initializes to zero the internal @a x, @a y, @a width and @a height members.
 216     */
 217     wxRect();
 218     /**
 219         Creates a wxRect object from @a x, @a y, @a width and @a height values.
 220     */
 221     wxRect(int x, int y, int width, int height);
 222     /**
 223         Creates a wxRect object from top-left and bottom-right points.
 224     */
 225     wxRect(const wxPoint& topLeft, const wxPoint& bottomRight);
 226     /**
 227         Creates a wxRect object from position @a pos and @a size values.
 228     */
 229     wxRect(const wxPoint& pos, const wxSize& size);
 230     /**
 231         Creates a wxRect object from @a size values at the origin.
 232     */
 233     wxRect(const wxSize& size);
 234
 235     //@{
 236     /**
 237         Returns the rectangle having the same size as this one but centered
 238         relatively to the given rectangle @a r. By default, rectangle is
 239         centred in both directions but if @a dir includes only @c wxVERTICAL or
 240         only @c wxHORIZONTAL, then it is only centered in this direction while
 241         the other component of its position remains unchanged.
 242     */
 243     wxRect CentreIn(const wxRect& r, int dir = wxBOTH) const;
 244     wxRect CenterIn(const wxRect& r, int dir = wxBOTH) const;
 245     //@}
 246
 247     /**
 248         Returns @true if the given point is inside the rectangle (or on its
 249         boundary) and @false otherwise.
 250     */
 251     bool Contains(int x, int y) const;
 252     /**
 253         Returns @true if the given point is inside the rectangle (or on its
 254         boundary) and @false otherwise.
 255     */
 256     bool Contains(const wxPoint& pt) const;
 257     /**
 258         Returns @true if the given rectangle is completely inside this
 259         rectangle (or touches its boundary) and @false otherwise.
 260     */
 261     bool Contains(const wxRect& rect) const;
 262
 263     //@{
 264     /**
 265         Decrease the rectangle size.
 266
 267         This method is the opposite from Inflate(): Deflate(a, b) is equivalent
 268         to Inflate(-a, -b). Please refer to Inflate() for full description.
 269     */
 270     wxRect& Deflate(wxCoord dx, wxCoord dy);
 271     wxRect& Deflate(const wxSize& diff);
 272     wxRect& Deflate(wxCoord diff);
 273     wxRect  Deflate(wxCoord dx, wxCoord dy) const;
 274     //@}
 275
 276     /**
 277         Gets the bottom point of the rectangle.
 278     */
 279     int GetBottom() const;
 280
 281     /**
 282         Gets the position of the bottom left corner.
 283     */
 284     wxPoint GetBottomLeft() const;
 285
 286     /**
 287         Gets the position of the bottom right corner.
 288     */
 289     wxPoint GetBottomRight() const;
 290
 291     /**
 292         Gets the height member.
 293     */
 294     int GetHeight() const;
 295
 296     /**
 297         Gets the left point of the rectangle (the same as GetX()).
 298     */
 299     int GetLeft() const;
 300
 301     /**
 302         Gets the position.
 303     */
 304     wxPoint GetPosition() const;
 305
 306     /**
 307         Gets the right point of the rectangle.
 308     */
 309     int GetRight() const;
 310
 311     /**
 312         Gets the size.
 313
 314         @see SetSize()
 315     */
 316     wxSize GetSize() const;
 317
 318     /**
 319         Gets the top point of the rectangle (the same as GetY()).
 320     */
 321     int GetTop() const;
 322
 323     /**
 324         Gets the position of the top left corner of the rectangle, same as
 325         GetPosition().
 326     */
 327     wxPoint GetTopLeft() const;
 328
 329     /**
 330         Gets the position of the top right corner.
 331     */
 332     wxPoint GetTopRight() const;
 333
 334     /**
 335         Gets the width member.
 336     */
 337     int GetWidth() const;
 338
 339     /**
 340         Gets the x member.
 341     */
 342     int GetX() const;
 343
 344     /**
 345         Gets the y member.
 346     */
 347     int GetY() const;
 348
 349     //@{
 350     /**
 351         Increases the size of the rectangle.
 352
 353         The left border is moved farther left and the right border is moved
 354         farther right by @a dx. The upper border is moved farther up and the
 355         bottom border is moved farther down by @a dy. (Note that the width and
 356         height of the rectangle thus change by 2*dx and 2*dy, respectively.) If
 357         one or both of @a dx and @a dy are negative, the opposite happens: the
 358         rectangle size decreases in the respective direction.
 359
 360         Inflating and deflating behaves "naturally". Defined more precisely,
 361         that means:
 362         -# "Real" inflates (that is, @a dx and/or @a dy = 0) are not
 363            constrained. Thus inflating a rectangle can cause its upper left
 364            corner to move into the negative numbers. (2.5.4 and older forced
 365            the top left coordinate to not fall below (0, 0), which implied a
 366            forced move of the rectangle.)
 367         -# Deflates are clamped to not reduce the width or height of the
 368            rectangle below zero. In such cases, the top-left corner is
 369            nonetheless handled properly. For example, a rectangle at (10, 10)
 370            with size (20, 40) that is inflated by (-15, -15) will become
 371            located at (20, 25) at size (0, 10). Finally, observe that the width
 372            and height are treated independently. In the above example, the
 373            width is reduced by 20, whereas the height is reduced by the full 30
 374            (rather than also stopping at 20, when the width reached zero).
 375
 376         @see Deflate()
 377     */
 378     wxRect& Inflate(wxCoord dx, wxCoord dy);
 379     wxRect& Inflate(const wxSize& diff);
 380     wxRect& Inflate(wxCoord diff);
 381     wxRect Inflate(wxCoord dx, wxCoord dy) const;
 382     //@}
 383
 384     /**
 385         Modifies this rectangle to contain the overlapping portion of this rectangle
 386         and the one passed in as parameter.
 387
 388         @return This rectangle, modified.
 389     */
 390     wxRect& Intersect(const wxRect& rect);
 391
 392     /**
 393         Returns the overlapping portion of this rectangle and the one passed in as
 394         parameter.
 395     */
 396     wxRect Intersect(const wxRect& rect) const;
 397
 398     /**
 399         Returns @true if this rectangle has a non-empty intersection with the
 400         rectangle @a rect and @false otherwise.
 401     */
 402     bool Intersects(const wxRect& rect) const;
 403
 404     /**
 405         Returns @true if this rectangle has a width or height less than or
 406         equal to 0 and @false otherwise.
 407     */
 408     bool IsEmpty() const;
 409
 410     //@{
 411     /**
 412         Moves the rectangle by the specified offset. If @a dx is positive, the
 413         rectangle is moved to the right, if @a dy is positive, it is moved to the
 414         bottom, otherwise it is moved to the left or top respectively.
 415     */
 416     void Offset(wxCoord dx, wxCoord dy);
 417     void Offset(const wxPoint& pt);
 418     //@}
 419
 420     /**
 421         Sets the height.
 422     */
 423     void SetHeight(int height);
 424
 425     /**
 426         Sets the position.
 427     */
 428     void SetPosition(const wxPoint& pos);
 429
 430     /**
 431         Sets the size.
 432
 433         @see GetSize()
 434     */
 435     void SetSize(const wxSize& s);
 436
 437     /**
 438         Sets the width.
 439     */
 440     void SetWidth(int width);
 441
 442     /**
 443         Sets the x position.
 444     */
 445     void SetX(int x);
 446
 447     /**
 448         Sets the y position.
 449     */
 450     void SetY(int y);
 451
 452     /**
 453        Set the left side of the rectangle.
 454
 455        Notice that because the rectangle stores its left side and width,
 456        calling SetLeft() changes the right side position too -- but does
 457        preserve the width.
 458     */
 459     void SetLeft(int left);
 460
 461     /**
 462        Set the right side of the rectangle.
 463
 464        Notice that this doesn't affect GetLeft() return value but changes the
 465        rectangle width to set its right side to the given position.
 466      */
 467     void SetRight(int right);
 468
 469     /**
 470        Set the top edge of the rectangle.
 471
 472        Notice that because the rectangle stores its top side and height,
 473        calling SetTop() changes the bottom side position too -- but does
 474        preserve the height.
 475      */
 476     void SetTop(int top);
 477
 478     /**
 479        Set the bottom edge of the rectangle.
 480
 481        Notice that this doesn't affect GetTop() return value but changes the
 482        rectangle height to set its bottom side to the given position.
 483      */
 484     void SetBottom(int bottom);
 485
 486     /**
 487        Set the top-left point of the rectangle.
 488      */
 489     void SetTopLeft(const wxPoint &p);
 490
 491     /**
 492        Set the bottom-right point of the rectangle.
 493      */
 494     void SetBottomRight(const wxPoint &p);
 495
 496     /**
 497        Set the top-right point of the rectangle.
 498      */
 499     void SetTopRight(const wxPoint &p);
 500
 501     /**
 502        Set the bottom-left point of the rectangle.
 503      */
 504     void SetBottomLeft(const wxPoint &p);
 505
 506
 507     //@{
 508     /**
 509         Modifies the rectangle to contain the bounding box of this rectangle
 510         and the one passed in as parameter.
 511     */
 512     wxRect Union(const wxRect& rect) const;
 513     wxRect& Union(const wxRect& rect);
 514     //@}
 515
 516     /**
 517         Inequality operator.
 518     */
 519     bool operator !=(const wxRect& r1, const wxRect& r2);
 520
 521     //@{
 522     /**
 523         Like Union(), but doesn't treat empty rectangles specially.
 524     */
 525     wxRect operator +(const wxRect& r1, const wxRect& r2);
 526     wxRect& operator +=(const wxRect& r);
 527     //@}
 528
 529     //@{
 530     /**
 531         Returns the intersection of two rectangles (which may be empty).
 532     */
 533     wxRect operator *(const wxRect& r1, const wxRect& r2);
 534     wxRect& operator *=(const wxRect& r);
 535     //@}
 536
 537     /**
 538         Assignment operator.
 539     */
 540     wxRect& operator=(const wxRect& rect);
 541
 542     /**
 543         Equality operator.
 544     */
 545     bool operator ==(const wxRect& r1, const wxRect& r2);
 546
 547     /**
 548         Height member.
 549     */
 550     int height;
 551
 552     /**
 553         Width member.
 554     */
 555     int width;
 556
 557     /**
 558         x coordinate of the top-level corner of the rectangle.
 559     */
 560     int x;
 561
 562     /**
 563         y coordinate of the top-level corner of the rectangle.
 564     */
 565     int y;
 566 };
 567
 568
 569
 570 /**
 571     @class wxPoint
 572
 573     A wxPoint is a useful data structure for graphics operations.
 574
 575     It contains integer @e x and @e y members.
 576     See wxRealPoint for a floating point version.
 577
 578     Note that the width and height stored inside a wxPoint object may be negative
 579     and that wxPoint functions do not perform any check against negative values
 580     (this is used to e.g. store the special -1 value in ::wxDefaultPosition instance).
 581
 582     @library{wxcore}
 583     @category{data}
 584
 585     @stdobjects
 586     ::wxDefaultPosition
 587
 588     @see wxRealPoint
 589 */
 590 class wxPoint
 591 {
 592 public:
 593     /**
 594         Constructs a point.
 595         Initializes the internal x and y coordinates to zero.
 596     */
 597     wxPoint();
 598
 599     /**
 600         Initializes the point object with the given @a x and @a y coordinates.
 601     */
 602     wxPoint(int x, int y);
 603
 604     /**
 605         Converts the given wxRealPoint (with floating point coordinates) to a
 606         wxPoint instance.
 607
 608         Notice that this truncates the floating point values of @a pt
 609         components, if you want to round them instead you need to do it
 610         manually, e.g.
 611         @code
 612             #include <wx/math.h>    // for wxRound()
 613
 614             wxRealPoint rp = ...;
 615             wxPoint p(wxRound(rp.x), wxRound(rp.y));
 616         @endcode
 617     */
 618     wxPoint(const wxRealPoint& pt);
 619
 620     /**
 621         @name Miscellaneous operators
 622
 623         Note that these operators are documented as class members
 624         (to make them easier to find) but, as their prototype shows,
 625         they are implemented as global operators; note that this is
 626         transparent to the user but it helps to understand why the
 627         following functions are documented to take the wxPoint they
 628         operate on as an explicit argument.
 629     */
 630     //@{
 631     wxPoint& operator=(const wxPoint& pt);
 632
 633     bool operator ==(const wxPoint& p1, const wxPoint& p2);
 634     bool operator !=(const wxPoint& p1, const wxPoint& p2);
 635
 636     wxPoint operator +(const wxPoint& p1, const wxPoint& p2);
 637     wxPoint operator -(const wxPoint& p1, const wxPoint& p2);
 638
 639     wxPoint& operator +=(const wxPoint& pt);
 640     wxPoint& operator -=(const wxPoint& pt);
 641
 642     wxPoint operator +(const wxPoint& pt, const wxSize& sz);
 643     wxPoint operator -(const wxPoint& pt, const wxSize& sz);
 644     wxPoint operator +(const wxSize& sz, const wxPoint& pt);
 645     wxPoint operator -(const wxSize& sz, const wxPoint& pt);
 646
 647     wxPoint& operator +=(const wxSize& sz);
 648     wxPoint& operator -=(const wxSize& sz);
 649
 650     wxSize operator /(const wxPoint& sz, int factor);
 651     wxSize operator *(const wxPoint& sz, int factor);
 652     wxSize operator *(int factor, const wxSize& sz);
 653     wxSize& operator /=(int factor);
 654     wxSize& operator *=(int factor);
 655     //@}
 656
 657
 658     /**
 659         @name Defaults handling.
 660
 661         Test for and set non-specified wxPoint components.
 662
 663         Although a wxPoint is always initialized to (0, 0), wxWidgets commonly
 664         uses wxDefaultCoord (defined as @c -1) to indicate that a point hasn't
 665         been initialized or specified. In particular, ::wxDefaultPosition is
 666         used in many places with this meaning.
 667      */
 668     //@{
 669
 670     /**
 671         Returns @true if neither of the point components is equal to
 672         wxDefaultCoord.
 673
 674         This method is typically used before calling SetDefaults().
 675
 676         @since 2.9.2
 677     */
 678     bool IsFullySpecified() const;
 679
 680     /**
 681         Combine this object with another one replacing the uninitialized
 682         values.
 683
 684         It is typically used like this:
 685
 686         @code
 687         if ( !pos.IsFullySpecified() )
 688         {
 689             pos.SetDefaults(GetDefaultPosition());
 690         }
 691         @endcode
 692
 693         @see IsFullySpecified()
 694
 695         @since 2.9.2
 696     */
 697     void SetDefaults(const wxPoint& pt);
 698     //@}
 699
 700     /**
 701         x member.
 702     */
 703     int x;
 704
 705     /**
 706         y member.
 707     */
 708     int  y;
 709 };
 710
 711 /**
 712     Global instance of a wxPoint initialized with values (-1,-1).
 713 */
 714 const wxPoint wxDefaultPosition;
 715
 716
 717 /**
 718     @class wxColourDatabase
 719
 720     wxWidgets maintains a database of standard RGB colours for a predefined
 721     set of named colours. The application may add to this set if desired by
 722     using AddColour() and may use it to look up colours by names using Find()
 723     or find the names for the standard colour using FindName().
 724
 725     There is one predefined, global instance of this class called
 726     ::wxTheColourDatabase.
 727
 728     The standard database contains at least the following colours:
 729
 730     @beginTable
 731     <tr><td>
 732        AQUAMARINE
 733     @n BLACK
 734     @n BLUE
 735     @n BLUE VIOLET
 736     @n BROWN
 737     @n CADET BLUE
 738     @n CORAL
 739     @n CORNFLOWER BLUE
 740     @n CYAN
 741     @n DARK GREY
 742     @n DARK GREEN
 743     @n DARK OLIVE GREEN
 744     @n DARK ORCHID
 745     @n DARK SLATE BLUE
 746     @n DARK SLATE GREY
 747     @n DARK TURQUOISE
 748     @n DIM GREY
 749     </td><td>
 750        FIREBRICK
 751     @n FOREST GREEN
 752     @n GOLD
 753     @n GOLDENROD
 754     @n GREY
 755     @n GREEN
 756     @n GREEN YELLOW
 757     @n INDIAN RED
 758     @n KHAKI
 759     @n LIGHT BLUE
 760     @n LIGHT GREY
 761     @n LIGHT STEEL BLUE
 762     @n LIME GREEN
 763     @n MAGENTA
 764     @n MAROON
 765     @n MEDIUM AQUAMARINE
 766     @n MEDIUM BLUE
 767     </td><td>
 768        MEDIUM FOREST GREEN
 769     @n MEDIUM GOLDENROD
 770     @n MEDIUM ORCHID
 771     @n MEDIUM SEA GREEN
 772     @n MEDIUM SLATE BLUE
 773     @n MEDIUM SPRING GREEN
 774     @n MEDIUM TURQUOISE
 775     @n MEDIUM VIOLET RED
 776     @n MIDNIGHT BLUE
 777     @n NAVY
 778     @n ORANGE
 779     @n ORANGE RED
 780     @n ORCHID
 781     @n PALE GREEN
 782     @n PINK
 783     @n PLUM
 784     @n PURPLE
 785     </td><td>
 786        RED
 787     @n SALMON
 788     @n SEA GREEN
 789     @n SIENNA
 790     @n SKY BLUE
 791     @n SLATE BLUE
 792     @n SPRING GREEN
 793     @n STEEL BLUE
 794     @n TAN
 795     @n THISTLE
 796     @n TURQUOISE
 797     @n VIOLET
 798     @n VIOLET RED
 799     @n WHEAT
 800     @n WHITE
 801     @n YELLOW
 802     @n YELLOW GREEN
 803     </td></tr>
 804     @endTable
 805
 806     @library{wxcore}
 807     @category{gdi}
 808
 809     @see wxColour
 810 */
 811 class wxColourDatabase
 812 {
 813 public:
 814     /**
 815         Constructs the colour database. It will be initialized at the first
 816         use.
 817     */
 818     wxColourDatabase();
 819
 820     /**
 821         Adds a colour to the database. If a colour with the same name already
 822         exists, it is replaced.
 823     */
 824     void AddColour(const wxString& colourName, const wxColour& colour);
 825
 826     /**
 827         Finds a colour given the name. Returns an invalid colour object (that
 828         is, wxColour::IsOk() will return @false) if the colour wasn't found in
 829         the database.
 830     */
 831     wxColour Find(const wxString& colourName) const;
 832
 833     /**
 834         Finds a colour name given the colour. Returns an empty string if the
 835         colour is not found in the database.
 836     */
 837     wxString FindName(const wxColour& colour) const;
 838 };
 839
 840
 841 /**
 842     Global instance of a wxColourDatabase.
 843 */
 844 wxColourDatabase* wxTheColourDatabase;
 845
 846
 847 /**
 848     @class wxSize
 849
 850     A wxSize is a useful data structure for graphics operations.
 851     It simply contains integer @e width and @e height members.
 852
 853     Note that the width and height stored inside a wxSize object may be negative
 854     and that wxSize functions do not perform any check against negative values
 855     (this is used to e.g. store the special -1 value in ::wxDefaultSize instance).
 856     See also IsFullySpecified() and SetDefaults() for utility functions regarding
 857     the special -1 value.
 858
 859     wxSize is used throughout wxWidgets as well as wxPoint which, although
 860     almost equivalent to wxSize, has a different meaning: wxPoint represents a
 861     position while wxSize represents the size.
 862
 863     @library{wxcore}
 864     @category{data}
 865
 866     @stdobjects
 867     ::wxDefaultSize
 868
 869     @see wxPoint, wxRealPoint
 870 */
 871 class wxSize
 872 {
 873 public:
 874     /**
 875         Initializes this size object with zero width and height.
 876     */
 877     wxSize();
 878
 879     /**
 880         Initializes this size object with the given @a width and @a height.
 881     */
 882     wxSize(int width, int height);
 883
 884     //@{
 885     /**
 886         Decreases the size in both x and y directions.
 887
 888         @see IncBy()
 889     */
 890     void DecBy(const wxPoint& pt);
 891     void DecBy(const wxSize& size);
 892     void DecBy(int dx, int dy);
 893     void DecBy(int d);
 894     //@}
 895
 896     /**
 897         Decrements this object so that both of its dimensions are not greater
 898         than the corresponding dimensions of the @a size.
 899
 900         @see IncTo()
 901     */
 902     void DecTo(const wxSize& size);
 903
 904     /**
 905         Decrements this object to be not bigger than the given size ignoring
 906         non-specified components.
 907
 908         This is similar to DecTo() but doesn't do anything for x or y
 909         component if the same component of @a size is not specified, i.e. set
 910         to ::wxDefaultCoord.
 911
 912         @since 2.9.5
 913      */
 914     void DecToIfSpecified(const wxSize& size);
 915
 916     /**
 917         Gets the height member.
 918     */
 919     int GetHeight() const;
 920
 921     /**
 922         Gets the width member.
 923     */
 924     int GetWidth() const;
 925
 926     //@{
 927     /**
 928         Increases the size in both x and y directions.
 929
 930         @see DecBy()
 931     */
 932     void IncBy(const wxPoint& pt);
 933     void IncBy(const wxSize& size);
 934     void IncBy(int dx, int dy);
 935     void IncBy(int d);
 936     //@}
 937
 938     /**
 939         Increments this object so that both of its dimensions are not less than
 940         the corresponding dimensions of the @a size.
 941
 942         @see DecTo()
 943     */
 944     void IncTo(const wxSize& size);
 945
 946     /**
 947         Returns @true if neither of the size object components is equal to -1,
 948         which is used as default for the size values in wxWidgets (hence the
 949         predefined ::wxDefaultSize has both of its components equal to -1).
 950
 951         This method is typically used before calling SetDefaults().
 952     */
 953     bool IsFullySpecified() const;
 954
 955     /**
 956         Scales the dimensions of this object by the given factors. If you want
 957         to scale both dimensions by the same factor you can also use
 958         operator*=().
 959
 960         @return A reference to this object (so that you can concatenate other
 961                  operations in the same line).
 962     */
 963     wxSize& Scale(float xscale, float yscale);
 964
 965     /**
 966         Sets the width and height members.
 967     */
 968     void Set(int width, int height);
 969
 970     /**
 971         Combine this size object with another one replacing the default (i.e.\ equal to -1)
 972         components of this object with those of the other. It is typically used like this:
 973
 974         @code
 975         if ( !size.IsFullySpecified() )
 976         {
 977             size.SetDefaults(GetDefaultSize());
 978         }
 979         @endcode
 980
 981         @see IsFullySpecified()
 982     */
 983     void SetDefaults(const wxSize& sizeDefault);
 984
 985     /**
 986         Sets the height.
 987     */
 988     void SetHeight(int height);
 989
 990     /**
 991         Sets the width.
 992     */
 993     void SetWidth(int width);
 994
 995
 996     /**
 997         @name Miscellaneous operators
 998
 999         Note that these operators are documented as class members
1000         (to make them easier to find) but, as their prototype shows,
1001         they are implemented as global operators; note that this is
1002         transparent to the user but it helps to understand why the
1003         following functions are documented to take the wxSize they
1004         operate on as an explicit argument.
1005     */
1006     //@{
1007     wxSize& operator=(const wxSize& sz);
1008
1009     bool operator ==(const wxSize& s1, const wxSize& s2);
1010     bool operator !=(const wxSize& s1, const wxSize& s2);
1011
1012     wxSize operator +(const wxSize& s1, const wxSize& s2);
1013     wxSize operator -(const wxSize& s1, const wxSize& s2);
1014     wxSize& operator +=(const wxSize& sz);
1015     wxSize& operator -=(const wxSize& sz);
1016
1017     wxSize operator /(const wxSize& sz, int factor);
1018     wxSize operator *(const wxSize& sz, int factor);
1019     wxSize operator *(int factor, const wxSize& sz);
1020     wxSize& operator /=(int factor);
1021     wxSize& operator *=(int factor);
1022     //@}
1023 };
1024
1025 /**
1026     Global instance of a wxSize object initialized to (-1,-1).
1027 */
1028 const wxSize wxDefaultSize;
1029
1030
1031
1032
1033 // ============================================================================
1034 // Global functions/macros
1035 // ============================================================================
1036
1037 /** @addtogroup group_funcmacro_gdi */
1038 //@{
1039
1040 /**
1041     This macro loads a bitmap from either application resources (on the
1042     platforms for which they exist, i.e. Windows and OS2) or from an XPM file.
1043     This can help to avoid using @ifdef_ when creating bitmaps.
1044
1045     @see @ref overview_bitmap, wxICON()
1046
1047     @header{wx/gdicmn.h}
1048 */
1049 #define wxBITMAP(bitmapName)
1050
1051 /**
1052     Creates a bitmap from either application resources or embedded image data
1053     in PNG format.
1054
1055     This macro is similar to wxBITMAP() but works with bitmap data in PNG
1056     format and not BMP or XPM.
1057
1058     Under Windows the given @a bitmapName must be present in the application
1059     resource file with the type @c RCDATA and refer to a PNG image. I.e. you
1060     should have a definition similar to the following in your @c .rc file:
1061     @code
1062         mybitmap    RCDATA  "mybitmap.png"
1063     @endcode
1064     to be able to use @c wxBITMAP_PNG(mybitmap) in the code.
1065
1066     Under OS X the file with the specified name and "png" extension must be
1067     present in the "Resources" subdirectory of the application bundle.
1068
1069     Under the other platforms, this is equivalent to wxBITMAP_PNG_FROM_DATA()
1070     and so loads the image data from the array called @c bitmapName_png that
1071     must exist. Notice that it @e must be an array and not a pointer as the
1072     macro needs to be able to determine its size. Such an array can be produced
1073     by a number of conversion programs. A very simple one is included in
1074     wxWidgets distribution as @c misc/scripts/png2c.py.
1075
1076     Finally notice that you must register PNG image handler to be able to
1077     load bitmaps from PNG data. This can be done either by calling
1078     wxInitAllImageHandlers() which also registers all the other image formats
1079     or including the necessary header:
1080     @code
1081         #include <wx/imagpng.h>
1082     @endcode
1083     and calling
1084     @code
1085         wxImage::AddHandler(new wxPNGHandler);
1086     @endcode
1087     in your application startup code.
1088
1089     @see wxBITMAP_PNG_FROM_DATA()
1090
1091     @header{wx/gdicmn.h}
1092
1093     @since 2.9.5
1094  */
1095 #define wxBITMAP_PNG(bitmapName)
1096
1097 /**
1098     Creates a bitmap from embedded image data in PNG format.
1099
1100     This macro is a thin wrapper around wxBitmap::NewFromPNGData() and takes
1101     just the base name of the array containing the image data and computes its
1102     size internally. In other words, the array called @c bitmapName_png must
1103     exist. Notice that it @e must be an array and not a pointer as the macro
1104     needs to be able to determine its size. Such an array can be produced by a
1105     number of conversion programs. A very simple one is included in wxWidgets
1106     distribution as @c misc/scripts/png2c.py.
1107
1108     You can use wxBITMAP_PNG() to load the PNG bitmaps from resources on the
1109     platforms that support this and only fall back to loading them from data
1110     under the other ones (i.e. not Windows and not OS X).
1111
1112     @header{wx/gdicmn.h}
1113
1114     @since 2.9.5
1115  */
1116 #define wxBITMAP_PNG_FROM_DATA(bitmapName)
1117
1118 /**
1119     This macro loads an icon from either application resources (on the
1120     platforms for which they exist, i.e. Windows and OS2) or from an XPM file.
1121     This can help to avoid using @ifdef_ when creating icons.
1122
1123     @see @ref overview_bitmap, wxBITMAP()
1124
1125     @header{wx/gdicmn.h}
1126 */
1127 #define wxICON(iconName)
1128
1129 /**
1130     Returns @true if the display is colour, @false otherwise.
1131
1132     @header{wx/gdicmn.h}
1133 */
1134 bool wxColourDisplay();
1135
1136 /**
1137     Returns the depth of the display (a value of 1 denotes a monochrome
1138     display).
1139
1140     @header{wx/gdicmn.h}
1141 */
1142 int wxDisplayDepth();
1143
1144 /**
1145     Globally sets the cursor; only has an effect on Windows, Mac and GTK+. You
1146     should call this function with wxNullCursor to restore the system cursor.
1147
1148     @see wxCursor, wxWindow::SetCursor()
1149
1150     @header{wx/gdicmn.h}
1151 */
1152 void wxSetCursor(const wxCursor& cursor);
1153
1154 //@}
1155
1156 /** @addtogroup group_funcmacro_gdi */
1157 //@{
1158 /**
1159     Returns the dimensions of the work area on the display.
1160
1161     This is the same as wxGetClientDisplayRect() but allows to retrieve the
1162     individual components instead of the entire rectangle.
1163
1164     Any of the output pointers can be @NULL if the corresponding value is not
1165     needed by the caller.
1166
1167     @see wxDisplay
1168
1169     @header{wx/gdicmn.h}
1170 */
1171 void wxClientDisplayRect(int* x, int* y, int* width, int* height);
1172 //@}
1173
1174 /** @addtogroup group_funcmacro_gdi */
1175 //@{
1176 /**
1177     Returns the dimensions of the work area on the display. On Windows this
1178     means the area not covered by the taskbar, etc. Other platforms are
1179     currently defaulting to the whole display until a way is found to provide
1180     this info for all window managers, etc.
1181
1182     @see wxDisplay
1183
1184     @header{wx/gdicmn.h}
1185 */
1186 wxRect wxGetClientDisplayRect();
1187 //@}
1188
1189 /** @addtogroup group_funcmacro_gdi */
1190 //@{
1191 /**
1192     Returns the display resolution in pixels per inch.
1193
1194     The @c x component of the returned wxSize object contains the horizontal
1195     resolution and the @c y one -- the vertical resolution.
1196
1197     @header{wx/gdicmn.h}
1198
1199     @see wxDisplay
1200
1201     @since 2.9.0
1202 */
1203 wxSize wxGetDisplayPPI();
1204 //@}
1205
1206 /** @addtogroup group_funcmacro_gdi */
1207 //@{
1208 /**
1209     Returns the display size in pixels.
1210
1211     Either of output pointers can be @NULL if the caller is not interested in
1212     the corresponding value.
1213
1214     @see wxGetDisplaySize(), wxDisplay
1215
1216     @header{wx/gdicmn.h}
1217 */
1218 void wxDisplaySize(int* width, int* height);
1219 //@}
1220
1221 /** @addtogroup group_funcmacro_gdi */
1222 //@{
1223 /**
1224     Returns the display size in pixels.
1225
1226     @see wxDisplay
1227
1228     @header{wx/gdicmn.h}
1229 */
1230 wxSize wxGetDisplaySize();
1231 //@}
1232
1233 /** @addtogroup group_funcmacro_gdi */
1234 //@{
1235 /**
1236     Returns the display size in millimeters.
1237
1238     Either of output pointers can be @NULL if the caller is not interested in
1239     the corresponding value.
1240
1241     @see wxGetDisplaySizeMM(), wxDisplay
1242
1243     @header{wx/gdicmn.h}
1244 */
1245 void wxDisplaySizeMM(int* width, int* height);
1246 //@}
1247
1248 /** @addtogroup group_funcmacro_gdi */
1249 //@{
1250 /**
1251     Returns the display size in millimeters.
1252
1253     @see wxDisplay
1254
1255     @header{wx/gdicmn.h}
1256 */
1257 wxSize wxGetDisplaySizeMM();
1258 //@}
1259