interface/gauge.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        gauge.h
   3 // Purpose:     documentation for wxGauge class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxGauge
  11     @wxheader{gauge.h}
  12
  13     A gauge is a horizontal or vertical bar which shows a quantity (often time).
  14
  15     wxGauge supports two working modes: determinate and indeterminate progress.
  16
  17     The first is the usual working mode (see wxGauge::SetValue
  18     and wxGauge::SetRange) while the second can be used when
  19     the program is doing some processing but you don't know how much progress is
  20     being done.
  21     In this case, you can periodically call the wxGauge::Pulse
  22     function to make the progress bar switch to indeterminate mode (graphically
  23     it's usually a set of blocks which move or bounce in the bar control).
  24
  25     wxGauge supports dynamic switch between these two work modes.
  26
  27     There are no user commands for the gauge.
  28
  29     @beginStyleTable
  30     @style{wxGA_HORIZONTAL}:
  31            Creates a horizontal gauge.
  32     @style{wxGA_VERTICAL}:
  33            Creates a vertical gauge.
  34     @style{wxGA_SMOOTH}:
  35            Creates smooth progress bar with one pixel wide update step (not
  36            supported by all platforms).
  37     @endStyleTable
  38
  39     @library{wxcore}
  40     @category{ctrl}
  41     @appearance{gauge.png}
  42
  43     @seealso
  44     wxSlider, wxScrollBar
  45 */
  46 class wxGauge : public wxControl
  47 {
  48 public:
  49     //@{
  50     /**
  51         Constructor, creating and showing a gauge.
  52
  53         @param parent
  54         Window parent.
  55
  56         @param id
  57         Window identifier.
  58
  59         @param range
  60         Integer range (maximum value) of the gauge. It is ignored when the gauge is
  61         used in indeterminate mode.
  62
  63         @param pos
  64         Window position.
  65
  66         @param size
  67         Window size.
  68
  69         @param style
  70         Gauge style. See wxGauge.
  71
  72         @param name
  73         Window name.
  74
  75         @sa Create()
  76     */
  77     wxGauge();
  78     wxGauge(wxWindow* parent, wxWindowID id, int range,
  79             const wxPoint& pos = wxDefaultPosition,
  80             const wxSize& size = wxDefaultSize,
  81             long style = wxGA_HORIZONTAL,
  82             const wxValidator& validator = wxDefaultValidator,
  83             const wxString& name = "gauge");
  84     //@}
  85
  86     /**
  87         Destructor, destroying the gauge.
  88     */
  89     ~wxGauge();
  90
  91     /**
  92         Creates the gauge for two-step construction. See wxGauge()
  93         for further details.
  94     */
  95     bool Create(wxWindow* parent, wxWindowID id, int range,
  96                 const wxPoint& pos = wxDefaultPosition,
  97                 const wxSize& size = wxDefaultSize,
  98                 long style = wxGA_HORIZONTAL,
  99                 const wxValidator& validator = wxDefaultValidator,
 100                 const wxString& name = "gauge");
 101
 102     /**
 103         Returns the width of the 3D bezel face.
 104
 105         @remarks This method is not implemented (returns 0) for most platforms.
 106
 107         @sa SetBezelFace()
 108     */
 109     int GetBezelFace();
 110
 111     /**
 112         Returns the maximum position of the gauge.
 113
 114         @sa SetRange()
 115     */
 116     int GetRange();
 117
 118     /**
 119         Returns the 3D shadow margin width.
 120
 121         @remarks This method is not implemented (returns 0) for most platforms.
 122
 123         @sa SetShadowWidth()
 124     */
 125     int GetShadowWidth();
 126
 127     /**
 128         Returns the current position of the gauge.
 129
 130         @sa SetValue()
 131     */
 132     int GetValue();
 133
 134     /**
 135         Returns @true if the gauge is vertical (has @c wxGA_VERTICAL style) and
 136         @false otherwise.
 137     */
 138     bool IsVertical();
 139
 140     /**
 141         Switch the gauge to indeterminate mode (if required) and makes the gauge move
 142         a bit to indicate the user that some progress has been made.
 143
 144         Note that after calling this function the value returned by GetValue()
 145         is undefined and thus you need to explicitely call SetValue() if you
 146         want to restore the determinate mode.
 147     */
 148     void Pulse();
 149
 150     /**
 151         Sets the 3D bezel face width.
 152
 153         @remarks This method is not implemented (doesn't do anything) for most
 154                    platforms.
 155
 156         @sa GetBezelFace()
 157     */
 158     void SetBezelFace(int width);
 159
 160     /**
 161         Sets the range (maximum value) of the gauge.
 162         This function makes the gauge switch to determinate mode, if it's not already.
 163
 164         @sa GetRange()
 165     */
 166     void SetRange(int range);
 167
 168     /**
 169         Sets the 3D shadow width.
 170
 171         @remarks This method is not implemented (doesn't do anything) for most
 172                    platforms.
 173     */
 174     void SetShadowWidth(int width);
 175
 176     /**
 177         Sets the position of the gauge. The @e pos must be between 0 and the gauge
 178         range as returned by GetRange(), inclusive.
 179
 180         This function makes the gauge switch to determinate mode, if it was in
 181         indeterminate mode before.
 182
 183         @param pos
 184         Position for the gauge level.
 185
 186         @sa GetValue()
 187     */
 188     void SetValue(int pos);
 189 };