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