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 };
  48
  49 /**
  50     @class wxStatusBar
  51
  52     A status bar is a narrow window that can be placed along the bottom of a frame
  53     to give small amounts of status information. It can contain one or more fields,
  54     one or more of which can be variable length according to the size of the window.
  55
  56     @beginStyleTable
  57     @style{wxST_SIZEGRIP}
  58         Displays a gripper at the right-hand side of the status bar.
  59     @endStyleTable
  60
  61     @remarks
  62     It is possible to create controls and other windows on the status bar.
  63     Position these windows from an OnSize() event handler.
  64
  65     @library{wxcore}
  66     @category{miscwnd}
  67
  68     @see wxStatusBarPane, wxFrame, @ref page_samples_statbar
  69 */
  70 class wxStatusBar : public wxWindow
  71 {
  72 public:
  73     /**
  74         Default ctor.
  75     */
  76     wxStatusBar();
  77
  78     /**
  79         Constructor, creating the window.
  80
  81         @param parent
  82             The window parent, usually a frame.
  83         @param id
  84             The window identifier.
  85             It may take a value of -1 to indicate a default value.
  86         @param style
  87             The window style. See wxStatusBar.
  88         @param name
  89             The name of the window. This parameter is used to associate a name with the
  90             item, allowing the application user to set Motif resource values for
  91             individual windows.
  92
  93         @see Create()
  94     */
  95     wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY,
  96                 long style = wxST_SIZEGRIP,
  97                 const wxString& name = wxStatusBarNameStr);
  98
  99     /**
 100         Destructor.
 101     */
 102     virtual ~wxStatusBar();
 103
 104     /**
 105         Creates the window, for two-step construction.
 106         See wxStatusBar() for details.
 107     */
 108     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 109                 long style = wxST_SIZEGRIP,
 110                 const wxString& name = wxStatusBarNameStr);
 111
 112     /**
 113         Returns the size and position of a field's internal bounding rectangle.
 114
 115         @param i
 116             The field in question.
 117         @param rect
 118             The rectangle values are placed in this variable.
 119
 120         @return @true if the field index is valid, @false otherwise.
 121
 122         @see wxRect
 123     */
 124     virtual bool GetFieldRect(int i, wxRect& rect) const;
 125
 126     /**
 127         Returns the number of fields in the status bar.
 128     */
 129     int GetFieldsCount() const;
 130
 131     /**
 132         Returns the wxStatusBarPane representing the @a n-th field.
 133     */
 134     const wxStatusBarPane& GetField(int n) const;
 135
 136     /**
 137         Returns the string associated with a status bar field.
 138
 139         @param i
 140             The number of the status field to retrieve, starting from zero.
 141
 142         @return The status field string if the field is valid, otherwise the
 143                 empty string.
 144
 145         @see SetStatusText()
 146     */
 147     virtual wxString GetStatusText(int i = 0) const;
 148
 149     /**
 150         Returns the stack of strings pushed (see PushStatusText()) on the
 151         @a n-th field.
 152
 153         See wxStatusBarPane::GetStack() for more info.
 154     */
 155     const wxArrayString& GetStatusStack(int n) const;
 156
 157     /**
 158         Returns the width of the @a n-th field.
 159
 160         See wxStatusBarPane::GetWidth() for more info.
 161     */
 162     int GetStatusWidth(int n) const;
 163
 164     /**
 165         Returns the style of the @a n-th field.
 166
 167         See wxStatusBarPane::GetStyle() for more info.
 168     */
 169     int GetStatusStyle(int n) const;
 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