docs/latex/wx/gauge.tex

   1 \section{\class{wxGauge}}\label{wxgauge}
   2
   3 A gauge is a horizontal or vertical bar which shows a quantity (often time).
   4
   5 wxGauge supports two working modes: determinate and indeterminate progress.
   6
   7 The first is the usual working mode (see \helpref{SetValue}{wxgaugesetvalue}
   8 and \helpref{SetRange}{wxgaugesetrange}) while the second can be used when
   9 the program is doing some processing but you don't know how much progress is
  10 being done.
  11 In this case, you can periodically call the \helpref{Pulse}{wxgaugepulse}
  12 function to make the progress bar switch to indeterminate mode (graphically
  13 it's usually a set of blocks which move or bounce in the bar control).
  14
  15 wxGauge supports dynamic switch between these two work modes.
  16
  17 There are no user commands for the gauge.
  18
  19 \wxheading{Derived from}
  20
  21 \helpref{wxControl}{wxcontrol}\\
  22 \helpref{wxWindow}{wxwindow}\\
  23 \helpref{wxEvtHandler}{wxevthandler}\\
  24 \helpref{wxObject}{wxobject}
  25
  26 \wxheading{Include files}
  27
  28 <wx/gauge.h>
  29
  30 \wxheading{Library}
  31
  32 \helpref{wxCore}{librarieslist}
  33
  34 \wxheading{Window styles}
  35
  36 \twocolwidtha{5cm}
  37 \begin{twocollist}\itemsep=0pt
  38 \twocolitem{\windowstyle{wxGA\_HORIZONTAL}}{Creates a horizontal gauge.}
  39 \twocolitem{\windowstyle{wxGA\_VERTICAL}}{Creates a vertical gauge.}
  40 %\twocolitem{\windowstyle{wxGA\_PROGRESSBAR}}{Obsolete, doesn't do anything any more}
  41 \twocolitem{\windowstyle{wxGA\_SMOOTH}}{Creates smooth progress bar with one pixel wide update step (not supported by all platforms).}
  42 \end{twocollist}
  43
  44 See also \helpref{window styles overview}{windowstyles}.
  45
  46 \wxheading{Event handling}
  47
  48 wxGauge is read-only so generates no events.
  49
  50 \wxheading{See also}
  51
  52 \helpref{wxSlider}{wxslider}, \helpref{wxScrollBar}{wxscrollbar}
  53
  54 \latexignore{\rtfignore{\wxheading{Members}}}
  55
  56
  57 \membersection{wxGauge::wxGauge}\label{wxgaugector}
  58
  59 \func{}{wxGauge}{\void}
  60
  61 Default constructor.
  62
  63 \func{}{wxGauge}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
  64 \param{int}{ range}, \param{const wxPoint\& }{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
  65 \param{long}{ style = wxGA\_HORIZONTAL}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``gauge"}}
  66
  67 Constructor, creating and showing a gauge.
  68
  69 \wxheading{Parameters}
  70
  71 \docparam{parent}{Window parent.}
  72
  73 \docparam{id}{Window identifier.}
  74
  75 \docparam{range}{Integer range (maximum value) of the gauge. It is ignored when the gauge is used in indeterminate mode.}
  76
  77 \docparam{pos}{Window position.}
  78
  79 \docparam{size}{Window size.}
  80
  81 \docparam{style}{Gauge style. See \helpref{wxGauge}{wxgauge}.}
  82
  83 \docparam{name}{Window name.}
  84
  85 \wxheading{See also}
  86
  87 \helpref{wxGauge::Create}{wxgaugecreate}
  88
  89
  90 \membersection{wxGauge::\destruct{wxGauge}}\label{wxgaugedtor}
  91
  92 \func{}{\destruct{wxGauge}}{\void}
  93
  94 Destructor, destroying the gauge.
  95
  96
  97 \membersection{wxGauge::Create}\label{wxgaugecreate}
  98
  99 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id},\rtfsp
 100 \param{int}{ range}, \param{const wxPoint\& }{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 101 \param{long}{ style = wxGA\_HORIZONTAL}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``gauge"}}
 102
 103 Creates the gauge for two-step construction. See \helpref{wxGauge::wxGauge}{wxgaugector}\rtfsp
 104 for further details.
 105
 106
 107 \membersection{wxGauge::GetBezelFace}\label{wxgaugegetbezelface}
 108
 109 \constfunc{int}{GetBezelFace}{\void}
 110
 111 Returns the width of the 3D bezel face.
 112
 113 \wxheading{Remarks}
 114
 115 This method is not implemented (returns $0$) for most platforms.
 116
 117 \wxheading{See also}
 118
 119 \helpref{wxGauge::SetBezelFace}{wxgaugesetbezelface}
 120
 121
 122 \membersection{wxGauge::GetRange}\label{wxgaugegetrange}
 123
 124 \constfunc{int}{GetRange}{\void}
 125
 126 Returns the maximum position of the gauge.
 127
 128 \wxheading{See also}
 129
 130 \helpref{wxGauge::SetRange}{wxgaugesetrange}
 131
 132
 133 \membersection{wxGauge::GetShadowWidth}\label{wxgaugegetshadowwidth}
 134
 135 \constfunc{int}{GetShadowWidth}{\void}
 136
 137 Returns the 3D shadow margin width.
 138
 139 \wxheading{Remarks}
 140
 141 This method is not implemented (returns $0$) for most platforms.
 142
 143 \wxheading{See also}
 144
 145 \helpref{wxGauge::SetShadowWidth}{wxgaugesetshadowwidth}
 146
 147
 148 \membersection{wxGauge::GetValue}\label{wxgaugegetvalue}
 149
 150 \constfunc{int}{GetValue}{\void}
 151
 152 Returns the current position of the gauge.
 153
 154 \wxheading{See also}
 155
 156 \helpref{wxGauge::SetValue}{wxgaugesetvalue}
 157
 158
 159 \membersection{wxGauge::IsVertical}\label{wxgaugeisvertical}
 160
 161 \constfunc{bool}{IsVertical}{\void}
 162
 163 Returns \true if the gauge is vertical (has \texttt{wxGA\_VERTICAL} style) and
 164 \false otherwise.
 165
 166
 167 \membersection{wxGauge::SetBezelFace}\label{wxgaugesetbezelface}
 168
 169 \func{void}{SetBezelFace}{\param{int }{width}}
 170
 171 Sets the 3D bezel face width.
 172
 173 \wxheading{Remarks}
 174
 175 This method is not implemented (doesn't do anything) for most platforms.
 176
 177 \wxheading{See also}
 178
 179 \helpref{wxGauge::GetBezelFace}{wxgaugegetbezelface}
 180
 181
 182 \membersection{wxGauge::SetRange}\label{wxgaugesetrange}
 183
 184 \func{void}{SetRange}{\param{int }{range}}
 185
 186 Sets the range (maximum value) of the gauge.
 187 This function makes the gauge switch to determinate mode, if it's not already.
 188
 189 \wxheading{See also}
 190
 191 \helpref{wxGauge::GetRange}{wxgaugegetrange}
 192
 193
 194 \membersection{wxGauge::SetShadowWidth}\label{wxgaugesetshadowwidth}
 195
 196 \func{void}{SetShadowWidth}{\param{int }{width}}
 197
 198 Sets the 3D shadow width.
 199
 200 \wxheading{Remarks}
 201
 202 This method is not implemented (doesn't do anything) for most platforms.
 203
 204
 205 \membersection{wxGauge::SetValue}\label{wxgaugesetvalue}
 206
 207 \func{void}{SetValue}{\param{int }{pos}}
 208
 209 Sets the position of the gauge. The \arg{pos} must be between $0$ and the gauge
 210 range as returned by \helpref{GetRange}{wxgaugegetrange}, inclusive.
 211
 212 This function makes the gauge switch to determinate mode, if it was in
 213 indeterminate mode before.
 214
 215 \wxheading{Parameters}
 216
 217 \docparam{pos}{Position for the gauge level.}
 218
 219 \wxheading{See also}
 220
 221 \helpref{wxGauge::GetValue}{wxgaugegetvalue}
 222
 223
 224 \membersection{wxGauge::Pulse}\label{wxgaugepulse}
 225
 226 \func{void}{Pulse}{\void}
 227
 228 Switch the gauge to indeterminate mode (if required) and makes the gauge move
 229 a bit to indicate the user that some progress has been made.
 230
 231 Note that after calling this function the value returned by \helpref{GetValue}{wxgaugegetvalue}
 232 is undefined and thus you need to explicitely call \helpref{SetValue}{wxgaugesetvalue} if you
 233 want to restore the determinate mode.
 234