Mac OS X Reference Library Apple Developer Connection spyglass button

CalRecurrenceRule Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/CalendarStore.framework
Availability
Available in Mac OS X v10.5 and later.
Companion guide
Declared in
CalRecurrenceRule.h

Overview

The CalRecurrenceRule class is used to describe the recurrence pattern for a recurring event. The recurrence rules that you can create are restricted to the recurrence patterns that you have access to in iCal. It is not possible to directly modify a CalRecurrenceRule object or any of its properties—all properties defined in this class are read-only.

Use one of the init... methods to create the desired recurrence rule. These init... methods set the receiver’s properties. For example, if you invoke one of the initMonthly... methods, the recurrenceType property is set to CalRecurrenceMonthly. All recurrence rules have a value set for the recurrenceType and recurrenceInterval properties. If the recurrenceEnd property is nil, an event repeats forever. The rest of the properties defined in this class have values depending on the type of recurrence rule and initializer method used to create the recurring event pattern. If a property is not needed to describe a recurrence pattern, then it’s value is nil.

Every initializer method has an interval and a CalRecurrenceEnd object as arguments. The interval is a value greater than 0 that is the number of units between occurrences of an event. For example, if the recurrenceType property is CalRecurrenceMonthly, then the unit of measurement is one month. If the interval is 1, the event occurs every month, but if it is 2, it occurs every other month. The CalRecurrenceEnd object specifies when a recurring event ends. This can be specified using a counter or an end date (see CalRecurrenceEnd Class Reference for details). Pass nil as the recurrence end argument if the event never ends.

In addition, there are some initializers for more sophisticated recurrence patterns. However, these initializers are restricted to patterns that can be represented in iCal and include custom repeating patterns. For example, you can specify a pattern where an event occurs on the Friday of the 2nd week of every month, or the Monday of the 3rd week of every fourth month of a year. You can create custom patterns for weekly, monthly, and yearly recurrence rules.

After you create a recurrence rule, use the recurrenceRule CalEvent property to set the recurrence rule for an event. Use the saveEvent:span:error: method to save your changes to the iCal database.

Tasks

Initializing Recurrence Rules

Getting Recurrence Properties

Properties

For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.

daysOfTheMonth

If the recurrenceType property is CalRecurrenceMonthly, an array of integer values ranging from 1 to 31 representing days of the month in the pattern; otherwise, nil. (read-only)

@property(readonly) NSArray *daysOfTheMonth
Availability
Declared In
CalRecurrenceRule.h

daysOfTheWeek

If the recurrenceType property is CalRecurrenceWeekly, an integer value ranging from 1 to 7 representing the day of the week in the pattern where Sunday is equal to 1; otherwise, nil. (read-only)

@property(readonly) NSArray *daysOfTheWeek
Availability
Declared In
CalRecurrenceRule.h

firstDayOfTheWeek

An integer value of 0 or 1 to 7 where 0 indicates no value is set, and 1 to 7 indicates the first day of the week where Sunday is represented by 1. (read-only)

@property(readonly) NSUInteger firstDayOfTheWeek
Discussion

This property only affects the way the recurrence is expanded for weekly recurrence rules with an interval greater than 1. For those types of recurrence rules, Calendar Store sets this property to 2 (Monday). For all other recurrence rules, this property defaults to 0.

Availability
Declared In
CalRecurrenceRule.h

monthsOfTheYear

If the recurrenceType property is CalRecurrenceYearly, an array of the months—integer values ranging from 1 to 12 representing the month of a year—that the event occurs; otherwise, nil. (read-only)

@property(readonly) NSArray *monthsOfTheYear
Availability
Declared In
CalRecurrenceRule.h

nthWeekDaysOfTheMonth

If the recurrenceType property is CalRecurrenceMonthly or CalRecurrenceYearly, an array of CalNthWeekDay objects representing the days within the weeks of a month; otherwise, nil. (read-only)

