From: Bryan Petty Date: Fri, 2 May 2008 04:12:39 +0000 (+0000) Subject: Finished initial review of a few [g*] interface headers. X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/3d2cf8844157339b7ebd4346cc1139154640da0a Finished initial review of a few [g*] interface headers. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53427 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/interface/cursor.h b/interface/cursor.h index 09c70fc8bb..7ffa1fdf10 100644 --- a/interface/cursor.h +++ b/interface/cursor.h @@ -79,7 +79,8 @@ - ::wxHOURGLASS_CURSOR - ::wxCROSS_CURSOR - @see wxBitmap, wxIcon, wxWindow::SetCursor(), wxSetCursor() + @see wxBitmap, wxIcon, wxWindow::SetCursor(), wxSetCursor(), + ::wxStockCursor */ class wxCursor : public wxBitmap { @@ -153,42 +154,9 @@ public: Constructs a cursor using a cursor identifier. @param cursorId - A stock cursor identifier. May be one of the following (note that - not all cursors are available on all platforms): - - wxCURSOR_ARROW - A standard arrow cursor. - - wxCURSOR_RIGHT_ARROW - A standard arrow cursor pointing to the - right. - - wxCURSOR_BLANK - Transparent cursor. - - wxCURSOR_BULLSEYE - Bullseye cursor. - - wxCURSOR_CHAR - Rectangular character cursor. - - wxCURSOR_CROSS - A cross cursor. - - wxCURSOR_HAND - A hand cursor. - - wxCURSOR_IBEAM - An I-beam cursor (vertical line). - - wxCURSOR_LEFT_BUTTON - Represents a mouse with the left button - depressed. - - wxCURSOR_MAGNIFIER - A magnifier icon. - - wxCURSOR_MIDDLE_BUTTON - Represents a mouse with the middle - button depressed. - - wxCURSOR_NO_ENTRY - A no-entry sign cursor. - - wxCURSOR_PAINT_BRUSH - A paintbrush cursor. - - wxCURSOR_PENCIL - A pencil cursor. - - wxCURSOR_POINT_LEFT - A cursor that points left. - - wxCURSOR_POINT_RIGHT - A cursor that points right. - - wxCURSOR_QUESTION_ARROW - An arrow and question mark. - - wxCURSOR_RIGHT_BUTTON - Represents a mouse with the right - button depressed. - - wxCURSOR_SIZENESW - A sizing cursor pointing NE-SW. - - wxCURSOR_SIZENS - A sizing cursor pointing N-S. - - wxCURSOR_SIZENWSE - A sizing cursor pointing NW-SE. - - wxCURSOR_SIZEWE - A sizing cursor pointing W-E. - - wxCURSOR_SIZING - A general sizing cursor. - - wxCURSOR_SPRAYCAN - A spraycan cursor. - - wxCURSOR_WAIT - A wait cursor. - - wxCURSOR_WATCH - A watch cursor. - - wxCURSOR_ARROWWAIT - A cursor with both an arrow and an - hourglass, (windows.) + A stock cursor identifier. See ::wxStockCursor. */ - wxCursor(int cursorId); + wxCursor(wxStockCursor cursorId); /** Constructs a cursor from a wxImage. If cursor are monochrome on the current platform, colors with the RGB elements all greater than 127 @@ -238,7 +206,11 @@ public: }; -/** @name Predefined cursors. */ +/** + @name Predefined cursors. + + @see wxStockCursor +*/ //@{ wxCursor wxNullCursor; wxCursor* wxSTANDARD_CURSOR; diff --git a/interface/gauge.h b/interface/gauge.h index 9585cba4ad..d617d7489b 100644 --- a/interface/gauge.h +++ b/interface/gauge.h @@ -10,17 +10,17 @@ @class wxGauge @wxheader{gauge.h} - A gauge is a horizontal or vertical bar which shows a quantity (often time). + A gauge is a horizontal or vertical bar which shows a quantity (often + time). wxGauge supports two working modes: determinate and indeterminate progress. - The first is the usual working mode (see wxGauge::SetValue - and wxGauge::SetRange) while the second can be used when - the program is doing some processing but you don't know how much progress is - being done. - In this case, you can periodically call the wxGauge::Pulse - function to make the progress bar switch to indeterminate mode (graphically - it's usually a set of blocks which move or bounce in the bar control). + The first is the usual working mode (see SetValue() and SetRange()) while + the second can be used when the program is doing some processing but you + don't know how much progress is being done. In this case, you can + periodically call the Pulse() function to make the progress bar switch to + indeterminate mode (graphically it's usually a set of blocks which move or + bounce in the bar control). wxGauge supports dynamic switch between these two work modes. @@ -38,14 +38,17 @@ @library{wxcore} @category{ctrl} - @appearance{gauge.png} + @see wxSlider, wxScrollBar */ class wxGauge : public wxControl { public: - //@{ + /** + Default constructor. + */ + wxGauge(); /** Constructor, creating and showing a gauge. @@ -54,27 +57,25 @@ public: @param id Window identifier. @param range - Integer range (maximum value) of the gauge. It is ignored when the gauge is - used in indeterminate mode. + Integer range (maximum value) of the gauge. It is ignored when the + gauge is used in indeterminate mode. @param pos Window position. @param size Window size. @param style - Gauge style. See wxGauge. + Gauge style. @param name Window name. @see Create() */ - wxGauge(); wxGauge(wxWindow* parent, wxWindowID id, int range, const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxGA_HORIZONTAL, const wxValidator& validator = wxDefaultValidator, const wxString& name = "gauge"); - //@} /** Destructor, destroying the gauge. @@ -82,8 +83,8 @@ public: ~wxGauge(); /** - Creates the gauge for two-step construction. See wxGauge() - for further details. + Creates the gauge for two-step construction. See wxGauge() for further + details. */ bool Create(wxWindow* parent, wxWindowID id, int range, const wxPoint& pos = wxDefaultPosition, @@ -131,11 +132,12 @@ public: bool IsVertical() const; /** - Switch the gauge to indeterminate mode (if required) and makes the gauge move - a bit to indicate the user that some progress has been made. - Note that after calling this function the value returned by GetValue() - is undefined and thus you need to explicitely call SetValue() if you - want to restore the determinate mode. + Switch the gauge to indeterminate mode (if required) and makes the + gauge move a bit to indicate the user that some progress has been made. + + @note After calling this function the value returned by GetValue() is + undefined and thus you need to explicitely call SetValue() if you + want to restore the determinate mode. */ void Pulse(); @@ -150,8 +152,8 @@ public: void SetBezelFace(int width); /** - Sets the range (maximum value) of the gauge. - This function makes the gauge switch to determinate mode, if it's not already. + Sets the range (maximum value) of the gauge. This function makes the + gauge switch to determinate mode, if it's not already. @see GetRange() */ @@ -166,8 +168,9 @@ public: void SetShadowWidth(int width); /** - Sets the position of the gauge. The @a pos must be between 0 and the gauge - range as returned by GetRange(), inclusive. + Sets the position of the gauge. The @a pos must be between 0 and the + gauge range as returned by GetRange(), inclusive. + This function makes the gauge switch to determinate mode, if it was in indeterminate mode before. diff --git a/interface/gbsizer.h b/interface/gbsizer.h index 9036d1edad..5dc8787188 100644 --- a/interface/gbsizer.h +++ b/interface/gbsizer.h @@ -10,23 +10,23 @@ @class wxGBPosition @wxheader{gbsizer.h} - This class represents the position of an item in a virtual grid of - rows and columns managed by a wxGridBagSizer. + This class represents the position of an item in a virtual grid of rows and + columns managed by a wxGridBagSizer. @library{wxcore} - @category{FIXME} + @category{winlayout} */ class wxGBPosition { public: - //@{ /** - Construct a new wxGBPosition, optionally setting the row and column. - The default is (0,0). + Default constructor, setting the row and column to (0,0). */ wxGBPosition(); + /** + Construct a new wxGBPosition, setting the row and column. + */ wxGBPosition(int row, int col); - //@} /** Get the current column value. @@ -49,14 +49,14 @@ public: void SetRow(int row); /** - Is the wxGBPosition valid? (An invalid wxGBPosition is (-1,-1). ) + Checks if the position is valid. An invalid position is (-1,-1). */ bool operator!(const wxGBPosition& p) const; /** Compare equality of two wxGBPositions. */ - bool operator operator==(const wxGBPosition& p) const; + bool operator==(const wxGBPosition& p) const; }; @@ -65,11 +65,10 @@ public: @class wxGridBagSizer @wxheader{gbsizer.h} - A wxSizer that can lay out items in a virtual grid - like a wxFlexGridSizer but in this case - explicit positioning of the items is allowed using - wxGBPosition, and items can optionally span - more than one row and/or column using wxGBSpan. + A wxSizer that can lay out items in a virtual grid like a wxFlexGridSizer + but in this case explicit positioning of the items is allowed using + wxGBPosition, and items can optionally span more than one row and/or column + using wxGBSpan. @library{wxcore} @category{winlayout} @@ -85,26 +84,20 @@ public: //@{ /** - The Add methods return a valid pointer if the item was successfully placed at - the - given position, @NULL if something was already there. + Adds the given item to the given position. + + @returns A valid pointer if the item was successfully placed at the + given position, or @NULL if something was already there. */ wxSizerItem* Add(wxWindow* window, const wxGBPosition& pos, const wxGBSpan& span = wxDefaultSpan, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + int flag = 0, int border = 0, wxObject* userData = NULL); wxSizerItem* Add(wxSizer* sizer, const wxGBPosition& pos, const wxGBSpan& span = wxDefaultSpan, - int flag = 0, - int border = 0, - wxObject* userData = NULL); - wxSizerItem* Add(int width, int height, - const wxGBPosition& pos, + int flag = 0, int border = 0, wxObject* userData = NULL); + wxSizerItem* Add(int width, int height, const wxGBPosition& pos, const wxGBSpan& span = wxDefaultSpan, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + int flag = 0, int border = 0, wxObject* userData = NULL); wxSizerItem* Add(wxGBSizerItem* item); //@} @@ -118,13 +111,12 @@ public: /** Look at all items and see if any intersect (or would overlap) the given item. Returns @true if so, @false if there would be no overlap. If an - excludeItem is given then it will not be checked for intersection, for - example it may be the item we are checking the position of. + @a excludeItem is given then it will not be checked for intersection, + for example it may be the item we are checking the position of. */ bool CheckForIntersection(wxGBSizerItem* item, wxGBSizerItem* excludeItem = NULL); - bool CheckForIntersection(const wxGBPosition& pos, - const wxGBSpan& span, + bool CheckForIntersection(const wxGBPosition& pos, const wxGBSpan& span, wxGBSizerItem* excludeItem = NULL); //@} @@ -139,8 +131,8 @@ public: /** Return the sizer item located at the point given in pt, or @NULL if - there is no item at that point. The (x,y) coordinates in pt correspond - to the client coordinates of the window using the sizer for + there is no item at that point. The (x,y) coordinates in @a pt + correspond to the client coordinates of the window using the sizer for layout. (non-recursive) */ wxGBSizerItem* FindItemAtPoint(const wxPoint& pt); @@ -158,8 +150,8 @@ public: wxGBSizerItem* FindItemWithData(const wxObject* userData); /** - Get the size of the specified cell, including hgap and vgap. Only - valid after a Layout. + Get the size of the specified cell, including hgap and vgap. Only valid + after window layout has been performed. */ wxSize GetCellSize(int row, int col) const; @@ -179,7 +171,7 @@ public: //@{ /** - Get the row/col spanning of the specified item + Get the row/col spanning of the specified item. */ wxGBSpan GetItemSpan(wxWindow* window); wxGBSpan GetItemSpan(wxSizer* sizer); @@ -226,40 +218,39 @@ public: @class wxGBSizerItem @wxheader{gbsizer.h} - The wxGBSizerItem class is used by the - wxGridBagSizer for tracking the items in the - sizer. It adds grid position and spanning information to the normal - wxSizerItem by adding - wxGBPosition and wxGBSpan - attrbibutes. Most of the time you will not need to use a - wxGBSizerItem directly in your code, but there are a couple of cases - where it is handy. + The wxGBSizerItem class is used by the wxGridBagSizer for tracking the + items in the sizer. It adds grid position and spanning information to the + normal wxSizerItem by adding wxGBPosition and wxGBSpan attrbibutes. Most of + the time you will not need to use a wxGBSizerItem directly in your code, + but there are a couple of cases where it is handy. @library{wxcore} - @category{FIXME} + @category{winlayout} */ class wxGBSizerItem : public wxSizerItem { public: - //@{ /** - Construct a sizer item for tracking a subsizer. + Construct a sizer item for tracking a spacer. */ wxGBSizerItem(int width, int height, const wxGBPosition& pos, - const wxGBSpan& span, int flag, - int border, wxObject* userData); + const wxGBSpan& span, int flag, int border, + wxObject* userData); + /** + Construct a sizer item for tracking a window. + */ wxGBSizerItem(wxWindow* window, const wxGBPosition& pos, - const wxGBSpan& span, - int flag, int border, + const wxGBSpan& span, int flag, int border, wxObject* userData); + /** + Construct a sizer item for tracking a subsizer. + */ wxGBSizerItem(wxSizer* sizer, const wxGBPosition& pos, - const wxGBSpan& span, - int flag, int border, + const wxGBSpan& span, int flag, int border, wxObject* userData); - //@} /** - Get the row and column of the endpoint of this item + Get the row and column of the endpoint of this item. */ void GetEndPos(int& row, int& col); @@ -268,7 +259,7 @@ public: Get the grid position of the item. */ wxGBPosition GetPos() const; - const void GetPos(int& row, int& col) const; + void GetPos(int& row, int& col) const; //@} //@{ @@ -276,29 +267,29 @@ public: Get the row and column spanning of the item. */ wxGBSpan GetSpan() const; - const void GetSpan(int& rowspan, int& colspan) const; + void GetSpan(int& rowspan, int& colspan) const; //@} - //@{ /** - Returns @true if the given pos/span would intersect with this item. + Returns @true if this item and the @a other item instersect. */ bool Intersects(const wxGBSizerItem& other); - bool Intersects(const wxGBPosition& pos, - const wxGBSpan& span); - //@} + /** + Returns @true if the given pos/span would intersect with this item. + */ + bool Intersects(const wxGBPosition& pos, const wxGBSpan& span); /** - If the item is already a member of a sizer then first ensure that - there is no other item that would intersect with this one at the new + If the item is already a member of a sizer then first ensure that there + is no other item that would intersect with this one at the new position, then set the new position. Returns @true if the change is successful and after the next Layout the item will be moved. */ bool SetPos(const wxGBPosition& pos); /** - If the item is already a member of a sizer then first ensure that - there is no other item that would intersect with this one with its new + If the item is already a member of a sizer then first ensure that there + is no other item that would intersect with this one with its new spanning size, then set the new spanning. Returns @true if the change is successful and after the next Layout the item will be resized. */ @@ -311,24 +302,24 @@ public: @class wxGBSpan @wxheader{gbsizer.h} - This class is used to hold the row and column spanning attributes of - items in a wxGridBagSizer. + This class is used to hold the row and column spanning attributes of items + in a wxGridBagSizer. @library{wxcore} - @category{FIXME} + @category{winlayout} */ class wxGBSpan { public: - //@{ /** - Construct a new wxGBSpan, optionally setting the rowspan and colspan. - The default is (1,1). (Meaning that the item occupies one cell in - each direction. + Default constructor, setting the rowspan and colspan to (1,1) meaning + that the item occupies one cell in each direction. */ wxGBSpan(); + /** + Construct a new wxGBSpan, setting the @a rowspan and @a colspan. + */ wxGBSpan(int rowspan, int colspan); - //@} /** Get the current colspan value. @@ -351,13 +342,13 @@ public: void SetRowspan(int rowspan); /** - Is the wxGBSpan valid? (An invalid wxGBSpan is (-1,-1). ) + Checks if the span is valid. An invalid span is (-1,-1). */ bool operator!(const wxGBSpan& o) const; /** Compare equality of two wxGBSpans. */ - bool operator operator==(const wxGBSpan& o) const; + bool operator==(const wxGBSpan& o) const; }; diff --git a/interface/gdicmn.h b/interface/gdicmn.h index 724de72b84..aeafd9d5f0 100644 --- a/interface/gdicmn.h +++ b/interface/gdicmn.h @@ -8,9 +8,7 @@ /** - Bitmap type flags. - - See wxBitmap and wxImage classes. + Bitmap type flags. See wxBitmap and wxImage classes. */ enum wxBitmapType { @@ -51,47 +49,44 @@ enum wxBitmapType }; /** - Standard cursors. - - See wxCursor. + Standard cursors. See wxCursor. */ enum wxStockCursor { wxCURSOR_NONE, - wxCURSOR_ARROW, - wxCURSOR_RIGHT_ARROW, - wxCURSOR_BULLSEYE, - wxCURSOR_CHAR, - wxCURSOR_CROSS, - wxCURSOR_HAND, - wxCURSOR_IBEAM, - wxCURSOR_LEFT_BUTTON, - wxCURSOR_MAGNIFIER, - wxCURSOR_MIDDLE_BUTTON, - wxCURSOR_NO_ENTRY, - wxCURSOR_PAINT_BRUSH, - wxCURSOR_PENCIL, - wxCURSOR_POINT_LEFT, - wxCURSOR_POINT_RIGHT, - wxCURSOR_QUESTION_ARROW, - wxCURSOR_RIGHT_BUTTON, - wxCURSOR_SIZENESW, - wxCURSOR_SIZENS, - wxCURSOR_SIZENWSE, - wxCURSOR_SIZEWE, - wxCURSOR_SIZING, - wxCURSOR_SPRAYCAN, - wxCURSOR_WAIT, - wxCURSOR_WATCH, - wxCURSOR_BLANK, - wxCURSOR_DEFAULT, //!< standard X11 cursor - wxCURSOR_COPY_ARROW , //!< MacOS Theme Plus arrow - // Not yet implemented for Windows - wxCURSOR_CROSS_REVERSE, - wxCURSOR_DOUBLE_ARROW, - wxCURSOR_BASED_ARROW_UP, - wxCURSOR_BASED_ARROW_DOWN, - wxCURSOR_ARROWWAIT, + wxCURSOR_ARROW, ///< A standard arrow cursor. + wxCURSOR_RIGHT_ARROW, ///< A standard arrow cursor pointing to the right. + wxCURSOR_BULLSEYE, ///< Bullseye cursor. + wxCURSOR_CHAR, ///< Rectangular character cursor. + wxCURSOR_CROSS, ///< A cross cursor. + wxCURSOR_HAND, ///< A hand cursor. + wxCURSOR_IBEAM, ///< An I-beam cursor (vertical line). + wxCURSOR_LEFT_BUTTON, ///< Represents a mouse with the left button depressed. + wxCURSOR_MAGNIFIER, ///< A magnifier icon. + wxCURSOR_MIDDLE_BUTTON, ///< Represents a mouse with the middle button depressed. + wxCURSOR_NO_ENTRY, ///< A no-entry sign cursor. + wxCURSOR_PAINT_BRUSH, ///< A paintbrush cursor. + wxCURSOR_PENCIL, ///< A pencil cursor. + wxCURSOR_POINT_LEFT, ///< A cursor that points left. + wxCURSOR_POINT_RIGHT, ///< A cursor that points right. + wxCURSOR_QUESTION_ARROW, ///< An arrow and question mark. + wxCURSOR_RIGHT_BUTTON, ///< Represents a mouse with the right button depressed. + wxCURSOR_SIZENESW, ///< A sizing cursor pointing NE-SW. + wxCURSOR_SIZENS, ///< A sizing cursor pointing N-S. + wxCURSOR_SIZENWSE, ///< A sizing cursor pointing NW-SE. + wxCURSOR_SIZEWE, ///< A sizing cursor pointing W-E. + wxCURSOR_SIZING, ///< A general sizing cursor. + wxCURSOR_SPRAYCAN, ///< A spraycan cursor. + wxCURSOR_WAIT, ///< A wait cursor. + wxCURSOR_WATCH, ///< A watch cursor. + wxCURSOR_BLANK, ///< Transparent cursor. + wxCURSOR_DEFAULT, ///< Standard X11 cursor (only in wxGTK). + wxCURSOR_COPY_ARROW , ///< MacOS Theme Plus arrow (only in wxMac). + wxCURSOR_CROSS_REVERSE, ///< Only available on wxX11. + wxCURSOR_DOUBLE_ARROW, ///< Only available on wxX11. + wxCURSOR_BASED_ARROW_UP, ///< Only available on wxX11. + wxCURSOR_BASED_ARROW_DOWN, ///< Only available on wxX11. + wxCURSOR_ARROWWAIT, ///< A wait cursor with a standard arrow. wxCURSOR_MAX }; @@ -101,10 +96,10 @@ enum wxStockCursor @class wxRealPoint @wxheader{gdicmn.h} - A @b wxRealPoint is a useful data structure for graphics operations. + A wxRealPoint is a useful data structure for graphics operations. - It contains floating point @e x and @e y members. - See also wxPoint for an integer version. + It contains floating point @e x and @e y members. See wxPoint for an + integer version. @library{wxcore} @category{data} @@ -148,51 +143,65 @@ public: class wxRect { public: - //@{ /** - Creates a wxRect object from size values at the origin. + Default constructor. */ wxRect(); + /** + Creates a wxRect object from @a x, @a y, @a width and @a height values. + */ wxRect(int x, int y, int width, int height); + /** + Creates a wxRect object from top-left and bottom-right points. + */ wxRect(const wxPoint& topLeft, const wxPoint& bottomRight); + /** + Creates a wxRect object from position and @a size values. + */ wxRect(const wxPoint& pos, const wxSize& size); + /** + Creates a wxRect object from @a size values at the origin. + */ wxRect(const wxSize& size); - //@} //@{ /** - Returns the rectangle having the same size as this one but centered relatively - to the given rectangle @e r. By default, rectangle is centred in both - directions but if @a dir includes only @c wxVERTICAL or only - @c wxHORIZONTAL flag, then it is only centered in this direction while + Returns the rectangle having the same size as this one but centered + relatively to the given rectangle @a r. By default, rectangle is + centred in both directions but if @a dir includes only @c wxVERTICAL or + only @c wxHORIZONTAL, then it is only centered in this direction while the other component of its position remains unchanged. */ wxRect CentreIn(const wxRect& r, int dir = wxBOTH) const; - const wxRect CenterIn(const wxRect& r, int dir = wxBOTH) const; + wxRect CenterIn(const wxRect& r, int dir = wxBOTH) const; //@} - //@{ /** - Returns @true if the given rectangle is completely inside this rectangle - (or touches its boundary) and @false otherwise. + Returns @true if the given point is inside the rectangle (or on its + boundary) and @false otherwise. */ bool Contains(int x, int y) const; - const bool Contains(const wxPoint& pt) const; - const bool Contains(const wxRect& rect) const; - //@} + /** + Returns @true if the given point is inside the rectangle (or on its + boundary) and @false otherwise. + */ + bool Contains(const wxPoint& pt) const; + /** + Returns @true if the given rectangle is completely inside this + rectangle (or touches its boundary) and @false otherwise. + */ + bool Contains(const wxRect& rect) const; //@{ /** Decrease the rectangle size. - This method is the opposite from Inflate(): - Deflate(a, b) is equivalent to Inflate(-a, -b). - Please refer to Inflate() for full description. - @see Inflate() + 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) const; - void Deflate(const wxSize& diff) const; - void Deflate(wxCoord diff) const; + void Deflate(wxCoord dx, wxCoord dy); + void Deflate(const wxSize& diff); + void Deflate(wxCoord diff); wxRect Deflate(wxCoord dx, wxCoord dy) const; //@} @@ -217,7 +226,7 @@ public: int GetHeight() const; /** - Gets the left point of the rectangle (the same as wxRect::GetX). + Gets the left point of the rectangle (the same as GetX()). */ int GetLeft() const; @@ -239,7 +248,7 @@ public: wxSize GetSize() const; /** - Gets the top point of the rectangle (the same as wxRect::GetY). + Gets the top point of the rectangle (the same as GetY()). */ int GetTop() const; @@ -272,47 +281,45 @@ public: //@{ /** Increases the size of the rectangle. - The second form uses the same @a diff for both @a dx and @e dy. - The first two versions modify the rectangle in place, the last one returns a - new rectangle leaving this one unchanged. - The left border is moved farther left and the right border is moved farther - right by @e dx. The upper border is moved farther up and the bottom border - is moved farther down by @e dy. (Note the the width and height of the - rectangle thus change by 2*@a dx and 2*@e 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. - Inflating and deflating behaves "naturally". Defined more precisely, that - means: - "Real" inflates (that is, @a dx and/or @a dy = 0) are not - constrained. Thus inflating a rectangle can cause its upper left corner - to move into the negative numbers. (the versions prior to 2.5.4 forced - the top left coordinate to not fall below (0, 0), which implied a - forced move of the rectangle.) - Deflates are clamped to not reduce the width or height of the - rectangle below zero. In such cases, the top-left corner is nonetheless - handled properly. For example, a rectangle at (10, 10) with size (20, - 40) that is inflated by (-15, -15) will become located at (20, 25) at - size (0, 10). Finally, observe that the width and height are treated - independently. In the above example, the width is reduced by 20, - whereas the height is reduced by the full 30 (rather than also stopping - at 20, when the width reached zero). + + 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 + 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. + + Inflating and deflating behaves "naturally". Defined more precisely, + that means: + -# "Real" inflates (that is, @a dx and/or @a dy = 0) are not + constrained. Thus inflating a rectangle can cause its upper left + corner to move into the negative numbers. (2.5.4 and older forced + the top left coordinate to not fall below (0, 0), which implied a + forced move of the rectangle.) + -# Deflates are clamped to not reduce the width or height of the + rectangle below zero. In such cases, the top-left corner is + nonetheless handled properly. For example, a rectangle at (10, 10) + with size (20, 40) that is inflated by (-15, -15) will become + located at (20, 25) at size (0, 10). Finally, observe that the width + and height are treated independently. In the above example, the + width is reduced by 20, whereas the height is reduced by the full 30 + (rather than also stopping at 20, when the width reached zero). @see Deflate() */ - void Inflate(wxCoord dx, wxCoord dy) const; - void Inflate(const wxSize& diff) const; - void Inflate(wxCoord diff) const; + void Inflate(wxCoord dx, wxCoord dy); + void Inflate(const wxSize& diff); + void Inflate(wxCoord diff); wxRect Inflate(wxCoord dx, wxCoord dy) const; //@} //@{ /** - Modifies the rectangle to contain the overlapping box of this rectangle and the - one passed in as parameter. The const version returns the new rectangle, the - other one modifies this rectangle in place. + Modifies the rectangle to contain the overlapping box of this rectangle + and the one passed in as parameter. */ - wxRect Intersect(const wxRect& rect); - const wxRect& Intersect(const wxRect& rect); + wxRect Intersect(const wxRect& rect) const; + wxRect& Intersect(const wxRect& rect); //@} /** @@ -322,8 +329,8 @@ public: bool Intersects(const wxRect& rect) const; /** - Returns @true if this rectangle has a width or height less than or equal to - 0 and @false otherwise. + Returns @true if this rectangle has a width or height less than or + equal to 0 and @false otherwise. */ bool IsEmpty() const; @@ -366,30 +373,32 @@ public: //@{ /** - Modifies the rectangle to contain the bounding box of this rectangle and the - one passed in as parameter. The const version returns the new rectangle, the - other one modifies this rectangle in place. + Modifies the rectangle to contain the bounding box of this rectangle + and the one passed in as parameter. */ - wxRect Union(const wxRect& rect); - const wxRect& Union(const wxRect& rect); + wxRect Union(const wxRect& rect) const; + wxRect& Union(const wxRect& rect); //@} /** - int height - Height member. + Inequality operator. */ + bool operator !=(const wxRect& r1, const wxRect& r2); + //@{ + /** + Like Union(), but doesn't treat empty rectangles specially. + */ + wxRect operator +(const wxRect& r1, const wxRect& r2); + wxRect& operator +=(const wxRect& r); + //@} //@{ /** Returns the intersection of two rectangles (which may be empty). */ - bool operator !=(const wxRect& r1, const wxRect& r2); - wxRect operator +(const wxRect& r1, const wxRect& r2); - wxRect operator +=(const wxRect& r); - See also wxRect operator *(const wxRect& r1, - const wxRect& r2); - wxRect operator *=(const wxRect& r); + wxRect operator *(const wxRect& r1, const wxRect& r2); + wxRect& operator *=(const wxRect& r); //@} /** @@ -403,21 +412,24 @@ public: bool operator ==(const wxRect& r1, const wxRect& r2); /** - int width - Width member. + Height member. */ + int height; + /** + Width member. + */ + int width; /** - int x x coordinate of the top-level corner of the rectangle. */ - + int x; /** - int y y coordinate of the top-level corner of the rectangle. */ + int y; }; @@ -426,10 +438,10 @@ public: @class wxPoint @wxheader{gdicmn.h} - A @b wxPoint is a useful data structure for graphics operations. - It simply contains integer @e x and @e y members. + A wxPoint is a useful data structure for graphics operations. - See also wxRealPoint for a floating point version. + It contains integer @e x and @e y members. See wxRealPoint for a floating + point version. @library{wxcore} @category{data} @@ -444,46 +456,47 @@ class wxPoint public: //@{ /** - Create a point. + Constructs a point. */ wxPoint(); wxPoint(int x, int y); //@} - //@{ /** - Operators for sum and subtraction between a wxPoint object and a - wxSize object. + Assignment operator. */ void operator =(const wxPoint& pt); + bool operator ==(const wxPoint& p1, const wxPoint& p2); bool operator !=(const wxPoint& p1, const wxPoint& p2); + wxPoint operator +(const wxPoint& p1, const wxPoint& p2); wxPoint operator -(const wxPoint& p1, const wxPoint& p2); - wxPoint operator +=(const wxPoint& pt); - wxPoint operator -=(const wxPoint& pt); + + wxPoint& operator +=(const wxPoint& pt); + wxPoint& operator -=(const wxPoint& pt); + wxPoint operator +(const wxPoint& pt, const wxSize& sz); wxPoint operator -(const wxPoint& pt, const wxSize& sz); wxPoint operator +(const wxSize& sz, const wxPoint& pt); wxPoint operator -(const wxSize& sz, const wxPoint& pt); - wxPoint operator +=(const wxSize& sz); - wxPoint operator -=(const wxSize& sz); - //@} + + wxPoint& operator +=(const wxSize& sz); + wxPoint& operator -=(const wxSize& sz); /** - int x x member. */ - + int x; /** - int y y member. */ + int y; }; /** - Global istance of a wxPoint initialized with values -1;-1. + Global istance of a wxPoint initialized with values (-1,-1). */ wxPoint wxDefaultPosition; @@ -493,17 +506,93 @@ wxPoint wxDefaultPosition; @wxheader{gdicmn.h} wxWidgets maintains a database of standard RGB colours for a predefined - set of named colours (such as "BLACK", "LIGHT GREY"). The - application may add to this set if desired by using - wxColourDatabase::AddColour and may use it to look up - colours by names using wxColourDatabase::Find or find the names - for the standard colour suing wxColourDatabase::FindName. - - There is one predefined instance of this class called - @b wxTheColourDatabase. + set of named colours. The application may add to this set if desired by + using AddColour() and may use it to look up colours by names using Find() + or find the names for the standard colour using FindName(). + + There is one predefined, global instance of this class called + ::wxTheColourDatabase. + + The standard database contains at least the following colours: + + @beginTable + + AQUAMARINE + @n BLACK + @n BLUE + @n BLUE VIOLET + @n BROWN + @n CADET BLUE + @n CORAL + @n CORNFLOWER BLUE + @n CYAN + @n DARK GREY + @n DARK GREEN + @n DARK OLIVE GREEN + @n DARK ORCHID + @n DARK SLATE BLUE + @n DARK SLATE GREY + @n DARK TURQUOISE + @n DIM GREY + + FIREBRICK + @n FOREST GREEN + @n GOLD + @n GOLDENROD + @n GREY + @n GREEN + @n GREEN YELLOW + @n INDIAN RED + @n KHAKI + @n LIGHT BLUE + @n LIGHT GREY + @n LIGHT STEEL BLUE + @n LIME GREEN + @n MAGENTA + @n MAROON + @n MEDIUM AQUAMARINE + @n MEDIUM BLUE + + MEDIUM FOREST GREEN + @n MEDIUM GOLDENROD + @n MEDIUM ORCHID + @n MEDIUM SEA GREEN + @n MEDIUM SLATE BLUE + @n MEDIUM SPRING GREEN + @n MEDIUM TURQUOISE + @n MEDIUM VIOLET RED + @n MIDNIGHT BLUE + @n NAVY + @n ORANGE + @n ORANGE RED + @n ORCHID + @n PALE GREEN + @n PINK + @n PLUM + @n PURPLE + + RED + @n SALMON + @n SEA GREEN + @n SIENNA + @n SKY BLUE + @n SLATE BLUE + @n SPRING GREEN + @n STEEL BLUE + @n TAN + @n THISTLE + @n TURQUOISE + @n VIOLET + @n VIOLET RED + @n WHEAT + @n WHITE + @n YELLOW + @n YELLOW GREEN + + @endTable @library{wxcore} - @category{FIXME} + @category{gdi} @see wxColour */ @@ -511,32 +600,27 @@ class wxColourDatabase { public: /** - Constructs the colour database. It will be initialized at the first use. + Constructs the colour database. It will be initialized at the first + use. */ wxColourDatabase(); - //@{ /** - Adds a colour to the database. If a colour with the same name already exists, - it is replaced. - Please note that the overload taking a pointer is deprecated and will be - removed in the next wxWidgets version, please don't use it. + Adds a colour to the database. If a colour with the same name already + exists, it is replaced. */ - void AddColour(const wxString& colourName, - const wxColour& colour); - void AddColour(const wxString& colourName, wxColour* colour); - //@} + void AddColour(const wxString& colourName, const wxColour& colour); /** - Finds a colour given the name. Returns an invalid colour object (that is, such - that its @ref wxColour::isok Ok method returns @false) if the colour wasn't - found in the database. + Finds a colour given the name. Returns an invalid colour object (that + is, wxColour::IsOk() will return @false) if the colour wasn't found in + the database. */ wxColour Find(const wxString& colourName); /** - Finds a colour name given the colour. Returns an empty string if the colour is - not found in the database. + Finds a colour name given the colour. Returns an empty string if the + colour is not found in the database. */ wxString FindName(const wxColour& colour) const; }; @@ -546,16 +630,17 @@ public: @class wxSize @wxheader{gdicmn.h} - A @b 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. - 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 - the size. + 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. - @b wxPython note: wxPython defines aliases for the @c x and @c y members - named @c width and @c height since it makes much more sense for - sizes. + @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} @@ -578,10 +663,7 @@ public: //@{ /** - Decreases the size in x- and y- directions - By @e size.x and @e size.y for the first overload - By @a dx and @a dy for the second one - By @a d and @a d for the third one + Decreases the size in both x and y directions. @see IncBy() */ @@ -591,8 +673,8 @@ public: //@} /** - Decrements this object so that both of its dimensions are not greater than the - corresponding dimensions of the @e size. + Decrements this object so that both of its dimensions are not greater + than the corresponding dimensions of the @a size. @see IncTo() */ @@ -610,10 +692,7 @@ public: //@{ /** - Increases the size in x- and y- directions - By @e size.x and @e size.y for the first overload - By @a dx and @a dy for the second one - By @a d and @a d for the third one + Increases the size in both x and y directions. @see DecBy() */ @@ -623,49 +702,31 @@ public: //@} /** - Increments this object so that both of its dimensions are not less than the - corresponding dimensions of the @e size. + Increments this object so that both of its dimensions are not less than + the corresponding dimensions of the @a size. @see DecTo() */ void IncTo(const wxSize& size); /** - Returns @true if neither of the size object components is equal to -1, which - is used as default for the size values in wxWidgets (hence the predefined - @c wxDefaultSize has both of its components equal to -1). - This method is typically used before calling - SetDefaults(). + Returns @true if neither of the size object components is equal to -1, + which is used as default for the size values in wxWidgets (hence the + predefined ::wxDefaultSize has both of its components equal to -1). + + This method is typically used before calling SetDefaults(). */ bool IsFullySpecified() const; - //@{ /** - Operators for division and multiplication between a wxSize object and an - integer. - */ - void operator =(const wxSize& sz); - bool operator ==(const wxSize& s1, const wxSize& s2); - bool operator !=(const wxSize& s1, const wxSize& s2); - wxSize operator +(const wxSize& s1, const wxSize& s2); - wxSize operator -(const wxSize& s1, const wxSize& s2); - wxSize operator +=(const wxSize& sz); - wxSize operator -=(const wxSize& sz); - wxSize operator /(const wxSize& sz, int factor); - wxSize operator *(const wxSize& sz, int factor); - wxSize operator *(int factor, const wxSize& sz); - wxSize operator /=(int factor); - wxSize operator *=(int factor); - //@} + Scales the dimensions of this object by the given factors. If you want + to scale both dimensions by the same factor you can also use + operator*=(). - /** - Scales the dimensions of this object by the given factors. - If you want to scale both dimensions by the same factor you can also use - the @ref operators() "operator *=" - Returns a reference to this object (so that you can concatenate other - operations in the same line). + @returns A reference to this object (so that you can concatenate other + operations in the same line). */ - wxSize Scale(float xscale, float yscale); + wxSize& Scale(float xscale, float yscale); /** Sets the width and height members. @@ -673,9 +734,16 @@ 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() ) + { + size.SetDefaults(GetDefaultSize()); + } + @endcode @see IsFullySpecified() */ @@ -690,10 +758,29 @@ public: Sets the width. */ void SetWidth(int width); + + /** + Assignment operator. + */ + void operator =(const wxSize& sz); + + bool operator ==(const wxSize& s1, const wxSize& s2); + bool operator !=(const wxSize& s1, const wxSize& s2); + + wxSize operator +(const wxSize& s1, const wxSize& s2); + wxSize operator -(const wxSize& s1, const wxSize& s2); + wxSize& operator +=(const wxSize& sz); + wxSize& operator -=(const wxSize& sz); + + wxSize operator /(const wxSize& sz, int factor); + wxSize operator *(const wxSize& sz, int factor); + wxSize operator *(int factor, const wxSize& sz); + wxSize& operator /=(int factor); + wxSize& operator *=(int factor); }; /** - Global instance of a wxSize object initialized with values -1;-1. + Global instance of a wxSize object initialized to (-1,-1). */ wxSize wxDefaultSize;