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