Windows api set timer

Функция SetTimer создает таймер с указанным значением времени простоя.

Синтаксис

Параметры

[in] Дескриптор окна, которое связано с таймером. Это окно должно быть собственностью вызывающего потока. Если этот параметр NULL, никакое окно не связано с таймером, а параметр nIDEIvent игнорируется.

[in] Указывает идентификатор таймера отличный от нуля. Если параметр hWnd — NULL, этот параметр игнорируется. Если параметр hWnd — не NULL, и у окна, указанного hWnd уже есть таймер со значением nIDEvent, то существующий таймер заменяется новым таймером. Когда SetTimer заменяет таймер, то таймер возвращается в исходное положение. Поэтому, сообщение должно отправляться после того, как текущее значение времени простоя истекает, а раньше установленное значение времени простоя игнорируется.

[in] Указывает значение времени простоя, в миллисекундах.

Windows NT/2000/XP: Если uElapse больше, чем USER_TIMER_MAXIMUM , блокировка по времени устанавливается в 1.

Windows 2000/XP: Если uElapse меньше, чем USER_TIMER_MINIMUM , блокировка по времени устанавливается в USER_TIMER_MINIMUM .

Windows Server 2003: Если uElapse больше, чем USER_TIMER_MAXIMUM , блокировка по времени устанавливается в USER_TIMER_MAXIMUM .

Windows XP SP2/Windows Server 2003 SP1: Если uElapse меньше, чем USER_TIMER_MINIMUM , блокировка по времени устанавливается в USER_TIMER_MINIMUM . Если uElapse больше, чем USER_TIMER_MAXIMUM , блокировка по времени устанавливается в USER_TIMER_MAXIMUM .

[in] Указатель на функцию, которая уведомляет, когда значение времени простоя истекает. Для получения дополнительной информации о функции, см. описание TimerProc. Если параметр lpTimerFunc — NULL, система помещает уведомление WM_TIMER в очередь прикладной программы. Член hwnd структуры MSG содержит в себе значение параметра hWnd.

Возвращаемое значение

Если функция завершается успешно, а параметр hWnd — NULL, возвращаемое значение — целое число, идентифицирующее новый таймер. Приложение может передать это значение в функцию KillTimer, чтобы уничтожить таймер.

Если функция завершается успешно, а hWnd параметр — не NULL, тогда возвращаемое значение — целое число отличное от нуля. Приложение может передать значение параметра nIDEvent в функцию KillTimer, чтобы уничтожить таймер.

Если при создании таймера функция завершается ошибкой, возвращаемое значение — нуль. Чтобы получить дополнительную информацию об ошибке, вызовите GetLastError.

Замечания

Приложение может обработать сообщения WM_TIMER включением оператора выбора WM_TIMER в оконной процедуре или указывая функцию обратного вызова TimerProc, когда создается таймер. Когда Вы указываете функцию обратного вызова TimerProc, оконная процедура по умолчанию вызывает функцию обратного вызова, когда он обрабатывает WM_TIMER. Поэтому, Вы должны распределить сообщения в вызывающем потоке, даже тогда, когда Вы используете TimerProc вместо того, чтобы обработать WM_TIMER обычным путем.

Параметр wParam сообщения WM_TIMER содержит значение параметра nIDEvent.

Идентификатор таймера nIDEvent, указывается связанным окном. Другое окно может иметь свой собственный таймер, у которого есть тот же самый идентификатор что и таймер, собственность другого окна. Таймеры индивидуальны.

SetTimer может многократно использовать идентификаторы (ID) таймера в случае, где hWnd — NULL.

Windows api set timer

Кроме функций перечисления, требующих в процессе своей работы вызов Callback функций, другим известным примером является функция SetTimer , создающая таймер. Во многих приложениях возникает необходимость синхронизировать его работу в соответствии с регулярно поступающими сообщениями от таймера. Общая схема такова: таймер посылает сообщения приложению с заданным интервалом, в ответ приложение выполняет определенную работу, вызывая ту или иную функцию ( Callback функцию). Класс таких диспетчерских приложений, регулярно обрабатывающих вновь поступившие заявки, весьма велик. При работе в приложении Access для этих целей введен специальный элемент управления — Timer . В приложениях Word или Excel такого элемента нет, но всегда можно воспользоваться соответствующими функциями Win32 API, чтобы создать один или несколько собственных таймеров и организовать работу приложения, реагирующего на их сообщения. Заметьте, несмотря на то, что физический таймер один, логических таймеров, посылающих приложению свои сообщения, может быть несколько.

Функция SetTimer

Эта функция создает таймер, посылающий сообщения с заданным интервалом. Ее описание, которое можно найти на Platform SDK, имеет вид:

Ее параметры:

