IUserEventTimer

The IUserEventTimer interface exposes a timing facility whose special feature is to disregard intervals during which there have been no user input events.

The IUserEventTimer methods, in order of their appearance in the virtual function table after the three IUnknown methods, are:

The functionality of these user event timers is broadly similar to the window timers that are created and destroyed by the standard API functions SetTimer and KillTimer. In general, each user event timer is described by the pairing of a window handle and an identifier, and the timer’s expiry is communicated by posting a message to the window, with the identifier as reference data. As far as concerns the interface, the key differences are just that the message number is configurable and that the choice of identifier can be left to the implementation.

A user event timer is started by calling the SetUserEventTimer method, to specify a window and optionally a window-relative identifier, plus the desired timeout and a message number for notification of the timeout’s expiry. Provision exists also for notification via a callback function. The timeout triggers recurringly until the timer is destroyed by calling the KillUserEventTimer method. The GetUserEventTimerElapsed method is available for polling the timer rather than waiting for a notification, and is perhaps intended primarily for gauging the discrepancy between actual time and user-active time. Remember always that the time measured by user event timers is time during which there has been user input. How they do this is essentially an implementation detail, but one aspect which has practical consequences is configurable, via the InitTimerTickInterval method.

The only known implementation is by SHELL32.DLL for the UserEventTimer class.

Availability

The IUserEventTimer interface is implemented in SHELL32.DLL version 6.00 and higher.

The interface seems never to have been documented, but is declared in the SHOBJIDL.IDL (and thus also SHOBJIDL.H) from the Platform SDK dated February 2003. This declaration may have been an oversight: it is removed from the Windows Vista SDK dated January 2007.