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
  14     time).
  15
  16     wxGauge supports two working modes: determinate and indeterminate progress.
  17
  18     The first is the usual working mode (see SetValue() and SetRange()) while
  19     the second can be used when the program is doing some processing but you
  20     don't know how much progress is being done. In this case, you can
  21     periodically call the Pulse() function to make the progress bar switch to
  22     indeterminate mode (graphically it's usually a set of blocks which move or
  23     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         Default constructor.
  50     */
  51     wxGauge();
  52     /**
  53         Constructor, creating and showing a gauge.
  54
  55         @param parent
  56             Window parent.
  57         @param id
  58             Window identifier.
  59         @param range
  60             Integer range (maximum value) of the gauge. It is ignored when the
  61             gauge is used in indeterminate mode.
  62         @param pos
  63             Window position.
  64         @param size
  65             Window size.
  66         @param style
  67             Gauge style.
  68         @param name
  69             Window name.
  70
  71         @see Create()
  72     */
  73     wxGauge(wxWindow* parent, wxWindowID id, int range,
  74             const wxPoint& pos = wxDefaultPosition,
  75             const wxSize& size = wxDefaultSize,
  76             long style = wxGA_HORIZONTAL,
  77             const wxValidator& validator = wxDefaultValidator,
  78             const wxString& name = "gauge");
  79
  80     /**
  81         Destructor, destroying the gauge.
  82     */
  83     ~wxGauge();
  84
  85     /**
  86         Creates the gauge for two-step construction. See wxGauge() for further
  87         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() const;
 104
 105     /**
 106         Returns the maximum position of the gauge.
 107
 108         @see SetRange()
 109     */
 110     int GetRange() const;
 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() const;
 120
 121     /**
 122         Returns the current position of the gauge.
 123
 124         @see SetValue()
 125     */
 126     int GetValue() const;
 127
 128     /**
 129         Returns @true if the gauge is vertical (has @c wxGA_VERTICAL style) and
 130         @false otherwise.
 131     */
 132     bool IsVertical() const;
 133
 134     /**
 135         Switch the gauge to indeterminate mode (if required) and makes the
 136         gauge move a bit to indicate the user that some progress has been made.
 137
 138         @note After calling this function the value returned by GetValue() is
 139               undefined and thus you need to explicitely call SetValue() if you
 140               want to restore the determinate mode.
 141     */
 142     void Pulse();
 143
 144     /**
 145         Sets the 3D bezel face width.
 146
 147         @remarks This method is not implemented (doesn't do anything) for most
 148                  platforms.
 149
 150         @see GetBezelFace()
 151     */
 152     void SetBezelFace(int width);
 153
 154     /**
 155         Sets the range (maximum value) of the gauge. This function makes the
 156         gauge switch to determinate mode, if it's not already.
 157
 158         @see GetRange()
 159     */
 160     void SetRange(int range);
 161
 162     /**
 163         Sets the 3D shadow width.
 164
 165         @remarks This method is not implemented (doesn't do anything) for most
 166                  platforms.
 167     */
 168     void SetShadowWidth(int width);
 169
 170     /**
 171         Sets the position of the gauge. The @a pos must be between 0 and the
 172         gauge range as returned by GetRange(), inclusive.
 173
 174         This function makes the gauge switch to determinate mode, if it was in
 175         indeterminate mode before.
 176
 177         @param pos
 178             Position for the gauge level.
 179
 180         @see GetValue()
 181     */
 182     void SetValue(int pos);
 183 };
 184