• hwnd — Описатель окна, которому будут посылаться сообщения таймера. В VBA программах таймер не связывается с окном и значение этого параметр задается как NULL .
• nIDEvent — Задает идентификатор таймера. Его значение игнорируется, когда таймер не связан с окном, что имеет место в рассматриваемом нами случае.
• uElapse — Задает интервал, с которым таймер будет посылать свои сообщения. Интервал задается в миллисекундах, так что значение 1000 соответствует одной секунде.
• lpTimerFunc — Указатель на Callback функцию, которая будет вызываться всякий раз, когда обрабатывается сообщение WM_Timer , поступающее от таймера.

Если функция успешно завершает свою работу и создает таймер, то в качестве результата она возвращает уникальный идентификатор этого таймера, идентифицирующий его. Этот идентификатор запоминается и используется для уничтожения таймера при вызове Win32 API функции KillTimer . В случае неуспеха возвращается значение 0 .

Заметьте, функция SetTimer только создает таймер. В отличие от функций перечисления вызов Callback функции не происходит в ее теле. Вызов осуществляется более сложным путем. Созданный таймер посылает сообщения с заданным интервалом, сообщения, как обычно, поступают в очередь сообщений и в обработчике сообщения WM_Timer автоматически вызывается функция обратного вызова. Поскольку при обработке сообщений очереди могут происходить разные задержки, то вызываемая функция не всегда будет вызываться с заданным интервалом, — возможны задержки.

Оператор Declare , задающий VBA описание этой функции имеет соответственно вид:

Функция обратного вызова TimerProc

Функция TimerProc является Callback функцией, определенной приложением и вызываемой при обработке сообщений, поступающих от таймера. Ее определение имеет вид:

Ее параметры:

• hwnd — Описатель окна.
• uMsg — Указывает WM_Timer сообщение.
• idEvent — Идентификатор таймера.
• dwTime — Задает текущее системное время, возвращаемое функцией GetTickCount .

Заметьте, имя TimerProc является лишь держателем места. В конкретной ситуации необходимо будет определить одну или несколько Callback функций с подходящими именами. Поскольку вызов каждой из этих функций производится автоматически, то нет необходимости заботиться о корректной передаче аргументов в момент вызова. Необходимо лишь позаботиться о корректной трансляции приведенного определения, взятого из справочной системы Platform SDK, к виду, воспринимаемому в программах на VBA. Вот как выглядит возможное определение:

Обратите внимание, мы транслировали функцию в процедуру, поскольку Callback функция TimerProc не возвращает значения. Все типы данных преобразованы в тип Long , в том числе UINT и DWORD . В данной ситуации нет причин для беспокойства о возможной некорректности передаваемых значений, поскольку их передачу обеспечивает сама система.

Функция KillTimer

Поскольку одновременно могут существовать несколько таймеров, также как и при необходимости заменить один таймер другим, — по разным причинам возникает необходимость удаления уже не нужных таймеров. Для этого и используется функция Win32 API KillTimer . Вот ее стандартное описание:

Ее параметры:

• hwnd — Описатель окна, ассоциированного с таймером, совпадающий по значению с соответствующим параметром функции SetTimer . Напомним, в VBA программах таймер не связывается с окном и значение этого параметр задается как NULL .
• nIDEvent — Задает идентификатор таймера, который должен быть удален. В нашем случае, когда первый параметр равен NULL , его значение задается идентификатором, возвращенным в качестве результата по окончании работы функции SetTimer .

Если функция успешно завершает свою работу и удаляет таймер, то в качестве результата она возвращает ненулевое значение. В случае неуспеха возвращается значение 0 .

Пример создания, работы и удаления таймера

В свое время в книге по языку Visual C++ , демонстрируя работу с таймером и соответствующими функциями Win32 API, мы разработали проект » Жизнь «. В этом проекте моделируется известная компьютерная игра, где можно задать начальную конфигурацию «жизни». Затем эта конфигурация начинает жить, изменяя свое состояние по заданным правилам. Изменение состояния происходит в качестве ответной реакции на сообщения таймера. Другим подобным примером, по существу вариацией на эту же тему, является создание экранных заставок. Сейчас мы решили обойтись более простым примером, демонстрирующим суть проблемы, но не имеющим эффектной формы. В нашем тестовом примере есть две командные кнопки Start и Finish . В ответ на нажатие первой кнопки создается таймер, соответствующая ему Callback функция ведет подсчет числа ее вызов и уведомляет об этом, печатая значение счетчика в окне отладки. При нажатии кнопки Finish таймер удаляется. Кнопки можно нажимать многократно. Все процедуры обработки помещены в модуль Таймер . Вот его текст:

Комментариев, приведенных в тексте, полагаем достаточно для понимания всех деталей. Приведем еще результаты печати, периодически появляющиеся в окне отладки. Следует только сказать, что дважды были поочередно нажаты кнопки Start и Finish :

Заметьте, в нашей реализации кнопки нужно нажимать поочередно, поскольку хранится только последнее значение идентификатора таймера, так что если подряд нажать несколько раз кнопку Start , то будет создано несколько таймеров, но при последующих нескольких нажатиях кнопки Finish будет удален только один, последний созданный таймер и печать в окне отладки будет продолжаться.

SetTimer function (winuser.h)

Creates a timer with the specified time-out value.

Syntax

Parameters

A handle to the window to be associated with the timer. This window must be owned by the calling thread. If a NULL value for hWnd is passed in along with an nIDEvent of an existing timer, that timer will be replaced in the same way that an existing non-NULL hWnd timer will be.

A nonzero timer identifier. If the hWnd parameter is NULL, and the nIDEvent does not match an existing timer then it is ignored and a new timer ID is generated. If the hWnd parameter is not NULL and the window specified by hWnd already has a timer with the value nIDEvent, then the existing timer is replaced by the new timer. When SetTimer replaces a timer, the timer is reset. Therefore, a message will be sent after the current time-out value elapses, but the previously set time-out value is ignored. If the call is not intended to replace an existing timer, nIDEvent should be 0 if the hWnd is NULL.

The time-out value, in milliseconds.

If uElapse is less than USER_TIMER_MINIMUM (0x0000000A), the timeout is set to USER_TIMER_MINIMUM. If uElapse is greater than USER_TIMER_MAXIMUM (0x7FFFFFFF), the timeout is set to USER_TIMER_MAXIMUM.

A pointer to the function to be notified when the time-out value elapses. For more information about the function, see TimerProc. If lpTimerFunc is NULL, the system posts a WM_TIMER message to the application queue. The hwnd member of the message’s MSG structure contains the value of the hWnd parameter.

Return value

If the function succeeds and the hWnd parameter is NULL, the return value is an integer identifying the new timer. An application can pass this value to the KillTimer function to destroy the timer.

If the function succeeds and the hWnd parameter is not NULL, then the return value is a nonzero integer. An application can pass the value of the nIDEvent parameter to the KillTimer function to destroy the timer.

If the function fails to create a timer, the return value is zero. To get extended error information, call GetLastError.

Remarks

An application can process WM_TIMER messages by including a WM_TIMER case statement in the window procedure or by specifying a TimerProc callback function when creating the timer. When you specify a TimerProc callback function, the default window procedure calls the callback function when it processes WM_TIMER. Therefore, you need to dispatch messages in the calling thread, even when you use TimerProc instead of processing WM_TIMER.

The wParam parameter of the WM_TIMER message contains the value of the nIDEvent parameter.

The timer identifier, nIDEvent, is specific to the associated window. Another window can have its own timer which has the same identifier as a timer owned by another window. The timers are distinct.

SetTimer can reuse timer IDs in the case where hWnd is NULL.

Using Timers

This topic shows how to create and destroy timers, and how to use a timer to trap mouse input at specified intervals.

This topic contains the following sections.

Creating a Timer

The following example uses the SetTimer function to create two timers. The first timer is set for every 10 seconds, the second for every five minutes.

To process the WM_TIMER messages generated by these timers, add a WM_TIMER case statement to the window procedure for the hwnd parameter.

An application can also create a timer whose WM_TIMER messages are processed not by the main window procedure but by an application-defined callback function, as in the following code sample, which creates a timer and uses the callback function MyTimerProc to process the timer’s WM_TIMER messages.

The calling convention for MyTimerProc must be based on the TimerProc callback function.

If your application creates a timer without specifying a window handle, your application must monitor the message queue for WM_TIMER messages and dispatch them to the appropriate window.

Destroying a Timer

Applications should use the KillTimer function to destroy timers that are no longer necessary. The following example destroys the timers identified by the constants IDT_TIMER1, IDT_TIMER2, and IDT_TIMER3.

Using Timer Functions to Trap Mouse Input

Sometimes it is necessary to prevent more input while you have a mouse pointer on the screen. One way to accomplish this is to create a special routine that traps mouse input until a specific event occurs. Many developers refer to this routine as «building a mousetrap.»

The following example uses the SetTimer and KillTimer functions to trap mouse input. SetTimer creates a timer that sends a WM_TIMER message every 10 seconds. Each time the application receives a WM_TIMER message, it records the mouse pointer location. If the current location is the same as the previous location and the application’s main window is minimized, the application moves the mouse pointer to the icon. When the application closes, KillTimer stops the timer.

Although the following example also shows you how to trap mouse input, it processes the WM_TIMER message through the application-defined callback function MyTimerProc, rather than through the application’s message queue.