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