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     wxStatusBar also maintains an independent stack of status texts for each field
  57     (see PushStatusText() and PopStatusText()).
  58
  59     Note that in wxStatusBar context, the terms @e pane and @e field are synonyms.
  60
  61     @beginStyleTable
  62     @style{wxSTB_SIZEGRIP}
  63         Displays a gripper at the right-hand side of the status bar which can be used
  64         to resize the parent window.
  65     @style{wxSTB_SHOW_TIPS}
  66         Displays tooltips for those panes whose status text has been ellipsized/truncated
  67         because the status text doesn't fit the pane width.
  68         Note that this style has effect only on wxGTK (with GTK+ >= 2.12) currently.
  69     @style{wxSTB_ELLIPSIZE_START}
  70         Replace the beginning of the status texts with an ellipsis when the status text
  71         widths exceed the status bar pane's widths (uses wxControl::Ellipsize).
  72     @style{wxSTB_ELLIPSIZE_MIDDLE}
  73         Replace the middle of the status texts with an ellipsis when the status text
  74         widths exceed the status bar pane's widths (uses wxControl::Ellipsize).
  75     @style{wxSTB_ELLIPSIZE_END}
  76         Replace the end of the status texts with an ellipsis when the status text
  77         widths exceed the status bar pane's widths (uses wxControl::Ellipsize).
  78     @style{wxSTB_DEFAULT_STYLE}
  79         The default style: includes
  80         @c wxSTB_SIZEGRIP|wxSTB_SHOW_TIPS|wxSTB_ELLIPSIZE_END|wxFULL_REPAINT_ON_RESIZE.
  81     @endStyleTable
  82
  83     @remarks
  84     It is possible to create controls and other windows on the status bar.
  85     Position these windows from an OnSize() event handler.
  86
  87     @library{wxcore}
  88     @category{miscwnd}
  89
  90     @see wxStatusBarPane, wxFrame, @ref page_samples_statbar
  91 */
  92 class wxStatusBar : public wxWindow
  93 {
  94 public:
  95     /**
  96         Default ctor.
  97     */
  98     wxStatusBar();
  99
 100     /**
 101         Constructor, creating the window.
 102
 103         @param parent
 104             The window parent, usually a frame.
 105         @param id
 106             The window identifier.
 107             It may take a value of -1 to indicate a default value.
 108         @param style
 109             The window style. See wxStatusBar.
 110         @param name
 111             The name of the window. This parameter is used to associate a name with the
 112             item, allowing the application user to set Motif resource values for
 113             individual windows.
 114
 115         @see Create()
 116     */
 117     wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY,
 118                 long style = wxSTB_DEFAULT_STYLE,
 119                 const wxString& name = wxStatusBarNameStr);
 120
 121     /**
 122         Destructor.
 123     */
 124     virtual ~wxStatusBar();
 125
 126     /**
 127         Creates the window, for two-step construction.
 128         See wxStatusBar() for details.
 129     */
 130     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 131                 long style = wxSTB_DEFAULT_STYLE,
 132                 const wxString& name = wxStatusBarNameStr);
 133
 134     /**
 135         Returns the size and position of a field's internal bounding rectangle.
 136
 137         @param i
 138             The field in question.
 139         @param rect
 140             The rectangle values are placed in this variable.
 141
 142         @return @true if the field index is valid, @false otherwise.
 143
 144         @see wxRect
 145     */
 146     virtual bool GetFieldRect(int i, wxRect& rect) const;
 147
 148     /**
 149         Returns the number of fields in the status bar.
 150     */
 151     int GetFieldsCount() const;
 152
 153     /**
 154         Returns the wxStatusBarPane representing the @a n-th field.
 155     */
 156     const wxStatusBarPane& GetField(int n) const;
 157
 158     /**
 159         Returns the horizontal and vertical borders used when rendering the field
 160         text inside the field area.
 161
 162         Note that the rect returned by GetFieldRect() already accounts for the
 163         presence of horizontal and vertical border returned by this function.
 164     */
 165     wxSize GetBorders() const;
 166
 167     /**
 168         Returns the string associated with a status bar field.
 169
 170         @param i
 171             The number of the status field to retrieve, starting from zero.
 172
 173         @return The status field string if the field is valid, otherwise the
 174                 empty string.
 175
 176         @see SetStatusText()
 177     */
 178     virtual wxString GetStatusText(int i = 0) const;
 179
 180     /**
 181         Returns the stack of strings pushed (see PushStatusText()) on the
 182         @a n-th field.
 183
 184         See wxStatusBarPane::GetStack() for more info.
 185     */
 186     const wxArrayString& GetStatusStack(int n) const;
 187
 188     /**
 189         Returns the width of the @a n-th field.
 190
 191         See wxStatusBarPane::GetWidth() for more info.
 192     */
 193     int GetStatusWidth(int n) const;
 194
 195     /**
 196         Returns the style of the @a n-th field.
 197
 198         See wxStatusBarPane::GetStyle() for more info.
 199     */
 200     int GetStatusStyle(int n) const;
 201
 202     /**
 203         Sets the field text to the top of the stack, and pops the stack of saved
 204         strings.
 205
 206         @see PushStatusText()
 207     */
 208     void PopStatusText(int field = 0);
 209
 210     /**
 211         Saves the current field text in a per-field stack, and sets the field text
 212         to the string passed as argument.
 213
 214         @see PopStatusText()
 215     */
 216     void PushStatusText(const wxString& string, int field = 0);
 217
 218     /**
 219         Sets the number of fields, and optionally the field widths.
 220
 221         @param number
 222             The number of fields. If this is greater than the previous number,
 223             then new fields with empty strings will be added to the status bar.
 224         @param widths
 225             An array of n integers interpreted in the same way as
 226             in SetStatusWidths().
 227     */
 228     virtual void SetFieldsCount(int number = 1, const int* widths = NULL);
 229
 230     /**
 231         Sets the minimal possible height for the status bar.
 232
 233         The real height may be bigger than the height specified here depending
 234         on the size of the font used by the status bar.
 235     */
 236     virtual void SetMinHeight(int height);
 237
 238     /**
 239         Sets the styles of the fields in the status line which can make fields appear
 240         flat or raised instead of the standard sunken 3D border.
 241
 242         @param n
 243             The number of fields in the status bar. Must be equal to the
 244             number passed to SetFieldsCount() the last time it was called.
 245         @param styles
 246             Contains an array of @a n integers with the styles for each field.
 247             There are three possible styles:
 248             - @c wxSB_NORMAL (default): The field appears sunken with a standard 3D border.
 249             - @c wxSB_FLAT: No border is painted around the field so that it appears flat.
 250             - @c wxSB_RAISED: A raised 3D border is painted around the field.
 251     */
 252     virtual void SetStatusStyles(int n, const int* styles);
 253
 254     /**
 255         Sets the status text for the @a i-th field.
 256
 257         The given text will replace the current text. Note that unlike PushStatusText()
 258         this function won't save the current text (and calling PopStatusText() won't
 259         restore it!).
 260
 261         @param text
 262             The text to be set. Use an empty string ("") to clear the field.
 263         @param i
 264             The field to set, starting from zero.
 265
 266         @see GetStatusText(), wxFrame::SetStatusText
 267     */
 268     virtual void SetStatusText(const wxString& text, int i = 0);
 269
 270     /**
 271         Sets the widths of the fields in the status line. There are two types of
 272         fields: @b fixed widths and @b variable width fields. For the fixed width fields
 273         you should specify their (constant) width in pixels. For the variable width
 274         fields, specify a negative number which indicates how the field should expand:
 275         the space left for all variable width fields is divided between them according
 276         to the absolute value of this number. A variable width field with width of -2
 277         gets twice as much of it as a field with width -1 and so on.
 278
 279         For example, to create one fixed width field of width 100 in the right part of
 280         the status bar and two more fields which get 66% and 33% of the remaining
 281         space correspondingly, you should use an array containing -2, -1 and 100.
 282
 283         @param n
 284             The number of fields in the status bar. Must be equal to the
 285             number passed to SetFieldsCount() the last time it was called.
 286         @param widths_field
 287             Contains an array of n integers, each of which is either an
 288             absolute status field width in pixels if positive or indicates a
 289             variable width field if negative.
 290             The special value @NULL means that all fields should get the same width.
 291
 292         @remarks The widths of the variable fields are calculated from the total
 293                  width of all fields, minus the sum of widths of the
 294                  non-variable fields, divided by the number of variable fields.
 295
 296         @see SetFieldsCount(), wxFrame::SetStatusWidths()
 297     */
 298     virtual void SetStatusWidths(int n, const int* widths_field);
 299 };
 300