TTimerList � Documentation
Overview
This component helps you to manage timer driven events without wasting system resources. TTimerList is a
TTimer like component that can maintain a list of nodes each with another predefined event function which can
be executed after a specific start delay time (given in milliseconds) or in a specific interval. Very easy to use.
Resolution is 20 second, no CPU time wasting. Time scheduling in a very easy way.
Requirements
You need Borland C++ Builder (Version 1.0 will do). Sorry, but Delphi will not work because the component is
written entirely in C++. You can use TTimerList with either Window 95 (98)  and NT (4.0, 5.0).
Installation
Copy the files in the installation path
       cls_TimerList.obj
       cls_Timerlist.dcr
       cls_TimerList.h
to the place where you store your VCL classes.
>From inside C++ Builder select menu component and then install. Select cls_TimerList as new component and
then rebuild the library. Done.
Copyright
TTimerList is Shareware. If you have registered you have the permission to use the component in all non
commercial (Shareware, Cardware or something similar) software or package. You may not give this component
to any other person. If you want to use the component in commercial a software package please contact the
author for special conditions and package licenses.
For non-commercial use only:

The price for the component is 50$ (cash only). Delivery is done via email only. Send you registration the
product you want to buy and the cash to the following address:

       Hans-Peter Guenther
       Glockenblumenweg 17
       34128 Kassel
       Germany
You will receive the component as object code and the header as .h file and the documentation in Microsoft
Word and text file format. Also you got an example C++Builder project which demonstrates the use of
TTimerList. You got also free updates and technical support for one year.
Usage
TTimerList includes also the TDutyNode component. This component can be usd at design time to add Duties to
the list. Add a TTimerList and one or more TDutyNodes to your Form. Set up some properties such as
StartDelay or Interval and create event code to the OnReached event of the Node. Set the TimerList property of
the TDutynode to the TimerList of your Form. Done.

Component
TTimerList maintains a list of TDutyNodes. You have full access at any time through the Duty[] property.
Changing properties of a TDutyNode already linked to en TTimerList at runtime will lead to recalculate the start
delay time or interval time.
To use TDutyNodes at run time it is recommented to use instead of creation the TDutynode directly with new()
use the AddDutyXX functions. This has a smaller overhead.


TDutyNode � class documentation

TDutyNode is inherited from TComponent. There are two different ways to use this component, either use it as
component and add it to the form at design time. Set the proper properties. Don�t forget to set the TimerList
property of the DutyNode to the correct TimerList so the Node can be added after the application starts. Done.

Or the second method is to create the TDutyNode at design time. In this case you should not use the new ()
function to create a node. Instead use the method AddDuty() or AddDutyDT() methos from TTimerList. This
will guaranty that the node is corrently initialized and the node is automatically added to the TimerList. See also
the SourceCode of the Demo Application.

Note: If you specify as Options ddoFreeOnReached  the TDutyNode will be deleted after the OnReached event
code has been executed. Any further references (read or write operation) to the old node leads you to an
EAccessError!
To prevent this you should add aother node to the TimerList with AddDuty() and assign the old Node to the
newly created one.
Example:
       void __fastcall DutyNode1Reached(TObject *Sender , TDutyNode *dn)
{ // assuming the DutyNode1�s Options has been set to ddoFreeOnReached
       DoAnythingHere();
       // Note: DutyNode1 will be deleted after this function returns so add another node to the list
       int idx=TimerList1->AddDuty(true,dkOnce,ddoFreeOnReached,0,1000,DutyNode1Reached);
       DutyNode1=TimerList->Duty[idx];         // After the function returns the DutyNode1 points
// to a newly created one and the old will be
// automatically  deleted.
}



Properties:
? Enabled
bool Enabled � this specifies whether or not the TDutyNode should be processed when either
StartDelay time or Interval time has come

? DutyKind
TDutyKinds DutyKind � this specifies the kind of execution.

enum TDutyKinds
{
       dkOnce,
dkInterval
};

dkOnce
the OnReached associated function will be executed only once. This happens when the StartDelay time
has come. After this time the TDutyNode will be disabled or freed if you specify ddoFreeOnReached as
Option

dkInterval
the OnReached function will be called first when the StartDelay time has come and then each time the
interval time is reached.

? DutyOptions
enum TDutyOptions Options � if you set this to ddoFreeOnReached the node will be automatically
deleted the StartDelay time has come. This will only function if the DutyKind property is set to dkOnce

enum TDutyOptions
{
       ddoNone,  // does nothing == default
ddoFreeOnReached // automatically delete node after first execution
};

? StartDelay
long StartDelay � This is the time the DutyNode should call its OnReached event. This value is given in
milliseconds. A value of 0 means start the Node�s evetn as soon as possible.

? Interval
long Interval � this is the Interval time. Each time this Interval has gone the OnReached function will be
called. This does only work with dkInterval Nodes.

? Started
bool Started � if Started is set to true the OnReached event method is currently executed. This could
only happens if the examining task is executed in another thread. The TTimerList is executed only
synchronious! This value will be used by the TTimerList component internally.

