interface/wx/statusbr.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        statusbr.h
   3 // Purpose:     interface of wxStatusBar
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxStatusBarPane
  11
  12     A status bar pane data container used by wxStatusBar.
  13
  14     @library{wxcore}
  15     @category{miscwnd}
  16
  17     @see wxStatusBar
  18 */
  19 class wxStatusBarPane
  20 {
  21 public:
  22     /**
  23         Constructs the pane with the given @a style and @a width.
  24     */
  25     wxStatusBarPane(int style = wxSB_NORMAL, size_t width = 0);
  26
  27     /**
  28         Returns the pane width; it maybe negative, indicating a variable-width field.
  29     */
  30     int GetWidth() const;
  31
  32     /**
  33         Returns the pane style.
  34     */
  35     int GetStyle() const;
  36
  37     /**
  38         Returns the stack of strings pushed on this pane.
  39
  40         Note that this stack does include also the string currently displayed in this pane
  41         as the version stored in the native status bar control is possibly ellipsized.
  42
  43         Also note that GetStack().Last() is the top of the stack (i.e. the string shown
  44         in the status bar).
  45     */
  46     const wxArrayString& GetStack() const
  47         { return m_arrStack; }
  48 };
  49
  50 /**
  51     @class wxStatusBar
  52
  53     A status bar is a narrow window that can be placed along the bottom of a frame
  54     to give small amounts of status information. It can contain one or more fields,
  55     one or more of which can be variable length according to the size of the window.
  56
  57     @beginStyleTable
  58     @style{wxST_SIZEGRIP}
  59         Displays a gripper at the right-hand side of the status bar.
  60     @endStyleTable
  61
  62     @remarks
  63     It is possible to create controls and other windows on the status bar.
  64     Position these windows from an OnSize() event handler.
  65
  66     @library{wxcore}
  67     @category{miscwnd}
  68
  69     @see wxStatusBarPane, wxFrame, @ref page_samples_statbar
  70 */
  71 class wxStatusBar : public wxWindow
  72 {
  73 public:
  74     /**
  75         Default ctor.
  76     */
  77     wxStatusBar();
  78
  79     /**
  80         Constructor, creating the window.
  81
  82         @param parent
  83             The window parent, usually a frame.
  84         @param id
  85             The window identifier.
  86             It may take a value of -1 to indicate a default value.
  87         @param style
  88             The window style. See wxStatusBar.
  89         @param name
  90             The name of the window. This parameter is used to associate a name with the
  91             item, allowing the application user to set Motif resource values for
  92             individual windows.
  93
  94         @see Create()
  95     */
  96     wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY,
  97                 long style = wxST_SIZEGRIP,
  98                 const wxString& name = wxStatusBarNameStr);
  99
 100     /**
 101         Destructor.
 102     */
 103     virtual ~wxStatusBar();
 104
 105     /**
 106         Creates the window, for two-step construction.
 107         See wxStatusBar() for details.
 108     */
 109     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 110                 long style = wxST_SIZEGRIP,
 111                 const wxString& name = wxStatusBarNameStr);
 112
 113     /**
 114         Returns the size and position of a field's internal bounding rectangle.
 115
 116         @param i
 117             The field in question.
 118         @param rect
 119             The rectangle values are placed in this variable.
 120
 121         @return @true if the field index is valid, @false otherwise.
 122
 123         @see wxRect
 124     */
 125     virtual bool GetFieldRect(int i, wxRect& rect) const;
 126
 127     /**
 128         Returns the wxStatusBarPane representing the @a n-th field.
 129     */
 130     const wxStatusBarPane& GetField(int n) const
 131         { return m_panes[n]; }
 132
 133     /**
 134         Returns the string associated with a status bar field.
 135
 136         @param i
 137             The number of the status field to retrieve, starting from zero.
 138
 139         @return The status field string if the field is valid, otherwise the
 140                 empty string.
 141
 142         @see SetStatusText()
 143     */
 144     virtual wxString GetStatusText(int i = 0) const;
 145
 146     /**
 147         Returns the stack of strings pushed (see PushStatusText()) on the
 148         @a n-th field.
 149
 150         See wxStatusBarPane::GetStack() for more info.
 151     */
 152     const wxArrayString& GetStatusStack(int n) const
 153         { return m_panes[n].GetStack(); }
 154
 155     /**
 156         Returns the width of the @a n-th field.
 157
 158         See wxStatusBarPane::GetWidth() for more info.
 159     */
 160     int GetStatusWidth(int n) const
 161         { return m_panes[n].GetWidth(); }
 162
 163     /**
 164         Returns the style of the @a n-th field.
 165
 166         See wxStatusBarPane::GetStyle() for more info.
 167     */
 168     int GetStatusStyle(int n) const
 169         { return m_panes[n].GetStyle(); }
 170
 171     /**
 172         Sets the field text to the top of the stack, and pops the stack of saved
 173         strings.
 174
 175         @see PushStatusText()
 176     */
 177     void PopStatusText(int field = 0);
 178
 179     /**
 180         Saves the current field text in a per field stack, and sets the field text
 181         to the string passed as argument.
 182
 183         @see PopStatusText()
 184     */
 185     void PushStatusText(const wxString& string, int field = 0);
 186
 187     /**
 188         Sets the number of fields, and optionally the field widths.
 189
 190         @param number
 191             The number of fields. If this is greater than the previous number,
 192             then new fields with empty strings will be added to the status bar.
 193         @param widths
 194             An array of n integers interpreted in the same way as
 195             in SetStatusWidths().
 196     */
 197     virtual void SetFieldsCount(int number = 1, const int* widths = NULL);
 198
 199     /**
 200         Sets the minimal possible height for the status bar.
 201
 202         The real height may be bigger than the height specified here depending
 203         on the size of the font used by the status bar.
 204     */
 205     virtual void SetMinHeight(int height);
 206
 207     /**
 208         Sets the styles of the fields in the status line which can make fields appear
 209         flat or raised instead of the standard sunken 3D border.
 210
 211         @param n
 212             The number of fields in the status bar. Must be equal to the
 213             number passed to SetFieldsCount() the last time it was called.
 214         @param styles
 215             Contains an array of n integers with the styles for each field. There
 216             are three possible styles:
 217             - wxSB_NORMAL (default): The field appears sunken with a standard 3D border.
 218             - wxSB_FLAT: No border is painted around the field so that it appears flat.
 219             - wxSB_RAISED: A raised 3D border is painted around the field.
 220     */
 221     virtual void SetStatusStyles(int n, const int* styles);
 222
 223     /**
 224         Sets the text for one field.
 225
 226         @param text
 227             The text to be set. Use an empty string ("") to clear the field.
 228         @param i
 229             The field to set, starting from zero.
 230
 231         @see GetStatusText(), wxFrame::SetStatusText
 232     */
 233     virtual void SetStatusText(const wxString& text, int i = 0);
 234
 235     /**
 236         Sets the widths of the fields in the status line. There are two types of
 237         fields: @b fixed widths and @b variable width fields. For the fixed width fields
 238         you should specify their (constant) width in pixels. For the variable width
 239         fields, specify a negative number which indicates how the field should expand:
 240         the space left for all variable width fields is divided between them according
 241         to the absolute value of this number. A variable width field with width of -2
 242         gets twice as much of it as a field with width -1 and so on.
 243
 244         For example, to create one fixed width field of width 100 in the right part of
 245         the status bar and two more fields which get 66% and 33% of the remaining
 246         space correspondingly, you should use an array containing -2, -1 and 100.
 247
 248         @param n
 249             The number of fields in the status bar. Must be equal to the
 250             number passed to SetFieldsCount() the last time it was called.
 251         @param widths_field
 252             Contains an array of n integers, each of which is either an
 253             absolute status field width in pixels if positive or indicates a
 254             variable width field if negative.
 255             The special value @NULL means that all fields should get the same width.
 256
 257         @remarks The widths of the variable fields are calculated from the total
 258                  width of all fields, minus the sum of widths of the
 259                  non-variable fields, divided by the number of variable fields.
 260
 261         @see SetFieldsCount(), wxFrame::SetStatusWidths()
 262     */
 263     virtual void SetStatusWidths(int n, const int* widths_field);
 264 };
 265