fTIMER

Quick Data

Header file:timer.h
Object name:fTIMER
Object index:1 of 1 Object

General Description

Ever want to make tasks happen again and again under Windows, without having to write a function that consumes large amounts of CPU time to constantly check the time? Try the fTIMER - it sends an event every so often (the 'every so often' is set by you).

Now the fTIMER isn't perfect - and it's not my fault. The minimum time that you can set the timer to is 55 milliseconds (18 and a bit times a second). You can specify lower values, but they will be ignored. The actual timings will be to the nearest 55 milliseconds. It's all Windows' fault.

And there is another catch, although it isn't so big this time - the event that makes up the timer is not given the highest priority. As a matter of fact, the timer message is almost always sent to the back of the queue. You'll still get it, though.

Basically what I am saying is that don't rely on the timer for acurate timings. By all means use it - say, for some constantly updating program, update the screen every 500 milliseconds.

Methods

Prototype Description
void SetParameters(UINT Interval, UINT ID, HWND Handle, TIMERPROC TimerProc); This function sets up the time with all the properties that you want - but does not start the timer. Interval is the time (in milliseconds) between each time the timer goes off. ID is an ID for the timer. Handle is the handle to the window that the messages are sent to - if using the GUI controller or handling it manually, just specify your main window. If using the TimerProc, just pass NULL for Handle. TimerProc is a function to be run each time the timer goes off - please see the examples at the end for an example of this.
int GetInterval(void);
int GetID(void);
HWND GetParentHandle(void);
bool IsEnabled(void);
int GetInternalID(void); 		Most of these functions should be self explanatory. They are here in case you forget what you assigned earlier... about the only one that needs explaining is the last one. If the timer calls a function as part of it's operation, then it needs to have an InternalID. Don't worry - this is handled for you, but should you need that ID, this is how to get it.
void Enable(bool Enable); This function starts or stops the timer. Passing TRUE will enable the timer if it is not already running, and passing FALSE will stop the timer if it is not already stopped. Please note that once a timer is activiated, it will keep sending timer events repeatedly (with the specified interval) until stopped.

Events

Please note that the events listed here are done in pairs; one as a property, and the other as a function. The property is assigned a function name, ie. Object.OnClick = &FunctionName, whilst the function is called to verify that an event has occured. Please see the chapter on event handling for information on how to use these correctly.

Prototype Description Sent under
bool CheckThisTimer(wParam);
void (*OnTimer)(fTIMER* Sender); 		This event occurs when the timers interval is up. WM_TIMER

Sample Code

The following snippet gives a basic idea of how to use this component.


//Ok, just create a simple timer...
fTIMER Timer;

Timer.SetParameters(500, TIMER_ID, Window.GetHandle(), NULL);
//The above sets: 500 millisecond intervals, and a window
//as the reciever.

Timer.Enable(TRUE); //Start the timer.

//Now, three ways to intercept the timer event...
//Firstly: the GUI controller:
Timer.OnTimer = &FunctionToCallOnTimer; //Now that was simple!

//Secondly: catching the event manually.
//In the WINDOW PROCEEDURE for the window that you
//specified when setting the parameters for the timer,
//catch this message:
   case WM_TIMER:
        if (Timer.CheckThisTimer(wParam))
           {
           //Then the event occurred!
           } else {
           //The event did not occur!
           }
        break;

//Stop the timer...
Timer.Enable(FALSE);

//Now, the third way: a timer function.
//Let's say that we create a function like this:
void CALLBACK TimerProc(HWND Handle, UINT Message, UINT ID, DWORD SystemTicks)
     {
     //Now Handle is the handle of the window (if you set one).
     //Message is WM_TIMER.
     //ID is the ID of the timer.
     //SystemTicks is the number of milliseconds that Windows
     //has been running (since last time you turned it on
     //or rebooted it - can also be retrieved with the GetSystemTicks()
     //function.
     //Now do something!
     MessageBox(NULL, "Timer activated via function!", "Timer", 0);
     }

//Now how do we reference the function? Like this:
Timer.SetParameters(500, TIMER_ID, NULL, TimerProc);
Timer.Enable(TRUE);

//Now the TimerProc function will be called every 500
//milliseconds! Be sure to include the CALLBACK keyword in
//the function's prototype!

//Last hint: STOP the timer before changing one of it's settings!
Back to indexThe FreeFoote Foundation Classes Documentation