Applying The Recurrence Pattern
- 3 minutes to read
Some user events are recurring – they occur repeatedly (on a regular basis). There are several elements that are used to define how the recurrence is applied to the recurring user event:
The base element that defines the recurrence’s behavior is frequency – the time base used to calculate when the user event repeats – daily, weekly, monthly, or yearly (see the TcxSchedulerCustomRecurrenceInfo.Recurrence property).
The next element is the interval which defines how the recurrence’s frequency is applied: every day, every 2nd…28/29/30th/31st day, every week, every 2nd…53rd/54th week, every month, every nth month, every year, or every nth year. This element is represented by the TcxSchedulerCustomRecurrenceInfo.Periodicity property for a frequency basis of days, weeks and months, by the TcxSchedulerCustomRecurrenceInfo.OccurDays property for specific days in a week for a frequency basis of a week, by the TcxSchedulerCustomRecurrenceInfo.DayNumber property for specific day for monthly frequency basis and by the TcxSchedulerCustomRecurrenceInfo.YearPeriodicity for yearly frequency intervals.
Both of these elements compose the so-called Recurrence pattern, which defines when the user event reoccurs.
There is one more element, which is called the Range of recurrence – it defines the time boundaries/limits of a recurrence. There are three possible scenarios for specifying values for this element:
The Range of recurrence is represented by the start and end time of the recurrence (the TcxSchedulerCustomRecurrenceInfo.Start and TcxSchedulerCustomRecurrenceInfo.Finish properties). This type of range is applied if the value of the TcxSchedulerCustomRecurrenceInfo.Count property is 0.
The Range of recurrence is represented by the number of occurrences that should elapse until the recurrence is no longer in effect. The TcxSchedulerCustomRecurrenceInfo.Count property specifies the number of occurrences if its value is greater than 0.
The Range of recurrence is unbound if the value of the TcxSchedulerCustomRecurrenceInfo.Count property is -1.
The user event’s EventType property plays a key role in specifying the occurrence status. If the specified user event is a parent of a chain of occurrences, assign etPattern to this property. If the details of an occurrence in the chain of reoccurrences are changed, this occurrence will be posted to storage with the EventType property set to etCustom. If the reoccurrence that is spawned from the parent is deleted it will then be saved to storage with the EventType property set to etException.
The following example shows how to apply the Recurrence pattern and the Range of recurrence so as to create a recurring user event.
// ...
with DBStorage.CreateEvent do
begin
ResourceID := 1; // assign the newly created user event to the Lesli Gritts resource. For how to set up a resource in bound mode see the Bound Mode topic
Caption := 'Appointment with a doctor'; // specify the subject
Start := Date + 10 * HourToTime; // the start time of the user event (the HourToTime constant is defined in the cxSchedulerUtils unit)
Duration := 30 * MinuteToTime; // the duration of the user event (the MinuteToTime constant is defined in the cxSchedulerUtils unit)
State := tlsOutOfOffice; // the availability status is "out of office"
EventType := etPattern; // start the series of the occurrences
RecurrenceInfo.Count := 3; // end after three occurrences
RecurrenceInfo.Recurrence := cxreDaily; // the daily basis
RecurrenceInfo.DayType := cxdtWeekDay;
RecurrenceInfo.Periodicity := 1; // repeat every weekday
Post; // synchronize with storage
end;
This is the code execution result:
Note
the output shown is produced when the scheduler’s LookAndFeel.NativeStyle property is set to False, the lfFlat flag on the LookAndFeel.Kind property is active, two resources are defined and the scheduler’s OptionsView.GroupingKind property is set to gkByDate.