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