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 licence
   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     @remarks
  82     Notice that only the first 127 characters of a string will be shown in
  83     status bar fields under pre-XP MSW systems (or even under later systems if
  84     a proper manifest indicating that the program uses version 6 of common
  85     controls library is not used). This is a limitation of the native control
  86     on these platforms.
  87
  88     @library{wxcore}
  89     @category{miscwnd}
  90
  91     @see wxStatusBarPane, wxFrame, @ref page_samples_statbar
  92 */
  93 class wxStatusBar : public wxControl
  94 {
  95 public:
  96     /**
  97         Default ctor.
  98     */
  99     wxStatusBar();
 100
 101     /**
 102         Constructor, creating the window.
 103
 104         @param parent
 105             The window parent, usually a frame.
 106         @param id
 107             The window identifier.
 108             It may take a value of -1 to indicate a default value.
 109         @param style
 110             The window style. See wxStatusBar.
 111         @param name
 112             The name of the window. This parameter is used to associate a name with the
 113             item, allowing the application user to set Motif resource values for
 114             individual windows.
 115
 116         @see Create()
 117     */
 118     wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY,
 119                 long style = wxSTB_DEFAULT_STYLE,
 120                 const wxString& name = wxStatusBarNameStr);
 121
 122     /**
 123         Destructor.
 124     */
 125     virtual ~wxStatusBar();
 126
 127     /**
 128         Creates the window, for two-step construction.
 129         See wxStatusBar() for details.
 130     */
 131     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 132                 long style = wxSTB_DEFAULT_STYLE,
 133                 const wxString& name = wxStatusBarNameStr);
 134
 135     /**
 136         Returns the size and position of a field's internal bounding rectangle.
 137
 138         @param i
 139             The field in question.
 140         @param rect
 141             The rectangle values are placed in this variable.
 142
 143         @return @true if the field index is valid, @false otherwise.
 144
 145         @beginWxPerlOnly
 146         In wxPerl this function returns a @c Wx::Rect if the field
 147         index is valid, @c undef otherwise.
 148         @endWxPerlOnly
 149
 150         @see wxRect
 151     */
 152     virtual bool GetFieldRect(int i, wxRect& rect) const;
 153
 154     /**
 155         Returns the number of fields in the status bar.
 156     */
 157     int GetFieldsCount() const;
 158
 159     /**
 160         Returns the wxStatusBarPane representing the @a n-th field.
 161     */
 162     const wxStatusBarPane& GetField(int n) const;
 163
 164     /**
 165         Returns the horizontal and vertical borders used when rendering the field
 166         text inside the field area.
 167
 168         Note that the rect returned by GetFieldRect() already accounts for the
 169         presence of horizontal and vertical border returned by this function.
 170     */
 171     wxSize GetBorders() const;
 172
 173     /**
 174         Returns the string associated with a status bar field.
 175
 176         @param i
 177             The number of the status field to retrieve, starting from zero.
 178
 179         @return The status field string if the field is valid, otherwise the
 180                 empty string.
 181
 182         @see SetStatusText()
 183     */
 184     virtual wxString GetStatusText(int i = 0) const;
 185
 186     /**
 187         Returns the width of the @a n-th field.
 188
 189         See wxStatusBarPane::GetWidth() for more info.
 190     */
 191     int GetStatusWidth(int n) const;
 192
 193     /**
 194         Returns the style of the @a n-th field.
 195
 196         See wxStatusBarPane::GetStyle() for more info.
 197     */
 198     int GetStatusStyle(int n) const;
 199
 200     /**
 201         Restores the text to the value it had before the last call to
 202         PushStatusText().
 203
 204         Notice that if SetStatusText() had been called in the meanwhile,
 205         PopStatusText() will not change the text, i.e. it does not override
 206         explicit changes to status text but only restores the saved text if it
 207         hadn't been changed since.
 208
 209         @see PushStatusText()
 210     */
 211     void PopStatusText(int field = 0);
 212
 213     /**
 214         Saves the current field text in a per-field stack, and sets the field
 215         text to the string passed as argument.
 216
 217         @see PopStatusText()
 218     */
 219     void PushStatusText(const wxString& string, int field = 0);
 220
 221     /**
 222         Sets the number of fields, and optionally the field widths.
 223
 224         @param number
 225             The number of fields. If this is greater than the previous number,
 226             then new fields with empty strings will be added to the status bar.
 227         @param widths
 228             An array of n integers interpreted in the same way as
 229             in SetStatusWidths().
 230
 231         @beginWxPerlOnly
 232         In wxPerl this function accepts only the @a number parameter.
 233         Use SetStatusWidths to set the field widths.
 234         @endWxPerlOnly
 235     */
 236     virtual void SetFieldsCount(int number = 1, const int* widths = NULL);
 237
 238     /**
 239         Sets the minimal possible height for the status bar.
 240
 241         The real height may be bigger than the height specified here depending
 242         on the size of the font used by the status bar.
 243     */
 244     virtual void SetMinHeight(int height);
 245
 246     /**
 247         Sets the styles of the fields in the status line which can make fields appear
 248         flat or raised instead of the standard sunken 3D border.
 249
 250         @param n
 251             The number of fields in the status bar. Must be equal to the
 252             number passed to SetFieldsCount() the last time it was called.
 253         @param styles
 254             Contains an array of @a n integers with the styles for each field.
 255             There are three possible styles:
 256             - @c wxSB_NORMAL (default): The field appears sunken with a standard 3D border.
 257             - @c wxSB_FLAT: No border is painted around the field so that it appears flat.
 258             - @c wxSB_RAISED: A raised 3D border is painted around the field.
 259     */
 260     virtual void SetStatusStyles(int n, const int* styles);
 261
 262     /**
 263         Sets the status text for the @a i-th field.
 264
 265         The given text will replace the current text.
 266
 267         Note that if PushStatusText() had been called before the new text will
 268         also replace the last saved value to make sure that the next call to
 269         PopStatusText() doesn't restore the old value, which was overwritten by
 270         the call to this function.
 271
 272         @param text
 273             The text to be set. Use an empty string ("") to clear the field.
 274         @param i
 275             The field to set, starting from zero.
 276
 277         @see GetStatusText(), wxFrame::SetStatusText
 278     */
 279     virtual void SetStatusText(const wxString& text, int i = 0);
 280
 281     /**
 282         Sets the widths of the fields in the status line. There are two types of
 283         fields: @b fixed widths and @b variable width fields. For the fixed width fields
 284         you should specify their (constant) width in pixels. For the variable width
 285         fields, specify a negative number which indicates how the field should expand:
 286         the space left for all variable width fields is divided between them according
 287         to the absolute value of this number. A variable width field with width of -2
 288         gets twice as much of it as a field with width -1 and so on.
 289
 290         For example, to create one fixed width field of width 100 in the right part of
 291         the status bar and two more fields which get 66% and 33% of the remaining
 292         space correspondingly, you should use an array containing -2, -1 and 100.
 293
 294         @param n
 295             The number of fields in the status bar. Must be equal to the
 296             number passed to SetFieldsCount() the last time it was called.
 297         @param widths_field
 298             Contains an array of n integers, each of which is either an
 299             absolute status field width in pixels if positive or indicates a
 300             variable width field if negative.
 301             The special value @NULL means that all fields should get the same width.
 302
 303         @remarks The widths of the variable fields are calculated from the total
 304                  width of all fields, minus the sum of widths of the
 305                  non-variable fields, divided by the number of variable fields.
 306
 307         @beginWxPerlOnly
 308         In wxPerl this method takes as parameters the field widths.
 309         @endWxPerlOnly
 310
 311         @see SetFieldsCount(), wxFrame::SetStatusWidths()
 312     */
 313     virtual void SetStatusWidths(int n, const int* widths_field);
 314 };
 315