// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
+
+/**
+ A generic orientation value.
+*/
+enum wxOrientation
+{
+ /* don't change the values of these elements, they are used elsewhere */
+ wxHORIZONTAL = 0x0004,
+ wxVERTICAL = 0x0008,
+
+ wxBOTH = wxVERTICAL | wxHORIZONTAL,
+
+ /* a mask to extract orientation from the combination of flags */
+ wxORIENTATION_MASK = wxBOTH
+};
+
+
/**
@class wxStdDialogButtonSizer
class wxSizerItem : public wxObject
{
public:
- //@{
/**
- Construct a sizer item for tracking a subsizer.
+ Construct a sizer item for tracking a spacer.
*/
wxSizerItem(int width, int height, int proportion, int flag,
int border, wxObject* userData);
+
+ //@{
+ /**
+ Construct a sizer item for tracking a window.
+ */
wxSizerItem(wxWindow* window, const wxSizerFlags& flags);
wxSizerItem(wxWindow* window, int proportion, int flag,
int border,
wxObject* userData);
+ //@}
+
+ //@{
+ /**
+ Construct a sizer item for tracking a subsizer.
+ */
wxSizerItem(wxSizer* window, const wxSizerFlags& flags);
wxSizerItem(wxSizer* sizer, int proportion, int flag,
int border,
wxObject* GetUserData() const;
/**
- If this item is tracking a window then return it. @NULL otherwise.
+ If this item is tracking a window then return it. @NULL otherwise.
*/
wxWindow* GetWindow() const;
virtual void SetDimension(const wxPoint& pos, const wxSize& size);
/**
- Set the flag item attribute.
+ Set the flag item attribute.
*/
void SetFlag(int flag);
void SetId(int id);
/**
-
+ @todo docme.
*/
void SetInitSize(int x, int y);
/**
Set the show item attribute, which sizers use to determine if the item
- is to be made part of the layout or not. If the item is tracking a
+ is to be made part of the layout or not. If the item is tracking a
window then it is shown or hidden as needed.
*/
void Show(bool show);
{
public:
/**
- Creates the wxSizer with the proportion specified by @e proportion.
+ Creates the wxSizer with the proportion specified by @a proportion.
*/
wxSizerFlags(int proportion = 0);
/**
- Sets the alignment of this wxSizerFlags to @e align.
+ Sets the alignment of this wxSizerFlags to @a align.
- This method replaces the previously set alignment with the specified
- one.
+ 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.
- @param align Combination of @c wxALIGN_XXX bit masks.
+ @see Top(), Left(), Right(), Bottom(), Centre()
*/
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.
+ by @a borderinpixels with the directions specified by @a direction.
*/
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.
+ @param direction
+ Direction(s) to apply the border in.
*/
wxSizerFlags& Border(int direction = wxALL);
@class wxFlexGridSizer
A flex grid sizer is a sizer which lays out its children in a two-dimensional
- table with all table fields in one row having the same
- height and all fields in one column having the same width, but all
- rows or all columns are not necessarily the same height or width as in
- the wxGridSizer.
+ table with all table fields in one row having the same height and all fields
+ in one column having the same width, but all rows or all columns are not
+ necessarily the same height or width as in the wxGridSizer.
Since wxWidgets 2.5.0, wxFlexGridSizer can also size items equally in one
direction but unequally ("flexibly") in the other. If the sizer is only
- flexible in one direction (this can be changed using
- wxFlexGridSizer::SetFlexibleDirection),
+ flexible in one direction (this can be changed using wxFlexGridSizer::SetFlexibleDirection),
it needs to be decided how the sizer should grow in the other ("non-flexible")
- direction in order to fill the available space. The
- wxFlexGridSizer::SetNonFlexibleGrowMode method
- serves this purpose.
+ direction in order to fill the available space.
+ The wxFlexGridSizer::SetNonFlexibleGrowMode() method serves this purpose.
@library{wxcore}
@category{winlayout}
- @see wxSizer, @ref overview_sizer "Sizer Overview"
+ @see wxSizer, @ref overview_sizer
*/
class wxFlexGridSizer : public wxGridSizer
{
public:
//@{
/**
- Constructor for a wxGridSizer. @a rows and @a cols determine the number of
- columns and rows in the sizer - if either of the parameters is zero, it will be
- calculated to form the total number of children in the sizer, thus making the
- sizer grow dynamically. @a vgap and @a hgap define extra space between
- all children.
+ Constructor for a wxFlexGridSizer.
+
+ @a rows and @a cols determine the number of columns and rows in the sizer -
+ if either of the parameters is zero, it will be calculated to form the
+ total number of children in the sizer, thus making the sizer grow
+ dynamically.
+
+ @a vgap and @a hgap define extra space between all children.
*/
wxFlexGridSizer(int rows, int cols, int vgap, int hgap);
wxFlexGridSizer(int cols, int vgap = 0, int hgap = 0);
Returns a wxOrientation value that specifies whether the sizer flexibly
resizes its columns, rows, or both (default).
- @return One of the following values:
+ @return
+ One of the following values:
+ - wxVERTICAL: Rows are flexibly sized.
+ - wxHORIZONTAL: Columns are flexibly sized.
+ - wxBOTH: Both rows and columns are flexibly sized (this is the default value).
@see SetFlexibleDirection()
*/
Returns the value that specifies how the sizer grows in the "non-flexible"
direction if there is one.
- @return One of the following values:
+ @return
+ One of the following values:
+ - wxFLEX_GROWMODE_NONE: Sizer doesn't grow in the non-flexible direction.
+ - wxFLEX_GROWMODE_SPECIFIED: Sizer honors growable columns/rows set with
+ AddGrowableCol() and AddGrowableRow(). In this case equal sizing applies
+ to minimum sizes of columns or rows (this is the default value).
+ - wxFLEX_GROWMODE_ALL: Sizer equally stretches all columns or rows in
+ the non-flexible direction, whether they are growable or not in the
+ flexible direction.
- @see SetFlexibleDirection(),
- SetNonFlexibleGrowMode()
+ @see SetFlexibleDirection(), SetNonFlexibleGrowMode()
*/
int GetNonFlexibleGrowMode() const;
void RemoveGrowableRow(size_t idx);
/**
- 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 GetFlexibleDirection() GetFlexibleDirection for the
- explanation of these values.
+ Specifies whether the sizer should flexibly resize its columns, rows, or both.
+
+ Argument @a direction can be @c wxVERTICAL, @c wxHORIZONTAL or @c wxBOTH
+ (which is the default value). Any other value is ignored.
+ See GetFlexibleDirection() for the explanation of these values.
Note that this method does not trigger relayout.
*/
void SetFlexibleDirection(int direction);
/**
Specifies how the sizer should grow in the non-flexible direction if
- there is one (so
- SetFlexibleDirection() must have
- been called previously). Argument @a mode can be one of those documented in
- GetNonFlexibleGrowMode(), please
- see there for their explanation.
+ there is one (so SetFlexibleDirection() must have been called previously).
+
+ Argument @a mode can be one of those documented in GetNonFlexibleGrowMode(),
+ please see there for their explanation.
Note that this method does not trigger relayout.
*/
void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode);
@class wxSizer
wxSizer is the abstract base class used for laying out subwindows in a window.
- You
- cannot use wxSizer directly; instead, you will have to use one of the sizer
- classes derived from it. Currently there are wxBoxSizer,
- wxStaticBoxSizer,
- wxGridSizer,
- wxFlexGridSizer,
- wxWrapSizer
- and wxGridBagSizer.
+ You cannot use wxSizer directly; instead, you will have to use one of the sizer
+ classes derived from it. Currently there are wxBoxSizer, wxStaticBoxSizer,
+ wxGridSizer, wxFlexGridSizer, wxWrapSizer and wxGridBagSizer.
The layout algorithm used by sizers in wxWidgets is closely related to layout
in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit.
- It is
- based upon the idea of the individual subwindows reporting their minimal
- required
- size and their ability to get stretched if the size of the parent window has
- changed.
+ It is based upon the idea of the individual subwindows reporting their minimal
+ required size and their ability to get stretched if the size of the parent window
+ has changed.
+
This will most often mean that the programmer does not set the original size of
a dialog in the beginning, rather the dialog will be assigned a sizer and this
- sizer
- will be queried about the recommended size. The sizer in turn will query its
- children, which can be normal windows, empty space or other sizers, so that
+ sizer will be queried about the recommended size. The sizer in turn will query
+ its children, which can be normal windows, empty space or other sizers, so that
a hierarchy of sizers can be constructed. Note that wxSizer does not derive
- from wxWindow
- and thus does not interfere with tab ordering and requires very little
- resources compared
- to a real window on screen.
+ from wxWindow and thus does not interfere with tab ordering and requires very little
+ resources compared to a real window on screen.
What makes sizers so well fitted for use in wxWidgets is the fact that every
- control
- reports its own minimal size and the algorithm can handle differences in font
- sizes
- or different window (dialog item) sizes on different platforms without
- problems. If e.g.
- the standard font as well as the overall design of Motif widgets requires more
- space than
- on Windows, the initial dialog size will automatically be bigger on Motif than
- on Windows.
+ control reports its own minimal size and the algorithm can handle differences in
+ font sizes or different window (dialog item) sizes on different platforms without
+ problems. If e.g. the standard font as well as the overall design of Motif widgets
+ requires more space than on Windows, the initial dialog size will automatically
+ be bigger on Motif than on Windows.
Sizers may also be used to control the layout of custom drawn items on the
- window. The 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 wxSizer::Add(), wxSizer::Insert(), and wxSizer::Prepend() functions
+ return a pointer to the newly added wxSizerItem.
+ Just add empty space of the desired size and attributes, and then use the
+ wxSizerItem::GetRect() method to determine where the drawing operations
+ should take place.
Please notice that sizers, like child windows, are owned by the library and
- will be deleted by it which implies that they must be allocated on the
- heap. However if you create a sizer and do not add it to another sizer or
+ 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
+ @beginWxPythonOnly
+ If you wish to create a sizer class in wxPython you should
derive the class from @c wxPySizer in order to get Python-aware
capabilities for the various virtual methods.
+ @endWxPythonOnly
@anchor wxsizer_flags
@par wxSizer flags
+
The "flag" argument accepted by wxSizeItem constructors and other
functions, e.g. wxSizer::Add(), is OR-combination of the following flags.
Two main behaviours are defined using these flags. One is the border around
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>
border if any.}
@endDefList
-
@library{wxcore}
@category{winlayout}
- @see @ref overview_sizer "Sizer Overview"
+ @see @ref overview_sizer
*/
class wxSizer : public wxObject
{
public:
/**
- The constructor. Note that wxSizer is an abstract base class and may not
- be instantiated.
+ The constructor.
+ Note that wxSizer is an abstract base class and may not be instantiated.
*/
wxSizer();
derived classes when sizing information is more complex than the
proportion and flag will allow for.
*/
- wxSizerItem* Add(wxWindow* window, int proportion = 0,
+ wxSizerItem* Add(wxWindow* window,
+ int proportion = 0,
int flag = 0,
int border = 0,
wxObject* userData = NULL);
derived classes when sizing information is more complex than the
proportion and flag will allow for.
*/
- wxSizerItem* Add(wxSizer* sizer, int proportion = 0,
+ wxSizerItem* Add(wxSizer* sizer,
+ int proportion = 0,
int flag = 0,
int border = 0,
wxObject* userData = NULL);
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,
+ 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
+ Adds non-stretchable space to the sizer.
+ More readable way of calling:
+ @code
wxSizer::Add(size, size, 0).
+ @endcode
*/
wxSizerItem* AddSpacer(int size);
/**
- Adds stretchable space to the sizer. More readable way of calling
+ Adds stretchable space to the sizer.
+ More readable way of calling:
+ @code
wxSizer::Add(0, 0, prop).
+ @endcode
*/
wxSizerItem* AddStretchSpacer(int prop = 1);
virtual wxSize CalcMin();
/**
- Detaches all children from the sizer. If @a delete_windows is @true then
- child windows will also be deleted.
+ Detaches all children from the sizer.
+ If @a delete_windows is @true then child windows will also be deleted.
*/
virtual void Clear(bool delete_windows = false);
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
+ previously set by wxWindow::SetMaxSize().
+
+ The returned value is suitable for passing to wxWindow::SetClientSize() or
wxWindow::SetMinClientSize().
@since 2.8.8
/**
Tell the sizer to resize the @a window so that its client area matches the
- sizer's minimal size
- (ComputeFittingClientSize() is called
- to determine it).
- This is commonly done in the constructor of the window
- itself, see sample in the description
- of wxBoxSizer. Returns the new window size.
+ sizer's minimal size (ComputeFittingClientSize() is called to determine it).
+ This is commonly done in the constructor of the window itself, see sample
+ in the description of wxBoxSizer.
+
+ @return The new window size.
@see ComputeFittingClientSize(), ComputeFittingWindowSize()
*/
/**
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
+ 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.
*/
void FitInside(wxWindow* window);
+ //@{
/**
- 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".
- */
- wxSizerItemList& GetChildren();
+ Returns the list of the items in this sizer.
- /**
- 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".
+ The elements of type-safe wxList @c wxSizerItemList are pointers to
+ objects of type wxSizerItem.
*/
+ wxSizerItemList& GetChildren();
const wxSizerItemList& GetChildren() const;
+ //@}
/**
Returns the window this sizer is used in or @NULL if none.
wxWindow* GetContainingWindow() const;
/**
- Finds wxSizerItem which holds the given @a window
+ 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
+ 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.
+ 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
- window id but the id of the wxSizerItem itself. This is mainly useful for
- retrieving the sizers created from XRC resources.
+ Finds item of the sizer which has the given @e id.
+ This @a id is not the window id but the id of the wxSizerItem itself.
+ This is mainly useful for retrieving the sizers created from XRC resources.
Use parameter @a recursive to search in subsizers too.
Returns pointer to item or @NULL.
*/
wxSizerItem* GetItemById(int id, bool recursive = false);
/**
- Returns the minimal size of the sizer. This is either the combined minimal
- size of all the children and their borders or the minimal size set by
- SetMinSize(), depending on which is bigger.
+ Returns the minimal size of the sizer.
+
+ This is either the combined minimal size of all the children and their
+ borders or the minimal size set by SetMinSize(), depending on which is bigger.
Note that the returned value is client size, not window size.
In particular, if you use the value to set toplevel window's minimal or
- actual size, use wxWindow::SetMinClientSize
- or wxWindow::SetClientSize, not
- wxWindow::SetMinSize
- or wxWindow::SetSize.
+ actual size, use wxWindow::SetMinClientSize() or wxWindow::SetClientSize(),
+ not wxWindow::SetMinSize() or wxWindow::SetSize().
*/
wxSize GetMinSize();
wxObject* userData = NULL);
/**
- Inserts non-stretchable space to the sizer. More readable way of calling
- wxSizer::Insert(size, size, 0).
+ Inserts non-stretchable space to the sizer.
+ More readable way of calling wxSizer::Insert(size, size, 0).
*/
wxSizerItem* InsertSpacer(size_t index, int size);
/**
- Inserts stretchable space to the sizer. More readable way of calling
- wxSizer::Insert(0, 0, prop).
+ Inserts stretchable space to the sizer.
+ More readable way of calling wxSizer::Insert(0, 0, prop).
*/
wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1);
/**
- Returns @true if the @e window is shown.
+ Returns @true if the @a window is shown.
@see Hide(), Show(), wxSizerItem::IsShown()
*/
bool IsShown(wxWindow* window) const;
/**
- Returns @true if the @e sizer is shown.
+ Returns @true if the @a sizer is shown.
@see Hide(), Show(), wxSizerItem::IsShown()
*/
/**
Call this to force layout of the children anew, e.g. after having added a child
to or removed a child (window, other sizer or space) from the sizer while
- keeping
- the current dimension.
+ keeping the current dimension.
*/
virtual void Layout();
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);
/**
- Prepends stretchable space to the sizer. More readable way of calling
- wxSizer::Prepend(0, 0, prop).
+ Prepends stretchable space to the sizer.
+ More readable way of calling wxSizer::Prepend(0, 0, prop).
*/
wxSizerItem* PrependStretchSpacer(int prop = 1);
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.
+ @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 @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).
+ Detaches the given @a oldwin from the sizer and replaces it with the
+ given @a newwin. The detached child window is @b not deleted (because
+ windows are owned by their parent window, not the sizer).
Use parameter @a recursive to search the given element recursively in subsizers.
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.
+ Detaches the given @a oldsz from the sizer and replaces it with the
+ given @a newsz. The detached child sizer is deleted.
Use parameter @a recursive to search the given element recursively in subsizers.
/**
Set 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
+ 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()
/**
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
+ 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()
/**
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
+ 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(const wxSize& size);
void SetMinSize(int width, int height);
/**
- This method first calls Fit() and then
- wxTopLevelWindow::SetSizeHints on the @e window
- passed to it. This only makes sense when @a window is actually a
- wxTopLevelWindow such as a wxFrame or a
- wxDialog, since SetSizeHints only has any effect in these classes.
+ This method first calls Fit() and then wxTopLevelWindow::SetSizeHints()
+ on the @a window passed to it.
+
+ This only makes sense when @a window is actually a wxTopLevelWindow such
+ as a wxFrame or a wxDialog, since SetSizeHints only has any effect in these classes.
It does nothing in normal windows or controls.
- This method is implicitly used by wxWindow::SetSizerAndFit
- which is commonly invoked in the constructor of a toplevel window itself (see
- the sample in the description of wxBoxSizer) if the
- toplevel window is resizable.
+
+ This method is implicitly used by wxWindow::SetSizerAndFit() which is
+ commonly invoked in the constructor of a toplevel window itself (see
+ the sample in the description of wxBoxSizer) if the toplevel window is
+ resizable.
*/
void SetSizeHints(wxWindow* window);
/**
Tell the sizer to set the minimal size of the @a window virtual area to match
- the sizer's
- minimal size. For windows with managed scrollbars this will set them
+ the sizer's minimal size. For windows with managed scrollbars this will set them
appropriately.
- @see wxScrolled::SetScrollbars()
@deprecated @todo provide deprecation description
+
+ @see wxScrolled::SetScrollbars()
*/
void SetVirtualSizeHints(wxWindow* window);
@class wxGridSizer
A grid sizer is a sizer which lays out its children in a two-dimensional
- table with all table fields having the same size,
- i.e. the width of each field is the width of the widest child,
- the height of each field is the height of the tallest child.
+ table with all table fields having the same size, i.e. the width of each
+ field is the width of the widest child, the height of each field is the
+ height of the tallest child.
@library{wxcore}
@category{winlayout}
- @see wxSizer, @ref overview_sizer "Sizer Overview"
+ @see wxSizer, @ref overview_sizer
*/
class wxGridSizer : public wxSizer
{
public:
//@{
/**
- Constructor for a wxGridSizer. @a rows and @a cols determine the number of
- columns and rows in the sizer - if either of the parameters is zero, it will be
- calculated to form the total number of children in the sizer, thus making the
- sizer grow dynamically. @a vgap and @a hgap define extra space between
- all children.
+ Constructor for a wxGridSizer.
+
+ @a rows and @a cols determine the number of columns and rows in the sizer -
+ if either of the parameters is zero, it will be calculated to form the
+ total number of children in the sizer, thus making the sizer grow dynamically.
+
+ @a vgap and @a hgap define extra space between all children.
*/
wxGridSizer(int rows, int cols, int vgap, int hgap);
wxGridSizer(int cols, int vgap = 0, int hgap = 0);
@class wxStaticBoxSizer
wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static
- box around the sizer. This static box may be either created independently or
- the sizer may create it itself as a convenience. In any case, the sizer owns
- the wxStaticBox control and will delete it if it is
- deleted.
+ box around the sizer.
+ This static box may be either created independently or the sizer may create
+ it itself as a convenience. In any case, the sizer owns the wxStaticBox control
+ and will delete it, if it is deleted.
@library{wxcore}
@category{winlayout}
@see wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizer
- "Sizer Overview"
*/
class wxStaticBoxSizer : public wxBoxSizer
{
public:
- //@{
/**
- The first constructor uses an already existing static box. It takes the
- associated static box and the orientation @e orient, which can be either
- @c wxVERTICAL or @c wxHORIZONTAL as parameters.
- The second one creates a new static box with the given label and parent window.
+ This constructor uses an already existing static box.
+
+ It takes the associated static box and the orientation @a orient, which
+ can be either @c wxVERTICAL or @c wxHORIZONTAL as parameters.
*/
wxStaticBoxSizer(wxStaticBox* box, int orient);
+
+ /**
+ This constructor creates a new static box with the given label and parent window.
+ */
wxStaticBoxSizer(int orient, wxWindow parent,
const wxString& label = wxEmptyString);
- //@}
/**
Returns the static box associated with the sizer.
@class wxBoxSizer
The basic idea behind a box sizer is that windows will most often be laid out
- in rather
- simple basic geometry, typically in a row or a column or several hierarchies of
- either.
+ in rather simple basic geometry, typically in a row or a column or several
+ hierarchies of either.
- For more information, please see @ref overview_sizer_box
- "Programming with wxBoxSizer".
+ For more information, please see @ref overview_sizer_box.
@library{wxcore}
@category{winlayout}
- @see wxSizer, @ref overview_sizer "Sizers Overview"
+ @see wxSizer, @ref overview_sizer
*/
class wxBoxSizer : public wxSizer
{
wxBoxSizer(int orient);
/**
- Implements the calculation of a box sizer's minimal. It is used internally
- only and must not be called by the user. Documented for information.
+ Implements the calculation of a box sizer's minimal.
+
+ It is used internally only and must not be called by the user.
+ Documented for information.
*/
virtual wxSize CalcMin();
/**
Implements the calculation of a box sizer's dimensions and then sets
- the size of its children (calling wxWindow::SetSize
- if the child is a window). It is used internally only and must not be called
- by the user (call Layout() if you want to resize). Documented for information.
+ the size of its children (calling wxWindow::SetSize if the child is a window).
+
+ It is used internally only and must not be called by the user
+ (call Layout() if you want to resize). Documented for information.
*/
void RecalcSizes();
};
Minimum slider position.
@param maxValue
Maximum slider position.
+ @param pos
+ Window position. If wxDefaultPosition is specified then a default position is chosen.
@param size
Window size. If wxDefaultSize is specified then a default size is chosen.
@param style
*/
wxSlider(wxWindow* parent, wxWindowID id, int value,
int minValue, int maxValue,
- const wxPoint& point = wxDefaultPosition,
+ const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = wxSL_HORIZONTAL,
const wxValidator& validator = wxDefaultValidator,
@class wxSingleInstanceChecker
wxSingleInstanceChecker class allows to check that only a single instance of a
- program is running. To do it, you should create an object of this class. As
- long as this object is alive, calls to
- wxSingleInstanceChecker::IsAnotherRunning from
- other processes will return @true.
+ program is running.
+
+ To do it, you should create an object of this class. As long as this object
+ is alive, calls to wxSingleInstanceChecker::IsAnotherRunning from other
+ processes will return @true.
As the object should have the life span as big as possible, it makes sense to
- create it either as a global or in wxApp::OnInit. For
- example:
+ create it either as a global or in wxApp::OnInit.
+ For example:
@code
bool MyApp::OnInit()
}
@endcode
- Note using wxGetUserId() to construct the name: this
- allows different user to run the application concurrently which is usually the
- intended goal. If you don't use the user name in the wxSingleInstanceChecker
- name, only one user would be able to run the application at a time.
+ Note using wxGetUserId() to construct the name: this allows different user
+ to run the application concurrently which is usually the intended goal.
+ If you don't use the user name in the wxSingleInstanceChecker name, only
+ one user would be able to run the application at a time.
This class is implemented for Win32 and Unix platforms (supporting @c fcntl()
system call, but almost all of modern Unix systems do) only.
{
public:
/**
- Like Create() but without
- error checking.
+ Default ctor, use Create() after it.
+ */
+ wxSingleInstanceChecker();
+
+ /**
+ Like Create() but without error checking.
*/
wxSingleInstanceChecker(const wxString& name,
const wxString& path = wxEmptyString);
/**
Destructor frees the associated resources.
- Note that it is not virtual, this class is not meant to be used polymorphically
+ Note that it is not virtual, this class is not meant to be used polymorphically.
*/
~wxSingleInstanceChecker();
/**
Initialize the object if it had been created using the default constructor.
Note that you can't call Create() more than once, so calling it if the
- @ref wxsingleinstancechecker() "non default ctor"
- had been used is an error.
+ @ref wxSingleInstanceChecker() "non default ctor" had been used is an error.
@param name
- must be given and be as unique as possible. It is used as the
+ Must be given and be as unique as possible. It is used as the
mutex name under Win32 and the lock file name under Unix.
- GetAppName() and wxGetUserId()
- are commonly used to construct this parameter.
+ GetAppName() and wxGetUserId() are commonly used to construct
+ this parameter.
@param path
- is optional and is ignored under Win32 and used as the directory to
- create the lock file in under Unix (default is
- wxGetHomeDir())
+ The path is optional and is ignored under Win32 and used as the
+ directory to create the lock file in under Unix
+ (default is wxGetHomeDir()).
@return Returns @false if initialization failed, it doesn't mean that
- another instance is running - use IsAnotherRunning()
- to check for it.
+ another instance is running - use IsAnotherRunning() to check
+ for it.
+
+ @note
+ One of possible reasons while Create may fail on Unix is that the lock
+ file used for checking already exists but was not created by the user.
+ Therefore applications shouldn't treat failure of this function as fatal
+ condition, because doing so would open them to the possibility of a
+ Denial of Service attack. Instead, they should alert the user about
+ the problem and offer to continue execution without checking if
+ another instance is running.
*/
bool Create(const wxString& name,
const wxString& path = wxEmptyString);
/////////////////////////////////////////////////////////////////////////////
// Name: socket.h
-// Purpose: interface of wxIPV4address
+// Purpose: interface of wxIP*address, wxSocket* classes
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
Set the address to hostname, which can be a host name or an IP-style address
- in dot notation(<tt>a.b.c.d</tt>)
+ in dot notation(<tt>a.b.c.d</tt>).
- @return @true on success, @false if something goes wrong (invalid hostname or
- invalid IP address).
+ @return @true on success, @false if something goes wrong (invalid
+ hostname or invalid IP address).
*/
bool Hostname(const wxString& hostname);
correctly handle multi-homed hosts and avoid other small problems.
@return @true on success, @false if something went wrong.
-
*/
bool LocalHost();
Set the port to that corresponding to the specified @a service.
@return @true on success, @false if something goes wrong (invalid @a service).
-
*/
bool Service(const wxString& service);
/**
@class wxSocketServer
+ @todo describe me.
+
@library{wxnet}
@category{net}
*/
@param address
Specifies the local address for the server (e.g. port number).
@param flags
- Socket flags (See wxSocketBase::SetFlags())
+ Socket flags (See wxSocketBase::SetFlags()).
*/
wxSocketServer(const wxSockAddress& address,
wxSocketFlags flags = wxSOCKET_NONE);
virtual ~wxSocketServer();
/**
- Accepts an incoming connection request, and creates a new wxSocketBase object
- which represents the server-side of the connection.
+ Accepts an incoming connection request, and creates a new wxSocketBase
+ object which represents the server-side of the connection.
If @a wait is @true and there are no pending connections to be
accepted, it will wait for the next incoming connection to
- arrive. @b Warning: This will block the GUI.
+ arrive.
+
+ @warning: This method will block the GUI.
If @a wait is @false, it will try to accept a pending connection
if there is one, but it will always return immediately without blocking
@param socket
Socket to be initialized
+ @param wait
+ See Accept() for more info.
- @return Returns @true on success, or @false if an error occurred or if the
- wait parameter was @false and there were no pending
- connections.
+ @return Returns @true on success, or @false if an error occurred or
+ if the wait parameter was @false and there were no pending
+ connections.
@see WaitForAccept(), wxSocketBase::SetNotify(),
wxSocketBase::Notify(), Accept()
bool AcceptWith(wxSocketBase& socket, bool wait = true);
/**
- This function waits for an incoming connection. Use it if you want to call
- Accept() or AcceptWith()
- with @e wait set to @false, to detect when an incoming connection is waiting
- to be accepted.
+ This function waits for an incoming connection.
+
+ Use it if you want to call Accept() or AcceptWith() with @e wait set
+ to @false, to detect when an incoming connection is waiting to be accepted.
@param seconds
Number of seconds to wait. If -1, it will wait for the default
/**
Returns the hostname which matches the IP address.
*/
- virtual wxString Hostname();
+ virtual wxString Hostname();
/**
Returns a wxString containing the IP address.
/**
@class wxSocketClient
+ @todo describe me.
+
@library{wxnet}
@category{net}
*/
Connects to a server using the specified address.
If @a wait is @true, Connect() will wait until the connection
- completes. @b Warning: This will block the GUI.
+ completes.
+
+ @warning: This method will block the GUI.
If @a wait is @false, Connect() will try to establish the connection
and return immediately, without blocking the GUI. When used this way,
If @true, waits for the connection to complete.
@return @true if the connection is established and no error occurs.
+ If @a wait was true, and Connect() returns @false, an error
+ occurred and the connection failed.
+ If @a wait was @false, and Connect() returns @false, you should
+ still be prepared to handle the completion of this connection request,
+ either with WaitOnConnect() or by watching wxSOCKET_CONNECTION
+ and wxSOCKET_LOST events.
@see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
*/
If @true, waits for the connection to complete.
@return @true if the connection is established and no error occurs.
+ If @a wait was true, and Connect() returns @false, an error
+ occurred and the connection failed.
+ If @a wait was @false, and Connect() returns @false, you should
+ still be prepared to handle the completion of this connection request,
+ either with WaitOnConnect() or by watching wxSOCKET_CONNECTION
+ and wxSOCKET_LOST events.
@see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
*/
/**
Wait until a connection request completes, or until the specified timeout
- elapses. Use this function after issuing a call
- to Connect() with @e wait set to @false.
+ elapses. Use this function after issuing a call to Connect() with
+ @e wait set to @false.
@param seconds
Number of seconds to wait.
- If -1, it will wait for the default timeout,
- as set with wxSocketBase::SetTimeout().
- @param millisecond
+ If -1, it will wait for the default timeout, as set with wxSocketBase::SetTimeout().
+ @param milliseconds
Number of milliseconds to wait.
- @return WaitOnConnect() returns @true if the connection request completes.
- This does not necessarily mean that the connection was
- successfully established; it might also happen that the
- connection was refused by the peer. Use wxSocketBase::IsConnected()
- to distinguish between these two situations.
- @n @n If the timeout elapses, WaitOnConnect() returns @false.
- @n @n These semantics allow code like this:
- @code
- // Issue the connection request
- client->Connect(addr, false);
-
- // Wait until the request completes or until we decide to give up
- bool waitmore = true;
- while ( !client->WaitOnConnect(seconds, millis) && waitmore )
- {
- // possibly give some feedback to the user,
- // and update waitmore as needed.
- }
- bool success = client->IsConnected();
- @endcode
+ @return
+ WaitOnConnect() returns @true if the connection request completes.
+ This does not necessarily mean that the connection was
+ successfully established; it might also happen that the
+ connection was refused by the peer. Use wxSocketBase::IsConnected()
+ to distinguish between these two situations.
+ @n @n If the timeout elapses, WaitOnConnect() returns @false.
+ @n @n These semantics allow code like this:
+ @code
+ // Issue the connection request
+ client->Connect(addr, false);
+
+ // Wait until the request completes or until we decide to give up
+ bool waitmore = true;
+ while ( !client->WaitOnConnect(seconds, millis) && waitmore )
+ {
+ // possibly give some feedback to the user,
+ // and update waitmore as needed.
+ }
+ bool success = client->IsConnected();
+ @endcode
*/
bool WaitOnConnect(long seconds = -1, long milliseconds = 0);
};
void* GetClientData() const;
/**
- Returns the socket object to which this event refers to. This makes
- it possible to use the same event handler for different sockets.
+ Returns the socket object to which this event refers to.
+ This makes it possible to use the same event handler for different sockets.
*/
wxSocketBase* GetSocket() const;
/**
+ @anchor wxSocketEventFlags
+
wxSocket Event Flags.
A brief note on how to use these events:
wxIPaddress::BroadcastAddress().
So:
- @b wxSOCKET_NONE will try to read at least SOME data, no matter how much.
- @b wxSOCKET_NOWAIT will always return immediately, even if it cannot
- read or write ANY data.
- @b wxSOCKET_WAITALL will only return when it has read or written ALL
- the data.
- @b wxSOCKET_BLOCK has nothing to do with the previous flags and
- it controls whether the GUI blocks.
- @b wxSOCKET_REUSEADDR controls special platform-specific behavior for
- reusing local addresses/ports.
+ - @b wxSOCKET_NONE will try to read at least SOME data, no matter how much.
+ - @b wxSOCKET_NOWAIT will always return immediately, even if it cannot
+ read or write ANY data.
+ - @b wxSOCKET_WAITALL will only return when it has read or written ALL
+ the data.
+ - @b wxSOCKET_BLOCK has nothing to do with the previous flags and
+ it controls whether the GUI blocks.
+ - @b wxSOCKET_REUSEADDR controls special platform-specific behavior for
+ reusing local addresses/ports.
*/
enum
{
/**
@class wxSocketBase
-
wxSocketBase is the base class for all socket-related objects, and it
defines all basic IO functionality.
- @b Note: (Workaround for implementation limitation for wxWidgets up to 2.5.x)
+ @note
+ (Workaround for implementation limitation for wxWidgets up to 2.5.x)
If you want to use sockets or derived classes such as wxFTP in a secondary
- thread,
- call @b wxSocketBase::Initialize() (undocumented) from the main thread before
- creating any sockets - in wxApp::OnInit() for example.
+ thread, call @b wxSocketBase::Initialize() (undocumented) from the main
+ thread before creating any sockets - in wxApp::OnInit() for example.
See http://wiki.wxwidgets.org/wiki.pl?WxSocket or
http://www.litwindow.com/knowhow/knowhow.html for more details.
- @library{wxnet}
- @category{net}
-
- <b>wxSocket events:</b>
- @beginFlagTable
- @flag{wxSOCKET_INPUT}
- There is data available for reading.
- @flag{wxSOCKET_OUTPUT}
- The socket is ready to be written to.
- @flag{wxSOCKET_CONNECTION}
- Incoming connection request (server), or successful connection
- establishment (client).
- @flag{wxSOCKET_LOST}
- The connection has been closed.
- @endFlagTable
-
@beginEventTable{wxSocketEvent}
@event{EVT_SOCKET(id, func)}
Process a @c wxEVT_SOCKET event.
+ See @ref wxSocketEventFlags and @ref wxSocketFlags for more info.
@endEventTable
+ @library{wxnet}
+ @category{net}
+
@see wxSocketEvent, wxSocketClient, wxSocketServer, @sample{sockets},
@ref wxSocketFlags, ::wxSocketEventFlags, ::wxSocketError
*/
cases.
@remarks
-
For wxSocketClient, IsOk() won't return @true unless the client is connected to a server.
-
For wxSocketServer, IsOk() will return @true if the server could bind to the specified address
and is already listening for new connections.
-
IsOk() does not check for IO errors; use Error() instead for that purpose.
-
*/
bool IsOk() const;
Returns the last wxSocket error. See @ref wxSocketError .
@note
-
This function merely returns the last error code,
but it should not be used to determine if an error has occurred (this
is because successful operations do not change the LastError value).
void RestoreState();
/**
- This function saves the current state of the socket in a stack. Socket
- state includes flags, as set with SetFlags(),
- event mask, as set with SetNotify() and
- Notify(), user data, as set with
- SetClientData().
+ This function saves the current state of the socket in a stack.
+ Socket state includes flags, as set with SetFlags(), event mask, as set
+ with SetNotify() and Notify(), user data, as set with SetClientData().
Calls to SaveState and RestoreState can be nested.
@see RestoreState()
the socket, typically to notify the peer that you are closing the connection.
@remarks
-
Although Close() immediately disables events for the socket, it is possible
that event messages may be waiting in the application's event queue.
The application must therefore be prepared to handle socket event messages even
socket destruction), so you don't need to use it in these cases.
@see Wait(), WaitForLost(), WaitForRead(), WaitForWrite(),
- wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
+ wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
*/
void InterruptWait();
@return Returns a reference to the current object.
@remarks
-
- The exact behaviour of Peek() depends on the combination of flags being used.
- For a detailed explanation, see SetFlags()
+ The exact behaviour of Peek() depends on the combination of flags being used.
+ For a detailed explanation, see SetFlags()
@see Error(), LastError(), LastCount(), SetFlags()
*/
@return Returns a reference to the current object.
@remarks
-
- The exact behaviour of Read() depends on the combination of flags being used.
- For a detailed explanation, see SetFlags()
+ The exact behaviour of Read() depends on the combination of flags being used.
+ For a detailed explanation, see SetFlags()
@see Error(), LastError(), LastCount(),
SetFlags()
@return Returns a reference to the current object.
@remarks
-
- ReadMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set
- and it will always ignore the @b wxSOCKET_NOWAIT flag. The exact behaviour
- of ReadMsg() depends on the @b wxSOCKET_BLOCK flag.
- For a detailed explanation, see SetFlags().
+ ReadMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set
+ and it will always ignore the @b wxSOCKET_NOWAIT flag.
+ The exact behaviour of ReadMsg() depends on the @b wxSOCKET_BLOCK flag.
+ For a detailed explanation, see SetFlags().
@see Error(), LastError(), LastCount(), SetFlags(), WriteMsg()
*/
Number of milliseconds to wait.
@return Returns @true when any of the above conditions is satisfied,
- @false if the timeout was reached.
+ @false if the timeout was reached.
@see InterruptWait(), wxSocketServer::WaitForAccept(),
WaitForLost(), WaitForRead(),
Number of milliseconds to wait.
@return Returns @true if the connection was lost, @false if the timeout
- was reached.
+ was reached.
@see InterruptWait(), Wait()
*/
Number of bytes.
@return Returns a reference to the current object, and the address of
- the peer that sent the data on address param.
+ the peer that sent the data on address param.
@see wxSocketBase::LastError(), wxSocketBase::SetFlags()
*/
@class wxSound
This class represents a short sound (loaded from Windows WAV file), that
- can be stored in memory and played. Currently this class is implemented
- on Windows and Unix (and uses either
- Open Sound System or
- Simple DirectMedia Layer).
+ can be stored in memory and played.
+
+ Currently this class is implemented on Windows and Unix (and uses either
+ Open Sound System or Simple DirectMedia Layer).
@library{wxadv}
- @category{FIXME}
+ @category{misc}
*/
class wxSound : public wxObject
{
public:
- //@{
+ /**
+ Default ctor.
+ */
+ wxSound();
+
/**
Constructs a wave object from a file or, under Windows, from a Windows
- resource. Call IsOk() to determine whether this
- succeeded.
+ resource. Call IsOk() to determine whether this succeeded.
@param fileName
The filename or Windows resource.
@param isResource
@true if fileName is a resource, @false if it is a filename.
*/
- wxSound();
wxSound(const wxString& fileName, bool isResource = false);
- //@}
/**
Destroys the wxSound object.
//@{
/**
Plays the sound file. If another sound is playing, it will be interrupted.
+
Returns @true on success, @false otherwise. Note that in general it is
- possible
- to delete the object which is being asynchronously played any time after
- calling this function and the sound would continue playing, however this
+ possible to delete the object which is being asynchronously played any time
+ after calling this function and the sound would continue playing, however this
currently doesn't work under Windows for sound objects loaded from memory data.
- The possible values for @a flags are:
-
- wxSOUND_SYNC
-
- @c Play will block and wait until the sound is
- replayed.
- wxSOUND_ASYNC
-
- Sound is played asynchronously,
- @c Play returns immediately
-
- wxSOUND_ASYNC | wxSOUND_LOOP
-
- Sound is played asynchronously
- and loops until another sound is played,
- Stop() is called or the program terminates.
+ The possible values for @a flags are:
+ - wxSOUND_SYNC: @c Play will block and wait until the sound is replayed.
+ - wxSOUND_ASYNC: Sound is played asynchronously, @c Play returns immediately.
+ - wxSOUND_ASYNC|wxSOUND_LOOP: Sound is played asynchronously and loops
+ until another sound is played, Stop() is
+ called or the program terminates.
The static form is shorthand for this code:
+ @code
+ wxSound(filename).Play(flags);
+ @endcode
*/
- bool Play(unsigned flags = wxSOUND_ASYNC);
- const static bool Play(const wxString& filename,
- unsigned flags = wxSOUND_ASYNC);
+ bool Play(unsigned flags = wxSOUND_ASYNC) const;
+ static bool Play(const wxString& filename,
+ unsigned flags = wxSOUND_ASYNC);
//@}
/**
/////////////////////////////////////////////////////////////////////////////
// Name: spinbutt.h
-// Purpose: interface of wxSpinEvent
+// Purpose: interface of wxSpinEvent, wxSpinButton
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
@class wxSpinEvent
- This event class is used for the events generated by
- wxSpinButton and wxSpinCtrl.
+ This event class is used for the events generated by wxSpinButton and wxSpinCtrl.
+
+ @beginEventTable{wxSpinEvent}
+ @event{EVT_SPIN(id, func)}
+ Generated whenever an arrow is pressed.
+ @event{EVT_SPIN_UP(id, func)}
+ Generated when left/up arrow is pressed.
+ @event{EVT_SPIN_DOWN(id, func)}
+ Generated when right/down arrow is pressed.
+ @endEventTable
+
+ Note that if you handle both SPIN and UP or DOWN events, you will be notified
+ about each of them twice: first the UP/DOWN event will be received and then,
+ if it wasn't vetoed, the SPIN event will be sent.
@library{wxcore}
@category{events}
/**
@class wxSpinButton
- A wxSpinButton has two small up and down (or left and right) arrow buttons. It
- is often used next to a text control for increment and decrementing a value.
- Portable programs should try to use wxSpinCtrl instead
- as wxSpinButton is not implemented for all platforms but wxSpinCtrl is as it
- degenerates to a simple wxTextCtrl on such platforms.
+ A wxSpinButton has two small up and down (or left and right) arrow buttons.
+
+ It is often used next to a text control for increment and decrementing a value.
+ Portable programs should try to use wxSpinCtrl instead as wxSpinButton is not
+ implemented for all platforms but wxSpinCtrl is as it degenerates to a simple
+ wxTextCtrl on such platforms.
@note the range supported by this control (and wxSpinCtrl) depends on the
- platform but is at least @c -0x8000 to @c 0x7fff. Under GTK and
- Win32 with sufficiently new version of @c comctrl32.dll (at least 4.71 is
- required, 5.80 is recommended) the full 32 bit range is supported.
+ platform but is at least @c -0x8000 to @c 0x7fff. Under GTK and
+ Win32 with sufficiently new version of @c comctrl32.dll (at least 4.71
+ is required, 5.80 is recommended) the full 32 bit range is supported.
@beginStyleTable
@style{wxSP_HORIZONTAL}
The value wraps at the minimum and maximum.
@endStyleTable
+ @beginEventTable{wxSpinEvent}
+ @event{EVT_SPIN(id, func)}
+ Generated whenever an arrow is pressed.
+ @event{EVT_SPIN_UP(id, func)}
+ Generated when left/up arrow is pressed.
+ @event{EVT_SPIN_DOWN(id, func)}
+ Generated when right/down arrow is pressed.
+ @endEventTable
+
+ Note that if you handle both SPIN and UP or DOWN events, you will be notified
+ about each of them twice: first the UP/DOWN event will be received and then,
+ if it wasn't vetoed, the SPIN event will be sent.
+
@library{wxcore}
@category{ctrl}
<!-- @appearance{spinbutton.png} -->
Default constructor.
*/
wxSpinButton();
-
+
/**
Constructor, creating and showing a spin button.
@param id
Window identifier. The value wxID_ANY indicates a default value.
@param pos
- Window position. If wxDefaultPosition is specified then a default
- position is chosen.
+ Window position.
+ If wxDefaultPosition is specified then a default position is chosen.
@param size
- Window size. If wxDefaultSize is specified then a default size
- is chosen.
+ Window size.
+ If wxDefaultSize is specified then a default size is chosen.
@param style
- Window style. See wxSpinButton.
+ Window style. See wxSpinButton class description.
@param name
Window name.
/**
@class wxSpinCtrl
- wxSpinCtrl combines wxTextCtrl and
- wxSpinButton in one control.
+ wxSpinCtrl combines wxTextCtrl and wxSpinButton in one control.
@beginStyleTable
@style{wxSP_ARROW_KEYS}
dialog) under MSW.
@endStyleTable
+
+ @beginEventTable{wxSpinEvent}
+ @event{EVT_SPINCTRL(id, func)}
+ Generated whenever the numeric value of the spinctrl is updated
+ @endEventTable
+
+ You may also use the wxSpinButton event macros, however the corresponding events
+ will not be generated under all platforms. Finally, if the user modifies the
+ text in the edit part of the spin control directly, the EVT_TEXT is generated,
+ like for the wxTextCtrl. When the use enters text into the text area, the text
+ is not validated until the control loses focus (e.g. by using the TAB key).
+ The value is then adjusted to the range and a wxSpinEvent sent then if the value
+ is different from the last value sent.
+
@library{wxcore}
@category{ctrl}
<!-- @appearance{spinctrl.png} -->
Default constructor.
*/
wxSpinCtrl();
-
+
/**
Constructor, creating and showing a spin control.
@param id
Window identifier. The value wxID_ANY indicates a default value.
@param pos
- Window position. If wxDefaultPosition is specified then a default
- position is chosen.
+ Window position.
+ If wxDefaultPosition is specified then a default position is chosen.
@param size
- Window size. If wxDefaultSize is specified then a default size
- is chosen.
+ Window size.
+ If wxDefaultSize is specified then a default size is chosen.
@param style
Window style. See wxSpinButton.
@param min
/**
Select the text in the text part of the control between positions
- @a from (inclusive) and @a to (exclusive). This is similar to
- wxTextCtrl::SetSelection.
+ @a from (inclusive) and @a to (exclusive).
+ This is similar to wxTextCtrl::SetSelection().
+
@note this is currently only implemented for Windows and generic versions
- of the control.
+ of the control.
*/
void SetSelection(long from, long to);
@class wxSplashScreen
wxSplashScreen shows a window with a thin border, displaying a bitmap
- describing your
- application. Show it in application initialisation, and then either explicitly
- destroy
+ describing your application.
+
+ Show it in application initialisation, and then either explicitly destroy
it or let it time-out.
Example usage:
@code
- wxBitmap bitmap;
+ wxBitmap bitmap;
if (bitmap.LoadFile("splash16.png", wxBITMAP_TYPE_PNG))
{
wxSplashScreen* splash = new wxSplashScreen(bitmap,
public:
/**
Construct the splash screen passing a bitmap, a style, a timeout, a window id,
- optional position
- and size, and a window style.
+ optional position and size, and a window style.
+
@a splashStyle is a bitlist of some of the following:
- wxSPLASH_CENTRE_ON_PARENT
- wxSPLASH_CENTRE_ON_SCREEN
- wxSPLASH_NO_CENTRE
- wxSPLASH_TIMEOUT
- wxSPLASH_NO_TIMEOUT
+ - wxSPLASH_CENTRE_ON_PARENT
+ - wxSPLASH_CENTRE_ON_SCREEN
+ - wxSPLASH_NO_CENTRE
+ - wxSPLASH_TIMEOUT
+ - wxSPLASH_NO_TIMEOUT
+
@a milliseconds is the timeout in milliseconds.
*/
wxSplashScreen(const wxBitmap& bitmap, long splashStyle,
virtual ~wxSplashScreen();
/**
- Returns the splash style (see wxSplashScreen() for
- details).
+ Returns the splash style (see wxSplashScreen() for details).
*/
long GetSplashStyle() const;
/**
@class wxSplitterWindow
- @ref overview_wxsplitterwindowoverview "wxSplitterWindow overview"
-
- This class manages up to two subwindows. The current view can be
- split into two programmatically (perhaps from a menu command), and unsplit
+ This class manages up to two subwindows. The current view can be split
+ into two programmatically (perhaps from a menu command), and unsplit
either programmatically or via the wxSplitterWindow user interface.
@beginStyleTable
using Windows XP theming, so the borders and sash will take on the
pre-XP look.
@style{wxSP_PERMIT_UNSPLIT}
- Always allow to unsplit, even with the minimum pane size other than
- zero.
+ Always allow to unsplit, even with the minimum pane size other than zero.
@style{wxSP_LIVE_UPDATE}
Don't draw XOR line but resize the child windows immediately.
@endStyleTable
+
+ @beginEventTable{wxSplitterEvent}
+ @event{EVT_SPLITTER_SASH_POS_CHANGING(id, func)}
+ The sash position is in the process of being changed.
+ May be used to modify the position of the tracking bar to properly
+ reflect the position that would be set if the drag were to be completed
+ at this point. Processes a wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING event.
+ @event{EVT_SPLITTER_SASH_POS_CHANGED(id, func)}
+ The sash position was changed. May be used to modify the sash position
+ before it is set, or to prevent the change from taking place.
+ Processes a wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED event.
+ @event{EVT_SPLITTER_UNSPLIT(id, func)}
+ The splitter has been just unsplit. Processes a wxEVT_COMMAND_SPLITTER_UNSPLIT event.
+ @event{EVT_SPLITTER_DCLICK(id, func)}
+ The sash was double clicked. The default behaviour is to unsplit the
+ window when this happens (unless the minimum pane size has been set
+ to a value greater than zero). Processes a wxEVT_COMMAND_SPLITTER_DOUBLECLICKED event.
+ @endEventTable
+
+
@library{wxcore}
@category{miscwnd}
- @see wxSplitterEvent
+ @see wxSplitterEvent, @ref overview_splitterwindow
*/
class wxSplitterWindow : public wxWindow
{
Default constructor
*/
wxSplitterWindow();
-
+
/**
Constructor for creating the window.
@param name
The window name.
- @remarks After using this constructor, you must create either one or two
- subwindows with the splitter window as parent, and then
- call one of Initialize(),
- SplitVertically() and
- SplitHorizontally() in order to set the
- pane(s).
+ @remarks
+ After using this constructor, you must create either one or two
+ subwindows with the splitter window as parent, and then call one
+ of Initialize(), SplitVertically() and SplitHorizontally() in order
+ to set the pane(s).
+ You can create two windows, with one hidden when not being shown;
+ or you can create and delete the second pane on demand.
- @see Initialize(), SplitVertically(),
- SplitHorizontally(), Create()
+ @see Initialize(), SplitVertically(), SplitHorizontally(), Create()
*/
wxSplitterWindow(wxWindow* parent, wxWindowID id,
- const wxPoint& point = wxDefaultPosition,
+ const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = wxSP_3D,
const wxString& name = "splitterWindow");
virtual ~wxSplitterWindow();
/**
- Creation function, for two-step construction. See wxSplitterWindow() for
- details.
+ Creation function, for two-step construction.
+ See wxSplitterWindow() for details.
*/
bool Create(wxWindow* parent, wxWindowID id,
const wxPoint& point = wxDefaultPosition,
/**
Gets the split mode.
- @see SetSplitMode(), SplitVertically(),
- SplitHorizontally().
+ @see SetSplitMode(), SplitVertically(), SplitHorizontally().
*/
int GetSplitMode() const;
wxWindow* GetWindow2() const;
/**
- Initializes the splitter window to have one pane. The child window is
- shown if it is currently hidden.
+ Initializes the splitter window to have one pane.
+ The child window is shown if it is currently hidden.
@param window
The pane for the unsplit window.
and then resplitting the window back because it will provoke much less flicker
(if any). It is valid to call this function whether the splitter has two
windows or only one.
+
Both parameters should be non-@NULL and @a winOld must specify one of the
windows managed by the splitter. If the parameters are incorrect or the window
couldn't be replaced, @false is returned. Otherwise the function will return
@param gravity
The sash gravity. Value between 0.0 and 1.0.
+ @remarks
+ Gravity is real factor which controls position of sash while resizing
+ wxSplitterWindow. Gravity tells wxSplitterWindow how much will left/top
+ window grow while resizing.
+ Example values:
+ - 0.0: only the bottom/right window is automatically resized
+ - 0.5: both windows grow by equal size
+ - 1.0: only left/top window grows
+ Gravity should be a real value between 0.0 and 1.0.
+ Default value of sash gravity is 0.0.
+ That value is compatible with previous (before gravity was introduced)
+ behaviour of wxSplitterWindow.
+
@see GetSashGravity()
*/
void SetSashGravity(double gravity);
@remarks Only sets the internal variable; does not update the display.
- @see GetSplitMode(), SplitVertically(),
- SplitHorizontally().
+ @see GetSplitMode(), SplitVertically(), SplitHorizontally().
*/
void SetSplitMode(int mode);
/**
- Initializes the top and bottom panes of the splitter window. The
- child windows are shown if they are currently hidden.
+ Initializes the top and bottom panes of the splitter window.
+ The child windows are shown if they are currently hidden.
@param window1
The top pane.
@param window2
The bottom pane.
@param sashPosition
- The initial position of the sash. If this value is
- positive, it specifies the size of the upper pane. If it is negative, its
- absolute value gives the size of the lower pane. Finally, specify 0
- (default)
- to choose the default position (half of the total window height).
+ The initial position of the sash. If this value is positive,
+ it specifies the size of the upper pane. If it is negative, its
+ absolute value gives the size of the lower pane.
+ Finally, specify 0 (default) to choose the default position
+ (half of the total window height).
- @return @true if successful, @false otherwise (the window was already
- split).
+ @return @true if successful, @false otherwise (the window was already split).
@remarks This should be called if you wish to initially view two panes.
- It can also be called at any subsequent time, but the
- application should check that the window is not
- currently split using IsSplit.
+ It can also be called at any subsequent time, but the application
+ should check that the window is not currently split using IsSplit().
- @see SplitVertically(), IsSplit(),
- Unsplit()
+ @see SplitVertically(), IsSplit(), Unsplit()
*/
bool SplitHorizontally(wxWindow* window1, wxWindow* window2,
int sashPosition = 0);
/**
- Initializes the left and right panes of the splitter window. The
- child windows are shown if they are currently hidden.
+ Initializes the left and right panes of the splitter window.
+ The child windows are shown if they are currently hidden.
@param window1
The left pane.
@param window2
The right pane.
@param sashPosition
- The initial position of the sash. If this value is
- positive, it specifies the size of the left pane. If it is negative, it is
- absolute value gives the size of the right pane. Finally, specify 0
- (default)
- to choose the default position (half of the total window width).
+ The initial position of the sash. If this value is positive, it
+ specifies the size of the left pane. If it is negative, it is
+ absolute value gives the size of the right pane.
+ Finally, specify 0 (default) to choose the default position
+ (half of the total window width).
- @return @true if successful, @false otherwise (the window was already
- split).
+ @return @true if successful, @false otherwise (the window was already split).
@remarks This should be called if you wish to initially view two panes.
It can also be called at any subsequent time, but the
- application should check that the window is not
- currently split using IsSplit.
+ application should check that the window is not currently
+ split using IsSplit().
- @see SplitHorizontally(), IsSplit(),
- Unsplit().
+ @see SplitHorizontally(), IsSplit(), Unsplit().
*/
bool SplitVertically(wxWindow* window1, wxWindow* window2,
int sashPosition = 0);
@return @true if successful, @false otherwise (the window was not split).
@remarks This call will not actually delete the pane being removed; it
- calls OnUnsplit which can be overridden for the desired
+ calls OnUnsplit() which can be overridden for the desired
behaviour. By default, the pane being removed is hidden.
- @see SplitHorizontally(), SplitVertically(),
- IsSplit(), OnUnsplit()
+ @see SplitHorizontally(), SplitVertically(), IsSplit(), OnUnsplit()
*/
bool Unsplit(wxWindow* toRemove = NULL);
/**
Causes any pending sizing of the sash and child panes to take place
immediately.
- Such resizing normally takes place in idle time, in order
- to wait for layout to be completed. However, this can cause
- unacceptable flicker as the panes are resized after the window has been
- shown. To work around this, you can perform window layout (for
- example by sending a size event to the parent window), and then
- call this function, before showing the top-level window.
+
+ Such resizing normally takes place in idle time, in order to wait for
+ layout to be completed. However, this can cause unacceptable flicker as
+ the panes are resized after the window has been shown.
+ To work around this, you can perform window layout (for example by
+ sending a size event to the parent window), and then call this function,
+ before showing the top-level window.
*/
void UpdateSize();
};
/**
@class wxSplitterEvent
- This class represents the events generated by a splitter control. Also there is
- only one event class, the data associated to the different events is not the
- same and so not all accessor functions may be called for each event. The
- documentation mentions the kind of event(s) for which the given accessor
+ This class represents the events generated by a splitter control.
+
+ Also there is only one event class, the data associated to the different events
+ is not the same and so not all accessor functions may be called for each event.
+ The documentation mentions the kind of event(s) for which the given accessor
function makes sense: calling it for other types of events will result
in assert failure (in debug mode) and will return meaningless results.
+ @beginEventTable{wxSplitterEvent}
+ @event{EVT_SPLITTER_SASH_POS_CHANGING(id, func)}
+ The sash position is in the process of being changed.
+ May be used to modify the position of the tracking bar to properly
+ reflect the position that would be set if the drag were to be completed
+ at this point. Processes a wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING event.
+ @event{EVT_SPLITTER_SASH_POS_CHANGED(id, func)}
+ The sash position was changed. May be used to modify the sash position
+ before it is set, or to prevent the change from taking place.
+ Processes a wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED event.
+ @event{EVT_SPLITTER_UNSPLIT(id, func)}
+ The splitter has been just unsplit. Processes a wxEVT_COMMAND_SPLITTER_UNSPLIT event.
+ @event{EVT_SPLITTER_DCLICK(id, func)}
+ The sash was double clicked. The default behaviour is to unsplit the
+ window when this happens (unless the minimum pane size has been set
+ to a value greater than zero). Processes a wxEVT_COMMAND_SPLITTER_DOUBLECLICKED event.
+ @endEventTable
+
@library{wxcore}
@category{events}
- @see wxSplitterWindow, @ref overview_eventhandlingoverview
+ @see wxSplitterWindow, @ref overview_eventhandling
*/
class wxSplitterEvent : public wxNotifyEvent
{
/**
Returns the new sash position.
+
May only be called while processing
- wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and
- wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events.
+ @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and
+ @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events.
*/
int GetSashPosition() const;
/**
Returns a pointer to the window being removed when a splitter window
is unsplit.
+
May only be called while processing
- wxEVT_COMMAND_SPLITTER_UNSPLIT events.
+ @c wxEVT_COMMAND_SPLITTER_UNSPLIT events.
*/
wxWindow* GetWindowBeingRemoved() const;
/**
Returns the x coordinate of the double-click point.
+
May only be called while processing
- wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events.
+ @c wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events.
*/
int GetX() const;
/**
Returns the y coordinate of the double-click point.
+
May only be called while processing
- wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events.
+ @c wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events.
*/
int GetY() const;
/**
- In the case of wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events,
- sets the new sash position. In the case of
- wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING events, sets the new
- tracking bar position so visual feedback during dragging will
+ In the case of @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events,
+ sets the new sash position.
+ In the case of @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING events,
+ sets the new tracking bar position so visual feedback during dragging will
represent that change that will actually take place. Set to -1 from
the event handler code to prevent repositioning.
+
May only be called while processing
- wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and
- wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events.
+ @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and
+ @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events.
@param pos
New sash position.
capitalized.
@endStyleTable
+ @beginEventTable{wxCommandEvent}
+ To retrieve actual search queries, use EVT_TEXT and EVT_TEXT_ENTER events,
+ just as you would with wxTextCtrl.
+ @event{EVT_SEARCHCTRL_SEARCH_BTN(id, func)}
+ Respond to a wxEVT_SEARCHCTRL_SEARCH_BTN event, generated when the
+ search button is clicked. Note that this does not initiate a search.
+ @event{EVT_SEARCHCTRL_CANCEL_BTN(id, func)}
+ Respond to a wxEVT_SEARCHCTRL_CANCEL_BTN event, generated when the
+ cancel button is clicked.
+ @endEventTable
+
@library{wxcore}
- @category{FIXME}
+ @category{ctrl}
@see wxTextCtrl::Create, wxValidator
*/
Default constructor
*/
wxSearchCtrl();
-
+
/**
Constructor, creating and showing a text control.
/**
Returns the search button visibility value.
If there is a menu attached, the search button will be visible regardless of
- the search
- button visibility value.
+ the search button visibility value.
+
This always returns @false in Mac OS X v10.3
*/
virtual bool IsSearchButtonVisible() const;
/**
- Sets the search control's menu object. If there is already a menu associated
- with
- the search control it is deleted.
+ Sets the search control's menu object.
+ If there is already a menu associated with the search control it is deleted.
@param menu
Menu to attach to the search control.
/**
Sets the search button visibility value on the search control.
If there is a menu attached, the search button will be visible regardless of
- the search
- button visibility value.
+ the search button visibility value.
+
This has no effect in Mac OS X v10.3
*/
virtual void ShowSearchButton(bool show);
/**
@class wxStringInputStream
- This class implements an input stream which reads data from a string. It
- supports seeking.
+ This class implements an input stream which reads data from a string.
+ It supports seeking.
@library{wxbase}
@category{streams}
{
public:
/**
- Creates a new read-only stream using the specified string. Note that the string
- is copied by the stream so if the original string is modified after using this
- constructor, changes to it are not reflected when reading from stream.
+ Creates a new read-only stream using the specified string.
+
+ Note that the string is copied by the stream so if the original string is
+ modified after using this constructor, changes to it are not reflected
+ when reading from stream.
*/
wxStringInputStream(const wxString& s);
};
@class wxStringOutputStream
This class implements an output stream which writes data either to a
- user-provided or internally allocated string. Note that currently this stream
- does not support seeking but can tell its current position.
+ user-provided or internally allocated string.
+
+ Note that currently this stream does not support seeking but can tell
+ its current position.
@library{wxbase}
@category{streams}
If @a str is used, data written to the stream is appended to the current
contents of it, i.e. the string is not cleared here. However if it is not
- empty, the positions returned by wxOutputStream::TellO will be
- offset by the initial string length, i.e. initial stream position will be the
+ empty, the positions returned by wxOutputStream::TellO will be offset by
+ the initial string length, i.e. initial stream position will be the
initial length of the string and not 0.
Notice that the life time of @a conv must be greater than the life time
of this object itself as it stores a reference to it. Also notice that
with default value of this argument the data written to the stream must
- be valid UTF-8, pass @c wxConvISO8859_1 to deal with arbitrary 8 bit
- data.
+ be valid UTF-8, pass @c wxConvISO8859_1 to deal with arbitrary 8 bit data.
*/
wxStringOutputStream(wxString str = NULL, wxMBConv& conv = wxConvUTF8);
projects / wxWidgets.git / commitdiff
