/////////////////////////////////////////////////////////////////////////////
// Name: sizer.h
-// Purpose: documentation for wxStdDialogButtonSizer class
+// Purpose: interface of wxStdDialogButtonSizer
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
OS X Human Interface Guidelines.
@library{wxcore}
- @category{FIXME}
+ @category{winlayout}
- @seealso
- wxSizer, @ref overview_sizeroverview "Sizer overview",
+ @see wxSizer, @ref overview_sizer "Sizer Overview",
wxDialog::CreateButtonSizer
*/
class wxStdDialogButtonSizer : public wxBoxSizer
wxStdDialogButtonSizer();
/**
- Adds a button to the wxStdDialogButtonSizer. The button must have one of the
- following identifiers:
+ Adds a button to the wxStdDialogButtonSizer. The @a button must have
+ one of the following identifiers:
wxID_OK
wxID_YES
wxID_SAVE
};
+
/**
@class wxSizerItem
@wxheader{sizer.h}
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.
+ attributes of each item managed by a wxSizer. It is not usually necessary
+ to use this class because the sizer elements can also be identified by
+ their positions or window or sizer pointers but sometimes it may be more
+ convenient to use it directly.
@library{wxcore}
- @category{FIXME}
+ @category{winlayout}
*/
class wxSizerItem : public wxObject
{
/**
Return the border attribute.
*/
- int GetBorder();
+ int GetBorder() const;
/**
Return the flags attribute.
+
+ See @ref wxsizer_flags "wxSizer flags list" for details.
*/
- int GetFlag();
+ int GetFlag() const;
/**
Return the numeric id of wxSizerItem, or @c wxID_NONE if the id has
not been set.
*/
- int GetId();
+ int GetId() const;
/**
Get the minimum size needed for the item.
*/
- wxSize GetMinSize();
+ 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.
*/
- wxPoint GetPosition();
+ wxPoint GetPosition() const;
/**
Get the proportion item attribute.
*/
- int GetProportion();
+ int GetProportion() const;
/**
Get the ration item attribute.
*/
- float GetRatio();
+ float GetRatio() const;
/**
Get the rectangle of the item on the parent window, excluding borders.
/**
Get the current size of the item, as set in the last Layout.
*/
- wxSize GetSize();
+ wxSize GetSize() const;
/**
If this item is tracking a sizer, return it. @NULL otherwise.
*/
- wxSizer* GetSizer();
+ wxSizer* GetSizer() const;
/**
If this item is tracking a spacer, return its size.
*/
- const wxSize GetSpacer();
+ const wxSize GetSpacer() const;
/**
Get the userData item attribute.
*/
- wxObject* GetUserData();
+ wxObject* GetUserData() const;
/**
If this item is tracking a window then return it. @NULL otherwise.
*/
- wxWindow* GetWindow();
+ 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();
+ bool IsShown() const;
/**
Is this item a sizer?
*/
- bool IsSizer();
+ bool IsSizer() const;
/**
Is this item a spacer?
*/
- bool IsSpacer();
+ bool IsSpacer() const;
/**
Is this item a window?
*/
- bool IsWindow();
+ bool IsWindow() const;
/**
Set the border item attribute.
void SetId(int id);
/**
-
+
*/
void SetInitSize(int x, int y);
};
+
/**
@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);
+ sizer->Add(ctrl, 0, wxEXPAND | wxALL, 10);
@endcode
you can now write
@code
- sizer-Add(ctrl, wxSizerFlags().Expand().Border(10));
+ sizer->Add(ctrl, wxSizerFlags().Expand().Border(10));
@endcode
This is more readable and also allows you to create wxSizerFlags objects which
wxSizerFlags flagsExpand(1);
flagsExpand.Expand().Border(10);
- sizer-Add(ctrl1, flagsExpand);
- sizer-Add(ctrl2, flagsExpand);
+ sizer->Add(ctrl1, flagsExpand);
+ sizer->Add(ctrl2, flagsExpand);
@endcode
Note that by specification, all methods of wxSizerFlags return the wxSizerFlags
above.
@library{wxcore}
- @category{FIXME}
+ @category{winlayout}
- @seealso
- wxSizer
+ @see wxSizer
*/
class wxSizerFlags
{
/**
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);
/**
- Aligns the object to the bottom, shortcut for @c Align(wxALIGN_BOTTOM)
-
- @see Align()
+ 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, similar for @c Align(wxALIGN_BOTTOM).
+
+ Unlike Align(), this method doesn't change the horizontal alignment of
+ the item.
+ */
+ wxSizerFlags& Bottom();
+
+ /**
+ Sets the object of the wxSizerFlags to center itself in the area it is
+ given.
*/
- wxSizerFlags Bottom();
+ wxSizerFlags& Center();
/**
- Sets the object of the wxSizerFlags to center itself in the area it is given.
+ Center() for people with the other dialect of English.
*/
- wxSizerFlags Center();
+ wxSizerFlags& Centre();
/**
- Center() for people with the other dialect of english.
+ Sets the border in the given @a direction having twice the default
+ border size.
*/
- wxSizerFlags Centre();
+ wxSizerFlags& DoubleBorder(int direction = wxALL);
/**
- Sets the border in the given @a direction having twice the default border
- size.
+ Sets the border in left and right directions having twice the default
+ border size.
*/
- wxSizerFlags DoubleBorder(int direction = wxALL);
+ wxSizerFlags& DoubleHorzBorder();
/**
- Sets the border in left and right directions having twice the default border
- size.
+ Sets the object of the wxSizerFlags to expand to fill as much area as
+ it can.
*/
- wxSizerFlags DoubleHorzBorder();
+ wxSizerFlags& Expand();
/**
- Sets the object of the wxSizerFlags to expand to fill as much area as it can.
+ Set the @c wxFIXED_MINSIZE flag which indicates that the initial size
+ of the window should be also set as its minimal size.
*/
- wxSizerFlags Expand();
+ wxSizerFlags& FixedMinSize();
/**
- 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 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 FixedMinSize();
+ wxSizerFlags& ReserveSpaceEvenIfHidden();
/**
Returns the border used by default in Border() method.
static int GetDefaultBorder();
/**
- Aligns the object to the left, shortcut for @c Align(wxALIGN_LEFT)
-
- @see Align()
+ 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.
*/
- 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)
-
- @see Align()
+ 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.
*/
- 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)
-
- @see Align()
+ 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.
*/
- 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);
};
+
/**
@class wxNotebookSizer
@wxheader{sizer.h}
- @b This class is deprecated and should not be used in new code! It is no
+ @deprecated
+ This class is deprecated and should not be used in new code! It is no
longer needed, wxNotebook control can be inserted
into any sizer class and its minimal size will be determined correctly.
- See @ref overview_sizeroverview "wxSizer overview" for more information.
wxNotebookSizer is a specialized sizer to make sizers work in connection
- with using notebooks. This sizer is different from any other sizer as
- you must not add any children to it - instead, it queries the notebook class
- itself.
- The only thing this sizer does is to determine the size of the biggest
- page of the notebook and report an adjusted minimal size to a more toplevel
- sizer.
+ with using notebooks. This sizer is different from any other sizer as you
+ must not add any children to it - instead, it queries the notebook class
+ itself. The only thing this sizer does is to determine the size of the
+ biggest page of the notebook and report an adjusted minimal size to a more
+ toplevel sizer.
@library{wxbase}
- @category{FIXME}
+ @category{winlayout}
- @seealso
- wxSizer, wxNotebook, @ref overview_sizeroverview "Sizer overview"
+ @see wxSizer, wxNotebook,
+ @ref overview_sizer "Sizers overview"
*/
class wxNotebookSizer : public wxSizer
{
};
+
/**
@class wxFlexGridSizer
@wxheader{sizer.h}
@library{wxcore}
@category{winlayout}
- @seealso
- wxSizer, @ref overview_sizeroverview "Sizer overview"
+ @see wxSizer, @ref overview_sizer "Sizer Overview"
*/
class wxFlexGridSizer : public wxGridSizer
{
Specifies that column @a idx (starting from zero) should be grown if
there is extra space available to the sizer.
The @a proportion parameter has the same meaning as the stretch factor for
- the sizers except that if all proportions are 0,
+ the sizers() except that if all proportions are 0,
then all columns are resized equally (instead of not being resized at all).
*/
void AddGrowableCol(size_t idx, int proportion = 0);
/**
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()
*/
- int GetFlexibleDirection();
+ int GetFlexibleDirection() const;
/**
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()
*/
- int GetNonFlexibleGrowMode();
+ int GetNonFlexibleGrowMode() const;
/**
Specifies that column idx is no longer growable.
Specifies whether the sizer should flexibly resize its columns, rows, or
both. Argument @c direction can be @c wxVERTICAL, @c wxHORIZONTAL
or @c wxBOTH (which is the default value). Any other value is ignored. See
- @ref getflexibledrection() GetFlexibleDirection for the
+ @ref GetFlexibleDirection() GetFlexibleDirection for the
explanation of these values.
Note that this method does not trigger relayout.
*/
};
+
/**
@class wxSizer
@wxheader{sizer.h}
on Windows.
Sizers may also be used to control the layout of custom drawn items on the
- window. The
- Add, Insert, and Prepend functions return a pointer to the newly added
- wxSizerItem. Just
- add empty space of the desired size and attributes, and then use the
- wxSizerItem::GetRect
- method to determine where the drawing operations should take place.
+ window. The Add(), Insert(), and Prepend() functions return a pointer to
+ the newly added wxSizerItem. Just add empty space of the desired size and
+ attributes, and then use the wxSizerItem::GetRect() method to determine
+ where the drawing operations should take place.
Please notice that sizers, like child windows, are owned by the library and
- will be deleted by it which implies that they must be allocated on the heap.
- However if you create a sizer and do not add it to another sizer or window, the
- library wouldn't be able to delete such an orphan sizer and in this, and only
- this, case it should be deleted explicitly.
+ will be deleted by it which implies that they must be allocated on the
+ heap. However if you create a sizer and do not add it to another sizer or
+ window, the library wouldn't be able to delete such an orphan sizer and in
+ this, and only this, case it should be deleted explicitly.
@b wxPython note: If you wish to create a sizer class in wxPython you should
derive the class from @c wxPySizer in order to get Python-aware
capabilities for the various virtual methods.
+ @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}
- @seealso
- @ref overview_sizeroverview "Sizer overview"
+ @see @ref overview_sizer "Sizer Overview"
*/
class wxSizer : public wxObject
{
*/
~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:
-
+ 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 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 width and height
- 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.
+ 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:
+
+ @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.
+ 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
- This parameter can be used to set a number of flags
- which can be combined using the binary OR operator |. 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.
-
-
-
-
-
-
- wxTOP
-
- wxBOTTOM
-
- wxLEFT
-
- wxRIGHT
-
- wxALL
-
-
-
-
- These flags are used to specify which side(s) of
- the sizer item the border width will apply to.
-
-
-
-
-
- wxEXPAND
-
-
-
-
- The item will be expanded to fill
- the space assigned to the item.
-
-
-
-
-
- wxSHAPED
-
-
-
-
- The item will be expanded as much
- as possible while also maintaining its aspect ratio
-
-
-
-
-
- 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.
-
-
-
-
-
- wxALIGN_CENTER wxALIGN_CENTRE
-
- wxALIGN_LEFT
-
- wxALIGN_RIGHT
-
- wxALIGN_TOP
-
- wxALIGN_BOTTOM
-
- wxALIGN_CENTER_VERTICAL wxALIGN_CENTRE_VERTICAL
-
- wxALIGN_CENTER_HORIZONTAL wxALIGN_CENTRE_HORIZONTAL
-
-
-
-
- The wxALIGN flags allow you to
- specify the alignment of the item within the space allotted to it by
- the sizer, adjusted for the border if any.
+ 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.
+ 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.
- @param flags
- A wxSizerFlags object that
- enables you to specify most of the above parameters more conveniently.
+ 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(wxWindow* window, const wxSizerFlags& flags);
wxSizerItem* Add(wxWindow* window, int proportion = 0,
int flag = 0,
int border = 0,
wxObject* userData = NULL);
+
+ /**
+ Appends a child to the sizer.
+
+ wxSizer itself is an abstract class, but the parameters are equivalent
+ in the derived classes that you will instantiate to use it so they are
+ described here:
+
+ @param sizer
+ The (child-)sizer to be added to the sizer. This allows placing a
+ child sizer in a sizer and thus to create hierarchies of sizers
+ (typically a vertical box as the top sizer and several horizontal
+ boxes on the level beneath).
+ @param flags
+ A wxSizerFlags object that enables you to specify most of the above
+ parameters more conveniently.
+ */
wxSizerItem* Add(wxSizer* sizer, 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:
+
+ @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.
+
+ 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.
+ */
wxSizerItem* Add(int width, int height, int proportion = 0,
int flag = 0,
int border = 0,
wxObject* userData = NULL);
- //@}
/**
Adds non-stretchable space to the sizer. More readable way of calling
void Clear(bool delete_windows = false);
/**
- 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.
-
+ Computes client area size for @a window so that it matches the sizer's
+ minimal size. Unlike GetMinSize(), this method accounts for other
+ constraints imposed on @e window, namely display's size (returned size
+ will never be too large for the display) and maximum window size if
+ previously set by wxWindow::SetMaxSize(). The returned value is
+ suitable for passing to wxWindow::SetClientSize() or
+ wxWindow::SetMinClientSize().
+
+ @since 2.8.8
+
@see ComputeFittingWindowSize(), Fit()
*/
wxSize ComputeFittingClientSize(wxWindow* window);
/**
- Like ComputeFittingClientSize(),
- but converts the result into window size.
- The returned value is suitable for passing to
- wxWindow::SetSize or
- wxWindow::SetMinSize.
-
+ 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
+
@see ComputeFittingClientSize(), Fit()
*/
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.
+ 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
This is commonly done in the constructor of the window
itself, see sample in the description
of wxBoxSizer. Returns the new window size.
-
+
@see ComputeFittingClientSize(), ComputeFittingWindowSize()
*/
wxSize Fit(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.
-
- @see wxScrolledWindow::SetScrollbars, SetVirtualSizeHints()
+ 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);
- //@{
/**
Returns the list of the items in this sizer. The elements of type-safe
- wxList @c wxSizerItemList are objects of type
- @ref overview_wxsizeritem "wxSizerItem *".
+ wxList @a wxSizerItemList are pointers to objects of type
+ @ref wxSizerItem "wxSizerItem".
*/
- const wxSizerItemList GetChildren();
- wxSizerItemList GetChildren();
- //@}
+ wxSizerItemList& GetChildren();
+
+ /**
+ Returns the list of the items in this sizer. The elements of type-safe
+ wxList @a wxSizerItemList are pointers to objects of type
+ @ref wxSizerItem "wxSizerItem".
+ */
+ const wxSizerItemList& GetChildren() const;
/**
Returns the window this sizer is used in or @NULL if none.
*/
- wxWindow* GetContainingWindow();
+ 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
*/
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.
-
- 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
*/
wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1);
- //@{
/**
- Returns @true if the @e window, @e sizer, or item at @a index is shown.
-
- @see Hide(), Show()
+ Returns @true if the @e window is shown.
+
+ @see Hide(), Show(), wxSizerItem::IsShown()
*/
- bool IsShown(wxWindow* window);
- bool IsShown(wxSizer* sizer);
- bool IsShown(size_t index);
- //@}
+ bool IsShown(wxWindow* window) 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
*/
void Layout();
- //@{
/**
Same as Add(), but prepends the items to the beginning of the
list of items (windows, subsizers or spaces) owned by this sizer.
*/
wxSizerItem* Prepend(wxWindow* window, const wxSizerFlags& flags);
+
+ /**
+ Same as Add(), but prepends the items to the beginning of the
+ list of items (windows, subsizers or spaces) owned by this sizer.
+ */
wxSizerItem* Prepend(wxWindow* window, int proportion = 0,
int flag = 0,
int border = 0,
wxObject* userData = NULL);
+
+ /**
+ Same as Add(), but prepends the items to the beginning of the
+ list of items (windows, subsizers or spaces) owned by this sizer.
+ */
wxSizerItem* Prepend(wxSizer* sizer,
const wxSizerFlags& flags);
+
+ /**
+ Same as Add(), but prepends the items to the beginning of the
+ list of items (windows, subsizers or spaces) owned by this sizer.
+ */
wxSizerItem* Prepend(wxSizer* sizer, int proportion = 0,
int flag = 0,
int border = 0,
wxObject* userData = NULL);
+
+ /**
+ Same as Add(), but prepends the items to the beginning of the
+ list of items (windows, subsizers or spaces) owned by this sizer.
+ */
wxSizerItem* Prepend(int width, int height,
int proportion = 0,
int flag = 0,
int border = 0,
wxObject* userData = NULL);
- //@}
/**
- Prepends non-stretchable space to the sizer. More readable way of calling
- wxSizer::Prepend(size, size, 0).
+ Prepends non-stretchable space to the sizer. More readable way of
+ calling wxSizer::Prepend(size, size, 0).
*/
wxSizerItem* PrependSpacer(int size);
/**
This method is abstract and has to be overwritten by any derived class.
- Here, the sizer will do the actual calculation of its children's positions
- and sizes.
+ Here, the sizer will do the actual calculation of its children's
+ positions and sizes.
*/
void RecalcSizes();
- //@{
/**
- 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). @a sizer is the wxSizer to be removed,
- @a index is the position of the child in the sizer, e.g. 0 for the first item.
- 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.
- @b NB: The 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.
- Returns @true if the child item was found and removed, @false otherwise.
+ Removes a child window from the sizer, but does @b not destroy it
+ (because windows are owned by their parent window, not the sizer).
+
+ @deprecated
+ The overload of this method taking a wxWindow* parameter
+ is deprecated as it does not destroy the window as would usually be
+ expected from Remove(). You should use Detach() in new code instead.
+ There is currently no wxSizer method that will both detach and destroy
+ a wxWindow item.
+
+ @note This method does not cause any layout or resizing to take
+ place, call Layout() to update the layout "on screen" after
+ removing a child from the sizer.
+
+ @return @true if the child item was found and removed, @false otherwise.
*/
bool Remove(wxWindow* window);
+
+ /**
+ 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.
+ */
bool Remove(wxSizer* 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).
+
+ @note This method does not cause any layout or resizing to take
+ place, call Layout() to update the layout "on screen" after
+ removing a child from the sizer.
+
+ @param index The position of the child in the sizer, e.g. 0 for the
+ first item.
+
+ @return @true if the child item was found and removed, @false otherwise.
+ */
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).
- Use parameter @a recursive to search the given element recursively in subsizers.
+ 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 method does not cause any layout or resizing to take place, call
- Layout() to update the layout "on screen" after replacing a
+ 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(wxWindow* oldwin, wxWindow* newwin,
bool recursive = false);
+
+ /**
+ Detaches the given @a oldsz from the sizer and
+ replaces it with the given @a newsz. The detached
+ child sizer is deleted.
+
+ Use parameter @a recursive to search the given element recursively in subsizers.
+
+ 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 @a newitem.
+
+ The detached child is deleted @b only if it is a sizer or a spacer
+ (but not if it is a wxWindow because windows are owned by their
+ parent window, not the sizer).
+
+ This method does not cause any layout or resizing to take place,
+ call Layout() to update the layout "on screen" after replacing a
+ child from the sizer.
+
+ Returns @true if the child item was found and removed, @false otherwise.
+ */
+ bool Replace(size_t index, wxSizerItem* newitem);
/**
- 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.
+ 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);
+
+ /**
+ @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 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.
+ 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 SetMinSize(int width, int height);
void SetMinSize(const wxSize& size);
- //@}
+
+ /**
+ @overload
+ */
+ void SetMinSize(int width, int height);
/**
This method first calls Fit() and then
the sizer's
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.
+ 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);
- //@}
};
+
/**
@class wxGridSizer
@wxheader{sizer.h}
@library{wxcore}
@category{winlayout}
- @seealso
- wxSizer, @ref overview_sizeroverview "Sizer overview"
+ @see wxSizer, @ref overview_sizer "Sizer Overview"
*/
class wxGridSizer : public wxSizer
{
};
+
/**
@class wxStaticBoxSizer
@wxheader{sizer.h}
@library{wxcore}
@category{winlayout}
- @seealso
- wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizeroverview "Sizer overview"
+ @see wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizer
+ "Sizer Overview"
*/
class wxStaticBoxSizer : public wxBoxSizer
{
};
+
/**
@class wxBoxSizer
@wxheader{sizer.h}
simple basic geometry, typically in a row or a column or several hierarchies of
either.
- For more information, please see @ref overview_boxsizerprogramming "Programming
- with wxBoxSizer".
+ For more information, please see @ref overview_sizer_box
+ "Programming with wxBoxSizer".
@library{wxcore}
@category{winlayout}
- @seealso
- wxSizer, @ref overview_sizeroverview "Sizer overview"
+ @see wxSizer, @ref overview_sizer "Sizers Overview"
*/
class wxBoxSizer : public wxSizer
{
*/
void RecalcSizes();
};
+
projects / wxWidgets.git / blobdiff