@property(readonly) NSArray *nthWeekDaysOfTheMonth
Availability
Declared In
CalRecurrenceRule.h

recurrenceEnd

An object that describes how a recurring event ends by specifying an end date or a counter. (read-only)

@property(readonly) CalRecurrenceEnd *recurrenceEnd
Discussion

If nil, the event never ends.

Availability
Declared In
CalRecurrenceRule.h

recurrenceInterval

The number of intervals between the specified pattern of a recurring event. The actual time between a pattern depends on the value of the recurrenceType property. (read-only)

@property(readonly) NSUInteger recurrenceInterval
Discussion

For example, if the recurrenceType property is CalRecurrenceMonthly and the recurrenceInterval property is 1, then the event occurs every month. If the recurrenceInterval property is 2, then the event occurs every other month.

Availability
Declared In
CalRecurrenceRule.h

recurrenceType

The unit of time between intervals. See “CalRecurrenceType” for possible values. (read-only)

@property(readonly) CalRecurrenceType recurrenceType
Availability
Declared In
CalRecurrenceRule.h

Instance Methods

initDailyRecurrenceWithInterval:end:

Initializes and returns a daily recurrence rule with the specified interval and ending rule.

- (id)initDailyRecurrenceWithInterval:(NSUInteger)interval end:(CalRecurrenceEnd *)end

Parameters
interval

The interval in days between occurrences of a recurring event. Must be a value greater than 0.

end

Describes how a recurring event ends. Pass nil if the event never ends.

Return Value

An initialized daily recurrence rule object—with the recurrenceType property set to CalRecurrenceDaily. Returns nil if interval is 0 or a negative number.

Availability
  • Available in Mac OS X v10.5 and later.
Declared In
CalRecurrenceRule.h

initMonthlyRecurrenceWithInterval:end:

Initializes and returns a monthly recurrence rule with the specified interval and end rule.

- (id)initMonthlyRecurrenceWithInterval:(NSUInteger)interval end:(CalRecurrenceEnd *)end

Parameters
interval

The interval in months between occurrences of a recurring event. Must be a value greater than 0.

end

Describes how a recurring event ends. Pass nil if the event never ends.

Return Value

A newly initialized monthly recurrence rule object—with the recurrenceType property set to CalRecurrenceMonthly. Returns nil if interval is 0 or a negative number.

Discussion

The returned recurrence rule defaults to the first day of the month.

Availability
  • Available in Mac OS X v10.5 and later.
See Also
Declared In
CalRecurrenceRule.h

initMonthlyRecurrenceWithInterval:forDayOfTheWeek:forWeekOfTheMonth:end:

Initializes and returns a monthly recurrence rule that represents an event that occurs on a specific day of the week and week of the month pattern—the pattern repeats at the specified monthly interval.

- (id)initMonthlyRecurrenceWithInterval:(NSUInteger)interval forDayOfTheWeek:(NSUInteger)weekDay forWeekOfTheMonth:(NSInteger)monthWeek end:(CalRecurrenceEnd *)end

Parameters
interval

The interval in months between occurrences of a recurring event. Must be a value greater than 0.

weekDay

The day of the week that the event occurs. An integer value ranging from 1 to 7 representing the day of the week where Sunday is equal to 1.

monthWeek

The week of the month that the event occurs. An integer value that is 1, 2, 3, 4, or -1 representing the week of a month where -1 is the last week of the month.

end

Describes how a recurring event ends. Pass nil if the event never ends.

Return Value

A newly initialized monthly recurrence rule object—with the recurrenceType property set to CalRecurrenceMonthly. Returns nil if interval is 0 or a negative number.

Discussion

For example, use this method to create a recurrence rule that represents an event that occurs on the first Monday of every month.

Availability
  • Available in Mac OS X v10.5 and later.
See Also
Declared In
CalRecurrenceRule.h

initMonthlyRecurrenceWithInterval:forDaysOfTheMonth:end:

