Creating Recurring Events

Recurring events repeat over a specified interval of time. To make an event a recurring event, assign it a recurrence rule, which describes when the event occurs. Recurrence rules are represented by instances of the EKRecurrenceRule class.

Recurrence is applicable to both calendar events and reminders. Unlike with recurring events, only the first incomplete reminder of a recurring set is obtainable. This is true with Event Kit as well as the Reminders app. When the reminder is completed, the next reminder in the recurrence set becomes available.

Using Basic Rules

You can create a recurrence rule with a simple daily, weekly, monthly, or yearly pattern using the initRecurrenceWithFrequency:interval:end: method. You provide three values to this method:

Using Complex Rules

You can create a recurrence rule with a complex pattern using the initRecurrenceWithFrequency:interval:daysOfTheWeek:daysOfTheMonth:monthsOfTheYear:weeksOfTheYear:daysOfTheYear:setPositions:end: method. As you do for a basic recurrence rule, you provide a frequency, an interval, and an optional end for the recurring event. In addition, you can provide a combination of optional values describing a custom rule, as listed in Table 4-1.

Table 4-1  Complex recurrence rule breakdown

Parameter name

Accepted values

Can be combined with

Example

days

The days of the week on which the event occurs.

An array of EKRecurrenceDayOfWeek objects.

All recurrence rules except for daily recurrence rules.

An array containing EKTuesday and EKFriday objects will create a recurrence that occurs every Tuesday and Friday.

monthDays

The days of the month on which the event occurs.

An array of nonzero NSNumber objects ranging from –31 to 31. Negative values indicate counting backward from the end of the month.

Monthly recurrence rules only.

An array containing the values 1 and –1 will create a recurrence that occurs on the first and last day of every month.

months

The months of the year in which the event occurs.

An array of NSNumber objects with values ranging from 1 to 12, corresponding to Gregorian calendar months.

Yearly recurrence rules only.

If your originating event occurs on January 10, you can provide an array containing the values 1 and 2 to create a recurrence that occurs every January 10 and February 10.

weeksOfTheYear

The weeks of the year in which the event occurs.

An array of nonzero NSNumber objects ranging from –53 to 53. Negative values indicate counting backward from the end of the year.

Yearly recurrence rules only.

If your originating event occurs on a Wednesday, you can provide an array containing the values 1 and –1 to create a recurrence that occurs on the Wednesday of the first and last weeks of every year. If a specified week does not contain a Wednesday in the current year, as can be the case for the first or last week of a year, the event does not occur.

daysOfTheYear

The days of the year on which the event occurs.

An array of nonzero NSNumber objects ranging from –366 to 366. Negative values indicate counting backward from the end of the year.

Yearly recurrence rules only.

You can provide an array containing the values 1 and –1 to create a recurrence that occurs on the first and last day of every year.

setPositions

The occurrences to include in the recurrence rule. This filter is applied to the set of occurrences determined from the other parameters you provide.

An array of nonzero NSNumber objects ranging from –366 to 366. Negative values indicate counting backward from the end of the list of occurrences.

All recurrence rules except for daily recurrence rules.

If you provide an array containing the values 1 and –1 to a yearly recurrence rule that has specified Monday through Friday as its value for days of the week, the recurrence occurs only on the first and last weekday of every year.

You can provide values for any number of the parameters in Table 4-1. Parameters that don’t apply to a particular recurrence rule are ignored. If you provide a value for more than one of the above parameters, the recurrence occurs only on days that apply to all provided values.

Once you have created a recurrence rule, you can apply it to a calendar event or reminder with the addRecurrenceRule: instance method of EKCalendarItem.