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