X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7e927914ef421ab856ef1733be610f63fad07099..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/sizer.h diff --git a/interface/sizer.h b/interface/sizer.h index 8d130f852e..619bd2dcba 100644 --- a/interface/sizer.h +++ b/interface/sizer.h @@ -322,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); @@ -367,10 +368,14 @@ public: wxSizerFlags(int proportion = 0); /** - Sets the alignment of this wxSizerFlags to @e align. Note that if this - method is not called, the wxSizerFlags has no specified alignment. + Sets the alignment of this wxSizerFlags to @e align. + + This method replaces the previously set alignment with the specified + one. @see Top(), Left(), Right(), Bottom(), Centre() + + @param align Combination of @c wxALIGN_XXX bit masks. */ wxSizerFlags& Align(int align = 0); @@ -389,9 +394,10 @@ public: 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(); @@ -447,9 +453,10 @@ 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(); @@ -459,9 +466,10 @@ public: 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(); @@ -472,9 +480,10 @@ public: 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(); @@ -585,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() */ @@ -595,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() @@ -978,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 @@ -1011,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 @@ -1079,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 @@ -1271,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 @@ -1297,8 +1407,12 @@ 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. @@ -1309,9 +1423,28 @@ public: @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 @@ -1347,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); - //@} };