X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..12346143b17b8682623f97a5cf14e44c0f8b8c73:/interface/wx/gdicmn.h diff --git a/interface/wx/gdicmn.h b/interface/wx/gdicmn.h index f415ecf9d8..ec06e76c6f 100644 --- a/interface/wx/gdicmn.h +++ b/interface/wx/gdicmn.h @@ -3,7 +3,7 @@ // Purpose: interface of wxRealPoint // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -24,8 +24,10 @@ enum wxBitmapType wxBITMAP_TYPE_XBM_DATA, wxBITMAP_TYPE_XPM, wxBITMAP_TYPE_XPM_DATA, - wxBITMAP_TYPE_TIF, - wxBITMAP_TYPE_TIF_RESOURCE, + wxBITMAP_TYPE_TIFF, + wxBITMAP_TYPE_TIF = wxBITMAP_TYPE_TIFF, + wxBITMAP_TYPE_TIFF_RESOURCE, + wxBITMAP_TYPE_TIF_RESOURCE = wxBITMAP_TYPE_TIFF_RESOURCE, wxBITMAP_TYPE_GIF, wxBITMAP_TYPE_GIF_RESOURCE, wxBITMAP_TYPE_PNG, @@ -49,7 +51,23 @@ enum wxBitmapType }; /** - Standard cursors. See wxCursor. + Polygon filling mode. See wxDC::DrawPolygon. +*/ +enum wxPolygonFillMode +{ + wxODDEVEN_RULE = 1, + wxWINDING_RULE +}; + +/** + Standard cursors. + + Notice that under wxMSW some of these cursors are defined in @c wx.rc file + and not by the system itself so you should include this file from your own + resource file (possibly creating a trivial resource file just containing a + single include line if you don't need it otherwise) to be able to use them. + + See wxCursor. */ enum wxStockCursor { @@ -94,12 +112,14 @@ enum wxStockCursor /** @class wxRealPoint - @wxheader{gdicmn.h} A wxRealPoint is a useful data structure for graphics operations. - It contains floating point @e x and @e y members. See wxPoint for an - integer version. + It contains floating point @e x and @e y members. + See wxPoint for an integer version. + + Note that the coordinates stored inside a wxRealPoint object may be negative + and that wxRealPoint functions do not perform any check against negative values. @library{wxcore} @category{data} @@ -109,6 +129,9 @@ enum wxStockCursor class wxRealPoint { public: + /** + Initializes to zero the x and y members. + */ wxRealPoint(); /** @@ -116,6 +139,48 @@ public: */ wxRealPoint(double x, double y); + /** + Converts the given wxPoint (with integer coordinates) to a wxRealPoint. + */ + wxRealPoint(const wxPoint& pt); + + /** + @name Miscellaneous operators + + Note that these operators are documented as class members + (to make them easier to find) but, as their prototype shows, + they are implemented as global operators; note that this is + transparent to the user but it helps to understand why the + following functions are documented to take the wxPoint they + operate on as an explicit argument. + */ + //@{ + wxRealPoint& operator=(const wxRealPoint& pt); + + bool operator ==(const wxRealPoint& p1, const wxRealPoint& p2); + bool operator !=(const wxRealPoint& p1, const wxRealPoint& p2); + + wxRealPoint operator +(const wxRealPoint& p1, const wxRealPoint& p2); + wxRealPoint operator -(const wxRealPoint& p1, const wxRealPoint& p2); + + wxRealPoint& operator +=(const wxRealPoint& pt); + wxRealPoint& operator -=(const wxRealPoint& pt); + + wxRealPoint operator +(const wxRealPoint& pt, const wxSize& sz); + wxRealPoint operator -(const wxRealPoint& pt, const wxSize& sz); + wxRealPoint operator +(const wxSize& sz, const wxRealPoint& pt); + wxRealPoint operator -(const wxSize& sz, const wxRealPoint& pt); + + wxRealPoint& operator +=(const wxSize& sz); + wxRealPoint& operator -=(const wxSize& sz); + + wxSize operator /(const wxRealPoint& sz, int factor); + wxSize operator *(const wxRealPoint& sz, int factor); + wxSize operator *(int factor, const wxSize& sz); + wxSize& operator /=(int factor); + wxSize& operator *=(int factor); + //@} + /** X coordinate of this point. */ @@ -131,10 +196,13 @@ public: /** @class wxRect - @wxheader{gdicmn.h} A class for manipulating rectangles. + Note that the x, y coordinates and the width and height stored inside a wxRect + object may be negative and that wxRect functions do not perform any check against + negative values. + @library{wxcore} @category{data} @@ -145,6 +213,7 @@ class wxRect public: /** Default constructor. + Initializes to zero the internal @a x, @a y, @a width and @a height members. */ wxRect(); /** @@ -156,7 +225,7 @@ public: */ wxRect(const wxPoint& topLeft, const wxPoint& bottomRight); /** - Creates a wxRect object from position and @a size values. + Creates a wxRect object from position @a pos and @a size values. */ wxRect(const wxPoint& pos, const wxSize& size); /** @@ -199,10 +268,10 @@ public: This method is the opposite from Inflate(): Deflate(a, b) is equivalent to Inflate(-a, -b). Please refer to Inflate() for full description. */ - void Deflate(wxCoord dx, wxCoord dy); - void Deflate(const wxSize& diff); - void Deflate(wxCoord diff); - wxRect Deflate(wxCoord dx, wxCoord dy) const; + wxRect& Deflate(wxCoord dx, wxCoord dy); + wxRect& Deflate(const wxSize& diff); + wxRect& Deflate(wxCoord diff); + wxRect Deflate(wxCoord dx, wxCoord dy) const; //@} /** @@ -284,7 +353,7 @@ public: The left border is moved farther left and the right border is moved farther right by @a dx. The upper border is moved farther up and the - bottom border is moved farther down by @a dy. (Note the the width and + bottom border is moved farther down by @a dy. (Note that the width and height of the rectangle thus change by 2*dx and 2*dy, respectively.) If one or both of @a dx and @a dy are negative, the opposite happens: the rectangle size decreases in the respective direction. @@ -307,20 +376,25 @@ public: @see Deflate() */ - void Inflate(wxCoord dx, wxCoord dy); - void Inflate(const wxSize& diff); - void Inflate(wxCoord diff); + wxRect& Inflate(wxCoord dx, wxCoord dy); + wxRect& Inflate(const wxSize& diff); + wxRect& Inflate(wxCoord diff); wxRect Inflate(wxCoord dx, wxCoord dy) const; //@} - //@{ /** - Modifies the rectangle to contain the overlapping box of this rectangle + Modifies this rectangle to contain the overlapping portion of this rectangle and the one passed in as parameter. + + @return This rectangle, modified. */ - wxRect Intersect(const wxRect& rect) const; wxRect& Intersect(const wxRect& rect); - //@} + + /** + Returns the overlapping portion of this rectangle and the one passed in as + parameter. + */ + wxRect Intersect(const wxRect& rect) const; /** Returns @true if this rectangle has a non-empty intersection with the @@ -349,6 +423,11 @@ public: */ void SetHeight(int height); + /** + Sets the position. + */ + void SetPosition(const wxPoint& pos); + /** Sets the size. @@ -371,6 +450,61 @@ public: */ void SetY(int y); + /** + Set the left side of the rectangle. + + Notice that because the rectangle stores its left side and width, + calling SetLeft() changes the right side position too -- but does + preserve the width. + */ + void SetLeft(int left); + + /** + Set the right side of the rectangle. + + Notice that this doesn't affect GetLeft() return value but changes the + rectangle width to set its right side to the given position. + */ + void SetRight(int right); + + /** + Set the top edge of the rectangle. + + Notice that because the rectangle stores its top side and height, + calling SetTop() changes the bottom side position too -- but does + preserve the height. + */ + void SetTop(int top); + + /** + Set the bottom edge of the rectangle. + + Notice that this doesn't affect GetTop() return value but changes the + rectangle height to set its bottom side to the given position. + */ + void SetBottom(int bottom); + + /** + Set the top-left point of the rectangle. + */ + void SetTopLeft(const wxPoint &p); + + /** + Set the bottom-right point of the rectangle. + */ + void SetBottomRight(const wxPoint &p); + + /** + Set the top-right point of the rectangle. + */ + void SetTopRight(const wxPoint &p); + + /** + Set the bottom-left point of the rectangle. + */ + void SetBottomLeft(const wxPoint &p); + + //@{ /** Modifies the rectangle to contain the bounding box of this rectangle @@ -404,7 +538,7 @@ public: /** Assignment operator. */ - void operator =(const wxRect& rect); + wxRect& operator=(const wxRect& rect); /** Equality operator. @@ -436,12 +570,15 @@ public: /** @class wxPoint - @wxheader{gdicmn.h} A wxPoint is a useful data structure for graphics operations. - It contains integer @e x and @e y members. See wxRealPoint for a floating - point version. + It contains integer @e x and @e y members. + See wxRealPoint for a floating point version. + + Note that the width and height stored inside a wxPoint object may be negative + and that wxPoint functions do not perform any check against negative values + (this is used to e.g. store the special -1 value in ::wxDefaultPosition instance). @library{wxcore} @category{data} @@ -454,18 +591,45 @@ public: class wxPoint { public: - //@{ /** Constructs a point. + Initializes the internal x and y coordinates to zero. */ wxPoint(); + + /** + Initializes the point object with the given @a x and @a y coordinates. + */ wxPoint(int x, int y); - //@} /** - Assignment operator. + Converts the given wxRealPoint (with floating point coordinates) to a + wxPoint instance. + + Notice that this truncates the floating point values of @a pt + components, if you want to round them instead you need to do it + manually, e.g. + @code + #include // for wxRound() + + wxRealPoint rp = ...; + wxPoint p(wxRound(rp.x), wxRound(rp.y)); + @endcode + */ + wxPoint(const wxRealPoint& pt); + + /** + @name Miscellaneous operators + + Note that these operators are documented as class members + (to make them easier to find) but, as their prototype shows, + they are implemented as global operators; note that this is + transparent to the user but it helps to understand why the + following functions are documented to take the wxPoint they + operate on as an explicit argument. */ - void operator =(const wxPoint& pt); + //@{ + wxPoint& operator=(const wxPoint& pt); bool operator ==(const wxPoint& p1, const wxPoint& p2); bool operator !=(const wxPoint& p1, const wxPoint& p2); @@ -484,6 +648,56 @@ public: wxPoint& operator +=(const wxSize& sz); wxPoint& operator -=(const wxSize& sz); + wxSize operator /(const wxPoint& sz, int factor); + wxSize operator *(const wxPoint& sz, int factor); + wxSize operator *(int factor, const wxSize& sz); + wxSize& operator /=(int factor); + wxSize& operator *=(int factor); + //@} + + + /** + @name Defaults handling. + + Test for and set non-specified wxPoint components. + + Although a wxPoint is always initialized to (0, 0), wxWidgets commonly + uses wxDefaultCoord (defined as @c -1) to indicate that a point hasn't + been initialized or specified. In particular, ::wxDefaultPosition is + used in many places with this meaning. + */ + //@{ + + /** + Returns @true if neither of the point components is equal to + wxDefaultCoord. + + This method is typically used before calling SetDefaults(). + + @since 2.9.2 + */ + bool IsFullySpecified() const; + + /** + Combine this object with another one replacing the uninitialized + values. + + It is typically used like this: + + @code + if ( !pos.IsFullySpecified() ) + { + pos.SetDefaults(GetDefaultPosition()); + } + @endcode + + @see IsFullySpecified() + + @since 2.9.2 + */ + void SetDefaults(const wxPoint& pt); + //@} + /** x member. */ @@ -496,14 +710,13 @@ public: }; /** - Global istance of a wxPoint initialized with values (-1,-1). + Global instance of a wxPoint initialized with values (-1,-1). */ -wxPoint wxDefaultPosition; +const wxPoint wxDefaultPosition; /** @class wxColourDatabase - @wxheader{gdicmn.h} wxWidgets maintains a database of standard RGB colours for a predefined set of named colours. The application may add to this set if desired by @@ -616,7 +829,7 @@ public: is, wxColour::IsOk() will return @false) if the colour wasn't found in the database. */ - wxColour Find(const wxString& colourName); + wxColour Find(const wxString& colourName) const; /** Finds a colour name given the colour. Returns an empty string if the @@ -626,22 +839,28 @@ public: }; +/** + Global instance of a wxColourDatabase. +*/ +wxColourDatabase* wxTheColourDatabase; + + /** @class wxSize - @wxheader{gdicmn.h} - A wxSize is a useful data structure for graphics operations. It simply - contains integer @e width and @e height members. + A wxSize is a useful data structure for graphics operations. + It simply contains integer @e width and @e height members. + + Note that the width and height stored inside a wxSize object may be negative + and that wxSize functions do not perform any check against negative values + (this is used to e.g. store the special -1 value in ::wxDefaultSize instance). + See also IsFullySpecified() and SetDefaults() for utility functions regarding + the special -1 value. wxSize is used throughout wxWidgets as well as wxPoint which, although almost equivalent to wxSize, has a different meaning: wxPoint represents a position while wxSize represents the size. - @beginWxPythonOnly - wxPython defines aliases for the @e x and @e y members named @e width and - @e height since it makes much more sense for sizes. - @endWxPythonOnly - @library{wxcore} @category{data} @@ -653,13 +872,15 @@ public: class wxSize { public: - //@{ /** - Creates a size object. + Initializes this size object with zero width and height. */ wxSize(); + + /** + Initializes this size object with the given @a width and @a height. + */ wxSize(int width, int height); - //@} //@{ /** @@ -667,6 +888,7 @@ public: @see IncBy() */ + void DecBy(const wxPoint& pt); void DecBy(const wxSize& size); void DecBy(int dx, int dy); void DecBy(int d); @@ -680,6 +902,18 @@ public: */ void DecTo(const wxSize& size); + /** + Decrements this object to be not bigger than the given size ignoring + non-specified components. + + This is similar to DecTo() but doesn't do anything for x or y + component if the same component of @a size is not specified, i.e. set + to ::wxDefaultCoord. + + @since 2.9.5 + */ + void DecToIfSpecified(const wxSize& size); + /** Gets the height member. */ @@ -696,6 +930,7 @@ public: @see DecBy() */ + void IncBy(const wxPoint& pt); void IncBy(const wxSize& size); void IncBy(int dx, int dy); void IncBy(int d); @@ -734,9 +969,8 @@ public: void Set(int width, int height); /** - Combine this size object with another one replacing the default (i.e. - equal to -1) components of this object with those of the other. It is - typically used like this: + Combine this size object with another one replacing the default (i.e.\ equal to -1) + components of this object with those of the other. It is typically used like this: @code if ( !size.IsFullySpecified() ) @@ -759,10 +993,19 @@ public: */ void SetWidth(int width); + /** - Assignment operator. + @name Miscellaneous operators + + Note that these operators are documented as class members + (to make them easier to find) but, as their prototype shows, + they are implemented as global operators; note that this is + transparent to the user but it helps to understand why the + following functions are documented to take the wxSize they + operate on as an explicit argument. */ - void operator =(const wxSize& sz); + //@{ + wxSize& operator=(const wxSize& sz); bool operator ==(const wxSize& s1, const wxSize& s2); bool operator !=(const wxSize& s1, const wxSize& s2); @@ -777,12 +1020,13 @@ public: wxSize operator *(int factor, const wxSize& sz); wxSize& operator /=(int factor); wxSize& operator *=(int factor); + //@} }; /** Global instance of a wxSize object initialized to (-1,-1). */ -wxSize wxDefaultSize; +const wxSize wxDefaultSize; @@ -791,7 +1035,7 @@ wxSize wxDefaultSize; // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_gdi */ +/** @addtogroup group_funcmacro_gdi */ //@{ /** @@ -805,6 +1049,73 @@ wxSize wxDefaultSize; */ #define wxBITMAP(bitmapName) +/** + Creates a bitmap from either application resources or embedded image data + in PNG format. + + This macro is similar to wxBITMAP() but works with bitmap data in PNG + format and not BMP or XPM. + + Under Windows the given @a bitmapName must be present in the application + resource file with the type @c RCDATA and refer to a PNG image. I.e. you + should have a definition similar to the following in your @c .rc file: + @code + mybitmap RCDATA "mybitmap.png" + @endcode + to be able to use @c wxBITMAP_PNG(mybitmap) in the code. + + Under OS X the file with the specified name and "png" extension must be + present in the "Resources" subdirectory of the application bundle. + + Under the other platforms, this is equivalent to wxBITMAP_PNG_FROM_DATA() + and so loads the image data from the array called @c bitmapName_png that + must exist. Notice that it @e must be an array and not a pointer as the + macro needs to be able to determine its size. Such an array can be produced + by a number of conversion programs. A very simple one is included in + wxWidgets distribution as @c misc/scripts/png2c.py. + + Finally notice that you must register PNG image handler to be able to + load bitmaps from PNG data. This can be done either by calling + wxInitAllImageHandlers() which also registers all the other image formats + or including the necessary header: + @code + #include + @endcode + and calling + @code + wxImage::AddHandler(new wxPNGHandler); + @endcode + in your application startup code. + + @see wxBITMAP_PNG_FROM_DATA() + + @header{wx/gdicmn.h} + + @since 2.9.5 + */ +#define wxBITMAP_PNG(bitmapName) + +/** + Creates a bitmap from embedded image data in PNG format. + + This macro is a thin wrapper around wxBitmap::NewFromPNGData() and takes + just the base name of the array containing the image data and computes its + size internally. In other words, the array called @c bitmapName_png must + exist. Notice that it @e must be an array and not a pointer as the macro + needs to be able to determine its size. Such an array can be produced by a + number of conversion programs. A very simple one is included in wxWidgets + distribution as @c misc/scripts/png2c.py. + + You can use wxBITMAP_PNG() to load the PNG bitmaps from resources on the + platforms that support this and only fall back to loading them from data + under the other ones (i.e. not Windows and not OS X). + + @header{wx/gdicmn.h} + + @since 2.9.5 + */ +#define wxBITMAP_PNG_FROM_DATA(bitmapName) + /** This macro loads an icon from either application resources (on the platforms for which they exist, i.e. Windows and OS2) or from an XPM file. @@ -814,7 +1125,7 @@ wxSize wxDefaultSize; @header{wx/gdicmn.h} */ -wxICON(); +#define wxICON(iconName) /** Returns @true if the display is colour, @false otherwise. @@ -843,7 +1154,7 @@ void wxSetCursor(const wxCursor& cursor); //@} -/** @ingroup group_funcmacro_gdi */ +/** @addtogroup group_funcmacro_gdi */ //@{ /** Returns the dimensions of the work area on the display. On Windows this @@ -857,22 +1168,45 @@ void wxClientDisplayRect(int* x, int* y, int* width, int* height); wxRect wxGetClientDisplayRect(); //@} -/** @ingroup group_funcmacro_gdi */ +/** @addtogroup group_funcmacro_gdi */ +//@{ +/** + Returns the display resolution in pixels per inch. + + The @c x component of the returned wxSize object contains the horizontal + resolution and the @c y one -- the vertical resolution. + + @header{wx/gdicmn.h} + + @since 2.9.0 +*/ +wxSize wxGetDisplayPPI(); +//@} + +/** @addtogroup group_funcmacro_gdi */ //@{ /** Returns the display size in pixels. + For the version taking @a width and @a header arguments, either of them + can be @NULL if the caller is not interested in the returned value. + @header{wx/gdicmn.h} */ void wxDisplaySize(int* width, int* height); wxSize wxGetDisplaySize(); //@} -/** @ingroup group_funcmacro_gdi */ +/** @addtogroup group_funcmacro_gdi */ //@{ /** Returns the display size in millimeters. + For the version taking @a width and @a header arguments, either of them + can be @NULL if the caller is not interested in the returned value. + + @see wxGetDisplayPPI() + @header{wx/gdicmn.h} */ void wxDisplaySizeMM(int* width, int* height);