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