Initializes and returns a monthly recurrence rule that represents an event that occurs more than once a month in a monthly pattern—the pattern repeats at the specified interval.

- (id)initMonthlyRecurrenceWithInterval:(NSUInteger)interval forDaysOfTheMonth:(NSArray *)monthDays end:(CalRecurrenceEnd *)end

Parameters
interval

The interval in months between occurrences of a recurring event. Must be a value greater than 0.

monthDays

An array of numbers specifying the days of the month pattern that repeats. The integer values can range from 1 to 31 representing the days of the month.

end

Describes how a recurring event ends. Pass nil if the event never ends.

Return Value

A newly initialized monthly recurrence rule object—with the recurrenceType property set to CalRecurrenceMonthly. Returns nil if interval is 0 or a negative number.

Availability
  • Available in Mac OS X v10.5 and later.
See Also
Declared In
CalRecurrenceRule.h

initWeeklyRecurrenceWithInterval:end:

Initializes and returns a weekly recurrence rule with the specified interval and ending rule.

- (id)initWeeklyRecurrenceWithInterval:(NSUInteger)interval end:(CalRecurrenceEnd *)end

Parameters
interval

The interval in weeks between occurrences of a recurring event. Must be a value greater than 0.

end

Describes how a recurring event ends. Pass nil if the event never ends.

Return Value

An initialized weekly recurrence rule object—with the recurrenceType property set to CalRecurrenceWeekly. Returns nil if interval is 0 or a negative number.

Availability
  • Available in Mac OS X v10.5 and later.
See Also
Declared In
CalRecurrenceRule.h

initWeeklyRecurrenceWithInterval:forDaysOfTheWeek:end:

Initializes and returns a weekly recurrence rule with the specified interval, ending rule, and specific days of the week.

- (id)initWeeklyRecurrenceWithInterval:(NSUInteger)interval forDaysOfTheWeek:(NSArray *)days end:(CalRecurrenceEnd *)end

Parameters
interval

The interval in weeks between occurrences of a recurring event. Must be a value greater than 0.

days

An array of numbers specifying the weekly pattern that repeats. The integer values can range from 1-7 where Sunday is equal to 1.

end

Describes how a recurring event ends. Pass nil if the event never ends.

Return Value

A newly initialized weekly recurrence rule object—with the recurrenceType property set to CalRecurrenceWeekly. Returns nil if interval is 0 or a negative number, or any of the other arguments are invalid.

Discussion

This initializer allows you to specify a weekly pattern that repeats. For example, if days contains the numbers 2 and 4, and interval is 2, then an event occurs biweekly on Mondays and Wednesdays.

Availability
  • Available in Mac OS X v10.5 and later.
See Also
Declared In
CalRecurrenceRule.h

initYearlyRecurrenceWithInterval:end:

Initializes and returns a yearly recurrence rule with the specified yearly interval and end rule.

- (id)initYearlyRecurrenceWithInterval:(NSUInteger)interval end:(CalRecurrenceEnd *)end

Parameters
interval

The interval in years between occurrences of a recurring event. Must be a value greater than 0.

end

Describes how a recurring event ends. Pass nil if the event never ends.

Return Value

A newly initialized yearly recurrence rule object—with the recurrenceType property set to CalRecurrenceYearly. Returns nil if interval is 0 or a negative number.

Availability
  • Available in Mac OS X v10.5 and later.
See Also
Declared In
CalRecurrenceRule.h

initYearlyRecurrenceWithInterval:forDayOfTheWeek:forWeekOfTheMonth:forMonthsOfTheYear:end:

Initializes and returns a yearly recurrence rule that represents an event that has a weekly and monthly pattern that repeats at the specified yearly interval.

- (id)initYearlyRecurrenceWithInterval:(NSUInteger)interval forDayOfTheWeek:(NSUInteger)weekDay forWeekOfTheMonth:(NSInteger)monthWeek forMonthsOfTheYear:(NSArray *)months end:(CalRecurrenceEnd *)end

Parameters
interval

