mac paths updated

[wxWidgets.git] / interface / sizer.h

diff --git a/interface/sizer.h b/interface/sizer.h
index 4b0bc74f9089ec65ab87df4545fed1e59245d25d..619bd2dcba35d767cc1c47d8be218249effadd58 100644 (file)
--- a/interface/sizer.h
+++ b/interface/sizer.h
@@ -322,11 +322,12 @@ public:
     @class wxSizerFlags
     @wxheader{sizer.h}
 
     @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);
 
     @code
     sizer->Add(ctrl, 0, wxEXPAND | wxALL, 10);


@@ -367,10 +368,14 @@ public:
     wxSizerFlags(int proportion = 0);
 
     /**
     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()
 
         @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);
 


@@ -389,9 +394,10 @@ public:
     wxSizerFlags& Border(int direction = wxALL);
 
     /**
     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();
 


@@ -447,9 +453,10 @@ public:
     static int GetDefaultBorder();
 
     /**
     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();
 


@@ -459,9 +466,10 @@ public:
     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();
 


@@ -472,9 +480,10 @@ public:
     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();
 


@@ -585,7 +594,7 @@ public:
         Returns a wxOrientation value that specifies whether the sizer flexibly
         resizes its columns, rows, or both (default).
 
         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()
     */
 
         @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 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()
 
         @see SetFlexibleDirection(),
              SetNonFlexibleGrowMode()


@@ -978,22 +987,40 @@ public:
     */
     wxSize ComputeFittingWindowSize(wxWindow* window);
 
     */
     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.
         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);
         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);
     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);
     bool Detach(size_t index);

-    //@}

 
     /**
         Tell the sizer to resize the @a window so that its client area matches the
 
     /**
         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
     /**
         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 wxScrolled::SetScrollbars(), SetVirtualSizeHints()
     */
     void FitInside(wxWindow* window);
 
 
         @see wxScrolled::SetScrollbars(), SetVirtualSizeHints()
     */
     void FitInside(wxWindow* window);
 

-    //@{

     /**
         Returns the list of the items in this sizer. The elements of type-safe
     /**
         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 *".
     */
         @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;
 
 
     /**
         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);
         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);
     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);
     wxSizerItem* GetItem(size_t index);

-    //@}

 
     /**
         Finds item of the sizer which has the given @e id.  This @a id is not the
 
     /**
         Finds item of the sizer which has the given @e id.  This @a id is not the


@@ -1079,48 +1118,90 @@ public:
     */
     wxSize GetSize();
 
     */
     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().
         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);
         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);
     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);
     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.
     /**
         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);
     */
     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);
     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);
     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);
     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);
     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
 
     /**
         Inserts non-stretchable space to the sizer. More readable way of calling


@@ -1271,25 +1352,54 @@ public:
     */
     bool Remove(size_t index);
 
     */
     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.
 
         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.
         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);
         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 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
 
     /**
         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);
         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.
 
     /**
         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);
         @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);
     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);
     void SetItemMinSize(size_t index, int width, int height);

-    //@}

 
     /**
         Call this to give the sizer a minimal size. Normally, the sizer will
 
     /**
         Call this to give the sizer a minimal size. Normally, the sizer will


@@ -1351,21 +1484,41 @@ public:
     */
     void SetVirtualSizeHints(wxWindow* window);
 
     */
     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().
         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.
         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);
         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);
     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);
     bool Show(size_t index, bool show = true);

-    //@}

 };
 
 
 };