michael@0: // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: 
michael@0: // IdleTimer is a recurring Timer which runs only when the system is idle.
michael@0: // System Idle time is defined as not having any user keyboard or mouse
michael@0: // activity for some period of time.  Because the timer is user dependant, it
michael@0: // is possible for the timer to never fire.
michael@0: //
michael@0: // Usage should be for low-priority work, and may look like this:
michael@0: //
michael@0: //   class MyIdleTimer : public IdleTimer {
michael@0: //    public:
michael@0: //     // This timer will run repeatedly after 5 seconds of idle time
michael@0: //     MyIdleTimer() : IdleTimer(TimeDelta::FromSeconds(5), true) {};
michael@0: //     virtual void OnIdle() { do something };
michael@0: //   }
michael@0: //
michael@0: //   MyIdleTimer *timer = new MyIdleTimer();
michael@0: //   timer->Start();
michael@0: //
michael@0: //   // As with all Timers, the caller must dispose the object.
michael@0: //   delete timer;  // Will Stop the timer and cleanup.
michael@0: //
michael@0: // NOTE: An IdleTimer can only be used on a thread that processes UI events.
michael@0: // Such a thread should be running a MessageLoopForUI.
michael@0: 
michael@0: #ifndef BASE_IDLE_TIMER_H_
michael@0: #define BASE_IDLE_TIMER_H_
michael@0: 
michael@0: #if defined(OS_WIN)
michael@0: #include <windows.h>
michael@0: #endif
michael@0: 
michael@0: #include "base/basictypes.h"
michael@0: #include "base/task.h"
michael@0: #include "base/timer.h"
michael@0: 
michael@0: namespace base {
michael@0: 
michael@0: // Function prototype - Get the number of milliseconds that the user has been
michael@0: // idle.
michael@0: typedef bool (*IdleTimeSource)(int32_t *milliseconds_interval_since_last_event);
michael@0: 
michael@0: class IdleTimer {
michael@0:  public:
michael@0:   // Create an IdleTimer.
michael@0:   // idle_time: idle time required before this timer can run.
michael@0:   // repeat: true if the timer should fire multiple times per idle,
michael@0:   //         false to fire once per idle.
michael@0:   IdleTimer(TimeDelta idle_time, bool repeat);
michael@0: 
michael@0:   // On destruction, the IdleTimer will Stop itself.
michael@0:   virtual ~IdleTimer();
michael@0: 
michael@0:   // Start the IdleTimer.
michael@0:   void Start();
michael@0: 
michael@0:   // Stop the IdleTimer.
michael@0:   void Stop();
michael@0: 
michael@0:   // The method to run when the timer elapses.
michael@0:   virtual void OnIdle() = 0;
michael@0: 
michael@0:  protected:
michael@0:   // Override the IdleTimeSource.
michael@0:   void set_idle_time_source(IdleTimeSource idle_time_source) {
michael@0:     idle_time_source_ = idle_time_source;
michael@0:   }
michael@0: 
michael@0:  private:
michael@0:   // Called when timer_ expires.
michael@0:   void Run();
michael@0: 
michael@0:   // Start the timer.
michael@0:   void StartTimer();
michael@0: 
michael@0:   // Gets the number of milliseconds since the last input event.
michael@0:   TimeDelta CurrentIdleTime();
michael@0: 
michael@0:   // Compute time until idle.  Returns 0 if we are now idle.
michael@0:   TimeDelta TimeUntilIdle();
michael@0: 
michael@0:   TimeDelta idle_interval_;
michael@0:   bool repeat_;
michael@0:   Time last_time_fired_;  // The last time the idle timer fired.
michael@0:                           // will be 0 until the timer fires the first time.
michael@0:   OneShotTimer<IdleTimer> timer_;
michael@0: 
michael@0:   IdleTimeSource idle_time_source_;
michael@0: 
michael@0:   DISALLOW_COPY_AND_ASSIGN(IdleTimer);
michael@0: };
michael@0: 
michael@0: }  // namespace base
michael@0: 
michael@0: #endif  // BASE_IDLE_TIMER_H_