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{wxSB\_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{const wxPoint\&}{ pos = wxDefaultPosition},\rtfsp
  50 \param{const wxSize\&}{ size = wxDefaultSize}, \param{long}{ style = 0},\rtfsp
  51 \param{const wxString\& }{name = ``statusBar"}}
  52
  53 Constructor, creating the window.
  54
  55 \wxheading{Parameters}
  56
  57 \docparam{parent}{The window parent, usually a frame.}
  58
  59 \docparam{id}{The window identifier. It may take a value of -1 to indicate a default value.}
  60
  61 \docparam{pos}{The window position. A value of (-1, -1) indicates a default position, chosen by
  62 either the windowing system or wxWindows, depending on platform.}
  63
  64 \docparam{size}{The window size. A value of (-1, -1) indicates a default size, chosen by
  65 either the windowing system or wxWindows, depending on platform.}
  66
  67 \docparam{style}{The window style. See \helpref{wxStatusBar}{wxstatusbar}.}
  68
  69 \docparam{name}{The name of the window. This parameter is used to associate a name with the item,
  70 allowing the application user to set Motif resource values for
  71 individual windows.}
  72
  73 \wxheading{See also}
  74
  75 \helpref{wxStatusBar::Create}{wxstatusbarcreate}
  76
  77 \membersection{wxStatusBar::\destruct{wxStatusBar}}
  78
  79 \func{void}{\destruct{wxStatusBar}}{\void}
  80
  81 Destructor.
  82
  83 \membersection{wxStatusBar::Create}\label{wxstatusbarcreate}
  84
  85 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
  86 \param{const wxPoint\&}{ pos = wxDefaultPosition},\rtfsp
  87 \param{const wxSize\&}{ size = wxDefaultSize}, \param{long}{ style = 0},\rtfsp
  88 \param{const wxString\& }{name = ``statusBar"}}
  89
  90 Creates the window, for two-step construction.
  91
  92 See \helpref{wxStatusBar::wxStatusBar}{wxstatusbarconstr} for details.
  93
  94 \membersection{wxStatusBar::GetFieldRect}\label{wxstatusbargetfieldrect}
  95
  96 \constfunc{virtual bool}{GetFieldRect}{\param{int}{ i}, \param{wxRect\&}{ rect}}
  97
  98 Returns the size and position of a fields internal bounding rectangle.
  99
 100 \wxheading{Parameters}
 101
 102 \docparam{i}{The field in question.}
 103
 104 \docparam{rect}{The rectangle values are placed in this variable.}
 105
 106 \wxheading{Return value}
 107
 108 TRUE if the field index is valid, FALSE otherwise.
 109
 110 \wxheading{See also}
 111
 112 \helpref{wxRect}{wxrect}
 113
 114 \membersection{wxStatusBar::GetFieldsCount}\label{wxstatusbargetfieldscount}
 115
 116 \constfunc{int}{GetFieldsCount}{\void}
 117
 118 Returns the number of fields in the status bar.
 119
 120 \membersection{wxStatusBar::GetStatusText}\label{wxstatusbargetstatustext}
 121
 122 \constfunc{virtual wxString}{GetStatusText}{\param{int}{ ir = 0}}
 123
 124 Returns the string associated with a status bar field.
 125
 126 \wxheading{Parameters}
 127
 128 \docparam{i}{The number of the status field to retrieve, starting from zero.}
 129
 130 \wxheading{Return value}
 131
 132 The status field string if the field is valid, otherwise the empty string.
 133
 134 \wxheading{See also}
 135
 136 \helpref{wxStatusBar::SetStatusText}{wxstatusbarsetstatustext}
 137
 138 \membersection{wxStatusBar::DrawField}\label{wxstatusbardrawfield}
 139
 140 \func{virtual void}{DrawField}{\param{wxDC\& }{dc}, \param{int }{i}}
 141
 142 Draws a field, including shaded borders and text.
 143
 144 \wxheading{Parameters}
 145
 146 \docparam{dc}{The device context to draw onto.}
 147
 148 \docparam{i}{The field to be drawn.}
 149
 150 \wxheading{See also}
 151
 152 \helpref{wxStatusBar::DrawFieldText}{wxstatusbardrawfieldtext}
 153
 154 \membersection{wxStatusBar::DrawFieldText}\label{wxstatusbardrawfieldtext}
 155
 156 \func{virtual void}{DrawFieldText}{\param{wxDC\& }{dc}, \param{int }{i}}
 157
 158 Draws a field's text.
 159
 160 \wxheading{Parameters}
 161
 162 \docparam{dc}{The device context to draw onto.}
 163
 164 \docparam{i}{The field whose text is to be drawn.}
 165
 166 \wxheading{See also}
 167
 168 \helpref{wxStatusBar::DrawField}{wxstatusbardrawfield}
 169
 170 \membersection{wxStatusBar::InitColours}\label{wxstatusbarinitcolours}
 171
 172 \func{virtual void}{InitColours}{\void}
 173
 174 Sets up the background colour and shading pens using suitable system colours (Windows) or tasteful shades
 175 of grey (other platforms).
 176
 177 \wxheading{Remarks}
 178
 179 This function is called when the window is created, and also
 180 from \helpref{wxStatusBar::OnSysColourChanged}{wxstatusbaronsyscolourchanged} on Windows.
 181
 182 \wxheading{See also}
 183
 184 \helpref{wxStatusBar::OnSysColourChanged}{wxstatusbaronsyscolourchanged}
 185
 186 \membersection{wxStatusBar::OnSysColourChanged}\label{wxstatusbaronsyscolourchanged}
 187
 188 \func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}}
 189
 190 Handles a system colour change by calling \helpref{wxStatusBar::InitColours}{wxstatusbarinitcolours},
 191 and refreshes the window.
 192
 193 \wxheading{Parameters}
 194
 195 \docparam{event}{The colour change event.}
 196
 197 \wxheading{See also}
 198
 199 \helpref{wxStatusBar::InitColours}{wxstatusbarinitcolours}
 200
 201 \membersection{wxStatusBar::SetFieldsCount}\label{wxstatusbarsetfieldscount}
 202
 203 \func{virtual void}{SetFieldsCount}{\param{int}{ number = 1}, \param{int* }{widths = NULL}}
 204
 205 Sets the number of fields, and optionally the field widths.
 206
 207 \pythonnote{Only the first parameter is accepted.  Use SetStatusWidths
 208 to set the widths of the fields.}
 209
 210 \perlnote{In wxPerl this function acceps only the {\tt n} parameter.
 211 Use SetStatusWidths to set the field widths.}
 212
 213 \wxheading{Parameters}
 214
 215 \docparam{number}{The number of fields.}
 216
 217 \docparam{widths}{An array of {\it n} integers, each of which is a status field width
 218 in pixels. A value of -1 indicates that the field is variable width; at least one
 219 field must be -1.}
 220
 221 \membersection{wxStatusBar::SetMinHeight}\label{wxstatusbarsetminheight}
 222
 223 \func{void}{SetMinHeight}{\param{int}{ height}}
 224
 225 Sets the minimal possible hight for the status bar. The real height may be
 226 bigger than the height specified here depending on the size of the font used by
 227 the status bar.
 228
 229 \membersection{wxStatusBar::SetStatusText}\label{wxstatusbarsetstatustext}
 230
 231 \func{virtual void}{SetStatusText}{\param{const wxString\& }{text}, \param{int}{ i = 0}}
 232
 233 Sets the text for one field.
 234
 235 \wxheading{Parameters}
 236
 237 \docparam{text}{The text to be set. Use an empty string (``") to clear the field.}
 238
 239 \docparam{i}{The field to set, starting from zero.}
 240
 241 \wxheading{See also}
 242
 243 \helpref{wxStatusBar::GetStatusText}{wxstatusbargetstatustext}, \helpref{wxFrame::SetStatusText}{wxframesetstatustext}
 244
 245 \membersection{wxStatusBar::SetStatusWidths}\label{wxstatusbarsetstatuswidths}
 246
 247 \func{virtual void}{SetStatusWidths}{\param{int}{ n}, \param{int *}{widths}}
 248
 249 Sets the widths of the fields in the status line.
 250
 251 \wxheading{Parameters}
 252
 253 \docparam{n}{The number of fields in the status bar.}
 254
 255 \docparam{widths}{Must contain an array of {\it n} integers, each of which is a status field width
 256 in pixels. A value of -1 indicates that the field is variable width; at least one
 257 field must be -1. You should delete this array after calling {\bf SetStatusWidths}.}
 258
 259 \wxheading{Remarks}
 260
 261 The widths of the variable fields are calculated from the total width of all fields,
 262 minus the sum of widths of the non-variable fields, divided by the number of
 263 variable fields.
 264
 265 \wxheading{See also}
 266
 267 \helpref{wxStatusBar::SetFieldsCount}{wxstatusbarsetfieldscount}, \helpref{wxFrame::SetStatusWidths}{wxframesetstatuswidths}
 268
 269 \pythonnote{Only a single parameter is required, a Python list of
 270 integers.}
 271
 272 \perlnote{In wxPerl this method takes as parameters the field widths.}