? TimerList
TTimerListSuper *TimerList. This should always point to a valid TTimerList. Set his property only at
design time !. At runtime you should add the node either with the Duty[] property of TTimerList or use
the indirect method AddDuty() to create a new Node. The TimerList property will be set by the
TTimerList internally.

Example1:

�.  // i.e. in the FormShow event method
// A TDutyNode1 is putted on the form without the TimerList property set
// This is the method to link the TDutyNode at design time to the TTimerList
TimerList->Duty[TimerList->Count]=DutyNode1;
// because the entry TimerList->Count is not valid, a new node will be added to the end of the list
DutyNode1->Enabled=true; // start the scheduling

Example2:

�.. // i.e in the FormShow event method
// Add new Duty to the list
TimerList->AddDutyDT(true,dkInterval,ddoNone,HHMMSS(12,12,12),SS(2),DoThisOnReached);
// This will add Duty which will be executed today (or next week if the time is past 12:12:12) at
// 12:12:12 and will be periodically called each 2 seconds.

Methods:
? __fastcall TDutyNode(void)
standard VCL constructor. If you want to add a TDutyNode at design time use instead the AddDuty or
AddDutyDT member function of TTimerlist.

Events:
? OnReached
TDutyEvent OnReached � this is the function which should be called when either the StartDelay or the
Interval time is reached.
TDutyEvent is defined as follow:
typedef void __fastcall (__closure *TDutyEvent)(TObject *Sender, TDutyNode *ThisDuty);
You have to supply a TDutyEvent also with the call to the AddDuty() function. See also AddDuty() for an
example how to use this.



TTimerList � class documentation

Properties:

? Enabled
bool Enabled � this specifies whether the TTimerList should schedule Duties or not.

? Count
int Count � Run time and read only. This value returns the number of DutyNodes in the TimerList.

? Resolution
long Resolution � this is the minimum time slit resolution. Adding nodes with a start delay or interval
value smaller than this will be ignored and the Resolution value will be used instead.
Node: Due to the limitation of the VCL Timer Resolution values smaller than 50 (ms) cannot be
realized. A function can at maximum be called 20 times a second!

? Duty[]
TDutyKind *Duty[int Index] � this guaranties full access to any Node in the current Timer queue.
If  you want to add an already created TDutyNode to the list use TTimerList::Duty[TTimerList::Count].
See also TDutyNode.

Methods:
? __fastcall TTimerList(TComponent* Owner);
       standard VCL constructor

?       int __fastcall AddDuty(bool En,TDutyKinds DKind,TDutyOptions DOption, long StD,long
Int, TDutyEvent OnR);
this function adds anew duty to the timerlist. The supplied parameter are equal to the properties of the
newly created TDutyNode. Use this function if you want to add a TDutyNode at run time.
En � TDutyNode->Enabled
DKind � TDutyNode->Kind
DOption � TDutyNode->Options
StD � TDutyNode->StartDelay
Int � TDutyNode->Interval
OnR � TDutyNode->OnReached

?       int __fastcall AddDutyTD(bool En,TDutyKinds DKind,TDutyOptions DOption, long days,long
hours,long minutes,long secs, long msecs, long ddays,long dhours,long dminutes,long dsecs,
long dmsecs, TDutyEvent OnR);
This function is just the same than add duty except that the startdelay and interval values are set here
with a more human way to specify time values.

?       void __fastcall DelDuty(int Index);
This function will try to delete the Duty with Index position in TTimerList.
Note: I will recomment not to delete any Node instead use the Enable property of TDutyNode and
set its value to false. DelDuty should only be called if the TTimerList is currently disabled and no
OnReached event is currently executed.

?     void __fastcall ModifyDuty(int Index,bool En, TDutyOptions DOption, TDutyKinds
Kind,long StD, long Int, TDutyEvent OnR);
With this function you can set all properties of a TDutyNode with one single function call. See also the
notes of the DelDuty() function.

Specials
There are some macros provided with the TTimerList.h file. This is a short overview of the usage.
Most macros can be used to calculate millisecond to minutes, hours or day or vice versa.

DAYOFWEEKNAME provides you with the full english name of the day of week you got as return value from
the TDateTime.DayOfWeek() method. All day references uses as base this DayOfWeek() result where day==0 is
Saturday etc.
MDAY, MHOUR, etc. are functions which calculates the milliseconds per DAY, HOUR etc.

MDHMS(d,h,m,s) is e.g. to define a date and time in milliseconds without the need to calculate this manually.
MDHMS(2,12,30,30) returns the milliseconds for 2 days, 12 hours, 30 minutes and 30 seconds.

xxxOVERFLOW() functions returns a evtl. Overflow between two days, hours etc. if the first argument is larger
then the second.
Use this macros in conjunction with the DAYDIFF, HOURDIFF etc macros.

Author
If you have any questions, suggestions or want to contact me send a message to the following address:
       [email protected]

Visit also my home page at
       http://members.aol.com/hpgue/hpgintl.htm


___

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.