fix LaTeX error (escape underscores); don't abuse bold face

[wxWidgets.git] / docs / latex / wx / gauge.tex

diff --git a/docs/latex/wx/gauge.tex b/docs/latex/wx/gauge.tex
index d615f8ec88f4055e22572b00fe462b66fa7894cb..ddef4738dbb67246005526a1c808ad640cad4509 100644 (file)
--- a/docs/latex/wx/gauge.tex
+++ b/docs/latex/wx/gauge.tex
@@ -1,6 +1,19 @@
 \section{\class{wxGauge}}\label{wxgauge}
 
 A gauge is a horizontal or vertical bar which shows a quantity (often time).
+
+wxGauge supports two working modes: determinate and indeterminate progress.
+
+The first is the usual working mode (see \helpref{SetValue}{wxgaugesetvalue}
+and \helpref{SetRange}{wxgaugesetrange}) while the second can be used when
+the program is doing some processing but you don't know how much progress is
+being done.
+In this case, you can periodically call the \helpref{Pulse}{wxgaugepulse}
+function to make the progress bar switch to indeterminate mode (graphically
+it's usually a set of blocks which move or bounce in the bar control).
+
+wxGauge supports dynamic switch between these two work modes.
+
 There are no user commands for the gauge.
 
 \wxheading{Derived from}
@@ -14,6 +27,10 @@ There are no user commands for the gauge.
 
 <wx/gauge.h>
 
+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+
 \wxheading{Window styles}
 
 \twocolwidtha{5cm}
@@ -37,7 +54,7 @@ wxGauge is read-only so generates no events.
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 
-\membersection{wxGauge::wxGauge}\label{wxgaugeconstr}
+\membersection{wxGauge::wxGauge}\label{wxgaugector}
 
 \func{}{wxGauge}{\void}
 
@@ -55,7 +72,7 @@ Constructor, creating and showing a gauge.
 
 \docparam{id}{Window identifier.}
 
-\docparam{range}{Integer range (maximum value) of the gauge.}
+\docparam{range}{Integer range (maximum value) of the gauge. It is ignored when the gauge is used in indeterminate mode.}
 
 \docparam{pos}{Window position.}
 
@@ -70,7 +87,7 @@ Constructor, creating and showing a gauge.
 \helpref{wxGauge::Create}{wxgaugecreate}
 
 
-\membersection{wxGauge::\destruct{wxGauge}}
+\membersection{wxGauge::\destruct{wxGauge}}\label{wxgaugedtor}
 
 \func{}{\destruct{wxGauge}}{\void}
 
@@ -83,7 +100,7 @@ Destructor, destroying the gauge.
 \param{int}{ range}, \param{const wxPoint\& }{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp
 \param{long}{ style = wxGA\_HORIZONTAL}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``gauge"}}
 
-Creates the gauge for two-step construction. See \helpref{wxGauge::wxGauge}{wxgaugeconstr}\rtfsp
+Creates the gauge for two-step construction. See \helpref{wxGauge::wxGauge}{wxgaugector}\rtfsp
 for further details.
 
 
@@ -108,10 +125,6 @@ This method is not implemented (returns $0$) for most platforms.
 
 Returns the maximum position of the gauge.
 
-\wxheading{Remarks}
-
-This method is not implemented (doesn't do anything) for most platforms.
-
 \wxheading{See also}
 
 \helpref{wxGauge::SetRange}{wxgaugesetrange}
@@ -171,6 +184,7 @@ This method is not implemented (doesn't do anything) for most platforms.
 \func{void}{SetRange}{\param{int }{range}}
 
 Sets the range (maximum value) of the gauge.
+This function makes the gauge switch to determinate mode, if it's not already.
 
 \wxheading{See also}
 
@@ -192,7 +206,11 @@ This method is not implemented (doesn't do anything) for most platforms.
 
 \func{void}{SetValue}{\param{int }{pos}}
 
-Sets the position of the gauge.
+Sets the position of the gauge. The \arg{pos} must be between $0$ and the gauge
+range as returned by \helpref{GetRange}{wxgaugegetrange}, inclusive.
+
+This function makes the gauge switch to determinate mode, if it was in
+indeterminate mode before.
 
 \wxheading{Parameters}
 
@@ -203,3 +221,14 @@ Sets the position of the gauge.
 \helpref{wxGauge::GetValue}{wxgaugegetvalue}
 
 
+\membersection{wxGauge::Pulse}\label{wxgaugepulse}
+
+\func{void}{Pulse}{\void}
+
+Switch the gauge to indeterminate mode (if required) and makes the gauge move
+a bit to indicate the user that some progress has been made.
+
+Note that after calling this function the value returned by \helpref{GetValue}{wxgaugegetvalue}
+is undefined and thus you need to explicitely call \helpref{SetValue}{wxgaugesetvalue} if you
+want to restore the determinate mode.
+