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