interface/gdicmn.h

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