---

CalAlarm Class Reference

Overview

The CalAlarm class represents alarm objects in iCal. Use the alarm class method to create an alarm and use the properties to set information about an alarm. Use the triggerDateRelativeTo: method if you need to know how much time is left before an alarm triggers. Use CalCalendarItem methods to add alarms to, or remove alarms from, events and tasks.

Tasks

Creating and Initializing Alarms

• + alarm

Getting and Setting Properties

•   absoluteTrigger  property
•   action  property
•   emailAddress  property
•   relativeTrigger  property
•   sound  property
•   URL  property

Getting Relative Dates

• – triggerDateRelativeTo:

Properties

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

absoluteTrigger

The date and time to trigger the alarm.

@property(copy) NSDate *absoluteTrigger;

Discussion

When you set the absoluteTrigger property, the relativeTrigger property is set to nil.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CalAlarm.h

action

The action to take when triggering the alarm.

@property(copy) NSString *action;

Discussion

The value of this property is one of the constants described in “Alarm Actions”.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CalAlarm.h

emailAddress

An email address that is the recipient of an email alarm—an alarm that triggers an email message.

@property(copy) NSString *emailAddress;

Discussion

When you set the emailAddress property, the action property is set to CalAlarmActionEmail, and the sound and URL properties are set to nil.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CalAlarm.h

relativeTrigger

The relative date and time to trigger the alarm.

@property(copy) NSTimeInterval relativeTrigger;

Discussion

When you set the relativeTrigger property, the absoluteTrigger property is set to nil.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CalAlarm.h

sound

The sound to play when the alarm triggers.

@property(copy) NSString *sound;

Discussion

The value of this property is the name of a system sound that can be used with the soundNamed: class method to create an NSSound object. When you set the sound property, the action property is set to CalAlarmActionSound, and the emailAddress and URL properties are set to nil.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CalAlarm.h

URL

The URL to open when the alarm triggers.

@property(copy) NSURL *url;

Discussion

When you set the URL property, the action property is set to CalAlarmActionProcedure, and the emailAddress and sound properties are set to nil.

Class Methods

alarm

Creates and returns a new alarm object.

+ (id)alarm

Return Value

Newly initialized CalAlarm object.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CalAlarm.h

Instance Methods

triggerDateRelativeTo:

Returns a delta value between the specified date and the date that the alarm is scheduled to trigger.

- (NSDate *)triggerDateRelativeTo:(NSDate *)date

Parameters

date

The start date that you want to compute the delta date from.

Return Value

The delta value between date and the date the alarm triggers.

Discussion

Use this method if you need to know precisely how long it will be before an alarm triggers. Alarms with relative triggers do not contain this information in the properties. Use this method to compute the delta value. For example, pass the current date and this method returns the time remaining until the alarm triggers.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CalAlarm.h

Constants

Alarm Actions

The action to take when an alarm triggers.

extern NSString * const CalAlarmActionDisplay;
extern NSString * const CalAlarmActionEmail;
extern NSString * const CalAlarmActionProcedure;
extern NSString * const CalAlarmActionSound;

Constants

CalAlarmActionDisplay

A message should be displayed when an alarm triggers.

Available in Mac OS X v10.5 and later.

Declared in CalAlarm.h

CalAlarmActionEmail

An email message should be sent when an alarm triggers.

Available in Mac OS X v10.5 and later.

Declared in CalAlarm.h

CalAlarmActionProcedure

A file should be opened when an alarm triggers.

Available in Mac OS X v10.5 and later.

Declared in CalAlarm.h

CalAlarmActionSound

A sound should be played when an alarm triggers.

Available in Mac OS X v10.5 and later.

Declared in CalAlarm.h

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CalendarStore/CalAlarm.h

---