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         @beginWxPerlOnly
 139         In wxPerl this function returns a @c Wx::Rect if the field
 140         index is valid, @c undef otherwise.
 141         @endWxPerlOnly
 142
 143         @see wxRect
 144     */
 145     virtual bool GetFieldRect(int i, wxRect& rect) const;
 146
 147     /**
 148         Returns the number of fields in the status bar.
 149     */
 150     int GetFieldsCount() const;
 151
 152     /**
 153         Returns the wxStatusBarPane representing the @a n-th field.
 154     */
 155     const wxStatusBarPane& GetField(int n) const;
 156
 157     /**
 158         Returns the horizontal and vertical borders used when rendering the field
 159         text inside the field area.
 160
 161         Note that the rect returned by GetFieldRect() already accounts for the
 162         presence of horizontal and vertical border returned by this function.
 163     */
 164     wxSize GetBorders() const;
 165
 166     /**
 167         Returns the string associated with a status bar field.
 168
 169         @param i
 170             The number of the status field to retrieve, starting from zero.
 171
 172         @return The status field string if the field is valid, otherwise the
 173                 empty string.
 174
 175         @see SetStatusText()
 176     */
 177     virtual wxString GetStatusText(int i = 0) const;
 178
 179     /**
 180         Returns the width of the @a n-th field.
 181
 182         See wxStatusBarPane::GetWidth() for more info.
 183     */
 184     int GetStatusWidth(int n) const;
 185
 186     /**
 187         Returns the style of the @a n-th field.
 188
 189         See wxStatusBarPane::GetStyle() for more info.
 190     */
 191     int GetStatusStyle(int n) const;
 192
 193     /**
 194         Restores the text to the value it had before the last call to
 195         PushStatusText().
 196
 197         Notice that if SetStatusText() had been called in the meanwhile,
 198         PopStatusText() will not change the text, i.e. it does not override
 199         explicit changes to status text but only restores the saved text if it
 200         hadn't been changed since.
 201
 202         @see PushStatusText()
 203     */
 204     void PopStatusText(int field = 0);
 205
 206     /**
 207         Saves the current field text in a per-field stack, and sets the field
 208         text to the string passed as argument.
 209
 210         @see PopStatusText()
 211     */
 212     void PushStatusText(const wxString& string, int field = 0);
 213
 214     /**
 215         Sets the number of fields, and optionally the field widths.
 216
 217         @param number
 218             The number of fields. If this is greater than the previous number,
 219             then new fields with empty strings will be added to the status bar.
 220         @param widths
 221             An array of n integers interpreted in the same way as
 222             in SetStatusWidths().
 223
 224         @beginWxPerlOnly
 225         In wxPerl this function accepts only the @a number parameter.
 226         Use SetStatusWidths to set the field widths.
 227         @endWxPerlOnly
 228     */
 229     virtual void SetFieldsCount(int number = 1, const int* widths = NULL);
 230
 231     /**
 232         Sets the minimal possible height for the status bar.
 233
 234         The real height may be bigger than the height specified here depending
 235         on the size of the font used by the status bar.
 236     */
 237     virtual void SetMinHeight(int height);
 238
 239     /**
 240         Sets the styles of the fields in the status line which can make fields appear
 241         flat or raised instead of the standard sunken 3D border.
 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 styles
 247             Contains an array of @a n integers with the styles for each field.
 248             There are three possible styles:
 249             - @c wxSB_NORMAL (default): The field appears sunken with a standard 3D border.
 250             - @c wxSB_FLAT: No border is painted around the field so that it appears flat.
 251             - @c wxSB_RAISED: A raised 3D border is painted around the field.
 252     */
 253     virtual void SetStatusStyles(int n, const int* styles);
 254
 255     /**
 256         Sets the status text for the @a i-th field.
 257
 258         The given text will replace the current text.
 259
 260         Note that if PushStatusText() had been called before the new text will
 261         also replace the last saved value to make sure that the next call to
 262         PopStatusText() doesn't restore the old value, which was overwritten by
 263         the call to this function.
 264
 265         @param text
 266             The text to be set. Use an empty string ("") to clear the field.
 267         @param i
 268             The field to set, starting from zero.
 269
 270         @see GetStatusText(), wxFrame::SetStatusText
 271     */
 272     virtual void SetStatusText(const wxString& text, int i = 0);
 273
 274     /**
 275         Sets the widths of the fields in the status line. There are two types of
 276         fields: @b fixed widths and @b variable width fields. For the fixed width fields
 277         you should specify their (constant) width in pixels. For the variable width
 278         fields, specify a negative number which indicates how the field should expand:
 279         the space left for all variable width fields is divided between them according
 280         to the absolute value of this number. A variable width field with width of -2
 281         gets twice as much of it as a field with width -1 and so on.
 282
 283         For example, to create one fixed width field of width 100 in the right part of
 284         the status bar and two more fields which get 66% and 33% of the remaining
 285         space correspondingly, you should use an array containing -2, -1 and 100.
 286
 287         @param n
 288             The number of fields in the status bar. Must be equal to the
 289             number passed to SetFieldsCount() the last time it was called.
 290         @param widths_field
 291             Contains an array of n integers, each of which is either an
 292             absolute status field width in pixels if positive or indicates a
 293             variable width field if negative.
 294             The special value @NULL means that all fields should get the same width.
 295
 296         @remarks The widths of the variable fields are calculated from the total
 297                  width of all fields, minus the sum of widths of the
 298                  non-variable fields, divided by the number of variable fields.
 299
 300         @beginWxPerlOnly
 301         In wxPerl this method takes as parameters the field widths.
 302         @endWxPerlOnly
 303
 304         @see SetFieldsCount(), wxFrame::SetStatusWidths()
 305     */
 306     virtual void SetStatusWidths(int n, const int* widths_field);
 307 };
 308