X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/43c48e1e53d74cef62d15f08f015d9efeb45a0c1..633e19307ce18ce24837db616feb9dda848056dd:/interface/wx/statusbr.h diff --git a/interface/wx/statusbr.h b/interface/wx/statusbr.h index 957f2e2339..8070fe0c10 100644 --- a/interface/wx/statusbr.h +++ b/interface/wx/statusbr.h @@ -3,9 +3,60 @@ // 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{data} + + @see wxStatusBar +*/ +class wxStatusBarPane +{ +public: + /** + 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 text currently shown in this pane. + */ + wxString GetText() const; +}; + /** @class wxStatusBar @@ -13,23 +64,50 @@ 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} - On Windows 95, displays a gripper at 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 - @todo reference to win95 may be old and wrong - @remarks It is possible to create controls and other windows on the status bar. - Position these windows from an OnSize event handler. + 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 wxFrame, @ref page_samples_statbar + @see wxStatusBarPane, wxFrame, @ref page_samples_statbar */ -class wxStatusBar : public wxWindow +class wxStatusBar : public wxControl { public: /** @@ -55,8 +133,8 @@ public: @see Create() */ wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY, - long style = wxST_SIZEGRIP, - const wxString& name = "statusBar"); + long style = wxSTB_DEFAULT_STYLE, + const wxString& name = wxStatusBarNameStr); /** Destructor. @@ -68,7 +146,7 @@ public: 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); /** @@ -81,6 +159,11 @@ public: @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; @@ -90,6 +173,20 @@ public: */ int GetFieldsCount() const; + /** + Returns the wxStatusBarPane representing the @a n-th field. + */ + 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. @@ -104,16 +201,37 @@ public: virtual wxString GetStatusText(int i = 0) const; /** - Sets the field text to the top of the stack, and pops the stack of saved - strings. + Returns the width of the @a n-th field. + + See wxStatusBarPane::GetWidth() for more info. + */ + 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; + + /** + 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() */ void PushStatusText(const wxString& string, int field = 0); @@ -121,10 +239,16 @@ public: Sets the number of fields, and optionally the field widths. @param number - The number of fields. + The number of fields. If this is greater than the previous number, + then new fields with empty strings will be added to the status bar. @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); @@ -144,16 +268,25 @@ public: 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. @@ -166,7 +299,7 @@ public: /** Sets the widths of the fields in the status line. There are two types of - fields: fixed widths one and variable width fields. For the fixed width fields + fields: @b fixed widths and @b variable width fields. For the fixed width fields you should specify their (constant) width in pixels. For the variable width fields, specify a negative number which indicates how the field should expand: the space left for all variable width fields is divided between them according @@ -180,15 +313,20 @@ public: @param n The number of fields in the status bar. Must be equal to the number passed to SetFieldsCount() the last time it was called. - @param widths + @param widths_field Contains an array of n integers, each of which is either an absolute status field width in pixels if positive or indicates a variable width field if negative. + The special value @NULL means that all fields should get the same width. @remarks The widths of the variable fields are calculated from the total 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);