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{wxstatusbarconstr}
  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}}
  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}{wxstatusbarconstr} 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 fields 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}{ ir = 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{wxstatusbarpushstatustext}
 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 %% VZ: these functions are not in wxStatusBar API, these are just
 152 %%     implementation details of wxStatusBarGeneric
 153 %%
 154 %% \membersection{wxStatusBar::DrawField}\label{wxstatusbardrawfield}
 155 %%
 156 %% \func{virtual void}{DrawField}{\param{wxDC\& }{dc}, \param{int }{i}}
 157 %%
 158 %% Draws a field, including shaded borders and text.
 159 %%
 160 %% \wxheading{Parameters}
 161 %%
 162 %% \docparam{dc}{The device context to draw onto.}
 163 %%
 164 %% \docparam{i}{The field to be drawn.}
 165 %%
 166 %% \wxheading{See also}
 167 %%
 168 %% \helpref{wxStatusBar::DrawFieldText}{wxstatusbardrawfieldtext}
 169 %%
 170 %% \membersection{wxStatusBar::DrawFieldText}\label{wxstatusbardrawfieldtext}
 171 %%
 172 %% \func{virtual void}{DrawFieldText}{\param{wxDC\& }{dc}, \param{int }{i}}
 173 %%
 174 %% Draws a field's text.
 175 %%
 176 %% \wxheading{Parameters}
 177 %%
 178 %% \docparam{dc}{The device context to draw onto.}
 179 %%
 180 %% \docparam{i}{The field whose text is to be drawn.}
 181 %%
 182 %% \wxheading{See also}
 183 %%
 184 %% \helpref{wxStatusBar::DrawField}{wxstatusbardrawfield}
 185 %%
 186 %% \membersection{wxStatusBar::InitColours}\label{wxstatusbarinitcolours}
 187 %%
 188 %% \func{virtual void}{InitColours}{\void}
 189 %%
 190 %% Sets up the background colour and shading pens using suitable system colours (Windows) or tasteful shades
 191 %% of grey (other platforms).
 192 %%
 193 %% \wxheading{Remarks}
 194 %%
 195 %% This function is called when the window is created, and also
 196 %% from \helpref{wxStatusBar::OnSysColourChanged}{wxstatusbaronsyscolourchanged} on Windows.
 197 %%
 198 %% \wxheading{See also}
 199 %%
 200 %% \helpref{wxStatusBar::OnSysColourChanged}{wxstatusbaronsyscolourchanged}
 201 %%
 202 %% \membersection{wxStatusBar::OnSysColourChanged}\label{wxstatusbaronsyscolourchanged}
 203 %%
 204 %% \func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}}
 205 %%
 206 %% Handles a system colour change by calling \helpref{wxStatusBar::InitColours}{wxstatusbarinitcolours},
 207 %% and refreshes the window.
 208 %%
 209 %% \wxheading{Parameters}
 210 %%
 211 %% \docparam{event}{The colour change event.}
 212 %%
 213 %% \wxheading{See also}
 214 %%
 215 %% \helpref{wxStatusBar::InitColours}{wxstatusbarinitcolours}
 216
 217 \membersection{wxStatusBar::SetFieldsCount}\label{wxstatusbarsetfieldscount}
 218
 219 \func{virtual void}{SetFieldsCount}{\param{int}{ number = 1}, \param{int* }{widths = NULL}}
 220
 221 Sets the number of fields, and optionally the field widths.
 222
 223 \pythonnote{Only the first parameter is accepted.  Use SetStatusWidths
 224 to set the widths of the fields.}
 225
 226 \perlnote{In wxPerl this function accepts only the {\tt n} parameter.
 227 Use SetStatusWidths to set the field widths.}
 228
 229 \wxheading{Parameters}
 230
 231 \docparam{number}{The number of fields.}
 232
 233 \docparam{widths}{An array of {\it n} integers, each of which is a status field width
 234 in pixels. A value of -1 indicates that the field is variable width; at least one
 235 field must be -1.}
 236
 237 \membersection{wxStatusBar::SetMinHeight}\label{wxstatusbarsetminheight}
 238
 239 \func{void}{SetMinHeight}{\param{int}{ height}}
 240
 241 Sets the minimal possible hight for the status bar. The real height may be
 242 bigger than the height specified here depending on the size of the font used by
 243 the status bar.
 244
 245 \membersection{wxStatusBar::SetStatusText}\label{wxstatusbarsetstatustext}
 246
 247 \func{virtual void}{SetStatusText}{\param{const wxString\& }{text}, \param{int}{ i = 0}}
 248
 249 Sets the text for one field.
 250
 251 \wxheading{Parameters}
 252
 253 \docparam{text}{The text to be set. Use an empty string (``") to clear the field.}
 254
 255 \docparam{i}{The field to set, starting from zero.}
 256
 257 \wxheading{See also}
 258
 259 \helpref{wxStatusBar::GetStatusText}{wxstatusbargetstatustext}, \helpref{wxFrame::SetStatusText}{wxframesetstatustext}
 260
 261 \membersection{wxStatusBar::SetStatusWidths}\label{wxstatusbarsetstatuswidths}
 262
 263 \func{virtual void}{SetStatusWidths}{\param{int}{ n}, \param{int *}{widths}}
 264
 265 Sets the widths of the fields in the status line. There are two types of
 266 fields: fixed widths one and variable width fields. For the fixed width fields
 267 you should specify their (constant) width in pixels. For the variable width
 268 fields, specify a negative number which indicates how should the field expand:
 269 the space left for all variable width fields is divided between them according
 270 to the absolute value of this number. A variable width field with width of $-2$
 271 gets twice as much of it as a field with width $-1$ and so on.
 272
 273 For example, to create one fixed width field of width $50$ in the right part of
 274 the status bar and two more fields which get $66$\% and $33$\% of the remaining
 275 space correspondingly, you should use an array containing $-2$, $-1$ and $100$.
 276
 277 \wxheading{Parameters}
 278
 279 \docparam{n}{The number of fields in the status bar. Must be equal to the
 280 number passed to \helpref{SetFieldsCount}{wxstatusbarsetfieldscount} the last
 281 time it was called.}
 282
 283 \docparam{widths}{Contains an array of {\it n} integers, each of which is
 284 either an absolute status field width in pixels if positive or indicates a
 285 variable width field if negative}
 286
 287 \wxheading{Remarks}
 288
 289 The widths of the variable fields are calculated from the total width of all fields,
 290 minus the sum of widths of the non-variable fields, divided by the number of
 291 variable fields.
 292
 293 \wxheading{See also}
 294
 295 \helpref{wxStatusBar::SetFieldsCount}{wxstatusbarsetfieldscount}, \helpref{wxFrame::SetStatusWidths}{wxframesetstatuswidths}
 296
 297 \pythonnote{Only a single parameter is required, a Python list of
 298 integers.}
 299
 300 \perlnote{In wxPerl this method takes as parameters the field widths.}
 301