TimerQ function

Requires: GfaWinx.lg32

Purpose

Creates a high-resolution multi-media-timer wrapped in a COM object.

Syntax

Set tmrQ = TimerQ([Form | hWnd], [TimerID], [Interval], [Resolution], [TimerProc])

tmrQ	: Object variable
Form	: Form object
TimerID, Interval Resolution, ProcAddr	: integer expression

Description

TimerQ creates a high-resolution multi-media timer with a minimum interval of 1 msec. (The Ocx Timer's shortest interval is approximately 15 msec.) The Form or hWnd parameter specifies the form or window that receives the WM_TIMER message after the time period (Interval) has expired. The TimerID must specify a value to identify the timer and is passed in the wParam of the WM_TIMER message. The Interval parameter can specify the period of timer in milliseconds with a minimum of 1 msec. TimerQ posts a WM_TIMER to the message queue of the specified Form/window and it can be handled in the Form_Message() event sub. The Resolution parameter determines the accuracy of the timer. A value of 0 will provide the highest accuracy, but might also have a negative influence of the performance of the system. By specifying -5 (default) for Resolution the accuracy is set to 5% of the Interval. By specifying the ProcAddr() of a TimerProc the timer's events can be directed to a user supplied procedure instead of being processed using the WM_TIMER message. The signature of the procedure must be:

Proc TmrQProc(uID%, uMsg%, dwUser%, dw1%, dw2%)

The timer is wrapped in an IDispatch COM object and the TimerQ's return value must be stored in an Object variable.

The timer is immediately started if the Interval parameter specifies a valid time and either the Form/hWnd is provided or a procedure address is provided.

Rather than specifying all parameters in the TimerQ() function, the timer's values can be set after creating the object using properties. The object has the following properties:

Enabled	R/W Bool	Returns or sets the running state of the timer. Set to False to stop a running timer or set to True to start a stopped timer.
Interval	R/W Integer	Returns or sets the time interval of the timer. The minimum value is 1 ms. Setting the Interval does not change the Resolution.
Resolution	R/W Integer	Returns or sets the accuracy time of the timer. The minimum value is 0 ms. By setting the Resolution to a negative value the accuracy is specified in a percentage of the Interval setting. E.g. setting Resolution to -5 will set the timer's accuracy to +/- 5% of the Interval. If Interval ia 100 ms, the tick's event will arrive between 95 ms and 105 ms.
TimerProc	R/W Integer	Returns or sets the current TimerProc for the timer. Either set it to an application defined callback procedure or to 0, which resets the TimerProc to the internal procedure that posts WM_TIMER messages to the target Form/window set with hWndTarget.
hWndTarget	R/W Integer	Returns the target window's handle or sets the target window from a Form or window-handle. The target window receives the WM_TIMER messages if ProcAddr == 0, otherwise the TimerProc is executed.
TimerID	R/W Integer	Returns or sets the timer's identifier, the value that is passed in the wParam of the WM_TIMER message.

Example

$Library "gfawinx"

OpenW 1, 0, 0, 600, 500, ~15

PrintScroll = 1 : PrintWrap = 1

Global Object tmrQ1, tmrQ2

Set tmrQ1 = TimerQ(Me, 1, 10) ' create & start timer

Set tmrQ2 = TimerQ() ' create timer

tmrQ2.InterVal = 1000 ' 1 sec

tmrQ2.Resolution = -1 ' +/- 1% of Interval = +/-10 ms

tmrQ2.TimerProc = ProcAddr(TmrQProc)

tmrQ2.Enabled = True ' start timer

Global Int tps

Sleep

Until Me Is Nothing

Sub Win_1_Message(hWnd%, Mess%, wParam%, lParam%)

If Mess% == WM_TIMER

If wParam% == 1 // 10 msec timer

tps++ // increment ticks every 10 msec

Print "."; // do something

EndIf

EndSub

Proc TmrQProc(uID%, uMsg%, dwUser%, dw1%, dw2%)

TitleW 1, "Ticks per second:" + Dec(tps)

tps = 0

EndProc

Remarks

A global Object variable is guaranteed to be released when the program terminates, even when the program stopped with a runtime error. Older versions of TimerQ created a CreateTimerQueueTimer resource; however, due to problems with this method, TimerQ now uses the multi-media timer functions from winmm.dll and sets the system clock to 1 ms.. When the program ends the timer resource(s) must be deleted and the system clock must be restored when all TimerQ objects are freed. By wrapping the creation and releasing in a minimal COM object, the program is guaranteed to free up the resources even when the program failed. See also: here.

TimerQ creates and returns an IDispatch COM object that should be stored in an Object variable. When the program ends, either normally or with an error, the COM object is guaranteed to be released. This will ensure properly release of the acquired resources and will reset the application's timer resolution to the default value. The first TimerQ() call will set the application's timer resolution to 1 ms using timeSetPeriod(). When the last TimerQ object has been released the timeSetPeriod() is called again to reset the timer resolution (to whatever it was before the first TimeSetPeriod call).