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}
  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 \wxheading{Parameters}
 208
 209 \docparam{number}{The number of fields.}
 210
 211 \docparam{widths}{An array of {\it n} integers, each of which is a status field width
 212 in pixels. A value of -1 indicates that the field is variable width; at least one
 213 field must be -1.}
 214
 215 \membersection{wxStatusBar::SetStatusText}\label{wxstatusbarsetstatustext}
 216
 217 \func{virtual void}{SetStatusText}{\param{const wxString\& }{text}, \param{int}{ i = 0}}
 218
 219 Sets the text for one field.
 220
 221 \wxheading{Parameters}
 222
 223 \docparam{text}{The text to be set. Use an empty string (``") to clear the field.}
 224
 225 \docparam{i}{The field to set, starting from zero.}
 226
 227 \wxheading{See also}
 228
 229 \helpref{wxStatusBar::GetStatusText}{wxstatusbargetstatustext}, \helpref{wxFrame::SetStatusText}{wxframesetstatustext}
 230
 231 \membersection{wxStatusBar::SetStatusWidths}\label{wxstatusbarsetstatuswidths}
 232
 233 \func{virtual void}{SetStatusWidths}{\param{int}{ n}, \param{int *}{widths}}
 234
 235 Sets the widths of the fields in the status line.
 236
 237 \wxheading{Parameters}
 238
 239 \docparam{n}{The number of fields in the status bar.}
 240
 241 \docparam{widths}{Must contain an array of {\it n} integers, each of which is a status field width
 242 in pixels. A value of -1 indicates that the field is variable width; at least one
 243 field must be -1. You should delete this array after calling {\bf SetStatusWidths}.}
 244
 245 \wxheading{Remarks}
 246
 247 The widths of the variable fields are calculated from the total width of all fields,
 248 minus the sum of widths of the non-variable fields, divided by the number of
 249 variable fields.
 250
 251 \wxheading{See also}
 252
 253 \helpref{wxStatusBar::SetFieldsCount}{wxstatusbarsetfieldscount}, \helpref{wxFrame::SetStatusWidths}{wxframesetstatuswidths}
 254
 255