RecurrencePattern
RadScheduleView includes support for recurring events on daily, weekly, monthly and yearly basis. Exceptions to the recurrence rules are also permitted. To support this recurrence behavior, the IAppointment interface includes the RecurrenceRule property. When an appointment is promoted into a recurring event its RecurrenceRule is set with correct RecurrencePattern.
The RecurrenceRule class is the engine for creating and evaluating recurrence rules. It has a mandatory property Pattern of type RecurrencePattern.
The purpose of this tutorial is to show you:
-
The main properties exposed by the RecurrencePattern class:
-
The main methods exposed by the RecurrencePattern class:
-
Examples - show you how to combine the exposed by the RecurrencePattern class properties to configure repeating appointments with ultimate flexibility. The following cases will be examined:
Create every day recurring appointment.
Create every week day recurring appointment.
Create an appointment that occurs on every "n" days.
Create an appointment that occurs on every "n-th" day of the month and the interval between each recurrence is "m" months.
Create an appointment that occurs on every "n-th" week day and the interval between each recurrence is "m" months.
Create a yearly appointment.
Set the maximum occurrences of the appointment.
Set the end date of the appointment's occurrences.
RecurrencePattern Class
While the RecurrenceRule class is the engine for creating and evaluating recurrence rules, the RecurrencePattern class carries the main information about the occurrence.
The RecurrencePattern class is located in the Telerik.Windows.Controls.ScheduleView namespace of the Telerik.Windows.Controls.ScheduleView.dll assembly.
The next several sections describe the main properties and methods exposed by the RecurrencePattern class.
Frequency
If you want to set the frequency of the recurrence, you need to set the RecurrencePattern's Frequency property. Its values are predefined in the RecurrenceFrequency enumeration, which exposes the following values:
Minutely (available since Q3 2012 SP1) - use RecurrenceFrequency.Minutely whenever you want the appointment to occur every minute.
Hourly (available since Q3 2012 SP1) - use RecurrenceFrequency.Hourly whenever you want the appointment to occur every hour.
Daily - use RecurrenceFrequency.Daily whenever you want the appointment to occur every day.
Monthly - use RecurrenceFrequency.Monthly whenever you want the appointment to occur every month.
Weekly - use RecurrenceFrequency.Weekly whenever you want the appointment to occur every week.
Yearly - use RecurrenceFrequency.Yearly whenever you want the appointment to occur every year.
The RecurrenceFrequency enumeration exposes also the following values:
- Secondly
- None
However, these values are invalid recurrence frequency and should not be used.
The default value of the RecurrencePattern's Frequency property is RecurrenceFrequency.None. Which means that the Frequency property is a mandatory property and you should always set it.
Minutely and Hourly Frequency can be set only with code ( not from the EditAppointmentDialog). In order to display these options, you should customize the EditAppointmentDialogStyle and add them in the template manually.
MinutesOfHour
When you want to specify the minutes of the hour when the appointment occurs, you should set this property. It is mainly used for Minutely Frequency and should be set to an array of integers.
HoursOfDay
When you want to specify the hours of the day when the appointment occurs, you should set this property. It is mainly used for Hourly Frequency and should be set to an array of integers.
DaysOfWeekMask
When you want to set the days of the week of the recurrence, you need to set the RecurrencePattern's DaysOfWeekMask property. Its values are predefined in the RecurrenceDays enumeration, which exposes the following values:
EveryDay
Friday
Monday
Saturday
Sunday
Thursday
Tuesday
Wednesday
WeekDays
WeekendDays
None
The default value of the RecurrencePattern's DaysOfWeekMask property is RecurrenceDays.None. However, the DaysOfWeekMask is not a mandatory property.
RecurrenceDays.WeekDays is equivalent to RecurrenceDays.Monday | RecurrenceDays.Tuesday | RecurrenceDays.Wednesday | RecurrenceDays.Thursday | RecurrenceDays.Friday.
RecurrenceDays.WeekendDays is equivalent to RecurrenceDays.Saturday | RecurrenceDays.Sunday.
RecurrenceDays.EveryDay is equivalent to RecurrenceDays.Monday | RecurrenceDays.Tuesday | RecurrenceDays.Wednesday | RecurrenceDays.Thursday | RecurrenceDays.Friday | RecurrenceDays.Saturday | RecurrenceDays.Sunday.
Enum members are often used in logical operation to create a combination of values. Often you should set more than one value of the DaysOfWeekMask property, like in the Example section at the end of the topic.
Interval
If you want to set the number of days between each recurrence, you need to specify the RecurrencePattern's Interval property.
The default value of the RecurrencePattern's Interval property is 1.
Combining the Interval property with the DaysOfWeekMask and Frequency pattern gives you even more flexibility when creating recurring appointments. For more information take a look at the Example section at the end of the topic.
DaysOfMonth
When you want to specify on which day of the month the appointment occurs, you need to set the DaysOfMonth property.
DayOrdinal
When you want to specify the day ordinal (first, second, third, fourth, etc.), you need to set the DayOrdinal property. For example, you may want to create an appointment that occurs on every second Monday of every third month. Check out the solution here.
MonthOfYear
When you want to specify on which month of the year the appointment occurs, you need to set the MonthOfYear property. This property is used mainly in the Yearly appointments. Check out the Example section for more information.
MaxOccurrences
When you want to specify a limit of the occurrences for the appointment, then you need to set the MaxOccurrences property. Check out the example at the end of the topic.
FirstDayOfWeek
Gets or sets the day on which the week starts. This property is only meaningful when RecurrenceFrequency is set to Weekly and Interval is greater than 1.
RecursUntil
When you want to specify the end date of the appointment's occurrences, then you need to set the RecursUntil property. Check out the example at the end of the topic.
Copy()
When you want to create a new instance of RecurrencePattern with the same values as a specified RecurrencePattern, then you need to use the Copy() method.
var pattern = new RecurrencePattern() {
Frequency = RecurrenceFrequency.Monthly,
MaxOccurrences = 10
};
var copyPattern = pattern.Copy();
Dim pattern = New RecurrencePattern() With {
.Frequency = RecurrenceFrequency.Monthly,
.MaxOccurrences = 10
}
Dim copyPattern = pattern.Copy()
In the above example, a new monthly recurrence pattern is created. It also has a limit of 10 occurrences. When you invoke the pattern.Copy() method this creates a new instance of the RecurrencePattern class with exactly the same characteristics as the source object (the Frequency property will be set to RecurrenceFrequency.Monthly and the MaxOccurrences property will be set to 10).
CopyFrom()
Use the CopyFrom() method to duplicate the pattern properties of the specified RecurrencePattern object in the RecurrencePattern object that calls this method.
var pattern = new RecurrencePattern() {
Frequency = RecurrenceFrequency.Monthly,
MaxOccurrences = 10
};
var newPattern = new RecurrencePattern();
newPattern.CopyFrom(pattern);
Dim pattern = New RecurrencePattern() With {
.Frequency = RecurrenceFrequency.Monthly,
.MaxOccurrences = 10
}
Dim newPattern As New RecurrencePattern()
newPattern.CopyFrom(pattern)
All properties in the current instance (newPattern object) will be replaced by the corresponding properties in the specified RecurrencePattern object.
Examples
For the next examples the following appointment declaration will be used.
var startDate = new DateTime(2011, 05, 11, 10, 0, 0);
var appointment = new Appointment() {
Start = startDate,
End = startDate.AddHours(2),
Subject = "Example"
};
Dim startDate = New DateTime(2011, 5, 11, 10, 0, 0)
Dim appointment = New Appointment() With {
.Start = startDate,
.End = startDate.AddHours(2),
.Subject = "Example"
}
A simple appointment that starts at 11/05/2011 10:00 AM and lasts two hours is created.
How to Create Every Day Recurring Appointment?
If you want to create an appointment that occurs every day, the only thing you should do is to set the RecurrencePattern's Frequency property to RecurrenceFrequency.Daily.
var pattern = new RecurrencePattern() {
Frequency = RecurrenceFrequency.Daily
};
appointment.RecurrenceRule = new RecurrenceRule(pattern);
Dim pattern = New RecurrencePattern() With {
Frequency = RecurrenceFrequency.Daily
}
appointment.RecurrenceRule = New RecurrenceRule(pattern)
The result can be seen on the next figure. As you can see the appointment with subject "Example" occurs on every day of the week.
How to Create Every Week Day Recurring Appointment?
Creating an every day recurring event is extremely simple - you just need to set the Frequency property. However, if you want to create every week (working) day recurring event, setting only the Frequency property won't be enough. You will need to set the DaysOfWeekMask property, too. See the following example:
var pattern = new RecurrencePattern() {
Frequency = RecurrenceFrequency.Weekly,
DaysOfWeekMask = RecurrenceDays.WeekDays
};
appointment.RecurrenceRule = new RecurrenceRule(pattern);
Dim pattern = New RecurrencePattern() With {
.Frequency = RecurrenceFrequency.Weekly,
.DaysOfWeekMask = RecurrenceDays.WeekDays
}
appointment.RecurrenceRule = New RecurrenceRule(pattern)
The result of the above example will be a RecurrencePattern which will create an appointment every week day, like on the image below.
Sometimes you may want to create an appointment that occurs during the weekend days, instead of every week day. The only thing you should change is to set the DaysOfWeekMask property to RecurrenceDays.WeekendDays.
If you want to create an appointment that occurs every specific week day (Monday, Tuesday, etc.), you need only to set the correct value for the DaysOfWeekMask property. For example, in order to create an appointment that occurs every Friday, set the DaysOfWeekMask property to RecurrenceDays.Friday.
How to Create an Appointment that Occurs on Every "n" Days?
When you want to create an appointment that occurs on every "n" days, you should set the Frequency, DaysOfWeekMask and the Interval properties of the RecurrencePattern object. For example, in order to create an appointment that occurs on every third day (that means the number of days between each recurrence is 3), you should:
Set the Frequency property to RecurrenceFrequency.Daily.
Set the DaysOfWeekMask property to RecurrenceDays.EveryDay.
Set the Interval property to 3.
var pattern = new RecurrencePattern() {
Frequency = RecurrenceFrequency.Daily,
DaysOfWeekMask = RecurrenceDays.EveryDay,
Interval = 3
};
appointment.RecurrenceRule = new RecurrenceRule(pattern);
Dim pattern = New RecurrencePattern() With {
.Frequency = RecurrenceFrequency.Daily,
.DaysOfWeekMask = RecurrenceDays.EveryDay,
.Interval = 3
}
appointment.RecurrenceRule = New RecurrenceRule(pattern)
Executing the previous pattern will result in creating an appointment that occurs on every third day. See the next image for the result.
In this example, the key moment is setting the Interval property. For example, if you want the number of days between each recurrence to be 4, 5, 6 or n days, then you just need to set the correct value to the Interval property.
How to Create an Appointment that Occurs on Every "n-th" Day of the Month and the Interval Between Each Recurrence is "m" Months?
For example, if you want to create an appointment that occurs on every fifth day of the month and the interval between each recurrence is two months, then you should perform the following steps:
Set the DaysOfMonth property to 5.
Set the Frequency property to RecurrenceFrequency.Monthly.
Set the Interval property to 2.
var pattern = new RecurrencePattern() {
DaysOfMonth = new int[] { 5 },
Frequency = RecurrenceFrequency.Monthly,
Interval = 2
};
appointment.RecurrenceRule = new RecurrenceRule(pattern);
Dim pattern = New RecurrencePattern() With {
.DaysOfMonth = New int[] { 5 },
.Frequency = RecurrenceFrequency.Monthly,
.Interval = 2
}
appointment.RecurrenceRule = New RecurrenceRule(pattern)
How to Create an Appointment that Occurs on Every "n-th" Week Day and the Interval Between Each Recurrence is "m" Months?
For example, if you want to create an appointment that occurs on every second Monday of the month and the interval between each recurrence is two months, then you should perform the following steps:
Set the DayOrdinal to 2.
Set the Frequency property to RecurrenceFrequency.Monthly.
Set the DaysOfWeekMask property to RecurrenceDays.Monday.
Set the Interval property to 2.
var pattern = new RecurrencePattern() {
DayOrdinal = 2,
DaysOfWeekMask = RecurrenceDays.Monday,
Frequency = RecurrenceFrequency.Monthly,
Interval = 2
};
appointment.RecurrenceRule = new RecurrenceRule(pattern);
Dim pattern = New RecurrencePattern() With {
.DayOrdinal = 2,
.DaysOfWeekMask = RecurrenceDays.Monday,
.Frequency = RecurrenceFrequency.Monthly,
.Interval = 2
}
appointment.RecurrenceRule = New RecurrenceRule(pattern)
How to Create an Yearly Appointment?
For example, if you want to create an appointment that occurs on 13th of November each year, then you should perform the following steps:
Set the Frequency property to RecurrenceFrequency.Yearly.
Set the MonthOfYear to 11.
Set the DaysOfMonth to 13.
var pattern = new RecurrencePattern() {
Frequency = RecurrenceFrequency.Yearly,
MonthOfYear = 11,
DaysOfMonth = new int[] { 13 }
};
appointment.RecurrenceRule = new RecurrenceRule(pattern);
Dim pattern = New RecurrencePattern() With {
.Frequency = RecurrenceFrequency.Yearly,
.MonthOfYear = 11,
.DaysOfMonth = New int[] { 13 }
}
appointment.RecurrenceRule = New RecurrenceRule(pattern)
Set the Maximum Occurrences of the Appointment
When you want to specify a limit of the occurrences for the appointment, then you need to set the MaxOccurrences property. For example if you want to specify a limit of 3 occurences for a daily appointment, then you should set the MaxOccurrences property to 3.
var pattern = new RecurrencePattern() {
Frequency = RecurrenceFrequency.Daily,
MaxOccurrences = 3
};
appointment.RecurrenceRule = new RecurrenceRule(pattern);
Dim pattern = New RecurrencePattern() With {
.Frequency = RecurrenceFrequency.Daily,
.MaxOccurrences = 3
}
appointment.RecurrenceRule = New RecurrenceRule(pattern)
Set the End Date of the Appointment's Occurrences
When you want to specify the end date of the appointment's occurrences, then you need to set the RepatUntil property.
var pattern = new RecurrencePattern() {
Frequency = RecurrenceFrequency.Daily,
RecursUntil = new DateTime( 2011, 05, 24, 10, 0, 0 )
};
appointment.RecurrenceRule = new RecurrenceRule(pattern);
Dim pattern = New RecurrencePattern() With {
.Frequency = RecurrenceFrequency.Daily,
.RecursUntil = New DateTime(2011, 5, 24, 10, 0, 0)
}
appointment.RecurrenceRule = New RecurrenceRule(pattern)
The appointment that starts on 11.05.201 will occur until 24.05.2011. See the next image.
