X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6e1f851b1760803b32c3d1d61bcc76feace46f9d..a8bda512079352ba81933e278d9ccdb8ef7a9866:/interface/wx/sizer.h?ds=inline diff --git a/interface/wx/sizer.h b/interface/wx/sizer.h index 86269f643f..719d4d2c4a 100644 --- a/interface/wx/sizer.h +++ b/interface/wx/sizer.h @@ -3,1567 +3,1586 @@ // Purpose: interface of wxStdDialogButtonSizer // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** - A generic orientation value. -*/ -enum wxOrientation -{ - /* don't change the values of these elements, they are used elsewhere */ - wxHORIZONTAL = 0x0004, - wxVERTICAL = 0x0008, + @class wxSizer - wxBOTH = wxVERTICAL | wxHORIZONTAL, + 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. - /* a mask to extract orientation from the combination of flags */ - wxORIENTATION_MASK = wxBOTH -}; + 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. -/** - @class wxStdDialogButtonSizer + 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. - 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. + 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. - When there aren't interface guidelines defined for a particular platform or - toolkit, wxStdDialogButtonSizer reverts to the Windows implementation. + 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. - 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. + @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 - 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. + @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<br> + wxBOTTOM<br> + wxLEFT<br> + wxRIGHT<br> + 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 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<br> + wxALIGN_CENTRE<br> + wxALIGN_LEFT<br> + wxALIGN_RIGHT<br> + wxALIGN_TOP<br> + wxALIGN_BOTTOM<br> + wxALIGN_CENTER_VERTICAL<br> + wxALIGN_CENTRE_VERTICAL<br> + wxALIGN_CENTER_HORIZONTAL<br> + 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, 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. - */ - void Realize(); + Appends a child to the sizer. - /** - Sets the affirmative button for 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: - This allows you to use identifiers other than the standard identifiers - outlined above. + @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 SetAffirmativeButton(wxButton* button); + wxSizerItem* Add(wxWindow* window, const wxSizerFlags& flags); /** - Sets the cancel button for the sizer. - - This allows you to use identifiers other than the standard identifiers - outlined above. - */ - void SetCancelButton(wxButton* button); + Appends a child to the sizer. - /** - Sets the negative button for 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: - This allows you to use identifiers other than the standard identifiers - outlined above. + @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. */ - void SetNegativeButton(wxButton* button); -}; - - - -/** - @class wxSizerItem - - 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. + wxSizerItem* Add(wxWindow* window, + 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 spacer. - */ - wxSizerItem(int width, int height, int proportion, int flag, - int border, wxObject* userData); + Appends a child to the sizer. - //@{ - /** - Construct a sizer item for tracking a window. - */ - wxSizerItem(wxWindow* window, const wxSizerFlags& flags); - wxSizerItem(wxWindow* window, 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: - //@{ - /** - Construct a sizer item for tracking a subsizer. + @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. */ - wxSizerItem(wxSizer* window, const wxSizerFlags& flags); - wxSizerItem(wxSizer* sizer, int proportion, int flag, - int border, - wxObject* userData); - //@} + wxSizerItem* Add(wxSizer* sizer, const wxSizerFlags& flags); /** - Deletes the user data and subsizer, if any. - */ - virtual ~wxSizerItem(); + 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. + @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. */ - virtual void DeleteWindows(); + wxSizerItem* Add(wxSizer* sizer, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - Enable deleting the SizerItem without destroying the contained sizer. + 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. + + @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. + + @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. */ - void DetachSizer(); + wxSizerItem* Add(int width, int height, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - Return the border attribute. + 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() */ - int GetBorder() const; + virtual wxSizerItem *AddSpacer(int size); /** - Return the flags attribute. - - See @ref wxsizer_flags "wxSizer flags list" for details. + Adds stretchable space to the sizer. + More readable way of calling: + @code + wxSizer::Add(0, 0, prop). + @endcode */ - int GetFlag() const; + wxSizerItem* AddStretchSpacer(int prop = 1); /** - Return the numeric id of wxSizerItem, or @c wxID_NONE if the id has - not been set. + 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. */ - int GetId() const; + virtual wxSize CalcMin() = 0; /** - Get the minimum size needed for the item. + Detaches all children from the sizer. + If @a delete_windows is @true then child windows will also be deleted. */ - wxSize GetMinSize() const; + virtual void Clear(bool delete_windows = false); /** - Sets the minimum size to be allocated for this item. + 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(). - If this item is a window, the @a size is also passed to - wxWindow::SetMinSize(). - */ - void SetMinSize(const wxSize& size); + The returned value is suitable for passing to wxWindow::SetClientSize() or + wxWindow::SetMinClientSize(). - /** - @overload - */ - void SetMinSize(int x, int y); + @since 2.8.8 - /** - What is the current position of the item, as set in the last Layout. + @see ComputeFittingWindowSize(), Fit() */ - wxPoint GetPosition() const; + wxSize ComputeFittingClientSize(wxWindow* window); /** - Get the proportion item attribute. - */ - int GetProportion() 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 ration item attribute. - */ - float GetRatio() const; + @since 2.8.8 - /** - Get the rectangle of the item on the parent window, excluding borders. + @see ComputeFittingClientSize(), Fit() */ - virtual wxRect GetRect(); + wxSize ComputeFittingWindowSize(wxWindow* window); /** - Get the current size of the item, as set in the last Layout. - */ - virtual wxSize GetSize() const; + Detach the child @a window from the sizer without destroying it. - /** - If this item is tracking a sizer, return it. @NULL otherwise. - */ - wxSizer* GetSizer() const; + 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. - /** - If this item is tracking a spacer, return its size. - */ - wxSize GetSpacer() const; + Returns @true if the child item was found and detached, @false otherwise. - /** - Get the userData item attribute. + @see Remove() */ - wxObject* GetUserData() const; + virtual bool Detach(wxWindow* window); /** - If this item is tracking a window then return it. @NULL otherwise. - */ - wxWindow* GetWindow() const; + Detach the child @a sizer from the sizer without destroying it. - /** - 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. + 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. - In other words, for sizer items, all of the child elements must be - hidden for the sizer itself to be considered hidden. + Returns @true if the child item was found and detached, @false otherwise. - 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()). + @see Remove() */ - bool IsShown() const; + virtual bool Detach(wxSizer* sizer); /** - Is this item a sizer? + 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() */ - bool IsSizer() const; + virtual bool Detach(int index); /** - Is this item a spacer? + 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() */ - bool IsSpacer() const; + wxSize Fit(wxWindow* window); /** - Is this item a window? + 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() */ - bool IsWindow() const; + void FitInside(wxWindow* window); + //@{ /** - Set the border item attribute. + Returns the list of the items in this sizer. + + The elements of type-safe wxList @c wxSizerItemList are pointers to + objects of type wxSizerItem. */ - void SetBorder(int border); + wxSizerItemList& GetChildren(); + const wxSizerItemList& GetChildren() 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. + Returns the window this sizer is used in or @NULL if none. */ - virtual void SetDimension(const wxPoint& pos, const wxSize& size); + wxWindow* GetContainingWindow() const; /** - Set the flag 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. */ - void SetFlag(int flag); + size_t GetItemCount() const; /** - Sets the numeric id of the wxSizerItem to @e id. + Finds wxSizerItem which holds the given @a window. + Use parameter @a recursive to search in subsizers too. + Returns pointer to item or @NULL. */ - void SetId(int id); + wxSizerItem* GetItem(wxWindow* window, bool recursive = false); /** - @todo docme. + Finds wxSizerItem which holds the given @a sizer. + Use parameter @a recursive to search in subsizers too. + Returns pointer to item or @NULL. */ - void SetInitSize(int x, int y); - /** - Set the proportion item attribute. - */ - void SetProportion(int proportion); + wxSizerItem* GetItem(wxSizer* sizer, bool recursive = false); - //@{ /** - Set the ratio item attribute. + 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. */ - void SetRatio(int width, int height); - void SetRatio(wxSize size); - void SetRatio(float ratio); - //@} + wxSizerItem* GetItem(size_t index); /** - Set the sizer tracked by this item. - @deprecated @todo provide deprecation description + 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. */ - void SetSizer(wxSizer* sizer); + wxSizerItem* GetItemById(int id, bool recursive = false); /** - Set the size of the spacer tracked by this item. - @deprecated @todo provide deprecation description + 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(). */ - void SetSpacer(const wxSize& size); + wxSize GetMinSize(); /** - Set the window to be tracked by this item. - @deprecated @todo provide deprecation description + Returns the current position of the sizer. */ - void SetWindow(wxWindow* window); + wxPoint GetPosition() const; /** - 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. + Returns the current size of the sizer. */ - void Show(bool show); -}; - - + wxSize GetSize() const; -/** - @class wxSizerFlags + /** + Hides the child @a window. - Container for sizer items flags providing readable names for them. + To make a sizer item disappear, use Hide() followed by Layout(). - 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 + Use parameter @a recursive to hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. - @code - sizer->Add(ctrl, 0, wxEXPAND | wxALL, 10); - @endcode + @see IsShown(), Show() + */ + bool Hide(wxWindow* window, bool recursive = false); - you can now write + /** + Hides the child @a sizer. - @code - sizer->Add(ctrl, wxSizerFlags().Expand().Border(wxALL, 10)); - @endcode + To make a sizer item disappear, use Hide() followed by Layout(). - This is more readable and also allows you to create wxSizerFlags objects which - can be reused for several sizer items. + Use parameter @a recursive to hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. - @code - wxSizerFlags flagsExpand(1); - flagsExpand.Expand().Border(wxALL, 10); + @see IsShown(), Show() + */ + bool Hide(wxSizer* sizer, bool recursive = false); - sizer->Add(ctrl1, flagsExpand); - sizer->Add(ctrl2, flagsExpand); - @endcode + /** + Hides the item at position @a index. - Note that by specification, all methods of wxSizerFlags return the wxSizerFlags - object itself to allowing chaining multiple methods calls like in the examples - above. + To make a sizer item disappear, use Hide() followed by Layout(). - @library{wxcore} - @category{winlayout} + Use parameter @a recursive to hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. - @see wxSizer -*/ -class wxSizerFlags -{ -public: - /** - Creates the wxSizer with the proportion specified by @a proportion. + @see IsShown(), Show() */ - wxSizerFlags(int proportion = 0); + bool Hide(size_t index); /** - Sets the alignment of this wxSizerFlags to @a align. - - This method replaces the previously set alignment with the specified one. - - @param alignment - Combination of @c wxALIGN_XXX bit masks. + Insert a child into the sizer before any existing item at @a index. - @see Top(), Left(), Right(), Bottom(), Centre() + See Add() for the meaning of the other parameters. */ - wxSizerFlags& Align(int alignment); + wxSizerItem* Insert(size_t index, wxWindow* window, + const wxSizerFlags& flags); /** - Sets the wxSizerFlags to have a border of a number of pixels specified - by @a borderinpixels with the directions specified by @a direction. + Insert a child into the sizer before any existing item at @a index. + + See Add() for the meaning of the other parameters. */ - wxSizerFlags& Border(int direction, int borderinpixels); + wxSizerItem* Insert(size_t index, wxWindow* window, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - Sets the wxSizerFlags to have a border with size as returned by - GetDefaultBorder(). + Insert a child into the sizer before any existing item at @a index. - @param direction - Direction(s) to apply the border in. + See Add() for the meaning of the other parameters. */ - wxSizerFlags& Border(int direction = wxALL); + wxSizerItem* Insert(size_t index, wxSizer* sizer, + const wxSizerFlags& flags); /** - Aligns the object to the bottom, similar for @c Align(wxALIGN_BOTTOM). + Insert a child into the sizer before any existing item at @a index. - Unlike Align(), this method doesn't change the horizontal alignment of - the item. + See Add() for the meaning of the other parameters. */ - wxSizerFlags& Bottom(); + wxSizerItem* Insert(size_t index, wxSizer* sizer, + 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. + Insert a child into the sizer before any existing item at @a index. + + See Add() for the meaning of the other parameters. */ - wxSizerFlags& Center(); + wxSizerItem* Insert(size_t index, int width, int height, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - Center() for people with the other dialect of English. + Inserts non-stretchable space to the sizer. + More readable way of calling wxSizer::Insert(index, size, size). */ - wxSizerFlags& Centre(); + wxSizerItem* InsertSpacer(size_t index, int size); /** - Sets the border in the given @a direction having twice the default - border size. + Inserts stretchable space to the sizer. + More readable way of calling wxSizer::Insert(0, 0, prop). */ - wxSizerFlags& DoubleBorder(int direction = wxALL); + wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1); /** - Sets the border in left and right directions having twice the default - border size. - */ - wxSizerFlags& DoubleHorzBorder(); + Return @true if the sizer has no elements. + + @see GetItemCount() + */ + bool IsEmpty() const; /** - Sets the object of the wxSizerFlags to expand to fill as much area as - it can. + Returns @true if the @a window is shown. + + @see Hide(), Show(), wxSizerItem::IsShown() */ - wxSizerFlags& Expand(); + bool IsShown(wxWindow* window) const; /** - Set the @c wxFIXED_MINSIZE flag which indicates that the initial size - of the window should be also set as its minimal size. + Returns @true if the @a sizer is shown. + + @see Hide(), Show(), wxSizerItem::IsShown() */ - wxSizerFlags& FixedMinSize(); + bool IsShown(wxSizer* sizer) const; /** - 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. + Returns @true if the item at @a index is shown. - @since 2.8.8 + @see Hide(), Show(), wxSizerItem::IsShown() */ - wxSizerFlags& ReserveSpaceEvenIfHidden(); + bool IsShown(size_t index) const; /** - Returns the border used by default in Border() method. + 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. */ - static int GetDefaultBorder(); + virtual void Layout(); /** - 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. + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. */ - wxSizerFlags& Left(); + wxSizerItem* Prepend(wxWindow* window, const wxSizerFlags& flags); /** - Sets the proportion of this wxSizerFlags to @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& Proportion(int proportion); + wxSizerItem* Prepend(wxWindow* window, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - 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. + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. */ - wxSizerFlags& Right(); + wxSizerItem* Prepend(wxSizer* sizer, + const wxSizerFlags& flags); /** - 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. + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. */ - wxSizerFlags& Shaped(); + wxSizerItem* Prepend(wxSizer* sizer, int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - 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. + Same as Add(), but prepends the items to the beginning of the + list of items (windows, subsizers or spaces) owned by this sizer. */ - wxSizerFlags& Top(); + wxSizerItem* Prepend(int width, int height, + int proportion = 0, + int flag = 0, + int border = 0, + wxObject* userData = NULL); /** - Sets the border in the given @a direction having thrice the default - border size. + Prepends non-stretchable space to the sizer. + More readable way of calling wxSizer::Prepend(size, size, 0). */ - wxSizerFlags& TripleBorder(int direction = wxALL); -}; + wxSizerItem* PrependSpacer(int size); + /** + Prepends stretchable space to the sizer. + More readable way of calling wxSizer::Prepend(0, 0, prop). + */ + wxSizerItem* PrependStretchSpacer(int prop = 1); + /** + 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. + */ + virtual void RecalcSizes() = 0; -/** - @class wxFlexGridSizer + /** + Removes a child window from the sizer, but does @b not destroy it + (because windows are owned by their parent window, not 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. + @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. - 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. + @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. - @library{wxcore} - @category{winlayout} + @return @true if the child item was found and removed, @false otherwise. + */ + virtual bool Remove(wxWindow* window); - @see wxSizer, @ref overview_sizer -*/ -class wxFlexGridSizer : public wxGridSizer -{ -public: - //@{ /** - Constructor for a wxFlexGridSizer. + 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. - @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. + @param sizer The wxSizer to be removed. - @a vgap and @a hgap define extra space between all children. + @return @true if the child item was found and removed, @false otherwise. */ - wxFlexGridSizer(int rows, int cols, int vgap, int hgap); - wxFlexGridSizer(int cols, int vgap = 0, int hgap = 0); - //@} + virtual bool Remove(wxSizer* sizer); /** - Specifies that column @a idx (starting from zero) should be grown if - there is extra space available to the sizer. + 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). - 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). + @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. - Notice that the row 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. + @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. */ - void AddGrowableCol(size_t idx, int proportion = 0); + virtual bool Remove(int index); /** - Specifies that row idx (starting from zero) should be grown if there - is extra space available to the sizer. + 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). - This is identical to AddGrowableCol() except that it works with rows - and not columns. + 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. */ - void AddGrowableRow(size_t idx, int proportion = 0); + virtual bool Replace(wxWindow* oldwin, wxWindow* newwin, + bool recursive = false); /** - Returns a wxOrientation value that specifies whether the sizer flexibly - resizes its columns, rows, or both (default). + Detaches the given @a oldsz from the sizer and replaces it with the + given @a newsz. The detached child sizer is deleted. - @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). + Use parameter @a recursive to search the given element recursively in subsizers. - @see SetFlexibleDirection() + 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. */ - int GetFlexibleDirection() const; + virtual bool Replace(wxSizer* oldsz, wxSizer* newsz, + bool recursive = false); /** - Returns the value that specifies how the sizer grows in the "non-flexible" - direction if there is one. + Detaches the given item at position @a index from the sizer and + replaces it with the given wxSizerItem @a newitem. - 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. + 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). - @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. + 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. - @see SetFlexibleDirection(), SetNonFlexibleGrowMode() + Returns @true if the child item was found and removed, @false otherwise. */ - wxFlexSizerGrowMode GetNonFlexibleGrowMode() const; + virtual bool Replace(size_t index, wxSizerItem* newitem); /** - Returns @true if column @a idx is growable. - - @since 2.9.0 + 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. */ - bool IsColGrowable(size_t idx); + void SetDimension(int x, int y, int width, int height); /** - Returns @true if row @a idx is growable. + @overload + */ + void SetDimension(const wxPoint& pos, const wxSize& size); - @since 2.9.0 + /** + 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. */ - bool IsRowGrowable(size_t idx); + //@{ + 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); + //@} /** - Specifies that column idx is no longer growable. + 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. */ - void RemoveGrowableCol(size_t idx); + void SetMinSize(const wxSize& size); /** - Specifies that row idx is no longer growable. - */ - void RemoveGrowableRow(size_t idx); + @overload + */ + void SetMinSize(int width, int height); /** - Specifies whether the sizer should flexibly resize its columns, rows, or both. + This method first calls Fit() and then wxTopLevelWindow::SetSizeHints() + on the @a window passed to it. - 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. + 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. */ - void SetFlexibleDirection(int direction); + void SetSizeHints(wxWindow* window); /** - Specifies how the sizer should grow in the non-flexible direction if - there is one (so SetFlexibleDirection() must have been called previously). + 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. - 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. + @deprecated @todo provide deprecation description + + @see wxScrolled::SetScrollbars() */ - void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode); -}; + void SetVirtualSizeHints(wxWindow* window); + /** + 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. -/** - @class wxSizer + Returns @true if the child item was found, @false otherwise. - 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. + @see Hide(), IsShown() + */ + bool Show(wxWindow* window, bool show = true, + bool recursive = false); - 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. + /** + Shows or hides @a sizer. + To make a sizer item disappear or reappear, use Show() followed by Layout(). - 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. + Use parameter @a recursive to show or hide elements found in subsizers. - 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 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 - - @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<br> - wxBOTTOM<br> - wxLEFT<br> - wxRIGHT<br> - 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<br> - wxALIGN_CENTRE<br> - wxALIGN_LEFT<br> - wxALIGN_RIGHT<br> - wxALIGN_TOP<br> - wxALIGN_BOTTOM<br> - wxALIGN_CENTER_VERTICAL<br> - wxALIGN_CENTRE_VERTICAL<br> - wxALIGN_CENTER_HORIZONTAL<br> - 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 - - @library{wxcore} - @category{winlayout} - - @see @ref overview_sizer -*/ -class wxSizer : public wxObject -{ -public: - /** - The constructor. - Note that wxSizer is an abstract base class and may not be instantiated. - */ - wxSizer(); - - /** - The destructor. - */ - virtual ~wxSizer(); - - /** - 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. - */ - wxSizerItem* Add(wxWindow* window, const wxSizerFlags& flags); - - /** - 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: + Returns @true if the child item was found, @false otherwise. - @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. + @see Hide(), IsShown() */ - wxSizerItem* Add(wxWindow* window, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + bool Show(wxSizer* sizer, bool show = true, + bool recursive = false); /** - Appends a child to the sizer. + Shows the item at @a index. + To make a sizer item disappear or reappear, use Show() followed by Layout(). - 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: + Returns @true if the child item was found, @false otherwise. - @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. + @see Hide(), IsShown() */ - wxSizerItem* Add(wxSizer* sizer, const wxSizerFlags& flags); - - /** - Appends a child to the sizer. + bool Show(size_t index, bool show = true); +}; - 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 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. - */ - wxSizerItem* Add(wxSizer* sizer, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); - - /** - Appends a spacer child to the sizer. +/** + @class wxStdDialogButtonSizer - 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. + 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. - @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. + When there aren't interface guidelines defined for a particular platform or + toolkit, wxStdDialogButtonSizer reverts to the Windows implementation. - @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. - */ - wxSizerItem* Add(int width, int height, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + 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. - /** - Adds non-stretchable space to the sizer. - More readable way of calling: - @code - wxSizer::Add(size, size, 0). - @endcode - */ - wxSizerItem* AddSpacer(int size); + 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. - /** - Adds stretchable space to the sizer. - More readable way of calling: - @code - wxSizer::Add(0, 0, prop). - @endcode - */ - wxSizerItem* AddStretchSpacer(int prop = 1); + @library{wxcore} + @category{winlayout} + @see wxSizer, @ref overview_sizer, wxDialog::CreateButtonSizer +*/ +class wxStdDialogButtonSizer : public wxBoxSizer +{ +public: /** - 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. + Constructor for a wxStdDialogButtonSizer. */ - virtual wxSize CalcMin() = 0; + wxStdDialogButtonSizer(); /** - Detaches all children from the sizer. - If @a delete_windows is @true then child windows will also be deleted. + 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 */ - virtual void Clear(bool delete_windows = false); + void AddButton(wxButton* button); /** - 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(). + Rearranges the buttons and applies proper spacing between buttons to make + them match the platform or toolkit's interface guidelines. + */ + void Realize(); - @since 2.8.8 + /** + Sets the affirmative button for the sizer. - @see ComputeFittingWindowSize(), Fit() + This allows you to use identifiers other than the standard identifiers + outlined above. */ - wxSize ComputeFittingClientSize(wxWindow* window); + void SetAffirmativeButton(wxButton* button); /** - Like ComputeFittingClientSize(), but converts the result into window - size. The returned value is suitable for passing to wxWindow::SetSize() - or wxWindow::SetMinSize(). - - @since 2.8.8 + Sets the cancel button for the sizer. - @see ComputeFittingClientSize(), Fit() + This allows you to use identifiers other than the standard identifiers + outlined above. */ - wxSize ComputeFittingWindowSize(wxWindow* window); + void SetCancelButton(wxButton* button); /** - Detach the child @a window from the sizer without destroying it. + Sets the negative button for the sizer. - 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. + This allows you to use identifiers other than the standard identifiers + outlined above. + */ + void SetNegativeButton(wxButton* button); +}; - Returns @true if the child item was found and detached, @false otherwise. - @see Remove() - */ - virtual bool Detach(wxWindow* window); - /** - Detach the child @a sizer from the sizer without destroying it. +/** + @class wxSizerItem - 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. + The wxSizerItem class is used to track the position, size and other + attributes of each item managed by a wxSizer. - Returns @true if the child item was found and detached, @false otherwise. + 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. - @see Remove() + @library{wxcore} + @category{winlayout} +*/ +class wxSizerItem : public wxObject +{ +public: + /** + Construct a sizer item for tracking a spacer. */ - virtual bool Detach(wxSizer* sizer); + wxSizerItem(int width, int height, int proportion, int flag, + int border, wxObject* userData); + //@{ /** - 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. + Construct a sizer item for tracking a window. + */ + wxSizerItem(wxWindow* window, const wxSizerFlags& flags); + wxSizerItem(wxWindow* window, int proportion, int flag, + int border, + wxObject* userData); + //@} - @see Remove() + //@{ + /** + Construct a sizer item for tracking a subsizer. */ - virtual bool Detach(int index); + wxSizerItem(wxSizer* window, const wxSizerFlags& flags); + wxSizerItem(wxSizer* sizer, int proportion, int flag, + int border, + wxObject* userData); + //@} /** - 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. + Deletes the user data and subsizer, if any. + */ + virtual ~wxSizerItem(); - @return The new window size. + /** + Set the window to be tracked by this item. - @see ComputeFittingClientSize(), ComputeFittingWindowSize() + The old window isn't deleted as it is now owned by the sizer item. */ - wxSize Fit(wxWindow* window); + void AssignWindow(wxWindow *window); /** - 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. + Set the sizer tracked by this item. - @see wxScrolled::SetScrollbars(), SetVirtualSizeHints() + Old sizer, if any, is deleted. */ - void FitInside(wxWindow* window); + void AssignSizer(wxSizer *sizer); //@{ /** - Returns the list of the items in this sizer. + Set the size of the spacer tracked by this item. - The elements of type-safe wxList @c wxSizerItemList are pointers to - objects of type wxSizerItem. + Old spacer, if any, is deleted. */ - wxSizerItemList& GetChildren(); - const wxSizerItemList& GetChildren() const; + void AssignSpacer(const wxSize& size); + void AssignSpacer(int w, int h) { AssignSpacer(wxSize(w, h)); } //@} /** - Returns the window this sizer is used in or @NULL if none. + Calculates the minimum desired size for the item, including any space + needed by borders. */ - wxWindow* GetContainingWindow() const; + virtual wxSize CalcMin(); /** - Returns the number of items in the sizer. + Destroy the window or the windows in a subsizer, depending on the type + of item. + */ + virtual void DeleteWindows(); - If you just need to test whether the sizer is empty or not you can also - use IsEmpty() function. + /** + Enable deleting the SizerItem without destroying the contained sizer. */ - size_t GetItemCount() const; + void DetachSizer(); /** - Finds wxSizerItem which holds the given @a window. - Use parameter @a recursive to search in subsizers too. - Returns pointer to item or @NULL. + Return the border attribute. */ - wxSizerItem* GetItem(wxWindow* window, bool recursive = false); + int GetBorder() const; /** - Finds wxSizerItem which holds the given @a sizer. - Use parameter @a recursive to search in subsizers too. - Returns pointer to item or @NULL. + Return the flags attribute. + + See @ref wxsizer_flags "wxSizer flags list" for details. */ + int GetFlag() const; - wxSizerItem* GetItem(wxSizer* sizer, bool recursive = false); + /** + Return the numeric id of wxSizerItem, or @c wxID_NONE if the id has + not been set. + */ + int GetId() const; /** - 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. + Get the minimum size needed for the item. */ - wxSizerItem* GetItem(size_t index); + wxSize GetMinSize() const; /** - 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. + Sets the minimum size to be allocated for this item. + + 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* GetItemById(int id, bool recursive = false); + wxPoint GetPosition() const; /** - Returns the minimal size of the sizer. + Get the proportion item attribute. + */ + int GetProportion() const; - 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(). + /** + Get the ration item attribute. */ - wxSize GetMinSize(); + float GetRatio() const; /** - Returns the current position of the sizer. + Get the rectangle of the item on the parent window, excluding borders. */ - wxPoint GetPosition() const; + virtual wxRect GetRect(); /** - Returns the current size of the sizer. + Get the current size of the item, as set in the last Layout. */ - wxSize GetSize() const; + virtual wxSize GetSize() const; /** - Hides the child @a window. + If this item is tracking a sizer, return it. @NULL otherwise. + */ + wxSizer* GetSizer() const; - To make a sizer item disappear, use Hide() followed by Layout(). + /** + If this item is tracking a spacer, return its size. + */ + wxSize GetSpacer() const; - Use parameter @a recursive to hide elements found in subsizers. - Returns @true if the child item was found, @false otherwise. + /** + Get the userData item attribute. + */ + wxObject* GetUserData() const; - @see IsShown(), Show() + /** + If this item is tracking a window then return it. @NULL otherwise. */ - bool Hide(wxWindow* window, bool recursive = false); + wxWindow* GetWindow() const; /** - Hides the child @a sizer. + 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. - To make a sizer item disappear, use Hide() followed by Layout(). + In other words, for sizer items, all of the child elements must be + hidden for the sizer itself to be considered hidden. - Use parameter @a recursive to hide elements found in subsizers. - Returns @true if the child item was found, @false otherwise. + 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()). + */ + bool IsShown() const; - @see IsShown(), Show() + /** + Is this item a sizer? */ - bool Hide(wxSizer* sizer, bool recursive = false); + bool IsSizer() const; /** - Hides the item at position @a index. + Is this item a spacer? + */ + bool IsSpacer() const; - To make a sizer item disappear, use Hide() followed by Layout(). + /** + Is this item a window? + */ + bool IsWindow() const; - Use parameter @a recursive to hide elements found in subsizers. - Returns @true if the child item was found, @false otherwise. + /** + Set the border item attribute. + */ + void SetBorder(int border); - @see IsShown(), Show() + /** + 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. */ - bool Hide(size_t index); + virtual void SetDimension(const wxPoint& pos, const wxSize& size); /** - Insert a child into the sizer before any existing item at @a index. - - See Add() for the meaning of the other parameters. + Set the flag item attribute. */ - wxSizerItem* Insert(size_t index, wxWindow* window, - const wxSizerFlags& flags); + void SetFlag(int flag); /** - Insert a child into the sizer before any existing item at @a index. + Sets the numeric id of the wxSizerItem to @e id. + */ + void SetId(int id); - See Add() for the meaning of the other parameters. + /** + @todo docme. */ - wxSizerItem* Insert(size_t index, wxWindow* window, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + void SetInitSize(int x, int y); /** - Insert a child into the sizer before any existing item at @a index. + Set the proportion item attribute. + */ + void SetProportion(int proportion); - See Add() for the meaning of the other parameters. + //@{ + /** + Set the ratio item attribute. */ - wxSizerItem* Insert(size_t index, wxSizer* sizer, - const wxSizerFlags& flags); + void SetRatio(int width, int height); + void SetRatio(wxSize size); + void SetRatio(float ratio); + //@} /** - Insert a child into the sizer before any existing item at @a index. + Set the sizer tracked by this item. - See Add() for the meaning of the other parameters. + @deprecated This function does not free the old sizer which may result + in memory leaks, use AssignSizer() which does free it instead. */ - wxSizerItem* Insert(size_t index, wxSizer* sizer, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + void SetSizer(wxSizer* sizer); /** - Insert a child into the sizer before any existing item at @a index. + Set the size of the spacer tracked by this item. - See Add() for the meaning of the other parameters. + @deprecated This function does not free the old spacer which may result + in memory leaks, use AssignSpacer() which does free it instead. */ - wxSizerItem* Insert(size_t index, int width, int height, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + void SetSpacer(const wxSize& size); /** - Inserts non-stretchable space to the sizer. - More readable way of calling wxSizer::Insert(size, size, 0). + Set the window to be tracked by this item. + @deprecated @todo provide deprecation description */ - wxSizerItem* InsertSpacer(size_t index, int size); + void SetWindow(wxWindow* window); /** - Inserts stretchable space to the sizer. - More readable way of calling wxSizer::Insert(0, 0, prop). + 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. */ - wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1); + void Show(bool show); +}; - /** - Return @true if the sizer has no elements. - @see GetItemCount() - */ - bool IsEmpty() const; - /** - Returns @true if the @a window is shown. +/** + @class wxSizerFlags - @see Hide(), Show(), wxSizerItem::IsShown() - */ - bool IsShown(wxWindow* window) const; + Container for sizer items flags providing readable names for them. - /** - Returns @true if the @a sizer is shown. + 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 Hide(), Show(), wxSizerItem::IsShown() + @code + sizer->Add(ctrl, 0, wxEXPAND | wxALL, 10); + @endcode + + you can now write + + @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. */ - bool IsShown(wxSizer* sizer) const; + wxSizerFlags(int proportion = 0); /** - Returns @true if the item at @a index is shown. + Sets the alignment of this wxSizerFlags to @a align. - @see Hide(), Show(), wxSizerItem::IsShown() + 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() */ - bool IsShown(size_t index) const; + wxSizerFlags& Align(int alignment); /** - 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. + Sets the wxSizerFlags to have a border of a number of pixels specified + by @a borderinpixels with the directions specified by @a direction. */ - virtual void Layout(); + wxSizerFlags& Border(int direction, int borderinpixels); /** - 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 wxSizerFlags to have a border with size as returned by + GetDefaultBorder(). + + @param direction + Direction(s) to apply the border in. */ - wxSizerItem* Prepend(wxWindow* window, const wxSizerFlags& flags); + wxSizerFlags& Border(int direction = wxALL); /** - 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 bottom, similar for @c Align(wxALIGN_BOTTOM). + + Unlike Align(), this method doesn't change the horizontal alignment of + the item. */ - wxSizerItem* Prepend(wxWindow* window, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + wxSizerFlags& Bottom(); /** - 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 object of the wxSizerFlags to center itself in the area it is + given. */ - wxSizerItem* Prepend(wxSizer* sizer, - const wxSizerFlags& flags); + wxSizerFlags& Center(); /** - Same as Add(), but prepends the items to the beginning of the - list of items (windows, subsizers or spaces) owned by this sizer. + Center() for people with the other dialect of English. */ - wxSizerItem* Prepend(wxSizer* sizer, int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + wxSizerFlags& Centre(); /** - 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 border in the given @a direction having twice the default + border size. */ - wxSizerItem* Prepend(int width, int height, - int proportion = 0, - int flag = 0, - int border = 0, - wxObject* userData = NULL); + wxSizerFlags& DoubleBorder(int direction = wxALL); /** - Prepends non-stretchable space to the sizer. - More readable way of calling wxSizer::Prepend(size, size, 0). + Sets the border in left and right directions having twice the default + border size. */ - wxSizerItem* PrependSpacer(int size); + wxSizerFlags& DoubleHorzBorder(); /** - Prepends stretchable space to the sizer. - More readable way of calling wxSizer::Prepend(0, 0, prop). + Sets the object of the wxSizerFlags to expand to fill as much area as + it can. */ - wxSizerItem* PrependStretchSpacer(int prop = 1); + wxSizerFlags& Expand(); /** - 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. + Set the @c wxFIXED_MINSIZE flag which indicates that the initial size + of the window should be also set as its minimal size. */ - virtual void RecalcSizes() = 0; + wxSizerFlags& FixedMinSize(); /** - 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. + 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. - @return @true if the child item was found and removed, @false otherwise. + @since 2.8.8 */ - virtual bool Remove(wxWindow* window); + wxSizerFlags& ReserveSpaceEvenIfHidden(); /** - 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. + Returns the border used by default in Border() method. */ - virtual bool Remove(wxSizer* sizer); + static int GetDefaultBorder(); /** - 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. + Aligns the object to the left, similar for @c Align(wxALIGN_LEFT). - @return @true if the child item was found and removed, @false otherwise. + Unlike Align(), this method doesn't change the vertical alignment of + the item. */ - virtual bool Remove(int index); + wxSizerFlags& Left(); /** - 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. + Sets the proportion of this wxSizerFlags to @e proportion + */ + wxSizerFlags& Proportion(int proportion); - 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. + /** + Aligns the object to the right, similar for @c Align(wxALIGN_RIGHT). - Returns @true if the child item was found and removed, @false otherwise. + Unlike Align(), this method doesn't change the vertical alignment of + the item. */ - virtual bool Replace(wxWindow* oldwin, wxWindow* newwin, - bool recursive = false); + wxSizerFlags& Right(); /** - 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. + 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. + */ + wxSizerFlags& Shaped(); - 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. + /** + Aligns the object to the top, similar for @c Align(wxALIGN_TOP). - Returns @true if the child item was found and removed, @false otherwise. + Unlike Align(), this method doesn't change the horizontal alignment of + the item. */ - virtual bool Replace(wxSizer* oldsz, wxSizer* newsz, - bool recursive = false); + wxSizerFlags& Top(); /** - Detaches the given item at position @a index from the sizer and - replaces it with the given wxSizerItem @a newitem. + Sets the border in the given @a direction having thrice the default + border size. + */ + wxSizerFlags& TripleBorder(int direction = wxALL); +}; - 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. +/** + 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, - Returns @true if the child item was found and removed, @false otherwise. - */ - virtual bool Replace(size_t index, wxSizerItem* newitem); + /// Uniformly resize only the specified ones (default). + wxFLEX_GROWMODE_SPECIFIED, - /** - 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. - */ - void SetDimension(int x, int y, int width, int height); + /// Uniformly resize all cells. + wxFLEX_GROWMODE_ALL +}; - /** - @overload - */ - void SetDimension(const wxPoint& pos, const wxSize& size); +/** + @class wxFlexGridSizer - /** - Set an item's minimum size by window, sizer, or position. + 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. - 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. + 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. - @see wxSizerItem::SetMinSize() - */ - bool SetItemMinSize(wxWindow* window, int width, int height); + @library{wxcore} + @category{winlayout} + @see wxSizer, @ref overview_sizer +*/ +class wxFlexGridSizer : public wxGridSizer +{ +public: + //@{ /** - Set an item's minimum size by window, sizer, or position. + wxFlexGridSizer constructors. - 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. + Please see wxGridSizer::wxGridSizer documentation. - @see wxSizerItem::SetMinSize() + @since 2.9.1 (except for the four argument overload) */ - bool SetItemMinSize(wxSizer* sizer, int width, int height); + wxFlexGridSizer( int cols, int vgap, int hgap ); + wxFlexGridSizer( int cols, const wxSize& gap = wxSize(0, 0) ); + + wxFlexGridSizer( int rows, int cols, int vgap, int hgap ); + wxFlexGridSizer( int rows, int cols, const wxSize& gap ); + //@} /** - Set an item's minimum size by window, sizer, or position. + Specifies that column @a idx (starting from zero) should be grown if + there is extra space available to the sizer. - The item will be found recursively in the sizer's descendants. - This function enables an application to set the size of an item after - initial creation. + The @a 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). - @see wxSizerItem::SetMinSize() + 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. */ - bool SetItemMinSize(size_t index, int width, int height); + void AddGrowableCol(size_t idx, int proportion = 0); /** - Call this to give the sizer a minimal size. + Specifies that row idx (starting from zero) should be grown if there + is extra space available to the sizer. - 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. + This is identical to AddGrowableCol() except that it works with rows + and not columns. */ - void SetMinSize(const wxSize& size); - - /** - @overload - */ - void SetMinSize(int width, int height); + void AddGrowableRow(size_t idx, int proportion = 0); /** - This method first calls Fit() and then wxTopLevelWindow::SetSizeHints() - on the @a window passed to it. + Returns a ::wxOrientation value that specifies whether the sizer flexibly + resizes its columns, rows, or both (default). - 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. + @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). - 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. + @see SetFlexibleDirection() */ - void SetSizeHints(wxWindow* window); + int GetFlexibleDirection() const; /** - 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 the value that specifies how the sizer grows in the "non-flexible" + direction if there is one. - @deprecated @todo provide deprecation description + 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 wxScrolled::SetScrollbars() + @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. + + @see SetFlexibleDirection(), SetNonFlexibleGrowMode() */ - void SetVirtualSizeHints(wxWindow* window); + wxFlexSizerGrowMode GetNonFlexibleGrowMode() const; /** - Shows or hides the @a window. - To make a sizer item disappear or reappear, use Show() followed by Layout(). + Returns @true if column @a idx is growable. - Use parameter @a recursive to show or hide elements found in subsizers. + @since 2.9.0 + */ + bool IsColGrowable(size_t idx); - Returns @true if the child item was found, @false otherwise. + /** + Returns @true if row @a idx is growable. - @see Hide(), IsShown() + @since 2.9.0 */ - bool Show(wxWindow* window, bool show = true, - bool recursive = false); + bool IsRowGrowable(size_t idx); /** - Shows or hides @a sizer. - To make a sizer item disappear or reappear, use Show() followed by Layout(). + Specifies that the @a idx column index is no longer growable. + */ + void RemoveGrowableCol(size_t idx); - Use parameter @a recursive to show or hide elements found in subsizers. + /** + Specifies that the @a idx row index is no longer growable. + */ + void RemoveGrowableRow(size_t idx); - 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 @@ -1582,32 +1601,82 @@ class wxGridSizer : public wxSizer public: //@{ /** - Constructor for a wxGridSizer. + wxGridSizer constructors. - @a rows and @a cols determine the number of columns and rows in the sizer - - if either of the parameters is zero, it will be calculated to form the - total number of children in the sizer, thus making the sizer grow dynamically. + Usually only the number of columns in the flex grid sizer needs to be + specified using @a cols argument. The number of rows will be deduced + automatically depending on the number of the elements added to the + sizer. - @a vgap and @a hgap define extra space between all children. + If a constructor form with @a rows parameter is used (and the value of + @a rows argument is not zero, meaning "unspecified") the sizer will + check that no more than @c cols*rows elements are added to it, i.e. + that no more than the given number of @a rows is used. Adding less than + maximally allowed number of items is not an error however. + + Finally, it is also possible to specify the number of rows and use 0 + for @a cols. In this case, the sizer will use the given fixed number of + rows and as many columns as necessary. + + The @a gap (or @a vgap and @a hgap, which correspond to the height and + width of the wxSize object) argument defines the size of the padding + between the rows (its vertical component, or @a vgap) and columns + (its horizontal component, or @a hgap), in pixels. + + + @since 2.9.1 (except for the four argument overload) */ - wxGridSizer(int rows, int cols, int vgap, int hgap); - wxGridSizer(int cols, int vgap = 0, int hgap = 0); + wxGridSizer( int cols, int vgap, int hgap ); + wxGridSizer( int cols, const wxSize& gap = wxSize(0, 0) ); + + wxGridSizer( int rows, int cols, int vgap, int hgap ); + wxGridSizer( int rows, int cols, const wxSize& gap ); //@} /** - Returns the number of columns in the sizer. + Returns the number of columns that has been specified for the + sizer. + + Returns zero if the sizer is automatically adjusting the number of + columns depending on number of its children. To get the effective + number of columns or rows being currently used, see GetEffectiveColsCount() */ int GetCols() const; + + /** + Returns the number of rows that has been specified for the + sizer. + + Returns zero if the sizer is automatically adjusting the number of + rows depending on number of its children. To get the effective + number of columns or rows being currently used, see GetEffectiveRowsCount(). + */ + int GetRows() const; /** - Returns the horizontal gap (in pixels) between cells in the sizer. + Returns the number of columns currently used by the sizer. + + This will depend on the number of children the sizer has if + the sizer is automatically adjusting the number of columns/rows. + + @since 2.9.1 */ - int GetHGap() const; + int GetEffectiveColsCount() const; + + /** + Returns the number of rows currently used by the sizer. + + This will depend on the number of children the sizer has if + the sizer is automatically adjusting the number of columns/rows. + + @since 2.9.1 + */ + int GetEffectiveRowsCount() const; /** - Returns the number of rows in the sizer. + Returns the horizontal gap (in pixels) between cells in the sizer. */ - int GetRows() const; + int GetHGap() const; /** Returns the vertical gap (in pixels) between the cells in the sizer. @@ -1640,11 +1709,29 @@ public: /** @class wxStaticBoxSizer - wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static - box around the sizer. - This static box may be either created independently or the sizer may create - it itself as a convenience. In any case, the sizer owns the wxStaticBox control - and will delete it, if it is deleted. + wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static box around + the sizer. + + The static box may be either created independently or the sizer may create it + itself as a convenience. In any case, the sizer owns the wxStaticBox control + and will delete it in the wxStaticBoxSizer destructor. + + Note that since wxWidgets 2.9.1 you are encouraged to create the windows + which are added to wxStaticBoxSizer as children of wxStaticBox itself, see + this class documentation for more details. + + Example of use of this class: + @code + void MyFrame::CreateControls() + { + wxPanel *panel = new wxPanel(this); + ... + wxStaticBoxSizer *sz = new wxStaticBoxSizer(wxVERTICAL, panel, "Box"); + sz->Add(new wxStaticText(sz->GetStaticBox(), wxID_ANY, + "This window is a child of the staticbox")); + ... + } + @endcode @library{wxcore} @category{winlayout} @@ -1657,8 +1744,11 @@ public: /** This constructor uses an already existing static box. - It takes the associated static box and the orientation @a orient, which - can be either @c wxVERTICAL or @c wxHORIZONTAL as parameters. + @param box + The static box to associate with the sizer (which will take its + ownership). + @param orient + Can be either @c wxVERTICAL or @c wxHORIZONTAL. */ wxStaticBoxSizer(wxStaticBox* box, int orient); @@ -1699,6 +1789,22 @@ public: */ wxBoxSizer(int orient); + /** + Adds non-stretchable space to the main orientation of the sizer only. + More readable way of calling: + @code + if ( wxBoxSizer::IsVertical() ) + { + wxBoxSizer::Add(0, size, 0). + } + else + { + wxBoxSizer::Add(size, 0, 0). + } + @endcode + */ + virtual wxSizerItem *AddSpacer(int size); + /** Implements the calculation of a box sizer's minimal.