CWnd::SetTimer

Installs a system timer.

UINT_PTR SetTimer(
   UINT_PTR nIDEvent,
   UINT nElapse,
   void (CALLBACK* lpfnTimer
)(HWND,
   UINT,
   UINT_PTR,
   DWORD
) 
);

Parameters

• nIDEvent
  Specifies a nonzero timer identifier. If the timer identifier is unique, this same value is returned by SetTimer. Otherwise, SetTimer determines a new unique value and returns that. For a window timer (which has a NULL callback function), the value must be unique only for other windows timers that are associated with the current window. For a callback timer, the value must be unique for all timers in all processes. Therefore, when you create a callback timer, it is more likely that the returned value might differ from the value you specify.

• nElapse
  Specifies the time-out value, or interval, in milliseconds.

• lpfnTimer
  Specifies the address of the application-supplied TimerProc callback function that processes the WM_TIMER messages. If this parameter is NULL, the WM_TIMER messages are placed in the message queue of the application and handled by the CWnd object.

Return Value

The timer identifier of the new timer if the function is successful. This value may or may not be equal to the value passed in through the nIDEvent parameter. An application should always pass the return value to the KillTimer member function to kill the timer. Nonzero if successful; otherwise, 0.

Remarks

An interval value is specified, and every time the interval elapses, the system posts a WM_TIMER message to the installing message queue of the installing application or passes the message to an application-defined TimerProc callback function.

The lpfnTimer callback function need not be named TimerProc, but it must be declared as static and defined as follows.

void CALLBACK TimerProc(
   HWND hWnd,      // handle of CWnd that called SetTimer
   UINT nMsg,      // WM_TIMER
   UINT_PTR nIDEvent,   // timer identification
   DWORD dwTime    // system time
);

Example

This example uses CWnd::SetTimer, CWnd::OnTimer, and CWnd::KillTimer to handle WM_TIMER messages. The first timer is set up to send a WM_TIMER message to the main frame window every 2 seconds in OnStartTimer. The OnTimer event handler handles WM_TIMER messages for the main frame window. This method causes the PC speaker to beep every 2 seconds. The second timer sends a message to the callback function every 37.5 seconds. OnStopTimer will stop both timers by calling CWnd::KillTimer for each timer ID.

void CMainFrame::OnStartTimer() 
{
    // This timer uses a WM_TIMER message, not a callback.
    // Therefore, the timer is specific to this window.
    // m_nWindowTimer is a UINT_PTR field.
    m_nWindowTimer = SetTimer(1, 2000, NULL);
    
    // For this demo, we specify an interval that won't overlap
    // with the window timer.
    m_nCallbackTimer = SetTimer(2, 3750, &CMainFrame::MyTimerProc);
    
    // See whether we got the ID we requested in the first parameter.
#ifdef _DEBUG
    CString str;
    str.Format(_T("m_ncallbackTImer ID = %d"), m_nCallbackTimer);
    TRACE(str);
#endif

}

 void CALLBACK CMainFrame::MyTimerProc(
   HWND hWnd,      // handle of CWnd that called SetTimer
   UINT nMsg,      // WM_TIMER
   UINT_PTR nIDEvent,   // timer identification
   DWORD dwTime    // system time
)
{
     MessageBeep(0x00000030L);   // Windows question sound.
}

void CMainFrame::OnStopTimer() 
{
   KillTimer(m_nWindowTimer);   
   KillTimer(m_nCallbackTimer);   
}

void CMainFrame::OnTimer(UINT nIDEvent) 
{
   MessageBeep(0xFFFFFFFF);   // Beep


   // Call base class handler.
   CMDIFrameWnd::OnTimer(nIDEvent);
}

Requirements

Header: afxwin.h

See Also

Reference

CWnd Class

Hierarchy Chart

WM_TIMER

CWnd::KillTimer

SetTimer

Concepts

CWnd Members

Change History

Date	History	Reason
June 2010	Corrected the signature of the callback function to use UINT_PTR for the third parameter. Added an example for a callback timer.	Customer feedback.