What is the proper use of WTL CIdleHandler?

I'm trying to learn WTL / Win32 programming, and I don't quite understand the design of the CIdleHandler mixin class.

For WTL 9.1, The CMessageLoop code is as follows (from atlapp.h):

for(;;)
    {
        while(bDoIdle && !::PeekMessage(&m_msg, NULL, 0, 0, PM_NOREMOVE))
        {
            if(!OnIdle(nIdleCount++))
                bDoIdle = FALSE;
        }

        bRet = ::GetMessage(&m_msg, NULL, 0, 0);

        if(bRet == -1)
        {
            ATLTRACE2(atlTraceUI, 0, _T("::GetMessage returned -1 (error)\n"));
            continue;   // error, don't process
        }
        else if(!bRet)
        {
            ATLTRACE2(atlTraceUI, 0, _T("CMessageLoop::Run - exiting\n"));
            break;   // WM_QUIT, exit message loop
        }

        if(!PreTranslateMessage(&m_msg))
        {
            ::TranslateMessage(&m_msg);
            ::DispatchMessage(&m_msg);
        }

        if(IsIdleMessage(&m_msg))
        {
            bDoIdle = TRUE;
            nIdleCount = 0;
        }
    }

The actual call to idle handlers is very straightforward.

// override to change idle processing
virtual BOOL OnIdle(int /*nIdleCount*/)
{
    for(int i = 0; i < m_aIdleHandler.GetSize(); i++)
    {
        CIdleHandler* pIdleHandler = m_aIdleHandler[i];
        if(pIdleHandler != NULL)
            pIdleHandler->OnIdle();
    }
    return FALSE;   // don't continue
}

As is the call to IsIdleMessage

static BOOL IsIdleMessage(MSG* pMsg)
{
    // These messages should NOT cause idle processing
    switch(pMsg->message)
    {
    case WM_MOUSEMOVE:
#ifndef _WIN32_WCE
    case WM_NCMOUSEMOVE:
#endif // !_WIN32_WCE
    case WM_PAINT:
    case 0x0118:    // WM_SYSTIMER (caret blink)
        return FALSE;
    }

    return TRUE;
}

---

My analysis is as follows: it seems like once per "PeekMessage Drought" (a period of time where no messages are sent to the Win32 Application), the OnIdle handlers are called.

But why just once? Wouldn't you want background idle tasks to continuously be called over and over again in the case when PeekMessage ? Furthermore, it seems strange to me that WM_LBUTTONDOWN (User has left-clicked something on the Window) would activate idle processing (bDoIdle = True), but WM_MOUSEMOVE is explicitly called out to prevent reactivation of idle processing.

Can anyone give me the "proper" use scenario of WTL Idle Loops (or more specifically: CIdleHandler)? I guess my expectation was that Idle-processing functions would be small, incremental tasks that take no more than say... 100ms to complete. And then they'd be called repeatedly in the background.

But it seems like this is not the case in WTL. Or maybe I'm not fully understanding Idle loops? Because if I had an incremental background task registered as a CIdleHandler... then if the user stepped away from the window, the task would get run only once! Without any messages pumped into the system (such as WM_LBUTTONDOWN), the bDoIdle variable would remain false for all time!

Does anyone have a good explanation for all this?

As said in the comments, OnIdle handler is supposed to be called when idling starts after certain activity, esp. in order to update UI. This explains "once" calling of the handlers: something happened and then you have a chance to once update the UI elements. If you need ongoing background processing, you are supposed to use timers or worker threads.

WTL samples suggest the use of idle handlers, e.g. in \Samples\Alpha\mainfrm.h.

Window class picks up message loop of the thread and requests idleness updates:

LRESULT OnCreate(UINT /*uMsg*/, WPARAM /*wParam*/, LPARAM /*lParam*/, BOOL& /*bHandled*/)
{
    // ...

    // register object for message filtering and idle updates
    CMessageLoop* pLoop = _Module.GetMessageLoop();
    ATLASSERT(pLoop != NULL);
    pLoop->AddMessageFilter(this);
    pLoop->AddIdleHandler(this);

Later on after message processing and user interaction, the idleness handler updates toolbar to reflect possible state changes:

virtual BOOL OnIdle()
{
    UIUpdateToolBar();
    return FALSE;
}