X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3a59bd2e784b77c91071ad76f1a958bd1a02ce1d..b72ed64277a2b16c6c8681995e5f3f304a8fe38d:/interface/wx/sizer.h diff --git a/interface/wx/sizer.h b/interface/wx/sizer.h index 66c5d207fa..ec02ec9e3c 100644 --- a/interface/wx/sizer.h +++ b/interface/wx/sizer.h @@ -3,1567 +3,1686 @@ // Purpose: interface of wxStdDialogButtonSizer // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// + /** - @class wxStdDialogButtonSizer + @class wxSizer - This class creates button layouts which conform to the standard button spacing - and ordering defined by the platform - or toolkit's user interface guidelines (if such things exist). By using this - class, you can ensure that all your - standard dialogs look correct on all major platforms. Currently it conforms to - the Windows, GTK+ and Mac OS X - human interface guidelines. + wxSizer is the abstract base class used for laying out subwindows in a window. + You cannot use wxSizer directly; instead, you will have to use one of the sizer + classes derived from it. Currently there are wxBoxSizer, wxStaticBoxSizer, + wxGridSizer, wxFlexGridSizer, wxWrapSizer and wxGridBagSizer. - When there aren't interface guidelines defined for a particular platform or - toolkit, wxStdDialogButtonSizer reverts - to the Windows implementation. + The layout algorithm used by sizers in wxWidgets is closely related to layout + in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. + It is based upon the idea of the individual subwindows reporting their minimal + required size and their ability to get stretched if the size of the parent window + has changed. + + This will most often mean that the programmer does not set the original size of + a dialog in the beginning, rather the dialog will be assigned a sizer and this + sizer will be queried about the recommended size. The sizer in turn will query + its children, which can be normal windows, empty space or other sizers, so that + a hierarchy of sizers can be constructed. Note that wxSizer does not derive + from wxWindow and thus does not interfere with tab ordering and requires very little + resources compared to a real window on screen. - To use this class, first add buttons to the sizer by calling AddButton (or - SetAffirmativeButton, SetNegativeButton, - or SetCancelButton) and then call Realize in order to create the actual button - layout used. Other than these special - operations, this sizer works like any other sizer. + What makes sizers so well fitted for use in wxWidgets is the fact that every + control reports its own minimal size and the algorithm can handle differences in + font sizes or different window (dialog item) sizes on different platforms without + problems. If e.g. the standard font as well as the overall design of Motif widgets + requires more space than on Windows, the initial dialog size will automatically + be bigger on Motif than on Windows. - If you add a button with wxID_SAVE, on Mac OS X the button will be renamed to - "Save" and - the wxID_NO button will be renamed to "Don't Save" in accordance with the Mac - OS X Human Interface Guidelines. + Sizers may also be used to control the layout of custom drawn items on the + window. The wxSizer::Add(), wxSizer::Insert(), and wxSizer::Prepend() functions + return a pointer to the newly added wxSizerItem. + Just add empty space of the desired size and attributes, and then use the + wxSizerItem::GetRect() method to determine where the drawing operations + should take place. + + Please notice that sizers, like child windows, are owned by the library and + will be deleted by it which implies that they must be allocated on the heap. + However if you create a sizer and do not add it to another sizer or + window, the library wouldn't be able to delete such an orphan sizer and in + this, and only this, case it should be deleted explicitly. + + @beginWxPythonOnly + If you wish to create a sizer class in wxPython you should + derive the class from @c wxPySizer in order to get Python-aware + capabilities for the various virtual methods. + @endWxPythonOnly + + @section wxsizer_flags wxSizer flags + + The "flag" argument accepted by wxSizeItem constructors and other + functions, e.g. wxSizer::Add(), is OR-combination of the following flags. + Two main behaviours are defined using these flags. One is the border around + a window: the border parameter determines the border width whereas the + flags given here determine which side(s) of the item that the border will + be added. The other flags determine how the sizer item behaves when the + space allotted to the sizer changes, and is somewhat dependent on the + specific kind of sizer used. + + @beginDefList + @itemdef{wxTOP
+ wxBOTTOM
+ wxLEFT
+ wxRIGHT
+ wxALL, + These flags are used to specify which side(s) of the sizer item + the border width will apply to.} + @itemdef{wxEXPAND, + The item will be expanded to fill the space assigned to the item.} + @itemdef{wxSHAPED, + The item will be expanded as much as possible while also + maintaining its aspect ratio.} + @itemdef{wxFIXED_MINSIZE, + Normally wxSizers will use GetAdjustedBestSize() to determine what + the minimal size of window items should be, and will use that size + to calculate the layout. This allows layouts to adjust when an + item changes and its best size becomes different. If you would + rather have a window item stay the size it started with then use + @c wxFIXED_MINSIZE.} + @itemdef{wxRESERVE_SPACE_EVEN_IF_HIDDEN, + Normally wxSizers don't allocate space for hidden windows or other + items. This flag overrides this behaviour so that sufficient space + is allocated for the window even if it isn't visible. This makes + it possible to dynamically show and hide controls without resizing + parent dialog, for example. (Available since 2.8.8.)} + @itemdef{wxALIGN_CENTER
+ wxALIGN_CENTRE
+ wxALIGN_LEFT
+ wxALIGN_RIGHT
+ wxALIGN_TOP
+ wxALIGN_BOTTOM
+ wxALIGN_CENTER_VERTICAL
+ wxALIGN_CENTRE_VERTICAL
+ wxALIGN_CENTER_HORIZONTAL
+ wxALIGN_CENTRE_HORIZONTAL, + The @c wxALIGN_* flags allow you to specify the alignment of the item + within the space allotted to it by the sizer, adjusted for the + border if any.} + @endDefList @library{wxcore} @category{winlayout} - @see wxSizer, @ref overview_sizer "Sizer Overview", - wxDialog::CreateButtonSizer + @see @ref overview_sizer */ -class wxStdDialogButtonSizer : public wxBoxSizer +class wxSizer : public wxObject { public: /** - Constructor for a wxStdDialogButtonSizer. + The constructor. + Note that wxSizer is an abstract base class and may not be instantiated. */ - wxStdDialogButtonSizer(); + wxSizer(); /** - Adds a button to the wxStdDialogButtonSizer. The @a button must have - one of the following identifiers: - wxID_OK - wxID_YES - wxID_SAVE - wxID_APPLY - wxID_CLOSE - wxID_NO - wxID_CANCEL - wxID_HELP - wxID_CONTEXT_HELP + The destructor. */ - void AddButton(wxButton* button); + virtual ~wxSizer(); /** - Rearranges the buttons and applies proper spacing between buttons to make them - match the platform or toolkit's interface guidelines. + Appends a child to the sizer. + + wxSizer itself is an abstract class, but the parameters are equivalent + in the derived classes that you will instantiate to use it so they are + described here: + + @param window + The window to be added to the sizer. Its initial size (either set + explicitly by the user or calculated internally when using + wxDefaultSize) is interpreted as the minimal and in many cases also + the initial size. + @param flags + A wxSizerFlags object that enables you to specify most of the above + parameters more conveniently. */ - void Realize(); + wxSizerItem* Add(wxWindow* window, const wxSizerFlags& flags); /** - Sets the affirmative button for the sizer. This allows you to use identifiers - other than the standard identifiers outlined above. + Appends a child to the sizer. + + wxSizer itself is an abstract class, but the parameters are equivalent + in the derived classes that you will instantiate to use it so they are + described here: + + @param window + The window to be added to the sizer. Its initial size (either set + explicitly by the user or calculated internally when using + wxDefaultSize) is interpreted as the minimal and in many cases also + the initial size. + @param proportion + Although the meaning of this parameter is undefined in wxSizer, it + is used in wxBoxSizer to indicate if a child of a sizer can change + its size in the main orientation of the wxBoxSizer - where 0 stands + for not changeable and a value of more than zero is interpreted + relative to the value of other children of the same wxBoxSizer. For + example, you might have a horizontal wxBoxSizer with three + children, two of which are supposed to change their size with the + sizer. Then the two stretchable windows would get a value of 1 each + to make them grow and shrink equally with the sizer's horizontal + dimension. + @param flag + OR-combination of flags affecting sizer's behaviour. See + @ref wxsizer_flags "wxSizer flags list" for details. + @param border + Determines the border width, if the flag parameter is set to + include any border flag. + @param userData + Allows an extra object to be attached to the sizer item, for use in + derived classes when sizing information is more complex than the + proportion and flag will allow for. */ - void SetAffirmativeButton(wxButton* button); + wxSizerItem* Add(wxWindow* window, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - Sets the cancel button for the sizer. This allows you to use identifiers other - than the standard identifiers outlined above. + Appends a child to the sizer. + + wxSizer itself is an abstract class, but the parameters are equivalent + in the derived classes that you will instantiate to use it so they are + described here: + + @param sizer + The (child-)sizer to be added to the sizer. This allows placing a + child sizer in a sizer and thus to create hierarchies of sizers + (typically a vertical box as the top sizer and several horizontal + boxes on the level beneath). + @param flags + A wxSizerFlags object that enables you to specify most of the above + parameters more conveniently. */ - void SetCancelButton(wxButton* button); + wxSizerItem* Add(wxSizer* sizer, const wxSizerFlags& flags); /** - Sets the negative button for the sizer. This allows you to use identifiers - other than the standard identifiers outlined above. + Appends a child to the sizer. + + wxSizer itself is an abstract class, but the parameters are equivalent + in the derived classes that you will instantiate to use it so they are + described here: + + @param sizer + The (child-)sizer to be added to the sizer. This allows placing a + child sizer in a sizer and thus to create hierarchies of sizers + (typically a vertical box as the top sizer and several horizontal + boxes on the level beneath). + @param proportion + Although the meaning of this parameter is undefined in wxSizer, it + is used in wxBoxSizer to indicate if a child of a sizer can change + its size in the main orientation of the wxBoxSizer - where 0 stands + for not changeable and a value of more than zero is interpreted + relative to the value of other children of the same wxBoxSizer. For + example, you might have a horizontal wxBoxSizer with three + children, two of which are supposed to change their size with the + sizer. Then the two stretchable windows would get a value of 1 each + to make them grow and shrink equally with the sizer's horizontal + dimension. + @param flag + OR-combination of flags affecting sizer's behaviour. See + @ref wxsizer_flags "wxSizer flags list" for details. + @param border + Determines the border width, if the flag parameter is set to + include any border flag. + @param userData + Allows an extra object to be attached to the sizer item, for use in + derived classes when sizing information is more complex than the + proportion and flag will allow for. */ - void SetNegativeButton(wxButton* button); -}; + wxSizerItem* Add(wxSizer* sizer, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); + /** + Appends a spacer child to the sizer. + wxSizer itself is an abstract class, but the parameters are equivalent + in the derived classes that you will instantiate to use it so they are + described here. -/** - @class wxSizerItem + @a width and @a height specify the dimension of a spacer to be added to + the sizer. Adding spacers to sizers gives more flexibility in the + design of dialogs; imagine for example a horizontal box with two + buttons at the bottom of a dialog: you might want to insert a space + between the two buttons and make that space stretchable using the + proportion flag and the result will be that the left button will be + aligned with the left side of the dialog and the right button with the + right side - the space in between will shrink and grow with the dialog. - The wxSizerItem class is used to track the position, size and other - attributes of each item managed by a wxSizer. It is not usually necessary - to use this class because the sizer elements can also be identified by - their positions or window or sizer pointers but sometimes it may be more - convenient to use it directly. + @param width + Width of the spacer. + @param height + Height of the spacer. + @param proportion + Although the meaning of this parameter is undefined in wxSizer, it + is used in wxBoxSizer to indicate if a child of a sizer can change + its size in the main orientation of the wxBoxSizer - where 0 stands + for not changeable and a value of more than zero is interpreted + relative to the value of other children of the same wxBoxSizer. For + example, you might have a horizontal wxBoxSizer with three + children, two of which are supposed to change their size with the + sizer. Then the two stretchable windows would get a value of 1 each + to make them grow and shrink equally with the sizer's horizontal + dimension. + @param flag + OR-combination of flags affecting sizer's behaviour. See + @ref wxsizer_flags "wxSizer flags list" for details. + @param border + Determines the border width, if the flag parameter is set to + include any border flag. + @param userData + Allows an extra object to be attached to the sizer item, for use in + derived classes when sizing information is more complex than the + proportion and flag will allow for. + */ + wxSizerItem* Add(int width, int height, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); - @library{wxcore} - @category{winlayout} -*/ -class wxSizerItem : public wxObject -{ -public: - //@{ /** - Construct a sizer item for tracking a subsizer. + 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(int width, int height, int proportion, int flag, - int border, wxObject* userData); - wxSizerItem(wxWindow* window, const wxSizerFlags& flags); - wxSizerItem(wxWindow* window, int proportion, int flag, - int border, - wxObject* userData); - wxSizerItem(wxSizer* window, const wxSizerFlags& flags); - wxSizerItem(wxSizer* sizer, int proportion, int flag, - int border, - wxObject* userData); - //@} + virtual wxSizerItem *AddSpacer(int size); /** - Deletes the user data and subsizer, if any. + Adds stretchable space to the sizer. + More readable way of calling: + @code + wxSizer::Add(0, 0, prop). + @endcode */ - ~wxSizerItem(); + wxSizerItem* AddStretchSpacer(int prop = 1); /** - Calculates the minimum desired size for the item, including any space - needed by borders. + This method is abstract and has to be overwritten by any derived class. + Here, the sizer will do the actual calculation of its children's minimal sizes. */ - wxSize CalcMin(); + virtual wxSize CalcMin() = 0; /** - Destroy the window or the windows in a subsizer, depending on the type - of item. + Detaches all children from the sizer. + If @a delete_windows is @true then child windows will also be deleted. */ - void DeleteWindows(); + virtual void Clear(bool delete_windows = false); /** - Enable deleting the SizerItem without destroying the contained sizer. - */ - void DetachSizer(); + Computes client area size for @a window so that it matches the sizer's + minimal size. Unlike GetMinSize(), this method accounts for other + constraints imposed on @e window, namely display's size (returned size + will never be too large for the display) and maximum window size if + previously set by wxWindow::SetMaxSize(). - /** - Return the border attribute. - */ - int GetBorder() const; + The returned value is suitable for passing to wxWindow::SetClientSize() or + wxWindow::SetMinClientSize(). - /** - Return the flags attribute. + @since 2.8.8 - See @ref wxsizer_flags "wxSizer flags list" for details. + @see ComputeFittingWindowSize(), Fit() */ - int GetFlag() const; + wxSize ComputeFittingClientSize(wxWindow* window); /** - Return the numeric id of wxSizerItem, or @c wxID_NONE if the id has - not been set. - */ - int GetId() const; + Like ComputeFittingClientSize(), but converts the result into window + size. The returned value is suitable for passing to wxWindow::SetSize() + or wxWindow::SetMinSize(). - /** - Get the minimum size needed for the item. + @since 2.8.8 + + @see ComputeFittingClientSize(), Fit() */ - wxSize GetMinSize() const; + wxSize ComputeFittingWindowSize(wxWindow* window); /** - Sets the minimum size to be allocated for this item. + Detach the child @a window from the sizer without destroying it. - If this item is a window, the @a size is also passed to - wxWindow::SetMinSize(). - */ - void SetMinSize(const wxSize& size); + This method does not cause any layout or resizing to take place, call Layout() + to update the layout "on screen" after detaching a child from the sizer. - /** - @overload - */ - void SetMinSize(int x, int y); + Returns @true if the child item was found and detached, @false otherwise. - /** - What is the current position of the item, as set in the last Layout. + @see Remove() */ - wxPoint GetPosition() const; + virtual bool Detach(wxWindow* window); /** - Get the proportion item attribute. + Detach the child @a sizer from the sizer without destroying it. + + This method does not cause any layout or resizing to take place, call Layout() + to update the layout "on screen" after detaching a child from the sizer. + + Returns @true if the child item was found and detached, @false otherwise. + + @see Remove() */ - int GetProportion() const; + virtual bool Detach(wxSizer* sizer); /** - Get the ration item attribute. + Detach a item at position @a index from the sizer without destroying it. + + This method does not cause any layout or resizing to take place, call Layout() + to update the layout "on screen" after detaching a child from the sizer. + Returns @true if the child item was found and detached, @false otherwise. + + @see Remove() */ - float GetRatio() const; + virtual bool Detach(int index); /** - Get the rectangle of the item on the parent window, excluding borders. + Tell the sizer to resize the @a window so that its client area matches the + sizer's minimal size (ComputeFittingClientSize() is called to determine it). + This is commonly done in the constructor of the window itself, see sample + in the description of wxBoxSizer. + + @return The new window size. + + @see ComputeFittingClientSize(), ComputeFittingWindowSize() */ - wxRect GetRect(); + wxSize Fit(wxWindow* window); /** - Get the current size of the item, as set in the last Layout. + Tell the sizer to resize the virtual size of the @a window to match the sizer's + minimal size. This will not alter the on screen size of the window, but may + cause the addition/removal/alteration of scrollbars required to view the virtual + area in windows which manage it. + + @see wxScrolled::SetScrollbars(), SetVirtualSizeHints() */ - wxSize GetSize() const; + void FitInside(wxWindow* window); + //@{ /** - If this item is tracking a sizer, return it. @NULL otherwise. + Returns the list of the items in this sizer. + + The elements of type-safe wxList @c wxSizerItemList are pointers to + objects of type wxSizerItem. */ - wxSizer* GetSizer() const; + wxSizerItemList& GetChildren(); + const wxSizerItemList& GetChildren() const; + //@} /** - If this item is tracking a spacer, return its size. + Returns the window this sizer is used in or @NULL if none. */ - const wxSize GetSpacer() const; + wxWindow* GetContainingWindow() const; /** - Get the userData item attribute. + Returns the number of items in the sizer. + + If you just need to test whether the sizer is empty or not you can also + use IsEmpty() function. */ - wxObject* GetUserData() const; + size_t GetItemCount() const; /** - If this item is tracking a window then return it. @NULL otherwise. + Finds wxSizerItem which holds the given @a window. + Use parameter @a recursive to search in subsizers too. + Returns pointer to item or @NULL. */ - wxWindow* GetWindow() const; + wxSizerItem* GetItem(wxWindow* window, bool recursive = false); /** - Returns @true if this item is a window or a spacer and it is shown or - if this item is a sizer and not all of its elements are hidden. + Finds wxSizerItem which holds the given @a sizer. + Use parameter @a recursive to search in subsizers too. + Returns pointer to item or @NULL. + */ - In other words, for sizer items, all of the child elements must be - hidden for the sizer itself to be considered hidden. + wxSizerItem* GetItem(wxSizer* sizer, bool recursive = false); - As an exception, if the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag was - used for this sizer item, then IsShown() always returns @true for it - (see wxSizerFlags::ReserveSpaceEvenIfHidden()). + /** + Finds wxSizerItem which is located in the sizer at position @a index. + Use parameter @a recursive to search in subsizers too. + Returns pointer to item or @NULL. */ - bool IsShown() const; + wxSizerItem* GetItem(size_t index); /** - Is this item a sizer? + Finds item of the sizer which has the given @e id. + This @a id is not the window id but the id of the wxSizerItem itself. + This is mainly useful for retrieving the sizers created from XRC resources. + Use parameter @a recursive to search in subsizers too. + Returns pointer to item or @NULL. */ - bool IsSizer() const; + wxSizerItem* GetItemById(int id, bool recursive = false); /** - Is this item a spacer? + Returns the minimal size of the sizer. + + This is either the combined minimal size of all the children and their + borders or the minimal size set by SetMinSize(), depending on which is bigger. + Note that the returned value is client size, not window size. + In particular, if you use the value to set toplevel window's minimal or + actual size, use wxWindow::SetMinClientSize() or wxWindow::SetClientSize(), + not wxWindow::SetMinSize() or wxWindow::SetSize(). */ - bool IsSpacer() const; + wxSize GetMinSize(); /** - Is this item a window? + Returns the current position of the sizer. */ - bool IsWindow() const; + wxPoint GetPosition() const; /** - Set the border item attribute. + Returns the current size of the sizer. */ - void SetBorder(int border); + wxSize GetSize() const; /** - Set the position and size of the space allocated to the sizer, and - adjust the position and size of the item to be within that space - taking alignment and borders into account. + Hides the child @a window. + + To make a sizer item disappear, use Hide() followed by Layout(). + + Use parameter @a recursive to hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. + + @see IsShown(), Show() */ - void SetDimension(const wxPoint& pos, const wxSize& size); + bool Hide(wxWindow* window, bool recursive = false); /** - Set the flag item attribute. + Hides the child @a sizer. + + To make a sizer item disappear, use Hide() followed by Layout(). + + Use parameter @a recursive to hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. + + @see IsShown(), Show() */ - void SetFlag(int flag); + bool Hide(wxSizer* sizer, bool recursive = false); /** - Sets the numeric id of the wxSizerItem to @e id. + Hides the item at position @a index. + + To make a sizer item disappear, use Hide() followed by Layout(). + + Use parameter @a recursive to hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. + + @see IsShown(), Show() */ - void SetId(int id); + bool Hide(size_t index); /** + Insert a child into the sizer before any existing item at @a index. + See Add() for the meaning of the other parameters. */ - void SetInitSize(int x, int y); + wxSizerItem* Insert(size_t index, wxWindow* window, + const wxSizerFlags& flags); /** - Set the proportion item attribute. + Insert a child into the sizer before any existing item at @a index. + + See Add() for the meaning of the other parameters. */ - void SetProportion(int proportion); + wxSizerItem* Insert(size_t index, wxWindow* window, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); - //@{ /** - Set the ratio item attribute. + Insert a child into the sizer before any existing item at @a index. + + See Add() for the meaning of the other parameters. */ - void SetRatio(int width, int height); - void SetRatio(wxSize size); - void SetRatio(float ratio); - //@} + wxSizerItem* Insert(size_t index, wxSizer* sizer, + const wxSizerFlags& flags); /** - Set the sizer tracked by this item. + Insert a child into the sizer before any existing item at @a index. + + See Add() for the meaning of the other parameters. */ - void SetSizer(wxSizer* sizer); + wxSizerItem* Insert(size_t index, wxSizer* sizer, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - Set the size of the spacer tracked by this item. + Insert a child into the sizer before any existing item at @a index. + + See Add() for the meaning of the other parameters. */ - void SetSpacer(const wxSize& size); + wxSizerItem* Insert(size_t index, int width, int height, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - Set the window to be tracked by thsi item. + Inserts non-stretchable space to the sizer. + More readable way of calling wxSizer::Insert(index, size, size). */ - void SetWindow(wxWindow* window); + wxSizerItem* InsertSpacer(size_t index, int size); /** - Set the show item attribute, which sizers use to determine if the item - is to be made part of the layout or not. If the item is tracking a - window then it is shown or hidden as needed. + Inserts stretchable space to the sizer. + More readable way of calling wxSizer::Insert(0, 0, prop). */ - void Show(bool show); -}; + wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1); + /** + Return @true if the sizer has no elements. + @see GetItemCount() + */ + bool IsEmpty() const; -/** - @class wxSizerFlags + /** + Returns @true if the @a window is shown. - Container for sizer items flags providing readable names for them. + @see Hide(), Show(), wxSizerItem::IsShown() + */ + bool IsShown(wxWindow* window) const; - Normally, when you add an item to a sizer via wxSizer::Add, you have to - specify a lot of flags and parameters which can be unwieldy. This is where - wxSizerFlags comes in: it allows you to specify all parameters using the - named methods instead. For example, instead of + /** + Returns @true if the @a sizer is shown. - @code - sizer->Add(ctrl, 0, wxEXPAND | wxALL, 10); - @endcode + @see Hide(), Show(), wxSizerItem::IsShown() + */ + bool IsShown(wxSizer* sizer) const; - you can now write + /** + Returns @true if the item at @a index is shown. - @code - sizer->Add(ctrl, wxSizerFlags().Expand().Border(wxALL, 10)); - @endcode + @see Hide(), Show(), wxSizerItem::IsShown() + */ + bool IsShown(size_t index) const; - This is more readable and also allows you to create wxSizerFlags objects which - can be reused for several sizer items. + /** + Call this to force layout of the children anew, e.g. after having added a child + to or removed a child (window, other sizer or space) from the sizer while + keeping the current dimension. + */ + virtual void Layout(); - @code - wxSizerFlags flagsExpand(1); - flagsExpand.Expand().Border(wxALL, 10); - - sizer->Add(ctrl1, flagsExpand); - sizer->Add(ctrl2, flagsExpand); - @endcode - - Note that by specification, all methods of wxSizerFlags return the wxSizerFlags - object itself to allowing chaining multiple methods calls like in the examples - above. - - @library{wxcore} - @category{winlayout} - - @see wxSizer -*/ -class wxSizerFlags -{ -public: /** - Creates the wxSizer with the proportion specified by @e proportion. + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. */ - wxSizerFlags(int proportion = 0); + wxSizerItem* Prepend(wxWindow* window, const wxSizerFlags& flags); /** - Sets the alignment of this wxSizerFlags to @e align. - - This method replaces the previously set alignment with the specified - one. - - @see Top(), Left(), Right(), Bottom(), Centre() - - @param align Combination of @c wxALIGN_XXX bit masks. + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. */ - wxSizerFlags& Align(int align = 0); + wxSizerItem* Prepend(wxWindow* window, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - Sets the wxSizerFlags to have a border of a number of pixels specified - by @a borderinpixels with the directions specified by @e direction. + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. */ - wxSizerFlags& Border(int direction, int borderinpixels); + wxSizerItem* Prepend(wxSizer* sizer, + const wxSizerFlags& flags); /** - Sets the wxSizerFlags to have a border with size as returned by - GetDefaultBorder(). - - @param direction Direction(s) to apply the border in. + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. */ - wxSizerFlags& Border(int direction = wxALL); + wxSizerItem* Prepend(wxSizer* sizer, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - Aligns the object to the bottom, similar for @c Align(wxALIGN_BOTTOM). - - Unlike Align(), this method doesn't change the horizontal alignment of - the item. + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. */ - wxSizerFlags& Bottom(); + wxSizerItem* Prepend(int width, int height, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - Sets the object of the wxSizerFlags to center itself in the area it is - given. + Prepends non-stretchable space to the sizer. + More readable way of calling wxSizer::Prepend(size, size, 0). */ - wxSizerFlags& Center(); + wxSizerItem* PrependSpacer(int size); /** - Center() for people with the other dialect of English. + Prepends stretchable space to the sizer. + More readable way of calling wxSizer::Prepend(0, 0, prop). */ - wxSizerFlags& Centre(); + wxSizerItem* PrependStretchSpacer(int prop = 1); /** - Sets the border in the given @a direction having twice the default - border size. + This method is abstract and has to be overwritten by any derived class. + Here, the sizer will do the actual calculation of its children's + positions and sizes. */ - wxSizerFlags& DoubleBorder(int direction = wxALL); + virtual void RecalcSizes() = 0; /** - Sets the border in left and right directions having twice the default - border size. + Removes a child window from the sizer, but does @b not destroy it + (because windows are owned by their parent window, not the sizer). + + @deprecated + The overload of this method taking a wxWindow* parameter + is deprecated as it does not destroy the window as would usually be + expected from Remove(). You should use Detach() in new code instead. + There is currently no wxSizer method that will both detach and destroy + a wxWindow item. + + @note This method does not cause any layout or resizing to take + place, call Layout() to update the layout "on screen" after + removing a child from the sizer. + + @return @true if the child item was found and removed, @false otherwise. */ - wxSizerFlags& DoubleHorzBorder(); + virtual bool Remove(wxWindow* window); /** - Sets the object of the wxSizerFlags to expand to fill as much area as - it can. + Removes a sizer child from the sizer and destroys it. + + @note This method does not cause any layout or resizing to take + place, call Layout() to update the layout "on screen" after + removing a child from the sizer. + + @param sizer The wxSizer to be removed. + + @return @true if the child item was found and removed, @false otherwise. */ - wxSizerFlags& Expand(); + virtual bool Remove(wxSizer* sizer); /** - Set the @c wxFIXED_MINSIZE flag which indicates that the initial size - of the window should be also set as its minimal size. + Removes a child from the sizer and destroys it if it is a sizer or a + spacer, but not if it is a window (because windows are owned by their + parent window, not the sizer). + + @note This method does not cause any layout or resizing to take + place, call Layout() to update the layout "on screen" after + removing a child from the sizer. + + @param index + The position of the child in the sizer, e.g. 0 for the first item. + + @return @true if the child item was found and removed, @false otherwise. */ - wxSizerFlags& FixedMinSize(); + virtual bool Remove(int index); /** - Set the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag. Normally wxSizers - don't allocate space for hidden windows or other items. This flag - overrides this behavior so that sufficient space is allocated for the - window even if it isn't visible. This makes it possible to dynamically - show and hide controls without resizing parent dialog, for example. + Detaches the given @a oldwin from the sizer and replaces it with the + given @a newwin. The detached child window is @b not deleted (because + windows are owned by their parent window, not the sizer). - @since 2.8.8 + Use parameter @a recursive to search the given element recursively in subsizers. + + This method does not cause any layout or resizing to take place, + call Layout() to update the layout "on screen" after replacing a + child from the sizer. + + Returns @true if the child item was found and removed, @false otherwise. */ - wxSizerFlags& ReserveSpaceEvenIfHidden(); + virtual bool Replace(wxWindow* oldwin, wxWindow* newwin, + bool recursive = false); /** - Returns the border used by default in Border() method. + Detaches the given @a oldsz from the sizer and replaces it with the + given @a newsz. The detached child sizer is deleted. + + Use parameter @a recursive to search the given element recursively in subsizers. + + This method does not cause any layout or resizing to take place, + call Layout() to update the layout "on screen" after replacing a + child from the sizer. + + Returns @true if the child item was found and removed, @false otherwise. */ - static int GetDefaultBorder(); + virtual bool Replace(wxSizer* oldsz, wxSizer* newsz, + bool recursive = false); /** - Aligns the object to the left, similar for @c Align(wxALIGN_LEFT). + Detaches the given item at position @a index from the sizer and + replaces it with the given wxSizerItem @a newitem. - Unlike Align(), this method doesn't change the vertical alignment of - the item. + The detached child is deleted @b only if it is a sizer or a spacer + (but not if it is a wxWindow because windows are owned by their + parent window, not the sizer). + + This method does not cause any layout or resizing to take place, + call Layout() to update the layout "on screen" after replacing a + child from the sizer. + + Returns @true if the child item was found and removed, @false otherwise. */ - wxSizerFlags& Left(); + virtual bool Replace(size_t index, wxSizerItem* newitem); /** - Sets the proportion of this wxSizerFlags to @e proportion + Call this to force the sizer to take the given dimension and thus force + the items owned by the sizer to resize themselves according to the + rules defined by the parameter in the Add() and Prepend() methods. */ - wxSizerFlags& Proportion(int proportion = 0); + void SetDimension(int x, int y, int width, int height); /** - Aligns the object to the right, similar for @c Align(wxALIGN_RIGHT). + @overload + */ + void SetDimension(const wxPoint& pos, const wxSize& size); - Unlike Align(), this method doesn't change the vertical alignment of - the item. + /** + Set an item's minimum size by window, sizer, or position. + + 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. */ - wxSizerFlags& Right(); + //@{ + bool SetItemMinSize(wxWindow* window, int width, int height); + bool SetItemMinSize(wxWindow* window, const wxSize& size); + + bool SetItemMinSize(wxSizer* sizer, int width, int height); + bool SetItemMinSize(wxSizer* sizer, const wxSize& size); + + bool SetItemMinSize(size_t index, int width, int height); + bool SetItemMinSize(size_t index, const wxSize& size); + //@} /** - Set the @c wx_SHAPED flag which indicates that the elements should - always keep the fixed width to height ratio equal to its original value. + Call this to give the sizer a minimal size. + + Normally, the sizer will calculate its minimal size based purely on how + much space its children need. After calling this method GetMinSize() + will return either the minimal size as requested by its children or the + minimal size set here, depending on which is bigger. */ - wxSizerFlags& Shaped(); + void SetMinSize(const wxSize& size); /** - Aligns the object to the top, similar for @c Align(wxALIGN_TOP). + @overload + */ + void SetMinSize(int width, int height); - Unlike Align(), this method doesn't change the horizontal alignment of - the item. + /** + This method first calls Fit() and then wxTopLevelWindow::SetSizeHints() + on the @a window passed to it. + + This only makes sense when @a window is actually a wxTopLevelWindow such + as a wxFrame or a wxDialog, since SetSizeHints only has any effect in these classes. + It does nothing in normal windows or controls. + + This method is implicitly used by wxWindow::SetSizerAndFit() which is + commonly invoked in the constructor of a toplevel window itself (see + the sample in the description of wxBoxSizer) if the toplevel window is + resizable. */ - wxSizerFlags& Top(); + void SetSizeHints(wxWindow* window); /** - Sets the border in the given @a direction having thrice the default - border size. - */ - wxSizerFlags& TripleBorder(int direction = wxALL); -}; + Tell the sizer to set the minimal size of the @a window virtual area to match + the sizer's minimal size. For windows with managed scrollbars this will set them + appropriately. + @deprecated This is exactly the same as FitInside() in wxWidgets 2.9 + and later, please replace calls to it with FitInside(). + @see wxScrolled::SetScrollbars() + */ + void SetVirtualSizeHints(wxWindow* window); -/** - @class wxNotebookSizer + /** + Shows or hides the @a window. + To make a sizer item disappear or reappear, use Show() followed by Layout(). - @deprecated - This class is deprecated and should not be used in new code! It is no - longer needed, wxNotebook control can be inserted - into any sizer class and its minimal size will be determined correctly. + Use parameter @a recursive to show or hide elements found in subsizers. - wxNotebookSizer is a specialized sizer to make sizers work in connection - with using notebooks. This sizer is different from any other sizer as you - must not add any children to it - instead, it queries the notebook class - itself. The only thing this sizer does is to determine the size of the - biggest page of the notebook and report an adjusted minimal size to a more - toplevel sizer. + Returns @true if the child item was found, @false otherwise. - @library{wxbase} - @category{winlayout} + @see Hide(), IsShown() + */ + bool Show(wxWindow* window, bool show = true, + bool recursive = false); - @see wxSizer, wxNotebook, - @ref overview_sizer "Sizers overview" -*/ -class wxNotebookSizer : public wxSizer -{ -public: /** - Constructor. It takes an associated notebook as its only parameter. + Shows or hides @a sizer. + To make a sizer item disappear or reappear, use Show() followed by Layout(). + + Use parameter @a recursive to show or hide elements found in subsizers. + + Returns @true if the child item was found, @false otherwise. + + @see Hide(), IsShown() */ - wxNotebookSizer(wxNotebook* notebook); + bool Show(wxSizer* sizer, bool show = true, + bool recursive = false); /** - Returns the notebook associated with the sizer. + Shows the item at @a index. + To make a sizer item disappear or reappear, use Show() followed by Layout(). + + Returns @true if the child item was found, @false otherwise. + + @see Hide(), IsShown() */ - wxNotebook* GetNotebook(); + bool Show(size_t index, bool show = true); }; - /** - @class wxFlexGridSizer + @class wxStdDialogButtonSizer - A flex grid sizer is a sizer which lays out its children in a two-dimensional - table with all table fields in one row having the same - height and all fields in one column having the same width, but all - rows or all columns are not necessarily the same height or width as in - the wxGridSizer. + This class creates button layouts which conform to the standard button spacing + and ordering defined by the platform or toolkit's user interface guidelines + (if such things exist). By using this class, you can ensure that all your + standard dialogs look correct on all major platforms. Currently it conforms to + the Windows, GTK+ and Mac OS X human interface guidelines. - Since wxWidgets 2.5.0, wxFlexGridSizer can also size items equally in one - direction but unequally ("flexibly") in the other. If the sizer is only - flexible in one direction (this can be changed using - wxFlexGridSizer::SetFlexibleDirection), - it needs to be decided how the sizer should grow in the other ("non-flexible") - direction in order to fill the available space. The - wxFlexGridSizer::SetNonFlexibleGrowMode method - serves this purpose. + When there aren't interface guidelines defined for a particular platform or + toolkit, wxStdDialogButtonSizer reverts to the Windows implementation. + + To use this class, first add buttons to the sizer by calling + wxStdDialogButtonSizer::AddButton (or wxStdDialogButtonSizer::SetAffirmativeButton, + wxStdDialogButtonSizer::SetNegativeButton or wxStdDialogButtonSizer::SetCancelButton) + and then call Realize in order to create the actual button layout used. + Other than these special operations, this sizer works like any other sizer. + + If you add a button with wxID_SAVE, on Mac OS X the button will be renamed to + "Save" and the wxID_NO button will be renamed to "Don't Save" in accordance + with the Mac OS X Human Interface Guidelines. @library{wxcore} @category{winlayout} - @see wxSizer, @ref overview_sizer "Sizer Overview" + @see wxSizer, @ref overview_sizer, wxDialog::CreateButtonSizer */ -class wxFlexGridSizer : public wxGridSizer +class wxStdDialogButtonSizer : public wxBoxSizer { public: - //@{ /** - Constructor for a wxGridSizer. @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. @a vgap and @a hgap define extra space between - all children. + Constructor for a wxStdDialogButtonSizer. */ - wxFlexGridSizer(int rows, int cols, int vgap, int hgap); - wxFlexGridSizer(int cols, int vgap = 0, int hgap = 0); - //@} + wxStdDialogButtonSizer(); /** - Specifies that column @a idx (starting from zero) should be grown if - there is extra space available to the sizer. - The @a proportion parameter has the same meaning as the stretch factor for - the sizers() except that if all proportions are 0, - then all columns are resized equally (instead of not being resized at all). - */ - void AddGrowableCol(size_t idx, int proportion = 0); - - /** - Specifies that row idx (starting from zero) should be grown if there - is extra space available to the sizer. - See AddGrowableCol() for the description - of @a proportion parameter. + Adds a button to the wxStdDialogButtonSizer. The @a button must have + one of the following identifiers: + - wxID_OK + - wxID_YES + - wxID_SAVE + - wxID_APPLY + - wxID_CLOSE + - wxID_NO + - wxID_CANCEL + - wxID_HELP + - wxID_CONTEXT_HELP */ - void AddGrowableRow(size_t idx, int proportion = 0); + void AddButton(wxButton* button); /** - Returns a wxOrientation value that specifies whether the sizer flexibly - resizes its columns, rows, or both (default). - - @return One of the following values: - - @see SetFlexibleDirection() + Rearranges the buttons and applies proper spacing between buttons to make + them match the platform or toolkit's interface guidelines. */ - int GetFlexibleDirection() const; + void Realize(); /** - Returns the value that specifies how the sizer grows in the "non-flexible" - direction if there is one. + Sets the affirmative button for the sizer. - @return One of the following values: - - @see SetFlexibleDirection(), - SetNonFlexibleGrowMode() + This allows you to use identifiers other than the standard identifiers + outlined above. */ - int GetNonFlexibleGrowMode() const; + void SetAffirmativeButton(wxButton* button); /** - Specifies that column idx is no longer growable. - */ - void RemoveGrowableCol(size_t idx); + Sets the cancel button for the sizer. - /** - Specifies that row idx is no longer growable. + This allows you to use identifiers other than the standard identifiers + outlined above. */ - void RemoveGrowableRow(size_t idx); + void SetCancelButton(wxButton* button); /** - Specifies whether the sizer should flexibly resize its columns, rows, or - both. Argument @c direction can be @c wxVERTICAL, @c wxHORIZONTAL - or @c wxBOTH (which is the default value). Any other value is ignored. See - @ref GetFlexibleDirection() GetFlexibleDirection for the - explanation of these values. - Note that this method does not trigger relayout. - */ - void SetFlexibleDirection(int direction); + Sets the negative button for the sizer. - /** - Specifies how the sizer should grow in the non-flexible direction if - there is one (so - SetFlexibleDirection() must have - been called previously). Argument @a mode can be one of those documented in - GetNonFlexibleGrowMode(), please - see there for their explanation. - Note that this method does not trigger relayout. + This allows you to use identifiers other than the standard identifiers + outlined above. */ - void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode); + void SetNegativeButton(wxButton* button); }; /** - @class wxSizer - - wxSizer is the abstract base class used for laying out subwindows in a window. - You - cannot use wxSizer directly; instead, you will have to use one of the sizer - classes derived from it. Currently there are wxBoxSizer, - wxStaticBoxSizer, - wxGridSizer, - wxFlexGridSizer, - wxWrapSizer - and wxGridBagSizer. - - The layout algorithm used by sizers in wxWidgets is closely related to layout - in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. - It is - based upon the idea of the individual subwindows reporting their minimal - required - size and their ability to get stretched if the size of the parent window has - changed. - This will most often mean that the programmer does not set the original size of - a dialog in the beginning, rather the dialog will be assigned a sizer and this - sizer - will be queried about the recommended size. The sizer in turn will query its - children, which can be normal windows, empty space or other sizers, so that - a hierarchy of sizers can be constructed. Note that wxSizer does not derive - from wxWindow - and thus does not interfere with tab ordering and requires very little - resources compared - to a real window on screen. - - What makes sizers so well fitted for use in wxWidgets is the fact that every - control - reports its own minimal size and the algorithm can handle differences in font - sizes - or different window (dialog item) sizes on different platforms without - problems. If e.g. - the standard font as well as the overall design of Motif widgets requires more - space than - on Windows, the initial dialog size will automatically be bigger on Motif than - on Windows. - - Sizers may also be used to control the layout of custom drawn items on the - window. The Add(), Insert(), and Prepend() functions return a pointer to - the newly added wxSizerItem. Just add empty space of the desired size and - attributes, and then use the wxSizerItem::GetRect() method to determine - where the drawing operations should take place. - - Please notice that sizers, like child windows, are owned by the library and - will be deleted by it which implies that they must be allocated on the - heap. However if you create a sizer and do not add it to another sizer or - window, the library wouldn't be able to delete such an orphan sizer and in - this, and only this, case it should be deleted explicitly. - - @b wxPython note: If you wish to create a sizer class in wxPython you should - derive the class from @c wxPySizer in order to get Python-aware - capabilities for the various virtual methods. + @class wxSizerItem - @anchor wxsizer_flags - @par wxSizer flags - The "flag" argument accepted by wxSizeItem constructors and other - functions, e.g. wxSizer::Add(), is OR-combination of the following flags. - Two main behaviours are defined using these flags. One is the border around - a window: the border parameter determines the border width whereas the - flags given here determine which side(s) of the item that the border will - be added. The other flags determine how the sizer item behaves when the - space allotted to the sizer changes, and is somewhat dependent on the - specific kind of sizer used. - @beginDefList - @itemdef{wxTOP
- wxBOTTOM
- wxLEFT
- wxRIGHT
- wxALL, - These flags are used to specify which side(s) of the sizer item - the border width will apply to.} - @itemdef{wxEXPAND, - The item will be expanded to fill the space assigned to the item.} - @itemdef{wxSHAPED, - The item will be expanded as much as possible while also - maintaining its aspect ratio.} - @itemdef{wxFIXED_MINSIZE, - Normally wxSizers will use GetAdjustedBestSize() to determine what - the minimal size of window items should be, and will use that size - to calculate the layout. This allows layouts to adjust when an - item changes and its best size becomes different. If you would - rather have a window item stay the size it started with then use - wxFIXED_MINSIZE.} - @itemdef{wxRESERVE_SPACE_EVEN_IF_HIDDEN, - Normally wxSizers don't allocate space for hidden windows or other - items. This flag overrides this behavior so that sufficient space - is allocated for the window even if it isn't visible. This makes - it possible to dynamically show and hide controls without resizing - parent dialog, for example. (Available since 2.8.8.) - } - @itemdef{wxALIGN_CENTER
- wxALIGN_CENTRE
- wxALIGN_LEFT
- wxALIGN_RIGHT
- wxALIGN_TOP
- wxALIGN_BOTTOM
- wxALIGN_CENTER_VERTICAL
- wxALIGN_CENTRE_VERTICAL
- wxALIGN_CENTER_HORIZONTAL
- wxALIGN_CENTRE_HORIZONTAL, - The wxALIGN flags allow you to specify the alignment of the item - within the space allotted to it by the sizer, adjusted for the - border if any.} - @endDefList + The wxSizerItem class is used to track the position, size and other + attributes of each item managed by a wxSizer. + It is not usually necessary to use this class because the sizer elements can + also be identified by their positions or window or sizer pointers but sometimes + it may be more convenient to use it directly. @library{wxcore} @category{winlayout} - - @see @ref overview_sizer "Sizer Overview" */ -class wxSizer : public wxObject +class wxSizerItem : public wxObject { public: /** - The constructor. Note that wxSizer is an abstract base class and may not - be instantiated. + Construct a sizer item for tracking a spacer. */ - wxSizer(); + wxSizerItem(int width, int height, int proportion, int flag, + int border, wxObject* userData); + //@{ /** - The destructor. + Construct a sizer item for tracking a window. */ - ~wxSizer(); + wxSizerItem(wxWindow* window, const wxSizerFlags& flags); + wxSizerItem(wxWindow* window, int proportion, int flag, + int border, + wxObject* userData); + //@} + //@{ /** - Appends a child to the sizer. + Construct a sizer item for tracking a subsizer. + */ + wxSizerItem(wxSizer* window, const wxSizerFlags& flags); + wxSizerItem(wxSizer* sizer, int proportion, int flag, + int border, + wxObject* userData); + //@} - wxSizer itself is an abstract class, but the parameters are equivalent - in the derived classes that you will instantiate to use it so they are - described here: + /** + Deletes the user data and subsizer, if any. + */ + virtual ~wxSizerItem(); - @param window - The window to be added to the sizer. Its initial size (either set - explicitly by the user or calculated internally when using - wxDefaultSize) is interpreted as the minimal and in many cases also - the initial size. - @param flags - A wxSizerFlags object that enables you to specify most of the above - parameters more conveniently. + /** + Set the window to be tracked by this item. + + The old window isn't deleted as it is now owned by the sizer item. */ - wxSizerItem* Add(wxWindow* window, const wxSizerFlags& flags); + void AssignWindow(wxWindow *window); /** - Appends a child to the sizer. + Set the sizer tracked by this item. - wxSizer itself is an abstract class, but the parameters are equivalent - in the derived classes that you will instantiate to use it so they are - described here: + Old sizer, if any, is deleted. + */ + void AssignSizer(wxSizer *sizer); - @param window - The window to be added to the sizer. Its initial size (either set - explicitly by the user or calculated internally when using - wxDefaultSize) is interpreted as the minimal and in many cases also - the initial size. - @param proportion - Although the meaning of this parameter is undefined in wxSizer, it - is used in wxBoxSizer to indicate if a child of a sizer can change - its size in the main orientation of the wxBoxSizer - where 0 stands - for not changeable and a value of more than zero is interpreted - relative to the value of other children of the same wxBoxSizer. For - example, you might have a horizontal wxBoxSizer with three - children, two of which are supposed to change their size with the - sizer. Then the two stretchable windows would get a value of 1 each - to make them grow and shrink equally with the sizer's horizontal - dimension. - @param flag - OR-combination of flags affecting sizer's behavior. See - @ref wxsizer_flags "wxSizer flags list" for details. - @param border - Determines the border width, if the flag parameter is set to - include any border flag. - @param userData - Allows an extra object to be attached to the sizer item, for use in - derived classes when sizing information is more complex than the - proportion and flag will allow for. + //@{ + /** + Set the size of the spacer tracked by this item. + + Old spacer, if any, is deleted. */ - wxSizerItem* Add(wxWindow* window, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + void AssignSpacer(const wxSize& size); + void AssignSpacer(int w, int h) { AssignSpacer(wxSize(w, h)); } + //@} /** - Appends a child to the sizer. + Calculates the minimum desired size for the item, including any space + needed by borders. + */ + virtual wxSize CalcMin(); - wxSizer itself is an abstract class, but the parameters are equivalent - in the derived classes that you will instantiate to use it so they are - described here: + /** + Destroy the window or the windows in a subsizer, depending on the type + of item. + */ + virtual void DeleteWindows(); - @param sizer - The (child-)sizer to be added to the sizer. This allows placing a - child sizer in a sizer and thus to create hierarchies of sizers - (typically a vertical box as the top sizer and several horizontal - boxes on the level beneath). - @param flags - A wxSizerFlags object that enables you to specify most of the above - parameters more conveniently. + /** + Enable deleting the SizerItem without destroying the contained sizer. */ - wxSizerItem* Add(wxSizer* sizer, const wxSizerFlags& flags); + void DetachSizer(); /** - Appends a child to the sizer. + Return the border attribute. + */ + int GetBorder() const; - wxSizer itself is an abstract class, but the parameters are equivalent - in the derived classes that you will instantiate to use it so they are - described here: + /** + Return the flags attribute. - @param sizer - The (child-)sizer to be added to the sizer. This allows placing a - child sizer in a sizer and thus to create hierarchies of sizers - (typically a vertical box as the top sizer and several horizontal - boxes on the level beneath). - @param proportion - Although the meaning of this parameter is undefined in wxSizer, it - is used in wxBoxSizer to indicate if a child of a sizer can change - its size in the main orientation of the wxBoxSizer - where 0 stands - for not changeable and a value of more than zero is interpreted - relative to the value of other children of the same wxBoxSizer. For - example, you might have a horizontal wxBoxSizer with three - children, two of which are supposed to change their size with the - sizer. Then the two stretchable windows would get a value of 1 each - to make them grow and shrink equally with the sizer's horizontal - dimension. - @param flag - OR-combination of flags affecting sizer's behavior. See - @ref wxsizer_flags "wxSizer flags list" for details. - @param border - Determines the border width, if the flag parameter is set to - include any border flag. - @param userData - Allows an extra object to be attached to the sizer item, for use in - derived classes when sizing information is more complex than the - proportion and flag will allow for. + See @ref wxsizer_flags "wxSizer flags list" for details. */ - wxSizerItem* Add(wxSizer* sizer, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + int GetFlag() const; /** - Appends a spacer child to the sizer. + Return the numeric id of wxSizerItem, or @c wxID_NONE if the id has + not been set. + */ + int GetId() const; - wxSizer itself is an abstract class, but the parameters are equivalent - in the derived classes that you will instantiate to use it so they are - described here. + /** + Get the minimum size needed for the item. + */ + wxSize GetMinSize() const; - @a width and @a height specify the dimension of a spacer to be added to - the sizer. Adding spacers to sizers gives more flexibility in the - design of dialogs; imagine for example a horizontal box with two - buttons at the bottom of a dialog: you might want to insert a space - between the two buttons and make that space stretchable using the - proportion flag and the result will be that the left button will be - aligned with the left side of the dialog and the right button with the - right side - the space in between will shrink and grow with the dialog. + /** + Sets the minimum size to be allocated for this item. - @param width - Width of the spacer. - @param height - Height of the spacer. - @param proportion - Although the meaning of this parameter is undefined in wxSizer, it - is used in wxBoxSizer to indicate if a child of a sizer can change - its size in the main orientation of the wxBoxSizer - where 0 stands - for not changeable and a value of more than zero is interpreted - relative to the value of other children of the same wxBoxSizer. For - example, you might have a horizontal wxBoxSizer with three - children, two of which are supposed to change their size with the - sizer. Then the two stretchable windows would get a value of 1 each - to make them grow and shrink equally with the sizer's horizontal - dimension. - @param flag - OR-combination of flags affecting sizer's behavior. See - @ref wxsizer_flags "wxSizer flags list" for details. - @param border - Determines the border width, if the flag parameter is set to - include any border flag. - @param userData - Allows an extra object to be attached to the sizer item, for use in - derived classes when sizing information is more complex than the - proportion and flag will allow for. + If this item is a window, the @a size is also passed to + wxWindow::SetMinSize(). + */ + void SetMinSize(const wxSize& size); + + /** + @overload + */ + void SetMinSize(int x, int y); + + /** + What is the current position of the item, as set in the last Layout. */ - wxSizerItem* Add(int width, int height, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + wxPoint GetPosition() const; + + /** + Get the proportion item attribute. + */ + int GetProportion() const; + + /** + Get the ration item attribute. + */ + float GetRatio() const; + + /** + Get the rectangle of the item on the parent window, excluding borders. + */ + virtual wxRect GetRect(); /** - Adds non-stretchable space to the sizer. More readable way of calling - wxSizer::Add(size, size, 0). + Get the current size of the item, as set in the last Layout. */ - wxSizerItem* AddSpacer(int size); + virtual wxSize GetSize() const; /** - Adds stretchable space to the sizer. More readable way of calling - wxSizer::Add(0, 0, prop). + If this item is tracking a sizer, return it. @NULL otherwise. */ - wxSizerItem* AddStretchSpacer(int prop = 1); + wxSizer* GetSizer() const; /** - This method is abstract and has to be overwritten by any derived class. - Here, the sizer will do the actual calculation of its children's minimal sizes. + If this item is tracking a spacer, return its size. */ - wxSize CalcMin(); + wxSize GetSpacer() const; /** - Detaches all children from the sizer. If @a delete_windows is @true then - child windows will also be deleted. + Get the userData item attribute. */ - void Clear(bool delete_windows = false); + wxObject* GetUserData() const; /** - Computes client area size for @a window so that it matches the sizer's - minimal size. Unlike GetMinSize(), this method accounts for other - constraints imposed on @e window, namely display's size (returned size - will never be too large for the display) and maximum window size if - previously set by wxWindow::SetMaxSize(). The returned value is - suitable for passing to wxWindow::SetClientSize() or - wxWindow::SetMinClientSize(). - - @since 2.8.8 - - @see ComputeFittingWindowSize(), Fit() + If this item is tracking a window then return it. @NULL otherwise. */ - wxSize ComputeFittingClientSize(wxWindow* window); + wxWindow* GetWindow() const; /** - Like ComputeFittingClientSize(), but converts the result into window - size. The returned value is suitable for passing to wxWindow::SetSize() - or wxWindow::SetMinSize(). + Returns @true if this item is a window or a spacer and it is shown or + if this item is a sizer and not all of its elements are hidden. - @since 2.8.8 + In other words, for sizer items, all of the child elements must be + hidden for the sizer itself to be considered hidden. - @see ComputeFittingClientSize(), Fit() + As an exception, if the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag was + used for this sizer item, then IsShown() always returns @true for it + (see wxSizerFlags::ReserveSpaceEvenIfHidden()). */ - wxSize ComputeFittingWindowSize(wxWindow* window); + bool IsShown() const; /** - Detach the child @a window from the sizer without destroying it. - - This method does not cause any layout or resizing to take place, call Layout() - to update the layout "on screen" after detaching a child from the sizer. - - Returns @true if the child item was found and detached, @false otherwise. - - @see Remove() + Is this item a sizer? */ - bool Detach(wxWindow* window); + bool IsSizer() const; /** - Detach the child @a sizer from the sizer without destroying it. - - This method does not cause any layout or resizing to take place, call Layout() - to update the layout "on screen" after detaching a child from the sizer. - - Returns @true if the child item was found and detached, @false otherwise. - - @see Remove() + Is this item a spacer? */ - bool Detach(wxSizer* sizer); + bool IsSpacer() const; /** - Detach a item at position @a index from the sizer without destroying it. - - This method does not cause any layout or resizing to take place, call Layout() - to update the layout "on screen" after detaching a child from the sizer. - Returns @true if the child item was found and detached, @false otherwise. - - @see Remove() + Is this item a window? */ - bool Detach(size_t index); + bool IsWindow() const; /** - Tell the sizer to resize the @a window so that its client area matches the - sizer's minimal size - (ComputeFittingClientSize() is called - to determine it). - This is commonly done in the constructor of the window - itself, see sample in the description - of wxBoxSizer. Returns the new window size. - - @see ComputeFittingClientSize(), ComputeFittingWindowSize() + Set the border item attribute. */ - wxSize Fit(wxWindow* window); + void SetBorder(int border); /** - Tell the sizer to resize the virtual size of the @a window to match the sizer's - minimal size. This will not alter the on screen size of the window, but may - cause the addition/removal/alteration of scrollbars required to view the virtual - area in windows which manage it. - - @see wxScrolled::SetScrollbars(), SetVirtualSizeHints() + Set the position and size of the space allocated to the sizer, and + adjust the position and size of the item to be within that space + taking alignment and borders into account. */ - void FitInside(wxWindow* window); + virtual void SetDimension(const wxPoint& pos, const wxSize& size); /** - Returns the list of the items in this sizer. The elements of type-safe - wxList @a wxSizerItemList are pointers to objects of type - @ref wxSizerItem "wxSizerItem". - */ - wxSizerItemList& GetChildren(); - - /** - Returns the list of the items in this sizer. The elements of type-safe - wxList @a wxSizerItemList are pointers to objects of type - @ref wxSizerItem "wxSizerItem". + Set the flag item attribute. */ - const wxSizerItemList& GetChildren() const; + void SetFlag(int flag); /** - Returns the window this sizer is used in or @NULL if none. + Sets the numeric id of the wxSizerItem to @e id. */ - wxWindow* GetContainingWindow() const; + void SetId(int id); /** - Finds wxSizerItem which holds the given @a window - Use parameter @a recursive to search in subsizers too. - Returns pointer to item or @NULL. + @todo docme. */ - wxSizerItem* GetItem(wxWindow* window, bool recursive = false); - + void SetInitSize(int x, int y); + /** - Finds wxSizerItem which holds the given @a sizer - Use parameter @a recursive to search in subsizers too. - Returns pointer to item or @NULL. + Set the proportion item attribute. */ - - wxSizerItem* GetItem(wxSizer* sizer, bool recursive = false); + void SetProportion(int proportion); + + //@{ /** - Finds wxSizerItem which is located in the sizer at position - @a index. - Use parameter @a recursive to search in subsizers too. - Returns pointer to item or @NULL. + Set the ratio item attribute. */ - wxSizerItem* GetItem(size_t index); + void SetRatio(int width, int height); + void SetRatio(wxSize size); + void SetRatio(float ratio); + //@} /** - Finds item of the sizer which has the given @e id. This @a id is not the - window id but the id of the wxSizerItem itself. This is mainly useful for - retrieving the sizers created from XRC resources. - Use parameter @a recursive to search in subsizers too. - Returns pointer to item or @NULL. + Set the sizer tracked by this item. + + @deprecated This function does not free the old sizer which may result + in memory leaks, use AssignSizer() which does free it instead. */ - wxSizerItem* GetItemById(int id, bool recursive = false); + void SetSizer(wxSizer* sizer); /** - Returns the minimal size of the sizer. This is either the combined minimal - size of all the children and their borders or the minimal size set by - SetMinSize(), depending on which is bigger. - Note that the returned value is client size, not window size. - In particular, if you use the value to set toplevel window's minimal or - actual size, use wxWindow::SetMinClientSize - or wxWindow::SetClientSize, not - wxWindow::SetMinSize - or wxWindow::SetSize. + Set the size of the spacer tracked by this item. + + @deprecated This function does not free the old spacer which may result + in memory leaks, use AssignSpacer() which does free it instead. */ - wxSize GetMinSize(); + void SetSpacer(const wxSize& size); /** - Returns the current position of the sizer. + Set the window to be tracked by this item. + @deprecated @todo provide deprecation description */ - wxPoint GetPosition(); + void SetWindow(wxWindow* window); /** - Returns the current size of the sizer. + Set the show item attribute, which sizers use to determine if the item + is to be made part of the layout or not. If the item is tracking a + window then it is shown or hidden as needed. */ - wxSize GetSize(); + void Show(bool show); +}; - /** - Hides the child @a window. - - To make a sizer item disappear, use Hide() followed by Layout(). - - Use parameter @a recursive to hide elements found in subsizers. - Returns @true if the child item was found, @false otherwise. - @see IsShown(), Show() - */ - bool Hide(wxWindow* window, bool recursive = false); - /** - Hides the child @a sizer. - - To make a sizer item disappear, use Hide() followed by Layout(). - - Use parameter @a recursive to hide elements found in subsizers. - Returns @true if the child item was found, @false otherwise. +/** + @class wxSizerFlags - @see IsShown(), Show() - */ - bool Hide(wxSizer* sizer, bool recursive = false); + Container for sizer items flags providing readable names for them. - /** - Hides the item at position @a index. - - To make a sizer item disappear, use Hide() followed by Layout(). - - Use parameter @a recursive to hide elements found in subsizers. - Returns @true if the child item was found, @false otherwise. + Normally, when you add an item to a sizer via wxSizer::Add, you have to + specify a lot of flags and parameters which can be unwieldy. This is where + wxSizerFlags comes in: it allows you to specify all parameters using the + named methods instead. For example, instead of - @see IsShown(), Show() - */ - bool Hide(size_t index); + @code + sizer->Add(ctrl, 0, wxEXPAND | wxALL, 10); + @endcode - /** - Insert a child into the sizer before any existing item at @a index. + you can now write - See Add() for the meaning of the other parameters. + @code + sizer->Add(ctrl, wxSizerFlags().Expand().Border(wxALL, 10)); + @endcode + + This is more readable and also allows you to create wxSizerFlags objects which + can be reused for several sizer items. + + @code + wxSizerFlags flagsExpand(1); + flagsExpand.Expand().Border(wxALL, 10); + + sizer->Add(ctrl1, flagsExpand); + sizer->Add(ctrl2, flagsExpand); + @endcode + + Note that by specification, all methods of wxSizerFlags return the wxSizerFlags + object itself to allowing chaining multiple methods calls like in the examples + above. + + @library{wxcore} + @category{winlayout} + + @see wxSizer +*/ +class wxSizerFlags +{ +public: + /** + Creates the wxSizer with the proportion specified by @a proportion. */ - wxSizerItem* Insert(size_t index, wxWindow* window, - const wxSizerFlags& flags); + wxSizerFlags(int proportion = 0); /** - Insert a child into the sizer before any existing item at @a index. + Sets the alignment of this wxSizerFlags to @a align. - See Add() for the meaning of the other parameters. + This method replaces the previously set alignment with the specified one. + + @param alignment + Combination of @c wxALIGN_XXX bit masks. + + @see Top(), Left(), Right(), Bottom(), Centre() */ - wxSizerItem* Insert(size_t index, wxWindow* window, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + wxSizerFlags& Align(int alignment); /** - Insert a child into the sizer before any existing item at @a index. - - See Add() for the meaning of the other parameters. + Sets the wxSizerFlags to have a border of a number of pixels specified + by @a borderinpixels with the directions specified by @a direction. */ - wxSizerItem* Insert(size_t index, wxSizer* sizer, - const wxSizerFlags& flags); + wxSizerFlags& Border(int direction, int borderinpixels); /** - Insert a child into the sizer before any existing item at @a index. + Sets the wxSizerFlags to have a border with size as returned by + GetDefaultBorder(). - See Add() for the meaning of the other parameters. + @param direction + Direction(s) to apply the border in. */ - wxSizerItem* Insert(size_t index, wxSizer* sizer, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + wxSizerFlags& Border(int direction = wxALL); /** - Insert a child into the sizer before any existing item at @a index. + Aligns the object to the bottom, similar for @c Align(wxALIGN_BOTTOM). - See Add() for the meaning of the other parameters. + Unlike Align(), this method doesn't change the horizontal alignment of + the item. */ - wxSizerItem* Insert(size_t index, int width, int height, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + wxSizerFlags& Bottom(); /** - Inserts non-stretchable space to the sizer. More readable way of calling - wxSizer::Insert(size, size, 0). + Sets the object of the wxSizerFlags to center itself in the area it is + given. */ - wxSizerItem* InsertSpacer(size_t index, int size); + wxSizerFlags& Center(); /** - Inserts stretchable space to the sizer. More readable way of calling - wxSizer::Insert(0, 0, prop). + Center() for people with the other dialect of English. */ - wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1); + wxSizerFlags& Centre(); /** - Returns @true if the @e window is shown. - - @see Hide(), Show(), wxSizerItem::IsShown() + Sets the border in the given @a direction having twice the default + border size. */ - bool IsShown(wxWindow* window) const; + wxSizerFlags& DoubleBorder(int direction = wxALL); /** - Returns @true if the @e sizer is shown. - - @see Hide(), Show(), wxSizerItem::IsShown() + Sets the border in left and right directions having twice the default + border size. */ - bool IsShown(wxSizer* sizer) const; + wxSizerFlags& DoubleHorzBorder(); /** - Returns @true if the item at @a index is shown. - - @see Hide(), Show(), wxSizerItem::IsShown() + Sets the object of the wxSizerFlags to expand to fill as much area as + it can. */ - bool IsShown(size_t index) const; + wxSizerFlags& Expand(); /** - Call this to force layout of the children anew, e.g. after having added a child - to or removed a child (window, other sizer or space) from the sizer while - keeping - the current dimension. + Set the @c wxFIXED_MINSIZE flag which indicates that the initial size + of the window should be also set as its minimal size. */ - void Layout(); + wxSizerFlags& FixedMinSize(); /** - Same as Add(), but prepends the items to the beginning of the - list of items (windows, subsizers or spaces) owned by this sizer. + Set the @c wxRESERVE_SPACE_EVEN_IF_HIDDEN flag. Normally wxSizers + don't allocate space for hidden windows or other items. This flag + overrides this behaviour so that sufficient space is allocated for the + window even if it isn't visible. This makes it possible to dynamically + show and hide controls without resizing parent dialog, for example. + + @since 2.8.8 */ - wxSizerItem* Prepend(wxWindow* window, const wxSizerFlags& flags); + wxSizerFlags& ReserveSpaceEvenIfHidden(); /** - Same as Add(), but prepends the items to the beginning of the - list of items (windows, subsizers or spaces) owned by this sizer. + Returns the border used by default in Border() method. */ - wxSizerItem* Prepend(wxWindow* window, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + static int GetDefaultBorder(); /** - Same as Add(), but prepends the items to the beginning of the - list of items (windows, subsizers or spaces) owned by this sizer. + Aligns the object to the left, similar for @c Align(wxALIGN_LEFT). + + Unlike Align(), this method doesn't change the vertical alignment of + the item. */ - wxSizerItem* Prepend(wxSizer* sizer, - const wxSizerFlags& flags); + wxSizerFlags& Left(); /** - Same as Add(), but prepends the items to the beginning of the - list of items (windows, subsizers or spaces) owned by this sizer. + Sets the proportion of this wxSizerFlags to @e proportion */ - wxSizerItem* Prepend(wxSizer* sizer, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + wxSizerFlags& Proportion(int proportion); /** - Same as Add(), but prepends the items to the beginning of the - list of items (windows, subsizers or spaces) owned by this sizer. + Aligns the object to the right, similar for @c Align(wxALIGN_RIGHT). + + Unlike Align(), this method doesn't change the vertical alignment of + the item. */ - wxSizerItem* Prepend(int width, int height, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + wxSizerFlags& Right(); /** - Prepends non-stretchable space to the sizer. More readable way of - calling wxSizer::Prepend(size, size, 0). + Set the @c wx_SHAPED flag which indicates that the elements should + always keep the fixed width to height ratio equal to its original value. */ - wxSizerItem* PrependSpacer(int size); + wxSizerFlags& Shaped(); /** - Prepends stretchable space to the sizer. More readable way of calling - wxSizer::Prepend(0, 0, prop). + Aligns the object to the top, similar for @c Align(wxALIGN_TOP). + + Unlike Align(), this method doesn't change the horizontal alignment of + the item. */ - wxSizerItem* PrependStretchSpacer(int prop = 1); + wxSizerFlags& Top(); /** - This method is abstract and has to be overwritten by any derived class. - Here, the sizer will do the actual calculation of its children's - positions and sizes. + Sets the border in the given @a direction having thrice the default + border size. */ - void RecalcSizes(); + wxSizerFlags& TripleBorder(int direction = wxALL); +}; - /** - Removes a child window from the sizer, but does @b not destroy it - (because windows are owned by their parent window, not the sizer). - @deprecated - The overload of this method taking a wxWindow* parameter - is deprecated as it does not destroy the window as would usually be - expected from Remove(). You should use Detach() in new code instead. - There is currently no wxSizer method that will both detach and destroy - a wxWindow item. +/** + Values which define the behaviour for resizing wxFlexGridSizer cells in the + "non-flexible" direction. +*/ +enum wxFlexSizerGrowMode +{ + /// Don't resize the cells in non-flexible direction at all. + wxFLEX_GROWMODE_NONE, - @note This method does not cause any layout or resizing to take - place, call Layout() to update the layout "on screen" after - removing a child from the sizer. + /// Uniformly resize only the specified ones (default). + wxFLEX_GROWMODE_SPECIFIED, - @return @true if the child item was found and removed, @false otherwise. - */ - bool Remove(wxWindow* window); + /// Uniformly resize all cells. + wxFLEX_GROWMODE_ALL +}; - /** - Removes a sizer child from the sizer and destroys it. +/** + @class wxFlexGridSizer - @note This method does not cause any layout or resizing to take - place, call Layout() to update the layout "on screen" after - removing a child from the sizer. + A flex grid sizer is a sizer which lays out its children in a two-dimensional + table with all table fields in one row having the same height and all fields + in one column having the same width, but all rows or all columns are not + necessarily the same height or width as in the wxGridSizer. - @param sizer The wxSizer to be removed. + Since wxWidgets 2.5.0, wxFlexGridSizer can also size items equally in one + direction but unequally ("flexibly") in the other. If the sizer is only + flexible in one direction (this can be changed using wxFlexGridSizer::SetFlexibleDirection), + it needs to be decided how the sizer should grow in the other ("non-flexible") + direction in order to fill the available space. + The wxFlexGridSizer::SetNonFlexibleGrowMode() method serves this purpose. - @return @true if the child item was found and removed, @false otherwise. - */ - bool Remove(wxSizer* sizer); + @library{wxcore} + @category{winlayout} + @see wxSizer, @ref overview_sizer +*/ +class wxFlexGridSizer : public wxGridSizer +{ +public: + //@{ /** - Removes a child from the sizer and destroys it if it is a sizer or a - spacer, but not if it is a window (because windows are owned by their - parent window, not the sizer). - - @note This method does not cause any layout or resizing to take - place, call Layout() to update the layout "on screen" after - removing a child from the sizer. + wxFlexGridSizer constructors. - @param index The position of the child in the sizer, e.g. 0 for the - first item. + Please see wxGridSizer::wxGridSizer documentation. - @return @true if the child item was found and removed, @false otherwise. + @since 2.9.1 (except for the four argument overload) */ - bool Remove(size_t index); + wxFlexGridSizer( int cols, int vgap, int hgap ); + wxFlexGridSizer( int cols, const wxSize& gap = wxSize(0, 0) ); - /** - Detaches the given @a oldwin from the sizer and - replaces it with the given @a newwin. The detached - child window is @b not deleted (because windows are - owned by their parent window, not the sizer). - - Use parameter @a recursive to search the given element recursively in subsizers. + wxFlexGridSizer( int rows, int cols, int vgap, int hgap ); + wxFlexGridSizer( int rows, int cols, const wxSize& gap ); + //@} - This method does not cause any layout or resizing to take place, - call Layout() to update the layout "on screen" after replacing a - child from the sizer. - - Returns @true if the child item was found and removed, @false otherwise. - */ - bool Replace(wxWindow* oldwin, wxWindow* newwin, - bool recursive = false); - /** - Detaches the given @a oldsz from the sizer and - replaces it with the given @a newsz. The detached - child sizer is deleted. - - Use parameter @a recursive to search the given element recursively in subsizers. + Specifies that column @a idx (starting from zero) should be grown if + there is extra space available to the sizer. - This method does not cause any layout or resizing to take place, - call Layout() to update the layout "on screen" after replacing a - child from the sizer. - - Returns @true if the child item was found and removed, @false otherwise. - */ - bool Replace(wxSizer* oldsz, wxSizer* newsz, - bool recursive = false); - - /** - Detaches the given item at position @a index from the sizer and - replaces it with the given wxSizerItem @a newitem. - - The detached child is deleted @b only if it is a sizer or a spacer - (but not if it is a wxWindow because windows are owned by their - parent window, not the sizer). - - This method does not cause any layout or resizing to take place, - call Layout() to update the layout "on screen" after replacing a - child from the sizer. - - Returns @true if the child item was found and removed, @false otherwise. - */ - bool Replace(size_t index, wxSizerItem* newitem); + The @a proportion parameter has the same meaning as the stretch factor + for the sizers (see wxBoxSizer) except that if all proportions are 0, + then all columns are resized equally (instead of not being resized at all). - /** - Call this to force the sizer to take the given dimension and thus force - the items owned by the sizer to resize themselves according to the - rules defined by the parameter in the Add() and Prepend() methods. + Notice that the column must not be already growable, if you need to change + the proportion you must call RemoveGrowableCol() first and then make it + growable (with a different proportion) again. You can use IsColGrowable() + to check whether a column is already growable. */ - void SetDimension(int x, int y, int width, int height); - - /** - @overload - */ - void SetDimension(const wxPoint& pos, const wxSize& size); + void AddGrowableCol(size_t idx, int proportion = 0); /** - 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. + Specifies that row idx (starting from zero) should be grown if there + is extra space available to the sizer. - @see wxSizerItem::SetMinSize() + This is identical to AddGrowableCol() except that it works with rows + and not columns. */ - void SetItemMinSize(wxWindow* window, int width, int height); + void AddGrowableRow(size_t idx, int proportion = 0); /** - Set an item's minimum size by window, sizer, or position. + Returns a ::wxOrientation value that specifies whether the sizer flexibly + resizes its columns, rows, or both (default). - 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. + @return + One of the following values: + - wxVERTICAL: Rows are flexibly sized. + - wxHORIZONTAL: Columns are flexibly sized. + - wxBOTH: Both rows and columns are flexibly sized (this is the default value). - @see wxSizerItem::SetMinSize() + @see SetFlexibleDirection() */ - void SetItemMinSize(wxSizer* sizer, int width, int height); + int GetFlexibleDirection() const; /** - Set an item's minimum size by window, sizer, or position. + Returns the value that specifies how the sizer grows in the "non-flexible" + direction if there is one. - 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 behaviour of the elements in the flexible direction (i.e. both rows + and columns by default, or rows only if GetFlexibleDirection() is + @c wxVERTICAL or columns only if it is @c wxHORIZONTAL) is always governed + by their proportion as specified in the call to AddGrowableRow() or + AddGrowableCol(). What happens in the other direction depends on the + value of returned by this function as described below. - @see wxSizerItem::SetMinSize() - */ - void SetItemMinSize(size_t index, int width, int height); + @return + One of the following values: + - wxFLEX_GROWMODE_NONE: Sizer doesn't grow its elements at all in + the non-flexible direction. + - wxFLEX_GROWMODE_SPECIFIED: Sizer honors growable columns/rows set + with AddGrowableCol() and AddGrowableRow() in the non-flexible + direction as well. In this case equal sizing applies to minimum + sizes of columns or rows (this is the default value). + - wxFLEX_GROWMODE_ALL: Sizer equally stretches all columns or rows in + the non-flexible direction, independently of the proportions + applied in the flexible direction. - /** - Call this to give the sizer a minimal size. Normally, the sizer will - calculate its minimal size based purely on how much space its children - need. After calling this method GetMinSize() will return either the - minimal size as requested by its children or the minimal size set here, - depending on which is bigger. + @see SetFlexibleDirection(), SetNonFlexibleGrowMode() */ - void SetMinSize(const wxSize& size); + wxFlexSizerGrowMode GetNonFlexibleGrowMode() const; /** - @overload - */ - void SetMinSize(int width, int height); + Returns @true if column @a idx is growable. - /** - This method first calls Fit() and then - wxTopLevelWindow::SetSizeHints on the @e window - passed to it. This only makes sense when @a window is actually a - wxTopLevelWindow such as a wxFrame or a - wxDialog, since SetSizeHints only has any effect in these classes. - It does nothing in normal windows or controls. - This method is implicitly used by wxWindow::SetSizerAndFit - which is commonly invoked in the constructor of a toplevel window itself (see - the sample in the description of wxBoxSizer) if the - toplevel window is resizable. + @since 2.9.0 */ - void SetSizeHints(wxWindow* window); + bool IsColGrowable(size_t idx); /** - Tell the sizer to set the minimal size of the @a window virtual area to match - the sizer's - minimal size. For windows with managed scrollbars this will set them - appropriately. + Returns @true if row @a idx is growable. - @see wxScrolled::SetScrollbars() + @since 2.9.0 */ - void SetVirtualSizeHints(wxWindow* window); + bool IsRowGrowable(size_t idx); /** - Shows or hides the @a window. - To make a sizer item disappear or reappear, use Show() followed by Layout(). - - Use parameter @a recursive to show or hide elements found in subsizers. - - Returns @true if the child item was found, @false otherwise. + Specifies that the @a idx column index is no longer growable. + */ + void RemoveGrowableCol(size_t idx); - @see Hide(), IsShown() + /** + Specifies that the @a idx row index is no longer growable. */ - bool Show(wxWindow* window, bool show = true, - bool recursive = false); + void RemoveGrowableRow(size_t idx); /** - Shows or hides @a sizer. - To make a sizer item disappear or reappear, use Show() followed by Layout(). - - Use parameter @a recursive to show or hide elements found in subsizers. - - Returns @true if the child item was found, @false otherwise. + Specifies whether the sizer should flexibly resize its columns, rows, or both. - @see Hide(), IsShown() + Argument @a direction can be @c wxVERTICAL, @c wxHORIZONTAL or @c wxBOTH + (which is the default value). Any other value is ignored. + + See GetFlexibleDirection() for the explanation of these values. + Note that this method does not trigger relayout. */ - bool Show(wxSizer* sizer, bool show = true, - bool recursive = false); + void SetFlexibleDirection(int direction); /** - Shows the item at @a index. - To make a sizer item disappear or reappear, use Show() followed by Layout(). - - Returns @true if the child item was found, @false otherwise. + Specifies how the sizer should grow in the non-flexible direction if + there is one (so SetFlexibleDirection() must have been called previously). - @see Hide(), IsShown() + Argument @a mode can be one of those documented in GetNonFlexibleGrowMode(), + please see there for their explanation. + Note that this method does not trigger relayout. */ - bool Show(size_t index, bool show = true); + void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode); }; - /** @class wxGridSizer A grid sizer is a sizer which lays out its children in a two-dimensional - table with all table fields having the same size, - i.e. the width of each field is the width of the widest child, - the height of each field is the height of the tallest child. + table with all table fields having the same size, i.e. the width of each + field is the width of the widest child, the height of each field is the + height of the tallest child. @library{wxcore} @category{winlayout} - @see wxSizer, @ref overview_sizer "Sizer Overview" + @see wxSizer, @ref overview_sizer */ class wxGridSizer : public wxSizer { public: //@{ /** - Constructor for a wxGridSizer. @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. @a vgap and @a hgap define extra space between - all children. + wxGridSizer constructors. + + 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. + + 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 GetCols(); + 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 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 GetHGap(); + int GetEffectiveRowsCount() const; /** - Returns the number of rows in the sizer. + Returns the horizontal gap (in pixels) between cells in the sizer. */ - int GetRows(); + int GetHGap() const; /** Returns the vertical gap (in pixels) between the cells in the sizer. */ - int GetVGap(); + int GetVGap() const; /** Sets the number of columns in the sizer. @@ -1591,37 +1710,59 @@ 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} - @see wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizer - "Sizer Overview" + @see wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizer */ class wxStaticBoxSizer : public wxBoxSizer { public: - //@{ /** - The first constructor uses an already existing static box. It takes the - associated static box and the orientation @e orient, which can be either - @c wxVERTICAL or @c wxHORIZONTAL as parameters. - The second one creates a new static box with the given label and parent window. + This constructor uses an already existing static box. + + @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); - wxStaticBoxSizer(int orient, wxWindow parent, + + /** + This constructor creates a new static box with the given label and parent window. + */ + wxStaticBoxSizer(int orient, wxWindow *parent, const wxString& label = wxEmptyString); - //@} /** Returns the static box associated with the sizer. */ - wxStaticBox* GetStaticBox(); + wxStaticBox* GetStaticBox() const; }; @@ -1630,17 +1771,15 @@ public: @class wxBoxSizer The basic idea behind a box sizer is that windows will most often be laid out - in rather - simple basic geometry, typically in a row or a column or several hierarchies of - either. + in rather simple basic geometry, typically in a row or a column or several + hierarchies of either. - For more information, please see @ref overview_sizer_box - "Programming with wxBoxSizer". + For more information, please see @ref overview_sizer_box. @library{wxcore} @category{winlayout} - @see wxSizer, @ref overview_sizer "Sizers Overview" + @see wxSizer, @ref overview_sizer */ class wxBoxSizer : public wxSizer { @@ -1652,22 +1791,41 @@ public: wxBoxSizer(int orient); /** - Implements the calculation of a box sizer's minimal. It is used internally - only and must not be called by the user. Documented for information. + 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. + + It is used internally only and must not be called by the user. + Documented for information. */ - wxSize CalcMin(); + virtual wxSize CalcMin(); /** Returns the orientation of the box sizer, either wxVERTICAL or wxHORIZONTAL. */ - int GetOrientation(); + int GetOrientation() const; /** Implements the calculation of a box sizer's dimensions and then sets - the size of its children (calling wxWindow::SetSize - if the child is a window). It is used internally only and must not be called - by the user (call Layout() if you want to resize). Documented for information. + the size of its children (calling wxWindow::SetSize if the child is a window). + + It is used internally only and must not be called by the user + (call Layout() if you want to resize). Documented for information. */ void RecalcSizes(); };