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{data}
  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 number of fields in the status bar.
 129     */
 130     int GetFieldsCount() const;
 131
 132     /**
 133         Returns the wxStatusBarPane representing the @a n-th field.
 134     */
 135     const wxStatusBarPane& GetField(int n) const
 136         { return m_panes[n]; }
 137
 138     /**
 139         Returns the string associated with a status bar field.
 140
 141         @param i
 142             The number of the status field to retrieve, starting from zero.
 143
 144         @return The status field string if the field is valid, otherwise the
 145                 empty string.
 146
 147         @see SetStatusText()
 148     */
 149     virtual wxString GetStatusText(int i = 0) const;
 150
 151     /**
 152         Returns the stack of strings pushed (see PushStatusText()) on the
 153         @a n-th field.
 154
 155         See wxStatusBarPane::GetStack() for more info.
 156     */
 157     const wxArrayString& GetStatusStack(int n) const
 158         { return m_panes[n].GetStack(); }
 159
 160     /**
 161         Returns the width of the @a n-th field.
 162
 163         See wxStatusBarPane::GetWidth() for more info.
 164     */
 165     int GetStatusWidth(int n) const
 166         { return m_panes[n].GetWidth(); }
 167
 168     /**
 169         Returns the style of the @a n-th field.
 170
 171         See wxStatusBarPane::GetStyle() for more info.
 172     */
 173     int GetStatusStyle(int n) const
 174         { return m_panes[n].GetStyle(); }
 175
 176     /**
 177         Sets the field text to the top of the stack, and pops the stack of saved
 178         strings.
 179
 180         @see PushStatusText()
 181     */
 182     void PopStatusText(int field = 0);
 183
 184     /**
 185         Saves the current field text in a per field stack, and sets the field text
 186         to the string passed as argument.
 187
 188         @see PopStatusText()
 189     */
 190     void PushStatusText(const wxString& string, int field = 0);
 191
 192     /**
 193         Sets the number of fields, and optionally the field widths.
 194
 195         @param number
 196             The number of fields. If this is greater than the previous number,
 197             then new fields with empty strings will be added to the status bar.
 198         @param widths
 199             An array of n integers interpreted in the same way as
 200             in SetStatusWidths().
 201     */
 202     virtual void SetFieldsCount(int number = 1, const int* widths = NULL);
 203
 204     /**
 205         Sets the minimal possible height for the status bar.
 206
 207         The real height may be bigger than the height specified here depending
 208         on the size of the font used by the status bar.
 209     */
 210     virtual void SetMinHeight(int height);
 211
 212     /**
 213         Sets the styles of the fields in the status line which can make fields appear
 214         flat or raised instead of the standard sunken 3D border.
 215
 216         @param n
 217             The number of fields in the status bar. Must be equal to the
 218             number passed to SetFieldsCount() the last time it was called.
 219         @param styles
 220             Contains an array of n integers with the styles for each field. There
 221             are three possible styles:
 222             - wxSB_NORMAL (default): The field appears sunken with a standard 3D border.
 223             - wxSB_FLAT: No border is painted around the field so that it appears flat.
 224             - wxSB_RAISED: A raised 3D border is painted around the field.
 225     */
 226     virtual void SetStatusStyles(int n, const int* styles);
 227
 228     /**
 229         Sets the text for one field.
 230
 231         @param text
 232             The text to be set. Use an empty string ("") to clear the field.
 233         @param i
 234             The field to set, starting from zero.
 235
 236         @see GetStatusText(), wxFrame::SetStatusText
 237     */
 238     virtual void SetStatusText(const wxString& text, int i = 0);
 239
 240     /**
 241         Sets the widths of the fields in the status line. There are two types of
 242         fields: @b fixed widths and @b variable width fields. For the fixed width fields
 243         you should specify their (constant) width in pixels. For the variable width
 244         fields, specify a negative number which indicates how the field should expand:
 245         the space left for all variable width fields is divided between them according
 246         to the absolute value of this number. A variable width field with width of -2
 247         gets twice as much of it as a field with width -1 and so on.
 248
 249         For example, to create one fixed width field of width 100 in the right part of
 250         the status bar and two more fields which get 66% and 33% of the remaining
 251         space correspondingly, you should use an array containing -2, -1 and 100.
 252
 253         @param n
 254             The number of fields in the status bar. Must be equal to the
 255             number passed to SetFieldsCount() the last time it was called.
 256         @param widths_field
 257             Contains an array of n integers, each of which is either an
 258             absolute status field width in pixels if positive or indicates a
 259             variable width field if negative.
 260             The special value @NULL means that all fields should get the same width.
 261
 262         @remarks The widths of the variable fields are calculated from the total
 263                  width of all fields, minus the sum of widths of the
 264                  non-variable fields, divided by the number of variable fields.
 265
 266         @see SetFieldsCount(), wxFrame::SetStatusWidths()
 267     */
 268     virtual void SetStatusWidths(int n, const int* widths_field);
 269 };
 270