X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/5886ce0247d3797007a6798da4af69c4cfe9926e..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/sizer.h diff --git a/interface/sizer.h b/interface/sizer.h index e86108c8ce..619bd2dcba 100644 --- a/interface/sizer.h +++ b/interface/sizer.h @@ -166,6 +166,19 @@ public: */ wxSize GetMinSize() const; + /** + 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. */ @@ -212,10 +225,15 @@ public: wxWindow* GetWindow() const; /** - 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 its elements are hidden. 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 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. + + In other words, for sizer items, all of the child elements must be + hidden for the sizer itself to be considered hidden. + + 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; @@ -304,11 +322,12 @@ public: @class wxSizerFlags @wxheader{sizer.h} - 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 + Container for sizer items flags providing readable names for them. + + 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 @code sizer->Add(ctrl, 0, wxEXPAND | wxALL, 10); @@ -350,65 +369,83 @@ public: /** Sets the alignment of this wxSizerFlags to @e align. - Note that if this method is not called, the wxSizerFlags has no specified - alignment. - @see Top(), Left(), Right(), - Bottom(), Centre() + This method replaces the previously set alignment with the specified + one. + + @see Top(), Left(), Right(), Bottom(), Centre() + + @param align Combination of @c wxALIGN_XXX bit masks. */ - wxSizerFlags Align(int align = 0); + wxSizerFlags& Align(int align = 0); - //@{ /** - Sets the wxSizerFlags to have a border of a number of pixels specified by - @a borderinpixels with the directions specified by @e direction. - In the overloaded version without @a borderinpixels parameter, the border of - default size, as returned by GetDefaultBorder(), - is used. + Sets the wxSizerFlags to have a border of a number of pixels specified + by @a borderinpixels with the directions specified by @e direction. */ - wxSizerFlags Border(int direction, int borderinpixels); - wxSizerFlags Border(int direction = wxALL); - //@} + wxSizerFlags& Border(int direction, int borderinpixels); + + /** + Sets the wxSizerFlags to have a border with size as returned by + GetDefaultBorder(). + + @param direction Direction(s) to apply the border in. + */ + wxSizerFlags& Border(int direction = wxALL); /** - Aligns the object to the bottom, shortcut for @c Align(wxALIGN_BOTTOM) + Aligns the object to the bottom, similar for @c Align(wxALIGN_BOTTOM). - @see Align() + Unlike Align(), this method doesn't change the horizontal alignment of + the item. */ - wxSizerFlags Bottom(); + wxSizerFlags& Bottom(); /** - Sets the object of the wxSizerFlags to center itself in the area it is given. + Sets the object of the wxSizerFlags to center itself in the area it is + given. */ - wxSizerFlags Center(); + wxSizerFlags& Center(); /** - Center() for people with the other dialect of english. + Center() for people with the other dialect of English. */ - wxSizerFlags Centre(); + wxSizerFlags& Centre(); /** - Sets the border in the given @a direction having twice the default border - size. + Sets the border in the given @a direction having twice the default + border size. */ - wxSizerFlags DoubleBorder(int direction = wxALL); + wxSizerFlags& DoubleBorder(int direction = wxALL); /** - Sets the border in left and right directions having twice the default border - size. + Sets the border in left and right directions having twice the default + border size. */ - wxSizerFlags DoubleHorzBorder(); + wxSizerFlags& DoubleHorzBorder(); /** - Sets the object of the wxSizerFlags to expand to fill as much area as it can. + Sets the object of the wxSizerFlags to expand to fill as much area as + it can. */ - wxSizerFlags Expand(); + wxSizerFlags& Expand(); /** - Set the @c wxFIXED_MINSIZE flag which indicates that the initial size of - the window should be also set as its minimal size. + Set the @c wxFIXED_MINSIZE flag which indicates that the initial size + of the window should be also set as its minimal size. */ - wxSizerFlags FixedMinSize(); + wxSizerFlags& FixedMinSize(); + + /** + 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. + + @since 2.8.8 + */ + wxSizerFlags& ReserveSpaceEvenIfHidden(); /** Returns the border used by default in Border() method. @@ -416,42 +453,45 @@ public: static int GetDefaultBorder(); /** - Aligns the object to the left, shortcut for @c Align(wxALIGN_LEFT) + Aligns the object to the left, similar for @c Align(wxALIGN_LEFT). - @see Align() + Unlike Align(), this method doesn't change the vertical alignment of + the item. */ - wxSizerFlags Left(); + wxSizerFlags& Left(); /** Sets the proportion of this wxSizerFlags to @e proportion */ - wxSizerFlags Proportion(int proportion = 0); + wxSizerFlags& Proportion(int proportion = 0); /** - Aligns the object to the right, shortcut for @c Align(wxALIGN_RIGHT) + Aligns the object to the right, similar for @c Align(wxALIGN_RIGHT). - @see Align() + Unlike Align(), this method doesn't change the vertical alignment of + the item. */ - wxSizerFlags Right(); + wxSizerFlags& Right(); /** 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(); + wxSizerFlags& Shaped(); /** - Aligns the object to the top, shortcut for @c Align(wxALIGN_TOP) + Aligns the object to the top, similar for @c Align(wxALIGN_TOP). - @see Align() + Unlike Align(), this method doesn't change the horizontal alignment of + the item. */ - wxSizerFlags Top(); + wxSizerFlags& Top(); /** - Sets the border in the given @a direction having thrice the default border - size. + Sets the border in the given @a direction having thrice the default + border size. */ - wxSizerFlags TripleBorder(int direction = wxALL); + wxSizerFlags& TripleBorder(int direction = wxALL); }; @@ -554,7 +594,7 @@ public: Returns a wxOrientation value that specifies whether the sizer flexibly resizes its columns, rows, or both (default). - @returns One of the following values: + @return One of the following values: @see SetFlexibleDirection() */ @@ -564,7 +604,7 @@ public: Returns the value that specifies how the sizer grows in the "non-flexible" direction if there is one. - @returns One of the following values: + @return One of the following values: @see SetFlexibleDirection(), SetNonFlexibleGrowMode() @@ -694,6 +734,13 @@ public: item changes and its best size becomes different. If you would rather have a window item stay the size it started with then use wxFIXED_MINSIZE.} + @itemdef{wxRESERVE_SPACE_EVEN_IF_HIDDEN, + Normally wxSizers don't allocate space for hidden windows or other + items. This flag overrides this behavior so that sufficient space + is allocated for the window even if it isn't visible. This makes + it possible to dynamically show and hide controls without resizing + parent dialog, for example. (Available since 2.8.8.) + } @itemdef{wxALIGN_CENTER
wxALIGN_CENTRE
wxALIGN_LEFT
@@ -940,22 +987,40 @@ public: */ wxSize ComputeFittingWindowSize(wxWindow* window); - //@{ /** - Detach a child from the sizer without destroying it. @a window is the window to - be - detached, @a sizer is the equivalent sizer and @a index is the position of - the child in the sizer, typically 0 for the first item. This method does not - cause any layout or resizing to take place, call Layout() + Detach the child @a window from the sizer without destroying it. + + This method does not cause any layout or resizing to take place, call Layout() to update the layout "on screen" after detaching a child from the sizer. + Returns @true if the child item was found and detached, @false otherwise. @see Remove() */ bool Detach(wxWindow* window); + + /** + Detach the child @a sizer from the sizer without destroying it. + + This method does not cause any layout or resizing to take place, call Layout() + to update the layout "on screen" after detaching a child from the sizer. + + Returns @true if the child item was found and detached, @false otherwise. + + @see Remove() + */ bool Detach(wxSizer* 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 Detach(size_t index); - //@} /** Tell the sizer to resize the @a window so that its client area matches the @@ -973,41 +1038,53 @@ public: /** 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. + cause the addition/removal/alteration of scrollbars required to view the virtual + area in windows which manage it. - @see wxScrolledWindow::SetScrollbars, SetVirtualSizeHints() + @see wxScrolled::SetScrollbars(), SetVirtualSizeHints() */ void FitInside(wxWindow* window); - //@{ /** Returns the list of the items in this sizer. The elements of type-safe - wxList @c wxSizerItemList are objects of type + wxList @a wxSizerItemList are objects of type @ref overview_wxsizeritem "wxSizerItem *". */ - const wxSizerItemList GetChildren(); - const wxSizerItemList GetChildren(); - //@} + wxSizerItemList& GetChildren(); + + /** + Returns the list of the items in this sizer. The elements of type-safe + wxList @a wxSizerItemList are objects of type + @ref overview_wxsizeritem "wxSizerItem *". + */ + const wxSizerItemList& GetChildren() const; /** Returns the window this sizer is used in or @NULL if none. */ wxWindow* GetContainingWindow() const; - //@{ /** - Finds item of the sizer which holds given @e window, @a sizer or is located - in sizer at position @e index. + Finds wxSizerItem which holds the given @a window Use parameter @a recursive to search in subsizers too. Returns pointer to item or @NULL. */ wxSizerItem* GetItem(wxWindow* window, bool recursive = false); + + /** + Finds wxSizerItem which holds the given @a sizer + Use parameter @a recursive to search in subsizers too. + Returns pointer to item or @NULL. + */ + wxSizerItem* GetItem(wxSizer* sizer, bool recursive = false); + /** + 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. + */ wxSizerItem* GetItem(size_t index); - //@} /** Finds item of the sizer which has the given @e id. This @a id is not the @@ -1041,48 +1118,90 @@ public: */ wxSize GetSize(); - //@{ /** - Hides the @e window, @e sizer, or item at @e index. + Hides the child @a window. + To make a sizer item disappear, use Hide() followed by Layout(). + Use parameter @a recursive to hide elements found in subsizers. Returns @true if the child item was found, @false otherwise. @see IsShown(), Show() */ bool Hide(wxWindow* window, bool recursive = false); + + /** + Hides the child @a sizer. + + To make a sizer item disappear, use Hide() followed by Layout(). + + Use parameter @a recursive to hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. + + @see IsShown(), Show() + */ bool Hide(wxSizer* sizer, bool recursive = false); + + /** + Hides the item at position @a index. + + To make a sizer item disappear, use Hide() followed by Layout(). + + Use parameter @a recursive to hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. + + @see IsShown(), Show() + */ bool Hide(size_t index); - //@} - //@{ /** Insert a child into the sizer before any existing item at See Add() for the meaning of the other parameters. - - @param index The position this child should assume in the sizer. */ wxSizerItem* Insert(size_t index, wxWindow* window, const wxSizerFlags& flags); + + /** + Insert a child into the sizer before any existing item at + + See Add() for the meaning of the other parameters. + */ wxSizerItem* Insert(size_t index, wxWindow* window, int proportion = 0, int flag = 0, int border = 0, wxObject* userData = NULL); + + /** + Insert a child into the sizer before any existing item at + + See Add() for the meaning of the other parameters. + */ wxSizerItem* Insert(size_t index, wxSizer* sizer, const wxSizerFlags& flags); + + /** + Insert a child into the sizer before any existing item at + + See Add() for the meaning of the other parameters. + */ wxSizerItem* Insert(size_t index, wxSizer* sizer, int proportion = 0, int flag = 0, int border = 0, wxObject* userData = NULL); + + /** + Insert a child into the sizer before any existing item at + + See Add() for the meaning of the other parameters. + */ wxSizerItem* Insert(size_t index, int width, int height, int proportion = 0, int flag = 0, int border = 0, wxObject* userData = NULL); - //@} /** Inserts non-stretchable space to the sizer. More readable way of calling @@ -1096,16 +1215,26 @@ public: */ wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1); - //@{ /** - Returns @true if the @e window, @e sizer, or item at @a index is shown. + Returns @true if the @e window is shown. - @see Hide(), Show() + @see Hide(), Show(), wxSizerItem::IsShown() */ bool IsShown(wxWindow* window) const; - const bool IsShown(wxSizer* sizer) const; - const bool IsShown(size_t index) const; - //@} + + /** + Returns @true if the @e sizer is shown. + + @see Hide(), Show(), wxSizerItem::IsShown() + */ + bool IsShown(wxSizer* sizer) const; + + /** + Returns @true if the item at @a index is shown. + + @see Hide(), Show(), wxSizerItem::IsShown() + */ + bool IsShown(size_t index) const; /** Call this to force layout of the children anew, e.g. after having added a child @@ -1223,25 +1352,54 @@ public: */ bool Remove(size_t index); - //@{ /** - Detaches the given @e oldwin, @a oldsz child from the sizer and - replaces it with the given window, sizer, or wxSizerItem. - The detached child is removed @b only if it is a sizer or a spacer - (because windows are owned by their parent window, not the sizer). + Detaches the given @a oldwin from the sizer and + replaces it with the given @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. - This method does not cause any layout or resizing to take place, call - Layout() to update the layout "on screen" after replacing a + This method does not cause any layout or resizing to take place, + call Layout() to update the layout "on screen" after replacing a child from the sizer. + Returns @true if the child item was found and removed, @false otherwise. */ bool Replace(wxWindow* oldwin, wxWindow* newwin, bool recursive = false); + + /** + Detaches the given @a oldsz from the sizer and + replaces it with the given @newwin. The detached + child sizer is deleted. + + Use parameter @a recursive to search the given element recursively in subsizers. + + This method does not cause any layout or resizing to take place, + call Layout() to update the layout "on screen" after replacing a + child from the sizer. + + Returns @true if the child item was found and removed, @false otherwise. + */ bool Replace(wxSizer* oldsz, wxSizer* newsz, bool recursive = false); - bool Remove(size_t oldindex, wxSizerItem* newitem); - //@} + + /** + Detaches the given item at position @a index from the sizer and + replaces it with the given wxSizerItem @ newitem. + + The detached child is deleted @b only if it is a sizer or a spacer + (but not if it is a wxWindow because windows are owned by their + parent window, not the sizer). + + This method does not cause any layout or resizing to take place, + call Layout() to update the layout "on screen" after replacing a + child from the sizer. + + Returns @true if the child item was found and removed, @false otherwise. + */ + bool Replace(size_t index, wxSizerItem* newitem); /** Call this to force the sizer to take the given dimension and thus force @@ -1249,19 +1407,44 @@ public: rules defined by the parameter in the Add() and Prepend() methods. */ void SetDimension(int x, int y, int width, int height); + + /** + @overload + */ + void SetDimension(const wxPoint& pos, const wxSize& size); - //@{ /** - Set an item's minimum size by window, sizer, or position. The item will be - found recursively - in the sizer's descendants. This function enables an application to set the - size of an item - after initial creation. + Set an item's minimum size by window, sizer, or position. + + The item will be found recursively in the sizer's descendants. This + function enables an application to set the size of an item after + initial creation. + + @see wxSizerItem::SetMinSize() */ void SetItemMinSize(wxWindow* window, int width, int height); + + /** + Set an item's minimum size by window, sizer, or position. + + The item will be found recursively in the sizer's descendants. This + function enables an application to set the size of an item after + initial creation. + + @see wxSizerItem::SetMinSize() + */ void SetItemMinSize(wxSizer* sizer, int width, int height); + + /** + Set an item's minimum size by window, sizer, or position. + + The item will be found recursively in the sizer's descendants. This + function enables an application to set the size of an item after + initial creation. + + @see wxSizerItem::SetMinSize() + */ void SetItemMinSize(size_t index, int width, int height); - //@} /** Call this to give the sizer a minimal size. Normally, the sizer will @@ -1297,25 +1480,45 @@ public: minimal size. For windows with managed scrollbars this will set them appropriately. - @see wxScrolledWindow::SetScrollbars + @see wxScrolled::SetScrollbars() */ void SetVirtualSizeHints(wxWindow* window); - //@{ /** - Shows or hides the @e window, @e sizer, or item at @e index. + Shows or hides the @a window. To make a sizer item disappear or reappear, use Show() followed by Layout(). + Use parameter @a recursive to show or hide elements found in subsizers. + Returns @true if the child item was found, @false otherwise. @see Hide(), IsShown() */ bool Show(wxWindow* window, bool show = true, bool recursive = false); + + /** + Shows or hides @a sizer. + To make a sizer item disappear or reappear, use Show() followed by Layout(). + + Use parameter @a recursive to show or hide elements found in subsizers. + + Returns @true if the child item was found, @false otherwise. + + @see Hide(), IsShown() + */ bool Show(wxSizer* sizer, bool show = true, bool recursive = false); + + /** + Shows the item at @a index. + To make a sizer item disappear or reappear, use Show() followed by Layout(). + + Returns @true if the child item was found, @false otherwise. + + @see Hide(), IsShown() + */ bool Show(size_t index, bool show = true); - //@} };