other s*h interface revisions

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56089 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-10-05 11:24:00 +00:00
parent 95645cce6e
commit e725ba4fc2
11 changed files with 636 additions and 491 deletions

View File

@@ -6,6 +6,23 @@
// Licence: wxWindows license // 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 wxStdDialogButtonSizer
@@ -105,16 +122,26 @@ public:
class wxSizerItem : public wxObject class wxSizerItem : public wxObject
{ {
public: 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, wxSizerItem(int width, int height, int proportion, int flag,
int border, wxObject* userData); int border, wxObject* userData);
//@{
/**
Construct a sizer item for tracking a window.
*/
wxSizerItem(wxWindow* window, const wxSizerFlags& flags); wxSizerItem(wxWindow* window, const wxSizerFlags& flags);
wxSizerItem(wxWindow* window, int proportion, int flag, wxSizerItem(wxWindow* window, int proportion, int flag,
int border, int border,
wxObject* userData); wxObject* userData);
//@}
//@{
/**
Construct a sizer item for tracking a subsizer.
*/
wxSizerItem(wxSizer* window, const wxSizerFlags& flags); wxSizerItem(wxSizer* window, const wxSizerFlags& flags);
wxSizerItem(wxSizer* sizer, int proportion, int flag, wxSizerItem(wxSizer* sizer, int proportion, int flag,
int border, int border,
@@ -220,7 +247,7 @@ public:
wxObject* GetUserData() const; 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; wxWindow* GetWindow() const;
@@ -265,7 +292,7 @@ public:
virtual void SetDimension(const wxPoint& pos, const wxSize& size); virtual void SetDimension(const wxPoint& pos, const wxSize& size);
/** /**
Set the flag item attribute. Set the flag item attribute.
*/ */
void SetFlag(int flag); void SetFlag(int flag);
@@ -275,7 +302,7 @@ public:
void SetId(int id); void SetId(int id);
/** /**
@todo docme.
*/ */
void SetInitSize(int x, int y); void SetInitSize(int x, int y);
@@ -313,7 +340,7 @@ public:
/** /**
Set the show item attribute, which sizers use to determine if the item 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. window then it is shown or hidden as needed.
*/ */
void Show(bool show); void Show(bool show);
@@ -365,25 +392,25 @@ class wxSizerFlags
{ {
public: 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); 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 This method replaces the previously set alignment with the specified one.
one.
@param align
Combination of @c wxALIGN_XXX bit masks.
@see Top(), Left(), Right(), Bottom(), Centre() @see Top(), Left(), Right(), Bottom(), Centre()
@param align Combination of @c wxALIGN_XXX bit masks.
*/ */
wxSizerFlags& Align(int align = 0); wxSizerFlags& Align(int align = 0);
/** /**
Sets the wxSizerFlags to have a border of a number of pixels specified 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); wxSizerFlags& Border(int direction, int borderinpixels);
@@ -391,7 +418,8 @@ public:
Sets the wxSizerFlags to have a border with size as returned by Sets the wxSizerFlags to have a border with size as returned by
GetDefaultBorder(). GetDefaultBorder().
@param direction Direction(s) to apply the border in. @param direction
Direction(s) to apply the border in.
*/ */
wxSizerFlags& Border(int direction = wxALL); wxSizerFlags& Border(int direction = wxALL);
@@ -539,35 +567,35 @@ public:
@class wxFlexGridSizer @class wxFlexGridSizer
A flex grid sizer is a sizer which lays out its children in a two-dimensional 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 table with all table fields in one row having the same height and all fields
height and all fields in one column having the same width, but all in one column having the same width, but all rows or all columns are not
rows or all columns are not necessarily the same height or width as in necessarily the same height or width as in the wxGridSizer.
the wxGridSizer.
Since wxWidgets 2.5.0, wxFlexGridSizer can also size items equally in one 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 direction but unequally ("flexibly") in the other. If the sizer is only
flexible in one direction (this can be changed using flexible in one direction (this can be changed using wxFlexGridSizer::SetFlexibleDirection),
wxFlexGridSizer::SetFlexibleDirection),
it needs to be decided how the sizer should grow in the other ("non-flexible") it needs to be decided how the sizer should grow in the other ("non-flexible")
direction in order to fill the available space. The direction in order to fill the available space.
wxFlexGridSizer::SetNonFlexibleGrowMode method The wxFlexGridSizer::SetNonFlexibleGrowMode() method serves this purpose.
serves this purpose.
@library{wxcore} @library{wxcore}
@category{winlayout} @category{winlayout}
@see wxSizer, @ref overview_sizer "Sizer Overview" @see wxSizer, @ref overview_sizer
*/ */
class wxFlexGridSizer : public wxGridSizer class wxFlexGridSizer : public wxGridSizer
{ {
public: public:
//@{ //@{
/** /**
Constructor for a wxGridSizer. @a rows and @a cols determine the number of Constructor for a wxFlexGridSizer.
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 @a rows and @a cols determine the number of columns and rows in the sizer -
sizer grow dynamically. @a vgap and @a hgap define extra space between if either of the parameters is zero, it will be calculated to form the
all children. 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 rows, int cols, int vgap, int hgap);
wxFlexGridSizer(int cols, int vgap = 0, int hgap = 0); wxFlexGridSizer(int cols, int vgap = 0, int hgap = 0);
@@ -601,7 +629,11 @@ public:
Returns a wxOrientation value that specifies whether the sizer flexibly Returns a wxOrientation value that specifies whether the sizer flexibly
resizes its columns, rows, or both (default). 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() @see SetFlexibleDirection()
*/ */
@@ -611,10 +643,17 @@ public:
Returns the value that specifies how the sizer grows in the "non-flexible" Returns the value that specifies how the sizer grows in the "non-flexible"
direction if there is one. 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(), @see SetFlexibleDirection(), SetNonFlexibleGrowMode()
SetNonFlexibleGrowMode()
*/ */
int GetNonFlexibleGrowMode() const; int GetNonFlexibleGrowMode() const;
@@ -643,22 +682,21 @@ public:
void RemoveGrowableRow(size_t idx); void RemoveGrowableRow(size_t idx);
/** /**
Specifies whether the sizer should flexibly resize its columns, rows, or Specifies whether the sizer should flexibly resize its columns, rows, or both.
both. Argument @c direction can be @c wxVERTICAL, @c wxHORIZONTAL
or @c wxBOTH (which is the default value). Any other value is ignored. See Argument @a direction can be @c wxVERTICAL, @c wxHORIZONTAL or @c wxBOTH
@ref GetFlexibleDirection() GetFlexibleDirection for the (which is the default value). Any other value is ignored.
explanation of these values. See GetFlexibleDirection() for the explanation of these values.
Note that this method does not trigger relayout. Note that this method does not trigger relayout.
*/ */
void SetFlexibleDirection(int direction); void SetFlexibleDirection(int direction);
/** /**
Specifies how the sizer should grow in the non-flexible direction if Specifies how the sizer should grow in the non-flexible direction if
there is one (so there is one (so SetFlexibleDirection() must have been called previously).
SetFlexibleDirection() must have
been called previously). Argument @a mode can be one of those documented in Argument @a mode can be one of those documented in GetNonFlexibleGrowMode(),
GetNonFlexibleGrowMode(), please please see there for their explanation.
see there for their explanation.
Note that this method does not trigger relayout. Note that this method does not trigger relayout.
*/ */
void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode); void SetNonFlexibleGrowMode(wxFlexSizerGrowMode mode);
@@ -670,62 +708,53 @@ public:
@class wxSizer @class wxSizer
wxSizer is the abstract base class used for laying out subwindows in a window. wxSizer is the abstract base class used for laying out subwindows in a window.
You You cannot use wxSizer directly; instead, you will have to use one of the sizer
cannot use wxSizer directly; instead, you will have to use one of the sizer classes derived from it. Currently there are wxBoxSizer, wxStaticBoxSizer,
classes derived from it. Currently there are wxBoxSizer, wxGridSizer, wxFlexGridSizer, wxWrapSizer and wxGridBagSizer.
wxStaticBoxSizer,
wxGridSizer,
wxFlexGridSizer,
wxWrapSizer
and wxGridBagSizer.
The layout algorithm used by sizers in wxWidgets is closely related to layout 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. in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit.
It is It is based upon the idea of the individual subwindows reporting their minimal
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
required has changed.
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 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 a dialog in the beginning, rather the dialog will be assigned a sizer and this
sizer sizer will be queried about the recommended size. The sizer in turn will query
will be queried about the recommended size. The sizer in turn will query its its children, which can be normal windows, empty space or other sizers, so that
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 a hierarchy of sizers can be constructed. Note that wxSizer does not derive
from wxWindow from wxWindow and thus does not interfere with tab ordering and requires very little
and thus does not interfere with tab ordering and requires very little resources compared to a real window on screen.
resources compared
to a real window on screen.
What makes sizers so well fitted for use in wxWidgets is the fact that every What makes sizers so well fitted for use in wxWidgets is the fact that every
control control reports its own minimal size and the algorithm can handle differences in
reports its own minimal size and the algorithm can handle differences in font font sizes or different window (dialog item) sizes on different platforms without
sizes problems. If e.g. the standard font as well as the overall design of Motif widgets
or different window (dialog item) sizes on different platforms without requires more space than on Windows, the initial dialog size will automatically
problems. If e.g. be bigger on Motif than on Windows.
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 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 window. The wxSizer::Add(), wxSizer::Insert(), and wxSizer::Prepend() functions
the newly added wxSizerItem. Just add empty space of the desired size and return a pointer to the newly added wxSizerItem.
attributes, and then use the wxSizerItem::GetRect() method to determine Just add empty space of the desired size and attributes, and then use the
where the drawing operations should take place. 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 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 will be deleted by it which implies that they must be allocated on the heap.
heap. However if you create a sizer and do not add it to another sizer or 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 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. 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 derive the class from @c wxPySizer in order to get Python-aware
capabilities for the various virtual methods. capabilities for the various virtual methods.
@endWxPythonOnly
@anchor wxsizer_flags @anchor wxsizer_flags
@par wxSizer flags @par wxSizer flags
The "flag" argument accepted by wxSizeItem constructors and other The "flag" argument accepted by wxSizeItem constructors and other
functions, e.g. wxSizer::Add(), is OR-combination of the following flags. 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 Two main behaviours are defined using these flags. One is the border around
@@ -734,6 +763,7 @@ public:
be added. The other flags determine how the sizer item behaves when the 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 space allotted to the sizer changes, and is somewhat dependent on the
specific kind of sizer used. specific kind of sizer used.
@beginDefList @beginDefList
@itemdef{wxTOP<br> @itemdef{wxTOP<br>
wxBOTTOM<br> wxBOTTOM<br>
@@ -776,18 +806,17 @@ public:
border if any.} border if any.}
@endDefList @endDefList
@library{wxcore} @library{wxcore}
@category{winlayout} @category{winlayout}
@see @ref overview_sizer "Sizer Overview" @see @ref overview_sizer
*/ */
class wxSizer : public wxObject class wxSizer : public wxObject
{ {
public: public:
/** /**
The constructor. Note that wxSizer is an abstract base class and may not The constructor.
be instantiated. Note that wxSizer is an abstract base class and may not be instantiated.
*/ */
wxSizer(); wxSizer();
@@ -848,7 +877,8 @@ public:
derived classes when sizing information is more complex than the derived classes when sizing information is more complex than the
proportion and flag will allow for. proportion and flag will allow for.
*/ */
wxSizerItem* Add(wxWindow* window, int proportion = 0, wxSizerItem* Add(wxWindow* window,
int proportion = 0,
int flag = 0, int flag = 0,
int border = 0, int border = 0,
wxObject* userData = NULL); wxObject* userData = NULL);
@@ -905,7 +935,8 @@ public:
derived classes when sizing information is more complex than the derived classes when sizing information is more complex than the
proportion and flag will allow for. proportion and flag will allow for.
*/ */
wxSizerItem* Add(wxSizer* sizer, int proportion = 0, wxSizerItem* Add(wxSizer* sizer,
int proportion = 0,
int flag = 0, int flag = 0,
int border = 0, int border = 0,
wxObject* userData = NULL); wxObject* userData = NULL);
@@ -952,20 +983,27 @@ public:
derived classes when sizing information is more complex than the derived classes when sizing information is more complex than the
proportion and flag will allow for. 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 flag = 0,
int border = 0, int border = 0,
wxObject* userData = NULL); 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). wxSizer::Add(size, size, 0).
@endcode
*/ */
wxSizerItem* AddSpacer(int size); 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). wxSizer::Add(0, 0, prop).
@endcode
*/ */
wxSizerItem* AddStretchSpacer(int prop = 1); wxSizerItem* AddStretchSpacer(int prop = 1);
@@ -976,8 +1014,8 @@ public:
virtual wxSize CalcMin(); virtual wxSize CalcMin();
/** /**
Detaches all children from the sizer. If @a delete_windows is @true then Detaches all children from the sizer.
child windows will also be deleted. If @a delete_windows is @true then child windows will also be deleted.
*/ */
virtual void Clear(bool delete_windows = false); virtual void Clear(bool delete_windows = false);
@@ -986,8 +1024,9 @@ public:
minimal size. Unlike GetMinSize(), this method accounts for other minimal size. Unlike GetMinSize(), this method accounts for other
constraints imposed on @e window, namely display's size (returned size constraints imposed on @e window, namely display's size (returned size
will never be too large for the display) and maximum window size if will never be too large for the display) and maximum window size if
previously set by wxWindow::SetMaxSize(). The returned value is previously set by wxWindow::SetMaxSize().
suitable for passing to wxWindow::SetClientSize() or
The returned value is suitable for passing to wxWindow::SetClientSize() or
wxWindow::SetMinClientSize(). wxWindow::SetMinClientSize().
@since 2.8.8 @since 2.8.8
@@ -1044,12 +1083,11 @@ public:
/** /**
Tell the sizer to resize the @a window so that its client area matches the Tell the sizer to resize the @a window so that its client area matches the
sizer's minimal size sizer's minimal size (ComputeFittingClientSize() is called to determine it).
(ComputeFittingClientSize() is called This is commonly done in the constructor of the window itself, see sample
to determine it). in the description of wxBoxSizer.
This is commonly done in the constructor of the window
itself, see sample in the description @return The new window size.
of wxBoxSizer. Returns the new window size.
@see ComputeFittingClientSize(), ComputeFittingWindowSize() @see ComputeFittingClientSize(), ComputeFittingWindowSize()
*/ */
@@ -1057,7 +1095,7 @@ public:
/** /**
Tell the sizer to resize the virtual size of the @a window to match the sizer's 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 cause the addition/removal/alteration of scrollbars required to view the virtual
area in windows which manage it. area in windows which manage it.
@@ -1065,19 +1103,16 @@ public:
*/ */
void FitInside(wxWindow* window); void FitInside(wxWindow* window);
//@{
/** /**
Returns the list of the items in this sizer. The elements of type-safe Returns the list of the items in this sizer.
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(); 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; const wxSizerItemList& GetChildren() const;
//@}
/** /**
Returns the window this sizer is used in or @NULL if none. Returns the window this sizer is used in or @NULL if none.
@@ -1085,46 +1120,45 @@ public:
wxWindow* GetContainingWindow() const; 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. Use parameter @a recursive to search in subsizers too.
Returns pointer to item or @NULL. Returns pointer to item or @NULL.
*/ */
wxSizerItem* GetItem(wxWindow* window, bool recursive = false); 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. Use parameter @a recursive to search in subsizers too.
Returns pointer to item or @NULL. Returns pointer to item or @NULL.
*/ */
wxSizerItem* GetItem(wxSizer* sizer, bool recursive = false); wxSizerItem* GetItem(wxSizer* sizer, bool recursive = false);
/** /**
Finds wxSizerItem which is located in the sizer at position Finds wxSizerItem which is located in the sizer at position @a index.
@a index.
Use parameter @a recursive to search in subsizers too. Use parameter @a recursive to search in subsizers too.
Returns pointer to item or @NULL. Returns pointer to item or @NULL.
*/ */
wxSizerItem* GetItem(size_t index); wxSizerItem* GetItem(size_t index);
/** /**
Finds item of the sizer which has the given @e id. This @a id is not the Finds item of the sizer which has the given @e id.
window id but the id of the wxSizerItem itself. This is mainly useful for This @a id is not the window id but the id of the wxSizerItem itself.
retrieving the sizers created from XRC resources. This is mainly useful for retrieving the sizers created from XRC resources.
Use parameter @a recursive to search in subsizers too. Use parameter @a recursive to search in subsizers too.
Returns pointer to item or @NULL. Returns pointer to item or @NULL.
*/ */
wxSizerItem* GetItemById(int id, bool recursive = false); wxSizerItem* GetItemById(int id, bool recursive = false);
/** /**
Returns the minimal size of the sizer. This is either the combined minimal Returns the minimal size of the sizer.
size of all the children and their borders or the minimal size set by
SetMinSize(), depending on which is bigger. 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. 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 In particular, if you use the value to set toplevel window's minimal or
actual size, use wxWindow::SetMinClientSize actual size, use wxWindow::SetMinClientSize() or wxWindow::SetClientSize(),
or wxWindow::SetClientSize, not not wxWindow::SetMinSize() or wxWindow::SetSize().
wxWindow::SetMinSize
or wxWindow::SetSize.
*/ */
wxSize GetMinSize(); wxSize GetMinSize();
@@ -1224,26 +1258,26 @@ public:
wxObject* userData = NULL); wxObject* userData = NULL);
/** /**
Inserts non-stretchable space to the sizer. More readable way of calling Inserts non-stretchable space to the sizer.
wxSizer::Insert(size, size, 0). More readable way of calling wxSizer::Insert(size, size, 0).
*/ */
wxSizerItem* InsertSpacer(size_t index, int size); wxSizerItem* InsertSpacer(size_t index, int size);
/** /**
Inserts stretchable space to the sizer. More readable way of calling Inserts stretchable space to the sizer.
wxSizer::Insert(0, 0, prop). More readable way of calling wxSizer::Insert(0, 0, prop).
*/ */
wxSizerItem* InsertStretchSpacer(size_t index, int prop = 1); 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() @see Hide(), Show(), wxSizerItem::IsShown()
*/ */
bool IsShown(wxWindow* window) const; 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() @see Hide(), Show(), wxSizerItem::IsShown()
*/ */
@@ -1259,8 +1293,7 @@ public:
/** /**
Call this to force layout of the children anew, e.g. after having added a child 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 to or removed a child (window, other sizer or space) from the sizer while
keeping keeping the current dimension.
the current dimension.
*/ */
virtual void Layout(); virtual void Layout();
@@ -1306,14 +1339,14 @@ public:
wxObject* userData = NULL); wxObject* userData = NULL);
/** /**
Prepends non-stretchable space to the sizer. More readable way of Prepends non-stretchable space to the sizer.
calling wxSizer::Prepend(size, size, 0). More readable way of calling wxSizer::Prepend(size, size, 0).
*/ */
wxSizerItem* PrependSpacer(int size); wxSizerItem* PrependSpacer(int size);
/** /**
Prepends stretchable space to the sizer. More readable way of calling Prepends stretchable space to the sizer.
wxSizer::Prepend(0, 0, prop). More readable way of calling wxSizer::Prepend(0, 0, prop).
*/ */
wxSizerItem* PrependStretchSpacer(int prop = 1); wxSizerItem* PrependStretchSpacer(int prop = 1);
@@ -1365,18 +1398,17 @@ public:
place, call Layout() to update the layout "on screen" after place, call Layout() to update the layout "on screen" after
removing a child from the sizer. removing a child from the sizer.
@param index The position of the child in the sizer, e.g. 0 for the @param index
first item. 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. @return @true if the child item was found and removed, @false otherwise.
*/ */
bool Remove(size_t index); bool Remove(size_t index);
/** /**
Detaches the given @a oldwin from the sizer and Detaches the given @a oldwin from the sizer and replaces it with the
replaces it with the given @a newwin. The detached given @a newwin. The detached child window is @b not deleted (because
child window is @b not deleted (because windows are windows are owned by their parent window, not the sizer).
owned by their parent window, not the sizer).
Use parameter @a recursive to search the given element recursively in subsizers. Use parameter @a recursive to search the given element recursively in subsizers.
@@ -1390,9 +1422,8 @@ public:
bool recursive = false); bool recursive = false);
/** /**
Detaches the given @a oldsz from the sizer and Detaches the given @a oldsz from the sizer and replaces it with the
replaces it with the given @a newsz. The detached given @a newsz. The detached child sizer is deleted.
child sizer is deleted.
Use parameter @a recursive to search the given element recursively in subsizers. Use parameter @a recursive to search the given element recursively in subsizers.
@@ -1436,8 +1467,8 @@ public:
/** /**
Set an item's minimum size by window, sizer, or position. Set an item's minimum size by window, sizer, or position.
The item will be found recursively in the sizer's descendants. This The item will be found recursively in the sizer's descendants.
function enables an application to set the size of an item after This function enables an application to set the size of an item after
initial creation. initial creation.
@see wxSizerItem::SetMinSize() @see wxSizerItem::SetMinSize()
@@ -1447,8 +1478,8 @@ public:
/** /**
Set an item's minimum size by window, sizer, or position. Set an item's minimum size by window, sizer, or position.
The item will be found recursively in the sizer's descendants. This The item will be found recursively in the sizer's descendants.
function enables an application to set the size of an item after This function enables an application to set the size of an item after
initial creation. initial creation.
@see wxSizerItem::SetMinSize() @see wxSizerItem::SetMinSize()
@@ -1458,8 +1489,8 @@ public:
/** /**
Set an item's minimum size by window, sizer, or position. Set an item's minimum size by window, sizer, or position.
The item will be found recursively in the sizer's descendants. This The item will be found recursively in the sizer's descendants.
function enables an application to set the size of an item after This function enables an application to set the size of an item after
initial creation. initial creation.
@see wxSizerItem::SetMinSize() @see wxSizerItem::SetMinSize()
@@ -1467,11 +1498,12 @@ public:
void SetItemMinSize(size_t index, int width, int height); void SetItemMinSize(size_t index, int width, int height);
/** /**
Call this to give the sizer a minimal size. Normally, the sizer will Call this to give the sizer a minimal size.
calculate its minimal size based purely on how much space its children
need. After calling this method GetMinSize() will return either the Normally, the sizer will calculate its minimal size based purely on how
minimal size as requested by its children or the minimal size set here, much space its children need. After calling this method GetMinSize()
depending on which is bigger. 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(const wxSize& size);
@@ -1481,27 +1513,28 @@ public:
void SetMinSize(int width, int height); void SetMinSize(int width, int height);
/** /**
This method first calls Fit() and then This method first calls Fit() and then wxTopLevelWindow::SetSizeHints()
wxTopLevelWindow::SetSizeHints on the @e window on the @a window passed to it.
passed to it. This only makes sense when @a window is actually a
wxTopLevelWindow such as a wxFrame or a This only makes sense when @a window is actually a wxTopLevelWindow such
wxDialog, since SetSizeHints only has any effect in these classes. as a wxFrame or a wxDialog, since SetSizeHints only has any effect in these classes.
It does nothing in normal windows or controls. 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 This method is implicitly used by wxWindow::SetSizerAndFit() which is
the sample in the description of wxBoxSizer) if the commonly invoked in the constructor of a toplevel window itself (see
toplevel window is resizable. the sample in the description of wxBoxSizer) if the toplevel window is
resizable.
*/ */
void SetSizeHints(wxWindow* window); void SetSizeHints(wxWindow* window);
/** /**
Tell the sizer to set the minimal size of the @a window virtual area to match Tell the sizer to set the minimal size of the @a window virtual area to match
the sizer's the sizer's minimal size. For windows with managed scrollbars this will set them
minimal size. For windows with managed scrollbars this will set them
appropriately. appropriately.
@see wxScrolled::SetScrollbars()
@deprecated @todo provide deprecation description @deprecated @todo provide deprecation description
@see wxScrolled::SetScrollbars()
*/ */
void SetVirtualSizeHints(wxWindow* window); void SetVirtualSizeHints(wxWindow* window);
@@ -1548,25 +1581,27 @@ public:
@class wxGridSizer @class wxGridSizer
A grid sizer is a sizer which lays out its children in a two-dimensional A grid sizer is a sizer which lays out its children in a two-dimensional
table with all table fields having the same size, table with all table fields having the same size, i.e. the width of each
i.e. the width of each field is the width of the widest child, field is the width of the widest child, the height of each field is the
the height of each field is the height of the tallest child. height of the tallest child.
@library{wxcore} @library{wxcore}
@category{winlayout} @category{winlayout}
@see wxSizer, @ref overview_sizer "Sizer Overview" @see wxSizer, @ref overview_sizer
*/ */
class wxGridSizer : public wxSizer class wxGridSizer : public wxSizer
{ {
public: public:
//@{ //@{
/** /**
Constructor for a wxGridSizer. @a rows and @a cols determine the number of Constructor for a wxGridSizer.
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 @a rows and @a cols determine the number of columns and rows in the sizer -
sizer grow dynamically. @a vgap and @a hgap define extra space between if either of the parameters is zero, it will be calculated to form the
all children. 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 rows, int cols, int vgap, int hgap);
wxGridSizer(int cols, int vgap = 0, int hgap = 0); wxGridSizer(int cols, int vgap = 0, int hgap = 0);
@@ -1619,31 +1654,32 @@ public:
@class wxStaticBoxSizer @class wxStaticBoxSizer
wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static
box around the sizer. This static box may be either created independently or box around the sizer.
the sizer may create it itself as a convenience. In any case, the sizer owns This static box may be either created independently or the sizer may create
the wxStaticBox control and will delete it if it is it itself as a convenience. In any case, the sizer owns the wxStaticBox control
deleted. and will delete it, if it is deleted.
@library{wxcore} @library{wxcore}
@category{winlayout} @category{winlayout}
@see wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizer @see wxSizer, wxStaticBox, wxBoxSizer, @ref overview_sizer
"Sizer Overview"
*/ */
class wxStaticBoxSizer : public wxBoxSizer class wxStaticBoxSizer : public wxBoxSizer
{ {
public: public:
//@{
/** /**
The first constructor uses an already existing static box. It takes the This constructor uses an already existing static box.
associated static box and the orientation @e orient, which can be either
@c wxVERTICAL or @c wxHORIZONTAL as parameters. It takes the associated static box and the orientation @a orient, which
The second one creates a new static box with the given label and parent window. can be either @c wxVERTICAL or @c wxHORIZONTAL as parameters.
*/ */
wxStaticBoxSizer(wxStaticBox* box, int orient); wxStaticBoxSizer(wxStaticBox* box, int orient);
/**
This constructor creates a new static box with the given label and parent window.
*/
wxStaticBoxSizer(int orient, wxWindow parent, wxStaticBoxSizer(int orient, wxWindow parent,
const wxString& label = wxEmptyString); const wxString& label = wxEmptyString);
//@}
/** /**
Returns the static box associated with the sizer. Returns the static box associated with the sizer.
@@ -1657,17 +1693,15 @@ public:
@class wxBoxSizer @class wxBoxSizer
The basic idea behind a box sizer is that windows will most often be laid out The basic idea behind a box sizer is that windows will most often be laid out
in rather in rather simple basic geometry, typically in a row or a column or several
simple basic geometry, typically in a row or a column or several hierarchies of hierarchies of either.
either.
For more information, please see @ref overview_sizer_box For more information, please see @ref overview_sizer_box.
"Programming with wxBoxSizer".
@library{wxcore} @library{wxcore}
@category{winlayout} @category{winlayout}
@see wxSizer, @ref overview_sizer "Sizers Overview" @see wxSizer, @ref overview_sizer
*/ */
class wxBoxSizer : public wxSizer class wxBoxSizer : public wxSizer
{ {
@@ -1679,8 +1713,10 @@ public:
wxBoxSizer(int orient); wxBoxSizer(int orient);
/** /**
Implements the calculation of a box sizer's minimal. It is used internally Implements the calculation of a box sizer's minimal.
only and must not be called by the user. Documented for information.
It is used internally only and must not be called by the user.
Documented for information.
*/ */
virtual wxSize CalcMin(); virtual wxSize CalcMin();
@@ -1692,9 +1728,10 @@ public:
/** /**
Implements the calculation of a box sizer's dimensions and then sets Implements the calculation of a box sizer's dimensions and then sets
the size of its children (calling wxWindow::SetSize the size of its children (calling wxWindow::SetSize if the child is a window).
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. 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(); void RecalcSizes();
}; };

View File

@@ -132,6 +132,8 @@ public:
Minimum slider position. Minimum slider position.
@param maxValue @param maxValue
Maximum slider position. Maximum slider position.
@param pos
Window position. If wxDefaultPosition is specified then a default position is chosen.
@param size @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 @param style
@@ -145,7 +147,7 @@ public:
*/ */
wxSlider(wxWindow* parent, wxWindowID id, int value, wxSlider(wxWindow* parent, wxWindowID id, int value,
int minValue, int maxValue, int minValue, int maxValue,
const wxPoint& point = wxDefaultPosition, const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize, const wxSize& size = wxDefaultSize,
long style = wxSL_HORIZONTAL, long style = wxSL_HORIZONTAL,
const wxValidator& validator = wxDefaultValidator, const wxValidator& validator = wxDefaultValidator,

View File

@@ -10,14 +10,15 @@
@class wxSingleInstanceChecker @class wxSingleInstanceChecker
wxSingleInstanceChecker class allows to check that only a single instance of a 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 program is running.
long as this object is alive, calls to
wxSingleInstanceChecker::IsAnotherRunning from To do it, you should create an object of this class. As long as this object
other processes will return @true. 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 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 create it either as a global or in wxApp::OnInit.
example: For example:
@code @code
bool MyApp::OnInit() bool MyApp::OnInit()
@@ -47,10 +48,10 @@
} }
@endcode @endcode
Note using wxGetUserId() to construct the name: this Note using wxGetUserId() to construct the name: this allows different user
allows different user to run the application concurrently which is usually the to run the application concurrently which is usually the intended goal.
intended goal. If you don't use the user name in the wxSingleInstanceChecker If you don't use the user name in the wxSingleInstanceChecker name, only
name, only one user would be able to run the application at a time. one user would be able to run the application at a time.
This class is implemented for Win32 and Unix platforms (supporting @c fcntl() This class is implemented for Win32 and Unix platforms (supporting @c fcntl()
system call, but almost all of modern Unix systems do) only. system call, but almost all of modern Unix systems do) only.
@@ -62,37 +63,49 @@ class wxSingleInstanceChecker
{ {
public: public:
/** /**
Like Create() but without Default ctor, use Create() after it.
error checking. */
wxSingleInstanceChecker();
/**
Like Create() but without error checking.
*/ */
wxSingleInstanceChecker(const wxString& name, wxSingleInstanceChecker(const wxString& name,
const wxString& path = wxEmptyString); const wxString& path = wxEmptyString);
/** /**
Destructor frees the associated resources. 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(); ~wxSingleInstanceChecker();
/** /**
Initialize the object if it had been created using the default constructor. 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 Note that you can't call Create() more than once, so calling it if the
@ref wxsingleinstancechecker() "non default ctor" @ref wxSingleInstanceChecker() "non default ctor" had been used is an error.
had been used is an error.
@param name @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. mutex name under Win32 and the lock file name under Unix.
GetAppName() and wxGetUserId() GetAppName() and wxGetUserId() are commonly used to construct
are commonly used to construct this parameter. this parameter.
@param path @param path
is optional and is ignored under Win32 and used as the directory to The path is optional and is ignored under Win32 and used as the
create the lock file in under Unix (default is directory to create the lock file in under Unix
wxGetHomeDir()) (default is wxGetHomeDir()).
@return Returns @false if initialization failed, it doesn't mean that @return Returns @false if initialization failed, it doesn't mean that
another instance is running - use IsAnotherRunning() another instance is running - use IsAnotherRunning() to check
to check for it. 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, bool Create(const wxString& name,
const wxString& path = wxEmptyString); const wxString& path = wxEmptyString);

View File

@@ -1,6 +1,6 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: socket.h // Name: socket.h
// Purpose: interface of wxIPV4address // Purpose: interface of wxIP*address, wxSocket* classes
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
// Licence: wxWindows license // Licence: wxWindows license
@@ -31,10 +31,10 @@ public:
/** /**
Set the address to hostname, which can be a host name or an IP-style address 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 @return @true on success, @false if something goes wrong (invalid
invalid IP address). hostname or invalid IP address).
*/ */
bool Hostname(const wxString& hostname); bool Hostname(const wxString& hostname);
@@ -55,7 +55,6 @@ public:
correctly handle multi-homed hosts and avoid other small problems. correctly handle multi-homed hosts and avoid other small problems.
@return @true on success, @false if something went wrong. @return @true on success, @false if something went wrong.
*/ */
bool LocalHost(); bool LocalHost();
@@ -63,7 +62,6 @@ public:
Set the port to that corresponding to the specified @a service. Set the port to that corresponding to the specified @a service.
@return @true on success, @false if something goes wrong (invalid @a service). @return @true on success, @false if something goes wrong (invalid @a service).
*/ */
bool Service(const wxString& service); bool Service(const wxString& service);
@@ -85,6 +83,8 @@ public:
/** /**
@class wxSocketServer @class wxSocketServer
@todo describe me.
@library{wxnet} @library{wxnet}
@category{net} @category{net}
*/ */
@@ -100,7 +100,7 @@ public:
@param address @param address
Specifies the local address for the server (e.g. port number). Specifies the local address for the server (e.g. port number).
@param flags @param flags
Socket flags (See wxSocketBase::SetFlags()) Socket flags (See wxSocketBase::SetFlags()).
*/ */
wxSocketServer(const wxSockAddress& address, wxSocketServer(const wxSockAddress& address,
wxSocketFlags flags = wxSOCKET_NONE); wxSocketFlags flags = wxSOCKET_NONE);
@@ -111,12 +111,14 @@ public:
virtual ~wxSocketServer(); virtual ~wxSocketServer();
/** /**
Accepts an incoming connection request, and creates a new wxSocketBase object Accepts an incoming connection request, and creates a new wxSocketBase
which represents the server-side of the connection. object which represents the server-side of the connection.
If @a wait is @true and there are no pending connections to be If @a wait is @true and there are no pending connections to be
accepted, it will wait for the next incoming connection to 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 @a wait is @false, it will try to accept a pending connection
if there is one, but it will always return immediately without blocking if there is one, but it will always return immediately without blocking
@@ -139,10 +141,12 @@ public:
@param socket @param socket
Socket to be initialized 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 @return Returns @true on success, or @false if an error occurred or
wait parameter was @false and there were no pending if the wait parameter was @false and there were no pending
connections. connections.
@see WaitForAccept(), wxSocketBase::SetNotify(), @see WaitForAccept(), wxSocketBase::SetNotify(),
wxSocketBase::Notify(), Accept() wxSocketBase::Notify(), Accept()
@@ -150,10 +154,10 @@ public:
bool AcceptWith(wxSocketBase& socket, bool wait = true); bool AcceptWith(wxSocketBase& socket, bool wait = true);
/** /**
This function waits for an incoming connection. Use it if you want to call This function waits for an incoming connection.
Accept() or AcceptWith()
with @e wait set to @false, to detect when an incoming connection is waiting Use it if you want to call Accept() or AcceptWith() with @e wait set
to be accepted. to @false, to detect when an incoming connection is waiting to be accepted.
@param seconds @param seconds
Number of seconds to wait. If -1, it will wait for the default Number of seconds to wait. If -1, it will wait for the default
@@ -216,7 +220,7 @@ public:
/** /**
Returns the hostname which matches the IP address. Returns the hostname which matches the IP address.
*/ */
virtual wxString Hostname(); virtual wxString Hostname();
/** /**
Returns a wxString containing the IP address. Returns a wxString containing the IP address.
@@ -266,6 +270,8 @@ public:
/** /**
@class wxSocketClient @class wxSocketClient
@todo describe me.
@library{wxnet} @library{wxnet}
@category{net} @category{net}
*/ */
@@ -289,7 +295,9 @@ public:
Connects to a server using the specified address. Connects to a server using the specified address.
If @a wait is @true, Connect() will wait until the connection 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 If @a wait is @false, Connect() will try to establish the connection
and return immediately, without blocking the GUI. When used this way, and return immediately, without blocking the GUI. When used this way,
@@ -304,6 +312,12 @@ public:
If @true, waits for the connection to complete. If @true, waits for the connection to complete.
@return @true if the connection is established and no error occurs. @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() @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
*/ */
@@ -332,6 +346,12 @@ public:
If @true, waits for the connection to complete. If @true, waits for the connection to complete.
@return @true if the connection is established and no error occurs. @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() @see WaitOnConnect(), wxSocketBase::SetNotify(), wxSocketBase::Notify()
*/ */
@@ -340,36 +360,36 @@ public:
/** /**
Wait until a connection request completes, or until the specified timeout Wait until a connection request completes, or until the specified timeout
elapses. Use this function after issuing a call elapses. Use this function after issuing a call to Connect() with
to Connect() with @e wait set to @false. @e wait set to @false.
@param seconds @param seconds
Number of seconds to wait. Number of seconds to wait.
If -1, it will wait for the default timeout, If -1, it will wait for the default timeout, as set with wxSocketBase::SetTimeout().
as set with wxSocketBase::SetTimeout(). @param milliseconds
@param millisecond
Number of milliseconds to wait. Number of milliseconds to wait.
@return WaitOnConnect() returns @true if the connection request completes. @return
This does not necessarily mean that the connection was WaitOnConnect() returns @true if the connection request completes.
successfully established; it might also happen that the This does not necessarily mean that the connection was
connection was refused by the peer. Use wxSocketBase::IsConnected() successfully established; it might also happen that the
to distinguish between these two situations. connection was refused by the peer. Use wxSocketBase::IsConnected()
@n @n If the timeout elapses, WaitOnConnect() returns @false. to distinguish between these two situations.
@n @n These semantics allow code like this: @n @n If the timeout elapses, WaitOnConnect() returns @false.
@code @n @n These semantics allow code like this:
// Issue the connection request @code
client->Connect(addr, false); // Issue the connection request
client->Connect(addr, false);
// Wait until the request completes or until we decide to give up // Wait until the request completes or until we decide to give up
bool waitmore = true; bool waitmore = true;
while ( !client->WaitOnConnect(seconds, millis) && waitmore ) while ( !client->WaitOnConnect(seconds, millis) && waitmore )
{ {
// possibly give some feedback to the user, // possibly give some feedback to the user,
// and update waitmore as needed. // and update waitmore as needed.
} }
bool success = client->IsConnected(); bool success = client->IsConnected();
@endcode @endcode
*/ */
bool WaitOnConnect(long seconds = -1, long milliseconds = 0); bool WaitOnConnect(long seconds = -1, long milliseconds = 0);
}; };
@@ -442,8 +462,8 @@ public:
void* GetClientData() const; void* GetClientData() const;
/** /**
Returns the socket object to which this event refers to. This makes Returns the socket object to which this event refers to.
it possible to use the same event handler for different sockets. This makes it possible to use the same event handler for different sockets.
*/ */
wxSocketBase* GetSocket() const; wxSocketBase* GetSocket() const;
@@ -473,6 +493,8 @@ enum wxSocketError
/** /**
@anchor wxSocketEventFlags
wxSocket Event Flags. wxSocket Event Flags.
A brief note on how to use these events: A brief note on how to use these events:
@@ -566,15 +588,15 @@ enum wxSocketEventFlags
wxIPaddress::BroadcastAddress(). wxIPaddress::BroadcastAddress().
So: So:
@b wxSOCKET_NONE will try to read at least SOME data, no matter how much. - @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 - @b wxSOCKET_NOWAIT will always return immediately, even if it cannot
read or write ANY data. read or write ANY data.
@b wxSOCKET_WAITALL will only return when it has read or written ALL - @b wxSOCKET_WAITALL will only return when it has read or written ALL
the data. the data.
@b wxSOCKET_BLOCK has nothing to do with the previous flags and - @b wxSOCKET_BLOCK has nothing to do with the previous flags and
it controls whether the GUI blocks. it controls whether the GUI blocks.
@b wxSOCKET_REUSEADDR controls special platform-specific behavior for - @b wxSOCKET_REUSEADDR controls special platform-specific behavior for
reusing local addresses/ports. reusing local addresses/ports.
*/ */
enum enum
{ {
@@ -593,39 +615,26 @@ enum
/** /**
@class wxSocketBase @class wxSocketBase
wxSocketBase is the base class for all socket-related objects, and it wxSocketBase is the base class for all socket-related objects, and it
defines all basic IO functionality. 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 If you want to use sockets or derived classes such as wxFTP in a secondary
thread, thread, call @b wxSocketBase::Initialize() (undocumented) from the main
call @b wxSocketBase::Initialize() (undocumented) from the main thread before thread before creating any sockets - in wxApp::OnInit() for example.
creating any sockets - in wxApp::OnInit() for example.
See http://wiki.wxwidgets.org/wiki.pl?WxSocket or See http://wiki.wxwidgets.org/wiki.pl?WxSocket or
http://www.litwindow.com/knowhow/knowhow.html for more details. 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} @beginEventTable{wxSocketEvent}
@event{EVT_SOCKET(id, func)} @event{EVT_SOCKET(id, func)}
Process a @c wxEVT_SOCKET event. Process a @c wxEVT_SOCKET event.
See @ref wxSocketEventFlags and @ref wxSocketFlags for more info.
@endEventTable @endEventTable
@library{wxnet}
@category{net}
@see wxSocketEvent, wxSocketClient, wxSocketServer, @sample{sockets}, @see wxSocketEvent, wxSocketClient, wxSocketServer, @sample{sockets},
@ref wxSocketFlags, ::wxSocketEventFlags, ::wxSocketError @ref wxSocketFlags, ::wxSocketEventFlags, ::wxSocketError
*/ */
@@ -728,14 +737,10 @@ public:
cases. cases.
@remarks @remarks
For wxSocketClient, IsOk() won't return @true unless the client is connected to a server. 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 For wxSocketServer, IsOk() will return @true if the server could bind to the specified address
and is already listening for new connections. and is already listening for new connections.
IsOk() does not check for IO errors; use Error() instead for that purpose. IsOk() does not check for IO errors; use Error() instead for that purpose.
*/ */
bool IsOk() const; bool IsOk() const;
@@ -752,7 +757,6 @@ public:
Returns the last wxSocket error. See @ref wxSocketError . Returns the last wxSocket error. See @ref wxSocketError .
@note @note
This function merely returns the last error code, This function merely returns the last error code,
but it should not be used to determine if an error has occurred (this but it should not be used to determine if an error has occurred (this
is because successful operations do not change the LastError value). is because successful operations do not change the LastError value).
@@ -772,11 +776,9 @@ public:
void RestoreState(); void RestoreState();
/** /**
This function saves the current state of the socket in a stack. Socket This function saves the current state of the socket in a stack.
state includes flags, as set with SetFlags(), Socket state includes flags, as set with SetFlags(), event mask, as set
event mask, as set with SetNotify() and with SetNotify() and Notify(), user data, as set with SetClientData().
Notify(), user data, as set with
SetClientData().
Calls to SaveState and RestoreState can be nested. Calls to SaveState and RestoreState can be nested.
@see RestoreState() @see RestoreState()
@@ -803,7 +805,6 @@ public:
the socket, typically to notify the peer that you are closing the connection. the socket, typically to notify the peer that you are closing the connection.
@remarks @remarks
Although Close() immediately disables events for the socket, it is possible Although Close() immediately disables events for the socket, it is possible
that event messages may be waiting in the application's event queue. that event messages may be waiting in the application's event queue.
The application must therefore be prepared to handle socket event messages even The application must therefore be prepared to handle socket event messages even
@@ -837,7 +838,7 @@ public:
socket destruction), so you don't need to use it in these cases. socket destruction), so you don't need to use it in these cases.
@see Wait(), WaitForLost(), WaitForRead(), WaitForWrite(), @see Wait(), WaitForLost(), WaitForRead(), WaitForWrite(),
wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect() wxSocketServer::WaitForAccept(), wxSocketClient::WaitOnConnect()
*/ */
void InterruptWait(); void InterruptWait();
@@ -858,9 +859,8 @@ public:
@return Returns a reference to the current object. @return Returns a reference to the current object.
@remarks @remarks
The exact behaviour of Peek() depends on the combination of flags being used.
The exact behaviour of Peek() depends on the combination of flags being used. For a detailed explanation, see SetFlags()
For a detailed explanation, see SetFlags()
@see Error(), LastError(), LastCount(), SetFlags() @see Error(), LastError(), LastCount(), SetFlags()
*/ */
@@ -879,9 +879,8 @@ public:
@return Returns a reference to the current object. @return Returns a reference to the current object.
@remarks @remarks
The exact behaviour of Read() depends on the combination of flags being used.
The exact behaviour of Read() depends on the combination of flags being used. For a detailed explanation, see SetFlags()
For a detailed explanation, see SetFlags()
@see Error(), LastError(), LastCount(), @see Error(), LastError(), LastCount(),
SetFlags() SetFlags()
@@ -906,11 +905,10 @@ public:
@return Returns a reference to the current object. @return Returns a reference to the current object.
@remarks @remarks
ReadMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set
ReadMsg() will behave as if the @b wxSOCKET_WAITALL flag was always set and it will always ignore the @b wxSOCKET_NOWAIT flag.
and it will always ignore the @b wxSOCKET_NOWAIT flag. The exact behaviour The exact behaviour of ReadMsg() depends on the @b wxSOCKET_BLOCK flag.
of ReadMsg() depends on the @b wxSOCKET_BLOCK flag. For a detailed explanation, see SetFlags().
For a detailed explanation, see SetFlags().
@see Error(), LastError(), LastCount(), SetFlags(), WriteMsg() @see Error(), LastError(), LastCount(), SetFlags(), WriteMsg()
*/ */
@@ -998,7 +996,7 @@ public:
Number of milliseconds to wait. Number of milliseconds to wait.
@return Returns @true when any of the above conditions is satisfied, @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(), @see InterruptWait(), wxSocketServer::WaitForAccept(),
WaitForLost(), WaitForRead(), WaitForLost(), WaitForRead(),
@@ -1018,7 +1016,7 @@ public:
Number of milliseconds to wait. Number of milliseconds to wait.
@return Returns @true if the connection was lost, @false if the timeout @return Returns @true if the connection was lost, @false if the timeout
was reached. was reached.
@see InterruptWait(), Wait() @see InterruptWait(), Wait()
*/ */
@@ -1231,7 +1229,7 @@ public:
Number of bytes. Number of bytes.
@return Returns a reference to the current object, and the address of @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() @see wxSocketBase::LastError(), wxSocketBase::SetFlags()
*/ */

View File

@@ -10,31 +10,32 @@
@class wxSound @class wxSound
This class represents a short sound (loaded from Windows WAV file), that This class represents a short sound (loaded from Windows WAV file), that
can be stored in memory and played. Currently this class is implemented can be stored in memory and played.
on Windows and Unix (and uses either
Open Sound System or Currently this class is implemented on Windows and Unix (and uses either
Simple DirectMedia Layer). Open Sound System or Simple DirectMedia Layer).
@library{wxadv} @library{wxadv}
@category{FIXME} @category{misc}
*/ */
class wxSound : public wxObject class wxSound : public wxObject
{ {
public: public:
//@{ /**
Default ctor.
*/
wxSound();
/** /**
Constructs a wave object from a file or, under Windows, from a Windows Constructs a wave object from a file or, under Windows, from a Windows
resource. Call IsOk() to determine whether this resource. Call IsOk() to determine whether this succeeded.
succeeded.
@param fileName @param fileName
The filename or Windows resource. The filename or Windows resource.
@param isResource @param isResource
@true if fileName is a resource, @false if it is a filename. @true if fileName is a resource, @false if it is a filename.
*/ */
wxSound();
wxSound(const wxString& fileName, bool isResource = false); wxSound(const wxString& fileName, bool isResource = false);
//@}
/** /**
Destroys the wxSound object. Destroys the wxSound object.
@@ -68,34 +69,27 @@ public:
//@{ //@{
/** /**
Plays the sound file. If another sound is playing, it will be interrupted. 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 Returns @true on success, @false otherwise. Note that in general it is
possible possible to delete the object which is being asynchronously played any time
to delete the object which is being asynchronously played any time after after calling this function and the sound would continue playing, however this
calling this function and the sound would continue playing, however this
currently doesn't work under Windows for sound objects loaded from memory data. currently doesn't work under Windows for sound objects loaded from memory data.
The possible values for @a flags are: The possible values for @a flags are:
- wxSOUND_SYNC: @c Play will block and wait until the sound is replayed.
wxSOUND_SYNC - wxSOUND_ASYNC: Sound is played asynchronously, @c Play returns immediately.
- wxSOUND_ASYNC|wxSOUND_LOOP: Sound is played asynchronously and loops
@c Play will block and wait until the sound is until another sound is played, Stop() is
replayed. called or the program terminates.
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: The static form is shorthand for this code:
@code
wxSound(filename).Play(flags);
@endcode
*/ */
bool Play(unsigned flags = wxSOUND_ASYNC); bool Play(unsigned flags = wxSOUND_ASYNC) const;
const static bool Play(const wxString& filename, static bool Play(const wxString& filename,
unsigned flags = wxSOUND_ASYNC); unsigned flags = wxSOUND_ASYNC);
//@} //@}
/** /**

View File

@@ -1,6 +1,6 @@
///////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////
// Name: spinbutt.h // Name: spinbutt.h
// Purpose: interface of wxSpinEvent // Purpose: interface of wxSpinEvent, wxSpinButton
// Author: wxWidgets team // Author: wxWidgets team
// RCS-ID: $Id$ // RCS-ID: $Id$
// Licence: wxWindows license // Licence: wxWindows license
@@ -9,8 +9,20 @@
/** /**
@class wxSpinEvent @class wxSpinEvent
This event class is used for the events generated by This event class is used for the events generated by wxSpinButton and wxSpinCtrl.
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} @library{wxcore}
@category{events} @category{events}
@@ -41,16 +53,17 @@ public:
/** /**
@class wxSpinButton @class wxSpinButton
A wxSpinButton has two small up and down (or left and right) arrow buttons. It A wxSpinButton has two small up and down (or left and right) arrow buttons.
is often used next to a text control for increment and decrementing a value.
Portable programs should try to use wxSpinCtrl instead It is often used next to a text control for increment and decrementing a value.
as wxSpinButton is not implemented for all platforms but wxSpinCtrl is as it Portable programs should try to use wxSpinCtrl instead as wxSpinButton is not
degenerates to a simple wxTextCtrl on such platforms. 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 @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 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 Win32 with sufficiently new version of @c comctrl32.dll (at least 4.71
required, 5.80 is recommended) the full 32 bit range is supported. is required, 5.80 is recommended) the full 32 bit range is supported.
@beginStyleTable @beginStyleTable
@style{wxSP_HORIZONTAL} @style{wxSP_HORIZONTAL}
@@ -64,6 +77,19 @@ public:
The value wraps at the minimum and maximum. The value wraps at the minimum and maximum.
@endStyleTable @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} @library{wxcore}
@category{ctrl} @category{ctrl}
<!-- @appearance{spinbutton.png} --> <!-- @appearance{spinbutton.png} -->
@@ -77,7 +103,7 @@ public:
Default constructor. Default constructor.
*/ */
wxSpinButton(); wxSpinButton();
/** /**
Constructor, creating and showing a spin button. Constructor, creating and showing a spin button.
@@ -86,13 +112,13 @@ public:
@param id @param id
Window identifier. The value wxID_ANY indicates a default value. Window identifier. The value wxID_ANY indicates a default value.
@param pos @param pos
Window position. If wxDefaultPosition is specified then a default Window position.
position is chosen. If wxDefaultPosition is specified then a default position is chosen.
@param size @param size
Window size. If wxDefaultSize is specified then a default size Window size.
is chosen. If wxDefaultSize is specified then a default size is chosen.
@param style @param style
Window style. See wxSpinButton. Window style. See wxSpinButton class description.
@param name @param name
Window name. Window name.

View File

@@ -9,8 +9,7 @@
/** /**
@class wxSpinCtrl @class wxSpinCtrl
wxSpinCtrl combines wxTextCtrl and wxSpinCtrl combines wxTextCtrl and wxSpinButton in one control.
wxSpinButton in one control.
@beginStyleTable @beginStyleTable
@style{wxSP_ARROW_KEYS} @style{wxSP_ARROW_KEYS}
@@ -24,6 +23,20 @@
dialog) under MSW. dialog) under MSW.
@endStyleTable @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} @library{wxcore}
@category{ctrl} @category{ctrl}
<!-- @appearance{spinctrl.png} --> <!-- @appearance{spinctrl.png} -->
@@ -37,7 +50,7 @@ public:
Default constructor. Default constructor.
*/ */
wxSpinCtrl(); wxSpinCtrl();
/** /**
Constructor, creating and showing a spin control. Constructor, creating and showing a spin control.
@@ -48,11 +61,11 @@ public:
@param id @param id
Window identifier. The value wxID_ANY indicates a default value. Window identifier. The value wxID_ANY indicates a default value.
@param pos @param pos
Window position. If wxDefaultPosition is specified then a default Window position.
position is chosen. If wxDefaultPosition is specified then a default position is chosen.
@param size @param size
Window size. If wxDefaultSize is specified then a default size Window size.
is chosen. If wxDefaultSize is specified then a default size is chosen.
@param style @param style
Window style. See wxSpinButton. Window style. See wxSpinButton.
@param min @param min
@@ -108,10 +121,11 @@ public:
/** /**
Select the text in the text part of the control between positions Select the text in the text part of the control between positions
@a from (inclusive) and @a to (exclusive). This is similar to @a from (inclusive) and @a to (exclusive).
wxTextCtrl::SetSelection. This is similar to wxTextCtrl::SetSelection().
@note this is currently only implemented for Windows and generic versions @note this is currently only implemented for Windows and generic versions
of the control. of the control.
*/ */
void SetSelection(long from, long to); void SetSelection(long from, long to);

View File

@@ -10,15 +10,15 @@
@class wxSplashScreen @class wxSplashScreen
wxSplashScreen shows a window with a thin border, displaying a bitmap wxSplashScreen shows a window with a thin border, displaying a bitmap
describing your describing your application.
application. Show it in application initialisation, and then either explicitly
destroy Show it in application initialisation, and then either explicitly destroy
it or let it time-out. it or let it time-out.
Example usage: Example usage:
@code @code
wxBitmap bitmap; wxBitmap bitmap;
if (bitmap.LoadFile("splash16.png", wxBITMAP_TYPE_PNG)) if (bitmap.LoadFile("splash16.png", wxBITMAP_TYPE_PNG))
{ {
wxSplashScreen* splash = new wxSplashScreen(bitmap, wxSplashScreen* splash = new wxSplashScreen(bitmap,
@@ -37,14 +37,15 @@ class wxSplashScreen : public wxFrame
public: public:
/** /**
Construct the splash screen passing a bitmap, a style, a timeout, a window id, Construct the splash screen passing a bitmap, a style, a timeout, a window id,
optional position optional position and size, and a window style.
and size, and a window style.
@a splashStyle is a bitlist of some of the following: @a splashStyle is a bitlist of some of the following:
wxSPLASH_CENTRE_ON_PARENT - wxSPLASH_CENTRE_ON_PARENT
wxSPLASH_CENTRE_ON_SCREEN - wxSPLASH_CENTRE_ON_SCREEN
wxSPLASH_NO_CENTRE - wxSPLASH_NO_CENTRE
wxSPLASH_TIMEOUT - wxSPLASH_TIMEOUT
wxSPLASH_NO_TIMEOUT - wxSPLASH_NO_TIMEOUT
@a milliseconds is the timeout in milliseconds. @a milliseconds is the timeout in milliseconds.
*/ */
wxSplashScreen(const wxBitmap& bitmap, long splashStyle, wxSplashScreen(const wxBitmap& bitmap, long splashStyle,
@@ -61,8 +62,7 @@ public:
virtual ~wxSplashScreen(); virtual ~wxSplashScreen();
/** /**
Returns the splash style (see wxSplashScreen() for Returns the splash style (see wxSplashScreen() for details).
details).
*/ */
long GetSplashStyle() const; long GetSplashStyle() const;

View File

@@ -9,10 +9,8 @@
/** /**
@class wxSplitterWindow @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. either programmatically or via the wxSplitterWindow user interface.
@beginStyleTable @beginStyleTable
@@ -33,16 +31,35 @@
using Windows XP theming, so the borders and sash will take on the using Windows XP theming, so the borders and sash will take on the
pre-XP look. pre-XP look.
@style{wxSP_PERMIT_UNSPLIT} @style{wxSP_PERMIT_UNSPLIT}
Always allow to unsplit, even with the minimum pane size other than Always allow to unsplit, even with the minimum pane size other than zero.
zero.
@style{wxSP_LIVE_UPDATE} @style{wxSP_LIVE_UPDATE}
Don't draw XOR line but resize the child windows immediately. Don't draw XOR line but resize the child windows immediately.
@endStyleTable @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} @library{wxcore}
@category{miscwnd} @category{miscwnd}
@see wxSplitterEvent @see wxSplitterEvent, @ref overview_splitterwindow
*/ */
class wxSplitterWindow : public wxWindow class wxSplitterWindow : public wxWindow
{ {
@@ -51,7 +68,7 @@ public:
Default constructor Default constructor
*/ */
wxSplitterWindow(); wxSplitterWindow();
/** /**
Constructor for creating the window. Constructor for creating the window.
@@ -68,18 +85,18 @@ public:
@param name @param name
The window name. The window name.
@remarks After using this constructor, you must create either one or two @remarks
subwindows with the splitter window as parent, and then After using this constructor, you must create either one or two
call one of Initialize(), subwindows with the splitter window as parent, and then call one
SplitVertically() and of Initialize(), SplitVertically() and SplitHorizontally() in order
SplitHorizontally() in order to set the to set the pane(s).
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(), @see Initialize(), SplitVertically(), SplitHorizontally(), Create()
SplitHorizontally(), Create()
*/ */
wxSplitterWindow(wxWindow* parent, wxWindowID id, wxSplitterWindow(wxWindow* parent, wxWindowID id,
const wxPoint& point = wxDefaultPosition, const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize, const wxSize& size = wxDefaultSize,
long style = wxSP_3D, long style = wxSP_3D,
const wxString& name = "splitterWindow"); const wxString& name = "splitterWindow");
@@ -90,8 +107,8 @@ public:
virtual ~wxSplitterWindow(); virtual ~wxSplitterWindow();
/** /**
Creation function, for two-step construction. See wxSplitterWindow() for Creation function, for two-step construction.
details. See wxSplitterWindow() for details.
*/ */
bool Create(wxWindow* parent, wxWindowID id, bool Create(wxWindow* parent, wxWindowID id,
const wxPoint& point = wxDefaultPosition, const wxPoint& point = wxDefaultPosition,
@@ -123,8 +140,7 @@ public:
/** /**
Gets the split mode. Gets the split mode.
@see SetSplitMode(), SplitVertically(), @see SetSplitMode(), SplitVertically(), SplitHorizontally().
SplitHorizontally().
*/ */
int GetSplitMode() const; int GetSplitMode() const;
@@ -139,8 +155,8 @@ public:
wxWindow* GetWindow2() const; wxWindow* GetWindow2() const;
/** /**
Initializes the splitter window to have one pane. The child window is Initializes the splitter window to have one pane.
shown if it is currently hidden. The child window is shown if it is currently hidden.
@param window @param window
The pane for the unsplit window. The pane for the unsplit window.
@@ -204,6 +220,7 @@ public:
and then resplitting the window back because it will provoke much less flicker 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 (if any). It is valid to call this function whether the splitter has two
windows or only one. windows or only one.
Both parameters should be non-@NULL and @a winOld must specify one of the 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 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 couldn't be replaced, @false is returned. Otherwise the function will return
@@ -238,6 +255,19 @@ public:
@param gravity @param gravity
The sash gravity. Value between 0.0 and 1.0. 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() @see GetSashGravity()
*/ */
void SetSashGravity(double gravity); void SetSashGravity(double gravity);
@@ -273,65 +303,59 @@ public:
@remarks Only sets the internal variable; does not update the display. @remarks Only sets the internal variable; does not update the display.
@see GetSplitMode(), SplitVertically(), @see GetSplitMode(), SplitVertically(), SplitHorizontally().
SplitHorizontally().
*/ */
void SetSplitMode(int mode); void SetSplitMode(int mode);
/** /**
Initializes the top and bottom panes of the splitter window. The Initializes the top and bottom panes of the splitter window.
child windows are shown if they are currently hidden. The child windows are shown if they are currently hidden.
@param window1 @param window1
The top pane. The top pane.
@param window2 @param window2
The bottom pane. The bottom pane.
@param sashPosition @param sashPosition
The initial position of the sash. If this value is The initial position of the sash. If this value is positive,
positive, it specifies the size of the upper pane. If it is negative, its 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 absolute value gives the size of the lower pane.
(default) Finally, specify 0 (default) to choose the default position
to choose the default position (half of the total window height). (half of the total window height).
@return @true if successful, @false otherwise (the window was already @return @true if successful, @false otherwise (the window was already split).
split).
@remarks This should be called if you wish to initially view two panes. @remarks This should be called if you wish to initially view two panes.
It can also be called at any subsequent time, but the It can also be called at any subsequent time, but the application
application should check that the window is not should check that the window is not currently split using IsSplit().
currently split using IsSplit.
@see SplitVertically(), IsSplit(), @see SplitVertically(), IsSplit(), Unsplit()
Unsplit()
*/ */
bool SplitHorizontally(wxWindow* window1, wxWindow* window2, bool SplitHorizontally(wxWindow* window1, wxWindow* window2,
int sashPosition = 0); int sashPosition = 0);
/** /**
Initializes the left and right panes of the splitter window. The Initializes the left and right panes of the splitter window.
child windows are shown if they are currently hidden. The child windows are shown if they are currently hidden.
@param window1 @param window1
The left pane. The left pane.
@param window2 @param window2
The right pane. The right pane.
@param sashPosition @param sashPosition
The initial position of the sash. If this value is The initial position of the sash. If this value is positive, it
positive, it specifies the size of the left pane. If it is negative, it is 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 absolute value gives the size of the right pane.
(default) Finally, specify 0 (default) to choose the default position
to choose the default position (half of the total window width). (half of the total window width).
@return @true if successful, @false otherwise (the window was already @return @true if successful, @false otherwise (the window was already split).
split).
@remarks This should be called if you wish to initially view two panes. @remarks This should be called if you wish to initially view two panes.
It can also be called at any subsequent time, but the It can also be called at any subsequent time, but the
application should check that the window is not application should check that the window is not currently
currently split using IsSplit. split using IsSplit().
@see SplitHorizontally(), IsSplit(), @see SplitHorizontally(), IsSplit(), Unsplit().
Unsplit().
*/ */
bool SplitVertically(wxWindow* window1, wxWindow* window2, bool SplitVertically(wxWindow* window1, wxWindow* window2,
int sashPosition = 0); int sashPosition = 0);
@@ -345,23 +369,23 @@ public:
@return @true if successful, @false otherwise (the window was not split). @return @true if successful, @false otherwise (the window was not split).
@remarks This call will not actually delete the pane being removed; it @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. behaviour. By default, the pane being removed is hidden.
@see SplitHorizontally(), SplitVertically(), @see SplitHorizontally(), SplitVertically(), IsSplit(), OnUnsplit()
IsSplit(), OnUnsplit()
*/ */
bool Unsplit(wxWindow* toRemove = NULL); bool Unsplit(wxWindow* toRemove = NULL);
/** /**
Causes any pending sizing of the sash and child panes to take place Causes any pending sizing of the sash and child panes to take place
immediately. immediately.
Such resizing normally takes place in idle time, in order
to wait for layout to be completed. However, this can cause Such resizing normally takes place in idle time, in order to wait for
unacceptable flicker as the panes are resized after the window has been layout to be completed. However, this can cause unacceptable flicker as
shown. To work around this, you can perform window layout (for the panes are resized after the window has been shown.
example by sending a size event to the parent window), and then To work around this, you can perform window layout (for example by
call this function, before showing the top-level window. sending a size event to the parent window), and then call this function,
before showing the top-level window.
*/ */
void UpdateSize(); void UpdateSize();
}; };
@@ -371,17 +395,36 @@ public:
/** /**
@class wxSplitterEvent @class wxSplitterEvent
This class represents the events generated by a splitter control. Also there is This class represents the events generated by a splitter control.
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 Also there is only one event class, the data associated to the different events
documentation mentions the kind of event(s) for which the given accessor 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 function makes sense: calling it for other types of events will result
in assert failure (in debug mode) and will return meaningless results. 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} @library{wxcore}
@category{events} @category{events}
@see wxSplitterWindow, @ref overview_eventhandlingoverview @see wxSplitterWindow, @ref overview_eventhandling
*/ */
class wxSplitterEvent : public wxNotifyEvent class wxSplitterEvent : public wxNotifyEvent
{ {
@@ -394,44 +437,49 @@ public:
/** /**
Returns the new sash position. Returns the new sash position.
May only be called while processing May only be called while processing
wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and
wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events. @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events.
*/ */
int GetSashPosition() const; int GetSashPosition() const;
/** /**
Returns a pointer to the window being removed when a splitter window Returns a pointer to the window being removed when a splitter window
is unsplit. is unsplit.
May only be called while processing May only be called while processing
wxEVT_COMMAND_SPLITTER_UNSPLIT events. @c wxEVT_COMMAND_SPLITTER_UNSPLIT events.
*/ */
wxWindow* GetWindowBeingRemoved() const; wxWindow* GetWindowBeingRemoved() const;
/** /**
Returns the x coordinate of the double-click point. Returns the x coordinate of the double-click point.
May only be called while processing May only be called while processing
wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events. @c wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events.
*/ */
int GetX() const; int GetX() const;
/** /**
Returns the y coordinate of the double-click point. Returns the y coordinate of the double-click point.
May only be called while processing May only be called while processing
wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events. @c wxEVT_COMMAND_SPLITTER_DOUBLECLICKED events.
*/ */
int GetY() const; int GetY() const;
/** /**
In the case of wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events, In the case of @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events,
sets the new sash position. In the case of sets the new sash position.
wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING events, sets the new In the case of @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING events,
tracking bar position so visual feedback during dragging will sets the new tracking bar position so visual feedback during dragging will
represent that change that will actually take place. Set to -1 from represent that change that will actually take place. Set to -1 from
the event handler code to prevent repositioning. the event handler code to prevent repositioning.
May only be called while processing May only be called while processing
wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGING and
wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events. @c wxEVT_COMMAND_SPLITTER_SASH_POS_CHANGED events.
@param pos @param pos
New sash position. New sash position.

View File

@@ -39,8 +39,19 @@
capitalized. capitalized.
@endStyleTable @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} @library{wxcore}
@category{FIXME} @category{ctrl}
@see wxTextCtrl::Create, wxValidator @see wxTextCtrl::Create, wxValidator
*/ */
@@ -51,7 +62,7 @@ public:
Default constructor Default constructor
*/ */
wxSearchCtrl(); wxSearchCtrl();
/** /**
Constructor, creating and showing a text control. Constructor, creating and showing a text control.
@@ -96,16 +107,15 @@ public:
/** /**
Returns the search button visibility value. Returns the search button visibility value.
If there is a menu attached, the search button will be visible regardless of If there is a menu attached, the search button will be visible regardless of
the search the search button visibility value.
button visibility value.
This always returns @false in Mac OS X v10.3 This always returns @false in Mac OS X v10.3
*/ */
virtual bool IsSearchButtonVisible() const; virtual bool IsSearchButtonVisible() const;
/** /**
Sets the search control's menu object. If there is already a menu associated Sets the search control's menu object.
with If there is already a menu associated with the search control it is deleted.
the search control it is deleted.
@param menu @param menu
Menu to attach to the search control. Menu to attach to the search control.
@@ -120,8 +130,8 @@ public:
/** /**
Sets the search button visibility value on 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 If there is a menu attached, the search button will be visible regardless of
the search the search button visibility value.
button visibility value.
This has no effect in Mac OS X v10.3 This has no effect in Mac OS X v10.3
*/ */
virtual void ShowSearchButton(bool show); virtual void ShowSearchButton(bool show);

View File

@@ -9,8 +9,8 @@
/** /**
@class wxStringInputStream @class wxStringInputStream
This class implements an input stream which reads data from a string. It This class implements an input stream which reads data from a string.
supports seeking. It supports seeking.
@library{wxbase} @library{wxbase}
@category{streams} @category{streams}
@@ -19,9 +19,11 @@ class wxStringInputStream : public wxInputStream
{ {
public: public:
/** /**
Creates a new read-only stream using the specified string. Note that the string Creates a new read-only stream using the specified 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. 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); wxStringInputStream(const wxString& s);
}; };
@@ -32,8 +34,10 @@ public:
@class wxStringOutputStream @class wxStringOutputStream
This class implements an output stream which writes data either to a This class implements an output stream which writes data either to a
user-provided or internally allocated string. Note that currently this stream user-provided or internally allocated string.
does not support seeking but can tell its current position.
Note that currently this stream does not support seeking but can tell
its current position.
@library{wxbase} @library{wxbase}
@category{streams} @category{streams}
@@ -50,15 +54,14 @@ public:
If @a str is used, data written to the stream is appended to the current 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 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 empty, the positions returned by wxOutputStream::TellO will be offset by
offset by the initial string length, i.e. initial stream position will be the the initial string length, i.e. initial stream position will be the
initial length of the string and not 0. initial length of the string and not 0.
Notice that the life time of @a conv must be greater than the life time 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 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 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 be valid UTF-8, pass @c wxConvISO8859_1 to deal with arbitrary 8 bit data.
data.
*/ */
wxStringOutputStream(wxString str = NULL, wxMBConv& conv = wxConvUTF8); wxStringOutputStream(wxString str = NULL, wxMBConv& conv = wxConvUTF8);