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{Window styles}
  12
  13 \twocolwidtha{5cm}
  14 \begin{twocollist}\itemsep=0pt
  15 \twocolitem{\windowstyle{wxSB\_SIZEGRIP}}{On Windows 95, displays a gripper at right-hand side of
  16 the status bar.}
  17 \end{twocollist}
  18
  19 See also \helpref{window styles overview}{windowstyles}.
  20
  21 \wxheading{Remarks}
  22
  23 It is possible to create controls and other windows on the status bar. Position these windows
  24 from an {\bf OnSize} event handler.
  25
  26 \wxheading{See also}
  27
  28 \helpref{wxFrame}{wxframe}
  29
  30 \latexignore{\rtfignore{\wxheading{Members}}}
  31
  32 \membersection{wxStatusBar::wxStatusBar}\label{wxstatusbarconstr}
  33
  34 \func{}{wxStatusBar}{\void}
  35
  36 Default constructor.
  37
  38 \func{}{wxStatusBar}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
  39 \param{const wxPoint\&}{ pos = wxDefaultPosition},\rtfsp
  40 \param{const wxSize\&}{ size = wxDefaultSize}, \param{long}{ style = 0},\rtfsp
  41 \param{const wxString\& }{name = ``statusBar"}}
  42
  43 Constructor, creating the window.
  44
  45 \wxheading{Parameters}
  46
  47 \docparam{parent}{The window parent, usually a frame.}
  48
  49 \docparam{id}{The window identifier. It may take a value of -1 to indicate a default value.}
  50
  51 \docparam{pos}{The window position. A value of (-1, -1) indicates a default position, chosen by
  52 either the windowing system or wxWindows, depending on platform.}
  53
  54 \docparam{size}{The window size. A value of (-1, -1) indicates a default size, chosen by
  55 either the windowing system or wxWindows, depending on platform.}
  56
  57 \docparam{style}{The window style. See \helpref{wxStatusBar}{wxstatusbar}.}
  58
  59 \docparam{name}{The name of the window. This parameter is used to associate a name with the item,
  60 allowing the application user to set Motif resource values for
  61 individual windows.}
  62
  63 \wxheading{See also}
  64
  65 \helpref{wxStatusBar::Create}{wxstatusbarcreate}
  66
  67 \membersection{wxStatusBar::\destruct{wxStatusBar}}
  68
  69 \func{void}{\destruct{wxStatusBar}}{\void}
  70
  71 Destructor.
  72
  73 \membersection{wxStatusBar::Create}\label{wxstatusbarcreate}
  74
  75 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
  76 \param{const wxPoint\&}{ pos = wxDefaultPosition},\rtfsp
  77 \param{const wxSize\&}{ size = wxDefaultSize}, \param{long}{ style = 0},\rtfsp
  78 \param{const wxString\& }{name = ``statusBar"}}
  79
  80 Creates the window, for two-step construction.
  81
  82 See \helpref{wxStatusBar::wxStatusBar}{wxstatusbarconstr} for details.
  83
  84 \membersection{wxStatusBar::GetFieldRect}\label{wxstatusbargetfieldrect}
  85
  86 \constfunc{virtual bool}{GetFieldRect}{\param{int}{ i}, \param{wxRect\&}{ rect}}
  87
  88 Returns the size and position of a fields internal bounding rectangle.
  89
  90 \wxheading{Parameters}
  91
  92 \docparam{i}{The field in question.}
  93
  94 \docparam{rect}{The rectangle values are placed in this variable.}
  95
  96 \wxheading{Return value}
  97
  98 TRUE if the field index is valid, FALSE otherwise.
  99
 100 \wxheading{See also}
 101
 102 \helpref{wxRect}{wxrect}
 103
 104 \membersection{wxStatusBar::GetFieldsCount}\label{wxstatusbargetfieldscount}
 105
 106 \constfunc{int}{GetFieldsCount}{\void}
 107
 108 Returns the number of fields in the status bar.
 109
 110 \membersection{wxStatusBar::GetStatusText}\label{wxstatusbargetstatustext}
 111
 112 \constfunc{virtual wxString}{GetStatusText}{\param{int}{ ir = 0}}
 113
 114 Returns the string associated with a status bar field.
 115
 116 \wxheading{Parameters}
 117
 118 \docparam{i}{The number of the status field to retrieve, starting from zero.}
 119
 120 \wxheading{Return value}
 121
 122 The status field string if the field is valid, otherwise the empty string.
 123
 124 \wxheading{See also}
 125
 126 \helpref{wxStatusBar::SetStatusText}{wxstatusbarsetstatustext}
 127
 128 \membersection{wxStatusBar::DrawField}\label{wxstatusbardrawfield}
 129
 130 \func{virtual void}{DrawField}{\param{wxDC\& }{dc}, \param{int }{i}}
 131
 132 Draws a field, including shaded borders and text.
 133
 134 \wxheading{Parameters}
 135
 136 \docparam{dc}{The device context to draw onto.}
 137
 138 \docparam{i}{The field to be drawn.}
 139
 140 \wxheading{See also}
 141
 142 \helpref{wxStatusBar::DrawFieldText}{wxstatusbardrawfieldtext}
 143
 144 \membersection{wxStatusBar::DrawFieldText}\label{wxstatusbardrawfieldtext}
 145
 146 \func{virtual void}{DrawFieldText}{\param{wxDC\& }{dc}, \param{int }{i}}
 147
 148 Draws a field's text.
 149
 150 \wxheading{Parameters}
 151
 152 \docparam{dc}{The device context to draw onto.}
 153
 154 \docparam{i}{The field whose text is to be drawn.}
 155
 156 \wxheading{See also}
 157
 158 \helpref{wxStatusBar::DrawField}{wxstatusbardrawfield}
 159
 160 \membersection{wxStatusBar::InitColours}\label{wxstatusbarinitcolours}
 161
 162 \func{virtual void}{InitColours}{\void}
 163
 164 Sets up the background colour and shading pens using suitable system colours (Windows) or tasteful shades
 165 of grey (other platforms).
 166
 167 \wxheading{Remarks}
 168
 169 This function is called when the window is created, and also
 170 from \helpref{wxStatusBar::OnSysColourChanged}{wxstatusbaronsyscolourchanged} on Windows.
 171
 172 \wxheading{See also}
 173
 174 \helpref{wxStatusBar::OnSysColourChanged}{wxstatusbaronsyscolourchanged}
 175
 176 \membersection{wxStatusBar::OnSysColourChanged}\label{wxstatusbaronsyscolourchanged}
 177
 178 \func{void}{OnSysColourChanged}{\param{wxSysColourChangedEvent\& }{event}}
 179
 180 Handles a system colour change by calling \helpref{wxStatusBar::InitColours}{wxstatusbarinitcolours},
 181 and refreshes the window.
 182
 183 \wxheading{Parameters}
 184
 185 \docparam{event}{The colour change event.}
 186
 187 \wxheading{See also}
 188
 189 \helpref{wxStatusBar::InitColours}{wxstatusbarinitcolours}
 190
 191 \membersection{wxStatusBar::SetFieldsCount}\label{wxstatusbarsetfieldscount}
 192
 193 \func{virtual void}{SetFieldsCount}{\param{int}{ number = 1}, \param{int* }{widths = NULL}}
 194
 195 Sets the number of fields, and optionally the field widths.
 196
 197 \wxheading{Parameters}
 198
 199 \docparam{number}{The number of fields.}
 200
 201 \docparam{widths}{An array of {\it n} integers, each of which is a status field width
 202 in pixels. A value of -1 indicates that the field is variable width; at least one
 203 field must be -1.}
 204
 205 \membersection{wxStatusBar::SetStatusText}\label{wxstatusbarsetstatustext}
 206
 207 \func{virtual void}{SetStatusText}{\param{const wxString\& }{text}, \param{int}{ i = 0}}
 208
 209 Sets the text for one field.
 210
 211 \wxheading{Parameters}
 212
 213 \docparam{text}{The text to be set. Use an empty string (``") to clear the field.}
 214
 215 \docparam{i}{The field to set, starting from zero.}
 216
 217 \wxheading{See also}
 218
 219 \helpref{wxStatusBar::GetStatusText}{wxstatusbargetstatustext}, \helpref{wxFrame::SetStatusText}{wxframesetstatustext}
 220
 221 \membersection{wxStatusBar::SetStatusWidths}\label{wxstatusbarsetstatuswidths}
 222
 223 \func{virtual void}{SetStatusWidths}{\param{int}{ n}, \param{int *}{widths}}
 224
 225 Sets the widths of the fields in the status line.
 226
 227 \wxheading{Parameters}
 228
 229 \docparam{n}{The number of fields in the status bar.}
 230
 231 \docparam{widths}{Must contain an array of {\it n} integers, each of which is a status field width
 232 in pixels. A value of -1 indicates that the field is variable width; at least one
 233 field must be -1. You should delete this array after calling {\bf SetStatusWidths}.}
 234
 235 \wxheading{Remarks}
 236
 237 The widths of the variable fields are calculated from the total width of all fields,
 238 minus the sum of widths of the non-variable fields, divided by the number of
 239 variable fields.
 240
 241 \wxheading{See also}
 242
 243 \helpref{wxStatusBar::SetFieldsCount}{wxstatusbarsetfieldscount}, \helpref{wxFrame::SetStatusWidths}{wxframesetstatuswidths}
 244
 245