interface/gauge.h

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