Reference » Window classes » MWindow » setTimer

Elgrint::MWindow::setTimer(MNum,MNum) method

Declaration (see MWindow.h):

void setTimer(MNum timerID, MNum delay);

Description

Schedules a TimerExpired message after delay milliseconds.

Parameters:

Name Type Description
timerID MNum

Numeric identifier of the timer (unique per window).

Details: Must be in the [0..MaxTimerID] range.

delay MNum

Time in milliseconds after which the timer should expire.

Details: Must be in the [MinTimerDelay..MaxTimerDelay] range, or None, or Same, or Auto.

Details

Every window owns many special devices called timers. Each timer is identified by a numeric ID, which ranges from 0 through MaxTimerID. Each timer is associated with a delay, which is also a number from MinTimerDelay through MaxTimerDelay, or None. The default delay is None, which means that the timer is inactive.

The setTimer function defines a new delay for the timer, whose ID is timerID. However, if delay is Same or Auto, the operation is ignored - the timer retains its previous delay setting (no error). If timerID is greater than MaxTimerID or if delay is greater than MaxTimerDelay (and not equal to None), the function generates exception 2001 and returns immediately. If delay is less than MinTimerDelay, the function generates a one time exception 4001 and sets the delay to MinTimerDelay (not an error). If delay is None, then the timer becomes inactive. The function can also fail with exception 2000 if too many timers are active at the same time (more than the system can handle).

If the function succeeds, the specified timer is now associated with the specified delay. This delay can be returned by getTimerDelay function as long as the timer is active.

Approximately delay milliseconds after setTimer is called, the timer expires, and the window that owns the timer receives a TimerExpired message. During the processing of this message, digTimerID identifies the timer that just expired, and getTimerDelay returns None (the timer is deactivated). The timer is not recycled automatically (see Remarks). To recycle the timer (i.e. to keep generating timer messages at specific intervals) the setTimer must be called again during the TimerExpired message processing. Of course, setTimer can also be called at any moment to change the delay, which immediately resets the timer to the new delay setting (or deactivates the timer if the new delay is None).

The timers are not very accurate time keepers due to the nature of messages, which can wait in the message queue for some time before being processed, so the actual delay between setTimer and OnTimerExpired is usually slightly greater than the specified delay, even though the error is usually too small for a user to notice. However, if the timer is recycled (i.e. setTimer is called in OnTimerExpired), then the error may accumulate over time and can become quite large (this depends more on the system than on the app). In most cases this error is not important and does not affect the user experience, but if the app requires an accurate time keeping, then OnTimerExpired should call C++ clock() or MSys::getDateTime to determine the actual passage of time, instead of relying on the timer delay.

Remarks

Let us know

Please Contact us to report any errors on this page, or to suggest any improvements.

Miranor Home | About Miranor | About Elgrint | Create account | Login | Account settings | Contact Us | Privacy Policy | Site map

© Copyright 2014 by Miranor. All rights reserved. By using this site you agree to the Terms of Use.

Page last updated on August 10th, 2014.