interface/wx/gauge.h

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