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 only known implementation is by SHELL32.DLL for the UserEventTimer object class.

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.