SetMode method

Sets the visibility mode of the timer.

Syntax

HRESULT retVal = object.SetMode(dwMode);

Parameters

dwMode [in]

Type: DWORD

A DWORD that contains the visibility mode of the timer.

TIMERMODE_NORMAL (0)

Default. The timer continues to function even when the window is disabled or not visible.

TIMERMODE_VISIBILITYAWARE (1)

The timer is aware of visibility changes and automatically halts when the page is not visible or is loaded into an inactive tab. The timer restarts when the page becomes visible, or the tab becomes active.

Remarks

ITimerEx was introduced in Windows Internet Explorer 7.

Use visibility-aware timers to reduce updates to pages that are displayed in nonvisible windows or inactive tabs.

While visibility-aware timers do not update the appearance of pages displayed in nonvisible windows or inactive tabs, they do expire as expected.

Examples

The following C++ code demonstrates how to create a visibility-aware timer for a Web document.

#include <exdisp.h>
#include <mshtml.h>
#include <ocmm.h>

HRESULT GetTimer(IHTMLDocument2* pDoc, ITimer **ppTimer)
{
    HRESULT hr = S_OK;
    CComPtr<IServiceProvider>   spServiceProvider;
    CComPtr<ITimerService>      spTimerService;

    hr = pDoc->QueryInterface(__uuidof(IServiceProvider),
                              (void **)&spServiceProvider);

    if (FAILED(hr))
    {
        goto Cleanup;
    }

    hr = spServiceProvider->QueryService(__uuidof(ITimerService),
                                         &spTimerService);

    if (FAILED(hr))
    {
        printf("Failed to get ITimerService.\n");
        goto Cleanup;
    }

    hr = spTimerService->CreateTimer(NULL, ppTimer);
    if (SUCCEEDED(hr))
    {
        CComPtr<ITimerEx> spTimerEx;
        hr = (*ppTimer)->QueryInterface(IID_ITimerEx, (void **)&spTimerEx);
        if (SUCCEEDED(hr))
        {
            spTimerEx->SetMode(TIMERMODE_VISIBILITYAWARE);
        }
    }

Cleanup:

    return hr;
}