interface/statusbr.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        statusbr.h
   3 // Purpose:     documentation for wxStatusBar class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxStatusBar
  11     @wxheader{statusbr.h}
  12
  13     A status bar is a narrow window that can be placed along the bottom of a frame
  14     to give
  15     small amounts of status information. It can contain one or more fields, one or
  16     more of which can
  17     be variable length according to the size of the window.
  18
  19     wxWindow
  20
  21     wxEvtHandler
  22
  23     wxObject
  24
  25     @beginStyleTable
  26     @style{wxST_SIZEGRIP}:
  27            On Windows 95, displays a gripper at right-hand side of the status
  28            bar.
  29     @endStyleTable
  30
  31     @library{wxcore}
  32     @category{miscwnd}
  33
  34     @seealso
  35     wxFrame, @ref overview_samplestatbar "Status bar sample"
  36 */
  37 class wxStatusBar : public wxWindow
  38 {
  39 public:
  40     //@{
  41     /**
  42         Constructor, creating the window.
  43
  44         @param parent
  45         The window parent, usually a frame.
  46
  47         @param id
  48         The window identifier. It may take a value of -1 to indicate a default value.
  49
  50         @param style
  51         The window style. See wxStatusBar.
  52
  53         @param name
  54         The name of the window. This parameter is used to associate a name with the
  55         item,
  56         allowing the application user to set Motif resource values for
  57         individual windows.
  58
  59         @sa Create()
  60     */
  61     wxStatusBar();
  62     wxStatusBar(wxWindow* parent, wxWindowID id = wxID_ANY,
  63                 long style = wxST_SIZEGRIP,
  64                 const wxString& name = "statusBar");
  65     //@}
  66
  67     /**
  68         Destructor.
  69     */
  70     ~wxStatusBar();
  71
  72     /**
  73         Creates the window, for two-step construction.
  74
  75         See wxStatusBar() for details.
  76     */
  77     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
  78                 long style = wxST_SIZEGRIP,
  79                 const wxString& name = "statusBar");
  80
  81     /**
  82         Returns the size and position of a field's internal bounding rectangle.
  83
  84         @param i
  85         The field in question.
  86
  87         @param rect
  88         The rectangle values are placed in this variable.
  89
  90         @returns @true if the field index is valid, @false otherwise.
  91
  92         @sa wxRect
  93     */
  94     virtual bool GetFieldRect(int i, wxRect& rect);
  95
  96     /**
  97         Returns the number of fields in the status bar.
  98     */
  99     int GetFieldsCount();
 100
 101     /**
 102         Returns the string associated with a status bar field.
 103
 104         @param i
 105         The number of the status field to retrieve, starting from zero.
 106
 107         @returns The status field string if the field is valid, otherwise the
 108                    empty string.
 109
 110         @sa SetStatusText()
 111     */
 112     virtual wxString GetStatusText(int i = 0);
 113
 114     /**
 115         Sets the field text to the top of the stack, and pops the stack of saved
 116         strings.
 117
 118         @sa PushStatusText()
 119     */
 120     void PopStatusText(int field = 0);
 121
 122     /**
 123         Saves the current field text in a per field stack, and sets the field text
 124         to the string passed as argument.
 125     */
 126     void PushStatusText(const wxString& string, int field = 0);
 127
 128     /**
 129         Sets the number of fields, and optionally the field widths.
 130
 131         @param number
 132         The number of fields.
 133
 134         @param widths
 135         An array of n integers interpreted in the same way as
 136         in SetStatusWidths
 137     */
 138     virtual void SetFieldsCount(int number = 1, int* widths = @NULL);
 139
 140     /**
 141         Sets the minimal possible height for the status bar. The real height may be
 142         bigger than the height specified here depending on the size of the font used by
 143         the status bar.
 144     */
 145     void SetMinHeight(int height);
 146
 147     /**
 148         Sets the styles of the fields in the status line which can make fields appear
 149         flat
 150         or raised instead of the standard sunken 3D border.
 151
 152         @param n
 153         The number of fields in the status bar. Must be equal to the
 154         number passed to SetFieldsCount the last
 155         time it was called.
 156
 157         @param styles
 158         Contains an array of n integers with the styles for each field. There
 159         are three possible styles:
 160
 161
 162         wxSB_NORMAL
 163
 164
 165         (default) The field appears sunken with a standard 3D border.
 166
 167         wxSB_FLAT
 168
 169
 170         No border is painted around the field so that it appears flat.
 171
 172         wxSB_RAISED
 173
 174
 175         A raised 3D border is painted around the field.
 176     */
 177     virtual void SetStatusStyles(int n, int * styles);
 178
 179     /**
 180         Sets the text for one field.
 181
 182         @param text
 183         The text to be set. Use an empty string ("") to clear the field.
 184
 185         @param i
 186         The field to set, starting from zero.
 187
 188         @sa GetStatusText(), wxFrame::SetStatusText
 189     */
 190     virtual void SetStatusText(const wxString& text, int i = 0);
 191
 192     /**
 193         Sets the widths of the fields in the status line. There are two types of
 194         fields: fixed widths one and variable width fields. For the fixed width fields
 195         you should specify their (constant) width in pixels. For the variable width
 196         fields, specify a negative number which indicates how the field should expand:
 197         the space left for all variable width fields is divided between them according
 198         to the absolute value of this number. A variable width field with width of -2
 199         gets twice as much of it as a field with width -1 and so on.
 200
 201         For example, to create one fixed width field of width 100 in the right part of
 202         the status bar and two more fields which get 66% and 33% of the remaining
 203         space correspondingly, you should use an array containing -2, -1 and 100.
 204
 205         @param n
 206         The number of fields in the status bar. Must be equal to the
 207         number passed to SetFieldsCount the last
 208         time it was called.
 209
 210         @param widths
 211         Contains an array of n integers, each of which is
 212         either an absolute status field width in pixels if positive or indicates a
 213         variable width field if negative.
 214
 215         @remarks The widths of the variable fields are calculated from the total
 216                    width of all fields, minus the sum of widths of the
 217                    non-variable fields, divided by the number of
 218                    variable fields.
 219
 220         @sa SetFieldsCount(), wxFrame::SetStatusWidths
 221     */
 222     virtual void SetStatusWidths(int n, int * widths);
 223 };