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