interface/gdicmn.h

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