// Purpose: interface of wxStatusBar
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+// wxStatusBar styles
+#define wxSTB_SIZEGRIP 0x0010
+#define wxSTB_SHOW_TIPS 0x0020
+
+#define wxSTB_ELLIPSIZE_START 0x0040
+#define wxSTB_ELLIPSIZE_MIDDLE 0x0080
+#define wxSTB_ELLIPSIZE_END 0x0100
+
+#define wxSTB_DEFAULT_STYLE (wxSTB_SIZEGRIP|wxSTB_ELLIPSIZE_END|wxSTB_SHOW_TIPS|wxFULL_REPAINT_ON_RESIZE)
+
+// style flags for wxStatusBar fields
+#define wxSB_NORMAL 0x0000
+#define wxSB_FLAT 0x0001
+#define wxSB_RAISED 0x0002
+#define wxSB_SUNKEN 0x0003
+
+
/**
@class wxStatusBarPane
-
+
A status bar pane data container used by wxStatusBar.
@library{wxcore}
- @category{miscwnd}
+ @category{data}
@see wxStatusBar
*/
Constructs the pane with the given @a style and @a width.
*/
wxStatusBarPane(int style = wxSB_NORMAL, size_t width = 0);
-
+
/**
Returns the pane width; it maybe negative, indicating a variable-width field.
*/
int GetWidth() const;
-
+
/**
Returns the pane style.
*/
int GetStyle() const;
-
+
/**
- Returns the stack of strings pushed on this pane.
-
- Note that this stack does include also the string currently displayed in this pane
- as the version stored in the native status bar control is possibly ellipsized.
-
- Also note that GetStack().Last() is the top of the stack (i.e. the string shown
- in the status bar).
- */
- const wxArrayString& GetStack() const
- { return m_arrStack; }
+ Returns the text currently shown in this pane.
+ */
+ wxString GetText() const;
};
/**
to give small amounts of status information. It can contain one or more fields,
one or more of which can be variable length according to the size of the window.
+ wxStatusBar also maintains an independent stack of status texts for each field
+ (see PushStatusText() and PopStatusText()).
+
+ Note that in wxStatusBar context, the terms @e pane and @e field are synonyms.
+
@beginStyleTable
- @style{wxST_SIZEGRIP}
- Displays a gripper at the right-hand side of the status bar.
+ @style{wxSTB_SIZEGRIP}
+ Displays a gripper at the right-hand side of the status bar which can be used
+ to resize the parent window.
+ @style{wxSTB_SHOW_TIPS}
+ Displays tooltips for those panes whose status text has been ellipsized/truncated
+ because the status text doesn't fit the pane width.
+ Note that this style has effect only on wxGTK (with GTK+ >= 2.12) currently.
+ @style{wxSTB_ELLIPSIZE_START}
+ Replace the beginning of the status texts with an ellipsis when the status text
+ widths exceed the status bar pane's widths (uses wxControl::Ellipsize).
+ @style{wxSTB_ELLIPSIZE_MIDDLE}
+ Replace the middle of the status texts with an ellipsis when the status text
+ widths exceed the status bar pane's widths (uses wxControl::Ellipsize).
+ @style{wxSTB_ELLIPSIZE_END}
+ Replace the end of the status texts with an ellipsis when the status text
+ widths exceed the status bar pane's widths (uses wxControl::Ellipsize).
+ @style{wxSTB_DEFAULT_STYLE}
+ The default style: includes
+ @c wxSTB_SIZEGRIP|wxSTB_SHOW_TIPS|wxSTB_ELLIPSIZE_END|wxFULL_REPAINT_ON_RESIZE.
@endStyleTable
@remarks
It is possible to create controls and other windows on the status bar.
Position these windows from an OnSize() event handler.
+ @remarks
+ Notice that only the first 127 characters of a string will be shown in
+ status bar fields under pre-XP MSW systems (or even under later systems if
+ a proper manifest indicating that the program uses version 6 of common
+ controls library is not used). This is a limitation of the native control
+ on these platforms.
+
@library{wxcore}
@category{miscwnd}
@see wxStatusBarPane, wxFrame, @ref page_samples_statbar
*/
-class wxStatusBar : public wxWindow
+class wxStatusBar : public wxControl
{
public:
/**
@see Create()
*/
wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY,
- long style = wxST_SIZEGRIP,
+ long style = wxSTB_DEFAULT_STYLE,
const wxString& name = wxStatusBarNameStr);
/**
See wxStatusBar() for details.
*/
bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
- long style = wxST_SIZEGRIP,
+ long style = wxSTB_DEFAULT_STYLE,
const wxString& name = wxStatusBarNameStr);
/**
@return @true if the field index is valid, @false otherwise.
+ @beginWxPerlOnly
+ In wxPerl this function returns a @c Wx::Rect if the field
+ index is valid, @c undef otherwise.
+ @endWxPerlOnly
+
@see wxRect
*/
virtual bool GetFieldRect(int i, wxRect& rect) const;
-
+
/**
- Returns the number of fields in the status bar.
+ Returns the number of fields in the status bar.
*/
int GetFieldsCount() const;
-
+
/**
Returns the wxStatusBarPane representing the @a n-th field.
*/
- const wxStatusBarPane& GetField(int n) const
- { return m_panes[n]; }
-
+ const wxStatusBarPane& GetField(int n) const;
+
+ /**
+ Returns the horizontal and vertical borders used when rendering the field
+ text inside the field area.
+
+ Note that the rect returned by GetFieldRect() already accounts for the
+ presence of horizontal and vertical border returned by this function.
+ */
+ wxSize GetBorders() const;
+
/**
Returns the string associated with a status bar field.
*/
virtual wxString GetStatusText(int i = 0) const;
- /**
- Returns the stack of strings pushed (see PushStatusText()) on the
- @a n-th field.
-
- See wxStatusBarPane::GetStack() for more info.
- */
- const wxArrayString& GetStatusStack(int n) const
- { return m_panes[n].GetStack(); }
-
/**
Returns the width of the @a n-th field.
-
+
See wxStatusBarPane::GetWidth() for more info.
*/
- int GetStatusWidth(int n) const
- { return m_panes[n].GetWidth(); }
+ int GetStatusWidth(int n) const;
/**
Returns the style of the @a n-th field.
-
+
See wxStatusBarPane::GetStyle() for more info.
*/
- int GetStatusStyle(int n) const
- { return m_panes[n].GetStyle(); }
-
+ int GetStatusStyle(int n) const;
+
/**
- Sets the field text to the top of the stack, and pops the stack of saved
- strings.
+ Restores the text to the value it had before the last call to
+ PushStatusText().
+
+ Notice that if SetStatusText() had been called in the meanwhile,
+ PopStatusText() will not change the text, i.e. it does not override
+ explicit changes to status text but only restores the saved text if it
+ hadn't been changed since.
@see PushStatusText()
*/
void PopStatusText(int field = 0);
/**
- Saves the current field text in a per field stack, and sets the field text
- to the string passed as argument.
+ Saves the current field text in a per-field stack, and sets the field
+ text to the string passed as argument.
@see PopStatusText()
*/
@param widths
An array of n integers interpreted in the same way as
in SetStatusWidths().
+
+ @beginWxPerlOnly
+ In wxPerl this function accepts only the @a number parameter.
+ Use SetStatusWidths to set the field widths.
+ @endWxPerlOnly
*/
virtual void SetFieldsCount(int number = 1, const int* widths = NULL);
The number of fields in the status bar. Must be equal to the
number passed to SetFieldsCount() the last time it was called.
@param styles
- Contains an array of n integers with the styles for each field. There
- are three possible styles:
- - wxSB_NORMAL (default): The field appears sunken with a standard 3D border.
- - wxSB_FLAT: No border is painted around the field so that it appears flat.
- - wxSB_RAISED: A raised 3D border is painted around the field.
+ Contains an array of @a n integers with the styles for each field.
+ There are four possible styles:
+ - @c wxSB_NORMAL (default): The field appears with the default native border.
+ - @c wxSB_FLAT: No border is painted around the field so that it appears flat.
+ - @c wxSB_RAISED: A raised 3D border is painted around the field.
+ - @c wxSB_SUNKEN: A sunken 3D border is painted around the field
+ (this style is new since wxWidgets 2.9.5).
*/
virtual void SetStatusStyles(int n, const int* styles);
/**
- Sets the text for one field.
+ Sets the status text for the @a i-th field.
+
+ The given text will replace the current text.
+
+ Note that if PushStatusText() had been called before the new text will
+ also replace the last saved value to make sure that the next call to
+ PopStatusText() doesn't restore the old value, which was overwritten by
+ the call to this function.
@param text
The text to be set. Use an empty string ("") to clear the field.
width of all fields, minus the sum of widths of the
non-variable fields, divided by the number of variable fields.
+ @beginWxPerlOnly
+ In wxPerl this method takes as parameters the field widths.
+ @endWxPerlOnly
+
@see SetFieldsCount(), wxFrame::SetStatusWidths()
*/
virtual void SetStatusWidths(int n, const int* widths_field);
projects / wxWidgets.git / blobdiff