docs/latex/wx/statusbr.tex

   1 \section{\class{wxStatusBar}}\label{wxstatusbar}
   2
   3 A status bar is a narrow window that can be placed along the bottom of a frame to give
   4 small amounts of status information. It can contain one or more fields, one or more of which can
   5 be variable length according to the size of the window.
   6
   7 \helpref{wxWindow}{wxwindow}\\
   8 \helpref{wxEvtHandler}{wxevthandler}\\
   9 \helpref{wxObject}{wxobject}
  10
  11 \wxheading{Derived from}
  12
  13 \helpref{wxWindow}{wxwindow}\\
  14 \helpref{wxEvtHandler}{wxevthandler}\\
  15 \helpref{wxObject}{wxobject}
  16
  17 \wxheading{Include files}
  18
  19 <wx/statusbr.h>
  20
  21 \wxheading{Window styles}
  22
  23 \twocolwidtha{5cm}
  24 \begin{twocollist}\itemsep=0pt
  25 \twocolitem{\windowstyle{wxST\_SIZEGRIP}}{On Windows 95, displays a gripper at right-hand side of
  26 the status bar.}
  27 \end{twocollist}
  28
  29 See also \helpref{window styles overview}{windowstyles}.
  30
  31 \wxheading{Remarks}
  32
  33 It is possible to create controls and other windows on the status bar. Position these windows
  34 from an {\bf OnSize} event handler.
  35
  36 \wxheading{See also}
  37
  38 \helpref{wxFrame}{wxframe}, \helpref{Status bar sample}{samplestatbar}
  39
  40 \latexignore{\rtfignore{\wxheading{Members}}}
  41
  42 \membersection{wxStatusBar::wxStatusBar}\label{wxstatusbarctor}
  43
  44 \func{}{wxStatusBar}{\void}
  45
  46 Default constructor.
  47
  48 \func{}{wxStatusBar}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
  49 \param{long}{ style = wxST\_SIZEGRIP},\rtfsp
  50 \param{const wxString\& }{name = ``statusBar"}}
  51
  52 Constructor, creating the window.
  53
  54 \wxheading{Parameters}
  55
  56 \docparam{parent}{The window parent, usually a frame.}
  57
  58 \docparam{id}{The window identifier. It may take a value of -1 to indicate a default value.}
  59
  60 \docparam{style}{The window style. See \helpref{wxStatusBar}{wxstatusbar}.}
  61
  62 \docparam{name}{The name of the window. This parameter is used to associate a name with the item,
  63 allowing the application user to set Motif resource values for
  64 individual windows.}
  65
  66 \wxheading{See also}
  67
  68 \helpref{wxStatusBar::Create}{wxstatusbarcreate}
  69
  70 \membersection{wxStatusBar::\destruct{wxStatusBar}}\label{wxstatusbardtor}
  71
  72 \func{void}{\destruct{wxStatusBar}}{\void}
  73
  74 Destructor.
  75
  76 \membersection{wxStatusBar::Create}\label{wxstatusbarcreate}
  77
  78 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
  79 \param{long}{ style = wxST\_SIZEGRIP},\rtfsp
  80 \param{const wxString\& }{name = ``statusBar"}}
  81
  82 Creates the window, for two-step construction.
  83
  84 See \helpref{wxStatusBar::wxStatusBar}{wxstatusbarctor} for details.
  85
  86 \membersection{wxStatusBar::GetFieldRect}\label{wxstatusbargetfieldrect}
  87
  88 \constfunc{virtual bool}{GetFieldRect}{\param{int}{ i}, \param{wxRect\&}{ rect}}
  89
  90 Returns the size and position of a field's internal bounding rectangle.
  91
  92 \wxheading{Parameters}
  93
  94 \docparam{i}{The field in question.}
  95
  96 \docparam{rect}{The rectangle values are placed in this variable.}
  97
  98 \wxheading{Return value}
  99
 100 true if the field index is valid, false otherwise.
 101
 102 \wxheading{See also}
 103
 104 \helpref{wxRect}{wxrect}
 105
 106 \perlnote{In wxPerl this function returns a {\tt Wx::Rect} if the field
 107   index is valid, {\tt undef} otherwise.}
 108
 109 \membersection{wxStatusBar::GetFieldsCount}\label{wxstatusbargetfieldscount}
 110
 111 \constfunc{int}{GetFieldsCount}{\void}
 112
 113 Returns the number of fields in the status bar.
 114
 115 \membersection{wxStatusBar::GetStatusText}\label{wxstatusbargetstatustext}
 116
 117 \constfunc{virtual wxString}{GetStatusText}{\param{int}{ i = 0}}
 118
 119 Returns the string associated with a status bar field.
 120
 121 \wxheading{Parameters}
 122
 123 \docparam{i}{The number of the status field to retrieve, starting from zero.}
 124
 125 \wxheading{Return value}
 126
 127 The status field string if the field is valid, otherwise the empty string.
 128
 129 \wxheading{See also}
 130
 131 \helpref{wxStatusBar::SetStatusText}{wxstatusbarsetstatustext}
 132
 133 \membersection{wxStatusBar::PopStatusText}\label{wxstatusbarpopstatustext}
 134
 135 \func{void}{PopStatusText}{\param{int}{ field = 0}}
 136
 137 Sets the field text to the top of the stack, and pops the stack of saved
 138 strings.
 139
 140 \wxheading{See also}
 141
 142 \helpref{wxStatusBar::PushStatusText}{wxstatusbarpushstatustext}
 143
 144 \membersection{wxStatusBar::PushStatusText}\label{wxstatusbarpushstatustext}
 145
 146 \func{void}{PushStatusText}{\param{const wxString\&}{ string}, \param{int}{ field = 0}}
 147
 148 Saves the current field text in a per field stack, and sets the field text
 149 to the string passed as argument.
 150
 151 \membersection{wxStatusBar::SetFieldsCount}\label{wxstatusbarsetfieldscount}
 152
 153 \func{virtual void}{SetFieldsCount}{\param{int}{ number = 1}, \param{int* }{widths = NULL}}
 154
 155 Sets the number of fields, and optionally the field widths.
 156
 157 \pythonnote{Only the first parameter is accepted.  Use SetStatusWidths
 158 to set the widths of the fields.}
 159
 160 \perlnote{In wxPerl this function accepts only the {\tt n} parameter.
 161 Use SetStatusWidths to set the field widths.}
 162
 163 \wxheading{Parameters}
 164
 165 \docparam{number}{The number of fields.}
 166
 167 \docparam{widths}{An array of {\it n} integers interpreted in the same way as
 168 in \helpref{SetStatusWidths}{wxstatusbarsetstatuswidths}}
 169
 170 \membersection{wxStatusBar::SetMinHeight}\label{wxstatusbarsetminheight}
 171
 172 \func{void}{SetMinHeight}{\param{int}{ height}}
 173
 174 Sets the minimal possible height for the status bar. The real height may be
 175 bigger than the height specified here depending on the size of the font used by
 176 the status bar.
 177
 178 \membersection{wxStatusBar::SetStatusText}\label{wxstatusbarsetstatustext}
 179
 180 \func{virtual void}{SetStatusText}{\param{const wxString\& }{text}, \param{int}{ i = 0}}
 181
 182 Sets the text for one field.
 183
 184 \wxheading{Parameters}
 185
 186 \docparam{text}{The text to be set. Use an empty string (``") to clear the field.}
 187
 188 \docparam{i}{The field to set, starting from zero.}
 189
 190 \wxheading{See also}
 191
 192 \helpref{wxStatusBar::GetStatusText}{wxstatusbargetstatustext}, \helpref{wxFrame::SetStatusText}{wxframesetstatustext}
 193
 194 \membersection{wxStatusBar::SetStatusWidths}\label{wxstatusbarsetstatuswidths}
 195
 196 \func{virtual void}{SetStatusWidths}{\param{int}{ n}, \param{int *}{widths}}
 197
 198 Sets the widths of the fields in the status line. There are two types of
 199 fields: fixed widths one and variable width fields. For the fixed width fields
 200 you should specify their (constant) width in pixels. For the variable width
 201 fields, specify a negative number which indicates how the field should expand:
 202 the space left for all variable width fields is divided between them according
 203 to the absolute value of this number. A variable width field with width of $-2$
 204 gets twice as much of it as a field with width $-1$ and so on.
 205
 206 For example, to create one fixed width field of width $100$ in the right part of
 207 the status bar and two more fields which get $66$\% and $33$\% of the remaining
 208 space correspondingly, you should use an array containing $-2$, $-1$ and $100$.
 209
 210 \wxheading{Parameters}
 211
 212 \docparam{n}{The number of fields in the status bar. Must be equal to the
 213 number passed to \helpref{SetFieldsCount}{wxstatusbarsetfieldscount} the last
 214 time it was called.}
 215
 216 \docparam{widths}{Contains an array of {\it n} integers, each of which is
 217 either an absolute status field width in pixels if positive or indicates a
 218 variable width field if negative.}
 219
 220 \wxheading{Remarks}
 221
 222 The widths of the variable fields are calculated from the total width of all fields,
 223 minus the sum of widths of the non-variable fields, divided by the number of
 224 variable fields.
 225
 226 \wxheading{See also}
 227
 228 \helpref{wxStatusBar::SetFieldsCount}{wxstatusbarsetfieldscount}, \helpref{wxFrame::SetStatusWidths}{wxframesetstatuswidths}
 229
 230 \pythonnote{Only a single parameter is required, a Python list of
 231 integers.}
 232
 233 \perlnote{In wxPerl this method takes as parameters the field widths.}
 234
 235 \membersection{wxStatusBar::SetStatusStyles}\label{wxstatusbarsetstatusstyles}
 236
 237 \func{virtual void}{SetStatusStyles}{\param{int}{ n}, \param{int *}{styles}}
 238
 239 Sets the styles of the fields in the status line which can make fields appear flat
 240 or raised instead of the standard sunken 3D border.
 241
 242 \wxheading{Parameters}
 243
 244 \docparam{n}{The number of fields in the status bar. Must be equal to the
 245 number passed to \helpref{SetFieldsCount}{wxstatusbarsetfieldscount} the last
 246 time it was called.}
 247
 248 \docparam{styles}{Contains an array of {\it n} integers with the styles for each field. There
 249 are three possible styles:
 250
 251 \twocolwidtha{5cm}
 252 \begin{twocollist}\itemsep=0pt
 253 \twocolitem{\windowstyle{wxSB\_NORMAL}}{(default) The field appears sunken with a standard 3D border.}
 254 \twocolitem{\windowstyle{wxSB\_FLAT}}{No border is painted around the field so that it appears flat.}
 255 \twocolitem{\windowstyle{wxSB\_RAISED}}{A raised 3D border is painted around the field.}
 256 \end{twocollist}
 257 }
 258
 259