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 license
   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         Constructor, creating and showing a gauge.
  53
  54         @param parent
  55             Window parent.
  56         @param id
  57             Window identifier.
  58         @param range
  59             Integer range (maximum value) of the gauge. It is ignored when the
  60             gauge is used in indeterminate mode.
  61         @param pos
  62             Window position.
  63         @param size
  64             Window size.
  65         @param style
  66             Gauge style.
  67         @param name
  68             Window name.
  69
  70         @see Create()
  71     */
  72     wxGauge(wxWindow* parent, wxWindowID id, int range,
  73             const wxPoint& pos = wxDefaultPosition,
  74             const wxSize& size = wxDefaultSize,
  75             long style = wxGA_HORIZONTAL,
  76             const wxValidator& validator = wxDefaultValidator,
  77             const wxString& name = "gauge");
  78
  79     /**
  80         Destructor, destroying the gauge.
  81     */
  82     ~wxGauge();
  83
  84     /**
  85         Creates the gauge for two-step construction. See wxGauge() for further
  86         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
 135         gauge move a bit to indicate the user that some progress has been made.
 136
 137         @note After calling this function the value returned by GetValue() is
 138               undefined and thus you need to explicitely call SetValue() if you
 139               want to restore the determinate mode.
 140     */
 141     void Pulse();
 142
 143     /**
 144         Sets the 3D bezel face width.
 145
 146         @remarks This method is not implemented (doesn't do anything) for most
 147                  platforms.
 148
 149         @see GetBezelFace()
 150     */
 151     void SetBezelFace(int width);
 152
 153     /**
 154         Sets the range (maximum value) of the gauge. This function makes the
 155         gauge switch to determinate mode, if it's not already.
 156
 157         @see GetRange()
 158     */
 159     void SetRange(int range);
 160
 161     /**
 162         Sets the 3D shadow width.
 163
 164         @remarks This method is not implemented (doesn't do anything) for most
 165                  platforms.
 166     */
 167     void SetShadowWidth(int width);
 168
 169     /**
 170         Sets the position of the gauge. The @a pos must be between 0 and the
 171         gauge range as returned by GetRange(), inclusive.
 172
 173         This function makes the gauge switch to determinate mode, if it was in
 174         indeterminate mode before.
 175
 176         @param pos
 177             Position for the gauge level.
 178
 179         @see GetValue()
 180     */
 181     void SetValue(int pos);
 182 };
 183