X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a008d6e585122561be3189cca56251752cd157cd..a8bda512079352ba81933e278d9ccdb8ef7a9866:/interface/wx/sizer.h diff --git a/interface/wx/sizer.h b/interface/wx/sizer.h index f346f22cd0..719d4d2c4a 100644 --- a/interface/wx/sizer.h +++ b/interface/wx/sizer.h @@ -3,7 +3,7 @@ // Purpose: interface of wxStdDialogButtonSizer // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -291,13 +291,15 @@ public: wxObject* userData = NULL); /** - Adds non-stretchable space to the sizer. + This base function adds non-stretchable space to both the horizontal + and vertical orientation of the sizer. More readable way of calling: @code wxSizer::Add(size, size, 0). @endcode + @see wxBoxSizer::AddSpacer() */ - wxSizerItem* AddSpacer(int size); + virtual wxSizerItem *AddSpacer(int size); /** Adds stretchable space to the sizer. @@ -568,7 +570,7 @@ public: /** Inserts non-stretchable space to the sizer. - More readable way of calling wxSizer::Insert(size, size, 0). + More readable way of calling wxSizer::Insert(index, size, size). */ wxSizerItem* InsertSpacer(size_t index, int size); @@ -783,35 +785,28 @@ public: /** Set an item's minimum size by window, sizer, or position. - The item will be found recursively in the sizer's descendants. This function enables an application to set the size of an item after initial creation. + The @a window or @a sizer will be found recursively in the sizer's + descendants. + @see wxSizerItem::SetMinSize() + + @return + @true if the minimal size was successfully set or @false if the + item was not found. */ + //@{ bool SetItemMinSize(wxWindow* window, int width, int height); + bool SetItemMinSize(wxWindow* window, const wxSize& size); - /** - Set an item's minimum size by window, sizer, or position. - - The item will be found recursively in the sizer's descendants. - This function enables an application to set the size of an item after - initial creation. - - @see wxSizerItem::SetMinSize() - */ bool SetItemMinSize(wxSizer* sizer, int width, int height); + bool SetItemMinSize(wxSizer* sizer, const wxSize& size); - /** - Set an item's minimum size by window, sizer, or position. - - The item will be found recursively in the sizer's descendants. - This function enables an application to set the size of an item after - initial creation. - - @see wxSizerItem::SetMinSize() - */ bool SetItemMinSize(size_t index, int width, int height); + bool SetItemMinSize(size_t index, const wxSize& size); + //@} /** Call this to give the sizer a minimal size. @@ -1022,6 +1017,30 @@ public: */ virtual ~wxSizerItem(); + /** + Set the window to be tracked by this item. + + The old window isn't deleted as it is now owned by the sizer item. + */ + void AssignWindow(wxWindow *window); + + /** + Set the sizer tracked by this item. + + Old sizer, if any, is deleted. + */ + void AssignSizer(wxSizer *sizer); + + //@{ + /** + Set the size of the spacer tracked by this item. + + Old spacer, if any, is deleted. + */ + void AssignSpacer(const wxSize& size); + void AssignSpacer(int w, int h) { AssignSpacer(wxSize(w, h)); } + //@} + /** Calculates the minimum desired size for the item, including any space needed by borders. @@ -1191,13 +1210,17 @@ public: /** Set the sizer tracked by this item. - @deprecated @todo provide deprecation description + + @deprecated This function does not free the old sizer which may result + in memory leaks, use AssignSizer() which does free it instead. */ void SetSizer(wxSizer* sizer); /** Set the size of the spacer tracked by this item. - @deprecated @todo provide deprecation description + + @deprecated This function does not free the old spacer which may result + in memory leaks, use AssignSpacer() which does free it instead. */ void SetSpacer(const wxSize& size); @@ -1435,17 +1458,17 @@ class wxFlexGridSizer : public wxGridSizer public: //@{ /** - Constructor for a wxFlexGridSizer. + wxFlexGridSizer constructors. - @a rows and @a cols determine the number of columns and rows in the sizer - - if either of the parameters is zero, it will be calculated to form the - total number of children in the sizer, thus making the sizer grow - dynamically. + Please see wxGridSizer::wxGridSizer documentation. - @a vgap and @a hgap define extra space between all children. + @since 2.9.1 (except for the four argument overload) */ - wxFlexGridSizer(int rows, int cols, int vgap, int hgap); - wxFlexGridSizer(int cols, int vgap = 0, int hgap = 0); + wxFlexGridSizer( int cols, int vgap, int hgap ); + wxFlexGridSizer( int cols, const wxSize& gap = wxSize(0, 0) ); + + wxFlexGridSizer( int rows, int cols, int vgap, int hgap ); + wxFlexGridSizer( int rows, int cols, const wxSize& gap ); //@} /** @@ -1578,32 +1601,82 @@ class wxGridSizer : public wxSizer public: //@{ /** - Constructor for a wxGridSizer. + wxGridSizer constructors. - @a rows and @a cols determine the number of columns and rows in the sizer - - if either of the parameters is zero, it will be calculated to form the - total number of children in the sizer, thus making the sizer grow dynamically. + Usually only the number of columns in the flex grid sizer needs to be + specified using @a cols argument. The number of rows will be deduced + automatically depending on the number of the elements added to the + sizer. - @a vgap and @a hgap define extra space between all children. + If a constructor form with @a rows parameter is used (and the value of + @a rows argument is not zero, meaning "unspecified") the sizer will + check that no more than @c cols*rows elements are added to it, i.e. + that no more than the given number of @a rows is used. Adding less than + maximally allowed number of items is not an error however. + + Finally, it is also possible to specify the number of rows and use 0 + for @a cols. In this case, the sizer will use the given fixed number of + rows and as many columns as necessary. + + The @a gap (or @a vgap and @a hgap, which correspond to the height and + width of the wxSize object) argument defines the size of the padding + between the rows (its vertical component, or @a vgap) and columns + (its horizontal component, or @a hgap), in pixels. + + + @since 2.9.1 (except for the four argument overload) */ - wxGridSizer(int rows, int cols, int vgap, int hgap); - wxGridSizer(int cols, int vgap = 0, int hgap = 0); + wxGridSizer( int cols, int vgap, int hgap ); + wxGridSizer( int cols, const wxSize& gap = wxSize(0, 0) ); + + wxGridSizer( int rows, int cols, int vgap, int hgap ); + wxGridSizer( int rows, int cols, const wxSize& gap ); //@} /** - Returns the number of columns in the sizer. + Returns the number of columns that has been specified for the + sizer. + + Returns zero if the sizer is automatically adjusting the number of + columns depending on number of its children. To get the effective + number of columns or rows being currently used, see GetEffectiveColsCount() */ int GetCols() const; + + /** + Returns the number of rows that has been specified for the + sizer. + + Returns zero if the sizer is automatically adjusting the number of + rows depending on number of its children. To get the effective + number of columns or rows being currently used, see GetEffectiveRowsCount(). + */ + int GetRows() const; /** - Returns the horizontal gap (in pixels) between cells in the sizer. + Returns the number of columns currently used by the sizer. + + This will depend on the number of children the sizer has if + the sizer is automatically adjusting the number of columns/rows. + + @since 2.9.1 */ - int GetHGap() const; + int GetEffectiveColsCount() const; + + /** + Returns the number of rows currently used by the sizer. + + This will depend on the number of children the sizer has if + the sizer is automatically adjusting the number of columns/rows. + + @since 2.9.1 + */ + int GetEffectiveRowsCount() const; /** - Returns the number of rows in the sizer. + Returns the horizontal gap (in pixels) between cells in the sizer. */ - int GetRows() const; + int GetHGap() const; /** Returns the vertical gap (in pixels) between the cells in the sizer. @@ -1636,11 +1709,29 @@ public: /** @class wxStaticBoxSizer - wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static - box around the sizer. - This static box may be either created independently or the sizer may create - it itself as a convenience. In any case, the sizer owns the wxStaticBox control - and will delete it, if it is deleted. + wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static box around + the sizer. + + The static box may be either created independently or the sizer may create it + itself as a convenience. In any case, the sizer owns the wxStaticBox control + and will delete it in the wxStaticBoxSizer destructor. + + Note that since wxWidgets 2.9.1 you are encouraged to create the windows + which are added to wxStaticBoxSizer as children of wxStaticBox itself, see + this class documentation for more details. + + Example of use of this class: + @code + void MyFrame::CreateControls() + { + wxPanel *panel = new wxPanel(this); + ... + wxStaticBoxSizer *sz = new wxStaticBoxSizer(wxVERTICAL, panel, "Box"); + sz->Add(new wxStaticText(sz->GetStaticBox(), wxID_ANY, + "This window is a child of the staticbox")); + ... + } + @endcode @library{wxcore} @category{winlayout} @@ -1653,8 +1744,11 @@ public: /** This constructor uses an already existing static box. - It takes the associated static box and the orientation @a orient, which - can be either @c wxVERTICAL or @c wxHORIZONTAL as parameters. + @param box + The static box to associate with the sizer (which will take its + ownership). + @param orient + Can be either @c wxVERTICAL or @c wxHORIZONTAL. */ wxStaticBoxSizer(wxStaticBox* box, int orient); @@ -1695,6 +1789,22 @@ public: */ wxBoxSizer(int orient); + /** + Adds non-stretchable space to the main orientation of the sizer only. + More readable way of calling: + @code + if ( wxBoxSizer::IsVertical() ) + { + wxBoxSizer::Add(0, size, 0). + } + else + { + wxBoxSizer::Add(size, 0, 0). + } + @endcode + */ + virtual wxSizerItem *AddSpacer(int size); + /** Implements the calculation of a box sizer's minimal.