Class Documentation

Name:Timer
Version:1.0
ID:ID_TIMER
Status:Beta
Category:System
Date:November 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2001. All rights reserved.
Short:  Provides an activation service at regularly timed intervals..



Description

The Timer class provides developers with a simple mechanism for triggering user defined actions at specific intervals or dates. Once a timer object has been set up, it will send Activate messages to its children whenever a 'trigger' occurs. Depending on your requirements, a trigger can be set to occur at a given interval or a specific time on a certain day.

The Timer class is accurate to 1/1000th of a second, which makes it useful for producing code that needs to run at a high frequency. There are no restrictions on the type of objects that can be placed in a Timer object; but they must be able to support the Activate action in order to respond to time signals.

If you need to reset a timer object so that its delay counter restarts from zero, use the Reset action. If you need a timer object to automatically reset itself in response to user activity, refer to the options available under the Flags field.

Actions

The Timer class supports the following actions:

Reset  Resets a timer object.

Structure

The Timer object consists of the following public fields:

Count  Indicates the total amount of times that a Timer object has been triggered.
Date  Determines a date and/or time at which a Timer object should be triggered.
Delay  The number of seconds to wait between each activation.
Flags  Special flags.
Limit  Places a limit on the total amount of times that activation can occur.
Field:Count
Short:Indicates the total amount of times that a Timer object has been triggered.
Type:LONG
Status:Read

The Count field is incremented each time that a Timer object is triggered. Reading the Count field will give you an accurate indication as to how many times activation has occurred.


Field:Date
Short:Determines a date and/or time at which a Timer object should be triggered.
Type:STRING
Status:Get/Set

The Date allows you to define a trigger that occurs at a specific date, or a set time each day. The allowed formats for the date string are as follows:

  • Day/Month/Year Hour:Min:Sec
  • Hour:Min:Sec

Here are some examples:

  • 24/10/2001 18:05:15
  • 8/5/2002 7:59
  • 8:00
  • 23:12:52

If you set a time value without a specific date, then activation will occur at that time, every day of the week.


Field:Delay
Synonyms:Interval
Short:The number of seconds to wait between each activation.
Type:DOUBLE
Status:Read/Write

If a timer object will be activated at regular intervals, you need to set the Delay field to determine the exact number of seconds between each activation. This field is floating point based, which allows you to specify an interval with an accuracy down to 1/1000th of a second.


Field:Flags
Short:Special flags.
Type:LONG
Status:Read/Set

You can specify flags in this field that will affect the behaviour of a Timer object. Valid flags are:

FlagDescription
RESETKEYPRESS  This flag tells a Timer object to reset its counter whenever a keypress is received.
RESETMOUSEThis flag tells a Timer object to reset its counter whenever the user moves the mouse.
RESETIOIf this flag is set, the timing counter will reset itself when any kind of user activity is detected (keypresses, mouse movement, joyport movement etc).

Field:Limit
Short:Places a limit on the total amount of times that activation can occur.
Type:LONG
Status:Read/Write

The Limit field alllows you to limit the total number of times that a Timer object can be triggered. For instance, if you would like to set an alarm that goes off in 3 minutes without a trigger occurring at 6, 9, 12 minutes or more, then you would set the Limit to a value of 1. Once the limit is met, the Timer object will automatically free itself from the system to prevent it from wasting system resources.

If the Limit is set to zero or less, the feature is turned off.