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         @param id
  56             Window identifier.
  57         @param range
  58             Integer range (maximum value) of the gauge. It is ignored when the gauge is
  59         used in indeterminate mode.
  60         @param pos
  61             Window position.
  62         @param size
  63             Window size.
  64         @param style
  65             Gauge style. See wxGauge.
  66         @param name
  67             Window name.
  68
  69         @see Create()
  70     */
  71     wxGauge();
  72     wxGauge(wxWindow* parent, wxWindowID id, int range,
  73             const wxPoint& pos = wxDefaultPosition,
  74             const wxSize& size = wxDefaultSize,
  75             long style = wxGA_HORIZONTAL,
  76             const wxValidator& validator = wxDefaultValidator,
  77             const wxString& name = "gauge");
  78     //@}
  79
  80     /**
  81         Destructor, destroying the gauge.
  82     */
  83     ~wxGauge();
  84
  85     /**
  86         Creates the gauge for two-step construction. See wxGauge()
  87         for further details.
  88     */
  89     bool Create(wxWindow* parent, wxWindowID id, int range,
  90                 const wxPoint& pos = wxDefaultPosition,
  91                 const wxSize& size = wxDefaultSize,
  92                 long style = wxGA_HORIZONTAL,
  93                 const wxValidator& validator = wxDefaultValidator,
  94                 const wxString& name = "gauge");
  95
  96     /**
  97         Returns the width of the 3D bezel face.
  98
  99         @remarks This method is not implemented (returns 0) for most platforms.
 100
 101         @see SetBezelFace()
 102     */
 103     int GetBezelFace();
 104
 105     /**
 106         Returns the maximum position of the gauge.
 107
 108         @see SetRange()
 109     */
 110     int GetRange();
 111
 112     /**
 113         Returns the 3D shadow margin width.
 114
 115         @remarks This method is not implemented (returns 0) for most platforms.
 116
 117         @see SetShadowWidth()
 118     */
 119     int GetShadowWidth();
 120
 121     /**
 122         Returns the current position of the gauge.
 123
 124         @see SetValue()
 125     */
 126     int GetValue();
 127
 128     /**
 129         Returns @true if the gauge is vertical (has @c wxGA_VERTICAL style) and
 130         @false otherwise.
 131     */
 132     bool IsVertical();
 133
 134     /**
 135         Switch the gauge to indeterminate mode (if required) and makes the gauge move
 136         a bit to indicate the user that some progress has been made.
 137         Note that after calling this function the value returned by GetValue()
 138         is undefined and thus you need to explicitely call SetValue() if you
 139         want to restore the determinate mode.
 140     */
 141     void Pulse();
 142
 143     /**
 144         Sets the 3D bezel face width.
 145
 146         @remarks This method is not implemented (doesn't do anything) for most
 147                  platforms.
 148
 149         @see GetBezelFace()
 150     */
 151     void SetBezelFace(int width);
 152
 153     /**
 154         Sets the range (maximum value) of the gauge.
 155         This function makes the gauge switch to determinate mode, if it's not already.
 156
 157         @see GetRange()
 158     */
 159     void SetRange(int range);
 160
 161     /**
 162         Sets the 3D shadow width.
 163
 164         @remarks This method is not implemented (doesn't do anything) for most
 165                  platforms.
 166     */
 167     void SetShadowWidth(int width);
 168
 169     /**
 170         Sets the position of the gauge. The @a pos must be between 0 and the gauge
 171         range as returned by GetRange(), inclusive.
 172         This function makes the gauge switch to determinate mode, if it was in
 173         indeterminate mode before.
 174
 175         @param pos
 176             Position for the gauge level.
 177
 178         @see GetValue()
 179     */
 180     void SetValue(int pos);
 181 };