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: hpgue@aol.com Visit also my home page at http://members.aol.com/hpgue/hpgintl.htm ___