CWinApp::OnIdle

Article
04/28/2015

Override this member function to perform idle-time processing.

virtual BOOL OnIdle( 
   LONG lCount  
);

Parameters

lCount
A counter incremented each time OnIdle is called when the application's message queue is empty. This count is reset to 0 each time a new message is processed. You can use the lCount parameter to determine the relative length of time the application has been idle without processing a message.

Return Value

Nonzero to receive more idle processing time; 0 if no more idle time is needed.

Remarks

OnIdle is called in the default message loop when the application's message queue is empty. Use your override to call your own background idle-handler tasks.

OnIdle should return 0 to indicate that no idle processing time is required. The lCount parameter is incremented each time OnIdle is called when the message queue is empty and resets to 0 each time a new message is processed. You can call your different idle routines based on this count.

The following summarizes idle loop processing:

If the message loop in the Microsoft Foundation Class Library checks the message queue and finds no pending messages, it calls OnIdle for the application object and supplies 0 as the lCount argument.
OnIdle performs some processing and returns a nonzero value to indicate it should be called again to do further processing.
The message loop checks the message queue again. If no messages are pending, it calls OnIdle again, incrementing the lCount argument.
Eventually, OnIdle finishes processing all its idle tasks and returns 0. This tells the message loop to stop calling OnIdle until the next message is received from the message queue, at which point the idle cycle restarts with the argument set to 0.

Do not perform lengthy tasks during OnIdle because your application cannot process user input until OnIdle returns.

Note

The default implementation of OnIdle updates command user-interface objects such as menu items and toolbar buttons, and it performs internal data structure cleanup. Therefore, if you override OnIdle, you must call CWinApp::OnIdle with the lCount in your overridden version. First call all base-class idle processing (that is, until the base class OnIdle returns 0). If you need to perform work before the base-class processing completes, review the base-class implementation to select the proper lCount during which to do your work.

If you do not want OnIdle to be called whenever a message is retrieved from the message queue, you can override the CWinThreadIsIdleMessage. If an application has set a very short timer, or if the system is sending the WM_SYSTIMER message, then OnIdle will be called repeatedly, and degrade performance.

Example

The following two examples show how to use OnIdle. The first example processes two idle tasks using the lCount argument to prioritize the tasks. The first task is high priority, and you should do it whenever possible. The second task is less important and should be done only when there is a long pause in user input. Note the call to the base-class version of OnIdle. The second example manages a group of idle tasks with different priorities.

BOOL CMyApp::OnIdle(LONG lCount)
{
   BOOL bMore = CWinApp::OnIdle(lCount);

   if (lCount == 0)
   {
      TRACE(_T("App idle for short period of time\n"));
      bMore = TRUE;
   }
   else if (lCount == 10)
   {
      TRACE(_T("App idle for longer amount of time\n"));
      bMore = TRUE;
   }
   else if (lCount == 100)
   {
      TRACE(_T("App idle for even longer amount of time\n"));
      bMore = TRUE;
   }
   else if (lCount == 1000)
   {
      TRACE(_T("App idle for quite a long period of time\n"));
      // bMore is not set to TRUE, no longer need idle 
      // IMPORTANT: bMore is not set to FALSE since CWinApp::OnIdle may 
      // have more idle tasks to complete.
   }

   return bMore;
   // return TRUE as long as there are any more idle tasks
}

Second Example

// In this example, four idle loop tasks are given various  
// opportunities to run: 
// Task1 is always given a chance to run during idle time, provided 
//   that no message has queued up while the framework was processing 
//   its own idle loop tasks (at lCount levels 0 and 1). 
// Task2 is given a chance to run only if Task1 has already run, 
//   provided that no message has queued up while Task1 was running. 
// Task3 and Task4 are given a chance to run only if both Task1 and 
//   Task2 have already run, and no message has queued up in the mean 
//   time.  If Task3 gets its chance to run, then Task4 always gets 
//   a chance to run immediately after Task3.

BOOL CMyWinApp::OnIdle(LONG lCount)
{
   // In this example, as in most applications, you should let the 
   // base class CWinApp::OnIdle complete its processing before you 
   // attempt any additional idle loop processing. 
   if (CWinApp::OnIdle(lCount))
      return TRUE;   

   // The base class CWinApp::OnIdle reserves the lCount values 0  
   // and 1 for the framework's own idle processing.   If you wish to 
   // share idle processing time at a peer level with the framework, 
   // then replace the above if-statement with a straight call to 
   // CWinApp::OnIdle; and then add a case statement for lCount value 
   // 0 and/or 1. Study the base class implementation first to  
   // understand how your idle loop tasks will compete with the  
   // framework's idle loop processing. 

   switch (lCount)
   {
      case 2:
         Task1();
         return TRUE; // next time give Task2 a chance 
      case 3:
         Task2();
         return TRUE; // next time give Task3 and Task4 a chance 
      case 4:
         Task3();
         Task4();
         return FALSE; // cycle through the idle loop tasks again
   }
   return TRUE;
}

Requirements

Header: afxwin.h

Partager via