interface/wx/stopwatch.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        stopwatch.h
   3 // Purpose:     interface of wxStopWatch
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxStopWatch
  11
  12     The wxStopWatch class allow you to measure time intervals.
  13
  14     For example, you may use it to measure the time elapsed by some function:
  15
  16     @code
  17         wxStopWatch sw;
  18         CallLongRunningFunction();
  19         wxLogMessage("The long running function took %ldms to execute",
  20                      sw.Time());
  21         sw.Pause();
  22         ... stopwatch is stopped now ...
  23         sw.Resume();
  24         CallLongRunningFunction();
  25         wxLogMessage("And calling it twice took $ldms in all", sw.Time());
  26     @endcode
  27
  28     Since wxWidgets 2.9.3 this class uses @c ::QueryPerformanceCounter()
  29     function under MSW to measure the elapsed time. It provides higher
  30     precision than the usual timer functions but can suffer from bugs in its
  31     implementation in some Windows XP versions. If you encounter such problems,
  32     installing a Microsoft hot fix from http://support.microsoft.com/?id=896256
  33     could be necessary.
  34
  35     @library{wxbase}
  36     @category{misc}
  37
  38     @see wxTimer
  39 */
  40 class wxStopWatch
  41 {
  42 public:
  43     /**
  44         Constructor. This starts the stop watch.
  45     */
  46     wxStopWatch();
  47
  48     /**
  49         Pauses the stop watch. Call Resume() to resume time measuring again.
  50
  51         If this method is called several times, @c Resume() must be called the same
  52         number of times to really resume the stop watch. You may, however, call
  53         Start() to resume it unconditionally.
  54     */
  55     void Pause();
  56
  57     /**
  58         Resumes the stop watch which had been paused with Pause().
  59     */
  60     void Resume();
  61
  62     /**
  63         (Re)starts the stop watch with a given initial value.
  64     */
  65     void Start(long milliseconds = 0);
  66
  67     /**
  68         Returns the time in milliseconds since the start (or restart) or the last
  69         call of Pause().
  70
  71         @see TimeInMicro()
  72     */
  73     long Time() const;
  74
  75     /**
  76         Returns elapsed time in microseconds.
  77
  78         This method is similar to Time() but returns the elapsed time in
  79         microseconds and not milliseconds. Notice that not all platforms really
  80         can measure times with this precision.
  81
  82         @since 2.9.3
  83      */
  84     wxLongLong TimeInMicro() const;
  85 };
  86
  87
  88
  89 // ============================================================================
  90 // Global functions/macros
  91 // ============================================================================
  92
  93 /** @addtogroup group_funcmacro_time */
  94 //@{
  95
  96 /**
  97     Returns the number of seconds since local time 00:00:00 Jan 1st 1970.
  98
  99     @see wxDateTime::Now()
 100
 101     @header{wx/stopwatch.h}
 102 */
 103 long wxGetLocalTime();
 104
 105 /**
 106     Returns the number of milliseconds since local time 00:00:00 Jan 1st 1970.
 107
 108     The use of wxGetUTCTimeMillis() is preferred as it provides a usually
 109     (except for changes to the system time) monotonic clock which the local
 110     time also changes whenever DST begins or ends.
 111
 112     @see wxDateTime::Now(), wxGetUTCTimeMillis(), wxGetUTCTimeUSec()
 113
 114     @header{wx/stopwatch.h}
 115 */
 116 wxLongLong wxGetLocalTimeMillis();
 117
 118 /**
 119     Returns the number of seconds since GMT 00:00:00 Jan 1st 1970.
 120
 121     @see wxDateTime::Now()
 122
 123     @header{wx/stopwatch.h}
 124 */
 125 long wxGetUTCTime();
 126
 127 /**
 128     Returns the number of milliseconds since GMT 00:00:00 Jan 1st 1970.
 129
 130     @since 2.9.3
 131  */
 132 wxLongLong wxGetUTCTimeMillis();
 133
 134 /**
 135     Returns the number of microseconds since GMT 00:00:00 Jan 1st 1970.
 136
 137     @since 2.9.3
 138  */
 139 wxLongLong wxGetUTCTimeUSec();
 140
 141 //@}
 142