interface/wx/gdicmn.h

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