The interval in years between this pattern of a recurring event. Must be a value greater than 0.

weekDay

The day of the week that the event occurs. An integer value ranging from 1-7 representing the day of the week where Sunday is equal to 1.

monthWeek

The week of the month that the event occurs. An integer value that is either 1, 2, 3, 4, or -1 representing the week of a month where -1 is the last week of the month.

months

The months of the year that the event occurs. An array of numbers where each number is an integer value ranging from 1-12 representing the month of a year.

end

Describes how a recurring event ends. Pass nil if the event never ends.

Return Value

A newly initialized yearly recurrence rule object—with the recurrenceType property set to CalRecurrenceYearly. Returns nil if interval is 0 or a negative number.

Discussion

This method allows you to create a pattern for an entire year that repeats—where an event occurs on the same day of the week, in the same week of a month, and possibly more than one month of a year. For example, use this method to represent an event that occurs every year on the first Friday of the sixth and twelfth months.

Availability
  • Available in Mac OS X v10.5 and later.
See Also
Declared In
CalRecurrenceRule.h

initYearlyRecurrenceWithInterval:forMonthsOfTheYear:end:

Initializes and returns a yearly recurrence rule representing an event that occurs multiple months within a year at a specified yearly interval.

- (id)initYearlyRecurrenceWithInterval:(NSUInteger)interval forMonthsOfTheYear:(NSArray *)months end:(CalRecurrenceEnd *)end

Parameters
interval

The interval in years between occurrences of a recurring event. Must be a value greater than 0.

end

Describes how a recurring event ends. Pass nil if the event never ends.

Return Value

A newly initialized yearly recurrence rule object—with the recurrenceType property set to CalRecurrenceYearly. Returns nil if interval is 0 or a negative number.

Discussion

For example, use this method if you want to represent an event that occurs every year on the first day of the first and seventh month of the year. If you need to specify the day of the month that the event occurs, use the initYearlyRecurrenceWithInterval:forDayOfWeek:forWeekOfMonth:forMonthsOfTheYear:end: method.

Availability
  • Available in Mac OS X v10.5 and later.
See Also
Declared In
CalRecurrenceRule.h

Constants

Recurrence Rule Constants

Constants used by this class.

extern NSUInteger const CalDefaultRecurrenceInterval;
Constants
CalDefaultRecurrenceInterval

The default recurrence interval. The default value of 1 indicates that the event repeats daily, weekly, monthly, or yearly depending on the recurrence type.

Available in Mac OS X v10.5 and later.

Declared in CalRecurrenceRule.h.

Declared In
CalendarStore/CalRecurrenceRule.h

CalRecurrenceType

The unit of measurement between occurrences of a recurring event.

typedef enum {
   CalRecurrenceDaily,
   CalRecurrenceWeekly,
   CalRecurrenceMonthly,
   CalRecurrenceYearly
} CalRecurrenceType;
Constants
CalRecurrenceDaily

Indicates a daily unit of measurement.

Available in Mac OS X v10.5 and later.

Declared in CalRecurrenceRule.h.

CalRecurrenceWeekly

Indicates a weekly unit of measurement.

Available in Mac OS X v10.5 and later.

Declared in CalRecurrenceRule.h.

CalRecurrenceMonthly

Indicates a monthly unit of measurement.

Available in Mac OS X v10.5 and later.

Declared in CalRecurrenceRule.h.

CalRecurrenceYearly

Indicates a yearly unit of measurement.

Available in Mac OS X v10.5 and later.

Declared in CalRecurrenceRule.h.

Discussion

The four types of units are days, weeks, months, and years which correspond to the types of recurrence rules. For example, if the recurrence rule is CalRecurrenceWeekly, then an interval of 1 indicates the event repeats weekly. If the interval is 2, the event repeats biweekly.

Declared In
CalendarStore/CalRecurrenceRule.h

Last updated: 2009-03-04

Did this document help you? Yes It's good, but... Not helpful...