interface/wx/gauge.h

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