KCalCore::Alarm Class Reference

#include <alarm.h>

Inheritance diagram for KCalCore::Alarm:

Public Types
typedef QVector< Ptr >	List
typedef QSharedPointer< Alarm >	Ptr
enum	Type {   Invalid, Display, Procedure, Email,   Audio }

Public Member Functions
	Alarm (Incidence *parent)
	Alarm (const Alarm &other)
virtual	~Alarm ()
void	addMailAddress (const Person::Ptr &mailAlarmAddress)
void	addMailAttachment (const QString &mailAttachFile)
QString	audioFile () const
Duration	duration () const
bool	enabled () const
Duration	endOffset () const
KDateTime	endTime () const
bool	hasEndOffset () const
bool	hasLocationRadius () const
bool	hasStartOffset () const
bool	hasTime () const
int	locationRadius () const
Person::List	mailAddresses () const
QStringList	mailAttachments () const
QString	mailSubject () const
QString	mailText () const
KDateTime	nextRepetition (const KDateTime &preTime) const
KDateTime	nextTime (const KDateTime &preTime, bool ignoreRepetitions=false) const
bool	operator!= (const Alarm &a) const
Alarm &	operator= (const Alarm &)
bool	operator== (const Alarm &a) const
QString	parentUid () const
KDateTime	previousRepetition (const KDateTime &afterTime) const
QString	programArguments () const
QString	programFile () const
int	repeatCount () const
void	setAudioAlarm (const QString &audioFile=QString())
void	setAudioFile (const QString &audioFile)
void	setDisplayAlarm (const QString &text=QString())
void	setEmailAlarm (const QString &subject, const QString &text, const Person::List &addressees, const QStringList &attachments=QStringList())
void	setEnabled (bool enable)
void	setEndOffset (const Duration &offset)
void	setHasLocationRadius (bool hasLocationRadius)
void	setLocationRadius (int locationRadius)
void	setMailAddress (const Person::Ptr &mailAlarmAddress)
void	setMailAddresses (const Person::List &mailAlarmAddresses)
void	setMailAttachment (const QString &mailAttachFile)
void	setMailAttachments (const QStringList &mailAttachFiles)
void	setMailSubject (const QString &mailAlarmSubject)
void	setMailText (const QString &text)
void	setParent (Incidence *parent)
void	setProcedureAlarm (const QString &programFile, const QString &arguments=QString())
void	setProgramArguments (const QString &arguments)
void	setProgramFile (const QString &programFile)
void	setRepeatCount (int alarmRepeatCount)
void	setSnoozeTime (const Duration &alarmSnoozeTime)
void	setStartOffset (const Duration &offset)
void	setText (const QString &text)
void	setTime (const KDateTime &alarmTime)
void	setType (Type type)
void	shiftTimes (const KDateTime::Spec &oldSpec, const KDateTime::Spec &newSpec)
Duration	snoozeTime () const
Duration	startOffset () const
QString	text () const
KDateTime	time () const
void	toggleAlarm ()
Type	type () const
Public Member Functions inherited from KCalCore::CustomProperties
	CustomProperties ()
	CustomProperties (const CustomProperties &other)
virtual	~CustomProperties ()
QMap< QByteArray, QString >	customProperties () const
QString	customProperty (const QByteArray &app, const QByteArray &key) const
QString	nonKDECustomProperty (const QByteArray &name) const
QString	nonKDECustomPropertyParameters (const QByteArray &name) const
CustomProperties &	operator= (const CustomProperties &other)
bool	operator== (const CustomProperties &properties) const
void	removeCustomProperty (const QByteArray &app, const QByteArray &key)
void	removeNonKDECustomProperty (const QByteArray &name)
void	setCustomProperties (const QMap< QByteArray, QString > &properties)
void	setCustomProperty (const QByteArray &app, const QByteArray &key, const QString &value)
void	setNonKDECustomProperty (const QByteArray &name, const QString &value, const QString &parameters=QString())

Protected Member Functions
virtual void	customPropertyUpdated ()
virtual void	virtual_hook (int id, void *data)
Protected Member Functions inherited from KCalCore::CustomProperties
virtual void	customPropertyUpdate ()

Friends
KCALCORE_EXPORT QDataStream &	operator<< (QDataStream &s, const KCalCore::Alarm::Ptr &)
KCALCORE_EXPORT QDataStream &	operator>> (QDataStream &s, const KCalCore::Alarm::Ptr &)

Additional Inherited Members
Static Public Member Functions inherited from KCalCore::CustomProperties
static QByteArray	customPropertyName (const QByteArray &app, const QByteArray &key)

Detailed Description

Represents an alarm notification.

Alarms are user notifications that occur at specified times. Notifications can be on-screen pop-up dialogs, email messages, the playing of audio files, or the running of another program.

Alarms always belong to a parent Incidence.

Definition at line 61 of file alarm.h.

Member Typedef Documentation

typedef QVector<Ptr> KCalCore::Alarm::List

List of alarms.

Definition at line 83 of file alarm.h.

typedef QSharedPointer<Alarm> KCalCore::Alarm::Ptr

A shared pointer to an Alarm object.

Definition at line 78 of file alarm.h.

Member Enumeration Documentation

enum KCalCore::Alarm::Type

The different types of alarms.

Enumerator
Invalid	Invalid, or no alarm.
Display	Display a dialog box.
Procedure	Call a script.
Email	Send email.
Audio	Play an audio file.

Definition at line 67 of file alarm.h.

Constructor & Destructor Documentation

Alarm::Alarm ( Incidence *  parent )

explicit

Constructs an alarm belonging to the parent Incidence.

Private class that helps to provide binary compatibility between releases.

Parameters

parent

is the Incidence this alarm will belong to.

Definition at line 105 of file alarm.cpp.

Alarm::Alarm

(

const Alarm &

other

)

Copy constructor.

Parameters

other

is the alarm to copy.

Definition at line 110 of file alarm.cpp.

Alarm::~Alarm ( )

virtual

Destroys the alarm.

Definition at line 115 of file alarm.cpp.

Member Function Documentation

void Alarm::addMailAddress

(

const Person::Ptr &

mailAlarmAddress

)

Adds an address to the list of email addresses to send mail to when the alarm is triggered.

Ignored if the alarm is not an Email type.

Parameters

mailAlarmAddress

is a Person to add to the list of addresses to receive a mail message when an Email type alarm is triggered.

See also

setMailAddress(), setMailAddresses(), mailAddresses()

Definition at line 373 of file alarm.cpp.

void Alarm::addMailAttachment

(

const QString &

mailAttachFile

)

Adds a filename to the list of files to attach to a mail message for an Email alarm type.

Ignored if the alarm is not an Email type.

Parameters

mailAttachFile

is a string containing a filename to be attached to an email message to send when the Email type alarm is triggered.

See also

setMailAttachment(), setMailAttachments(), mailAttachments()

Definition at line 436 of file alarm.cpp.

QString Alarm::audioFile

(

)

const

Returns the audio file name for an Audio alarm type.

Returns an empty string if the alarm is not an Audio type.

See also

setAudioAlarm(), setAudioFile()

Definition at line 274 of file alarm.cpp.

void Alarm::customPropertyUpdated ( )

protectedvirtual

CustomProperties::customPropertyUpdated()

Reimplemented from KCalCore::CustomProperties.

Definition at line 808 of file alarm.cpp.

Duration Alarm::duration

(

)

const

Returns the interval between the alarm's initial occurrence and its final repetition.

Definition at line 648 of file alarm.cpp.

bool Alarm::enabled

(

)

const

Returns the alarm enabled status: true (enabled) or false (disabled).

See also

setEnabled(), toggleAlarm()

Definition at line 747 of file alarm.cpp.

Duration Alarm::endOffset

(

)

const

Returns offset of alarm in time relative to the end of the event.

If the alarm's time is not defined in terms of an offset relative to the end of the event, returns zero.

See also

setEndOffset(), hasEndOffset()

Definition at line 793 of file alarm.cpp.

KDateTime Alarm::endTime

(

)

const

Returns the date/time when the last repetition of the alarm goes off.

If the alarm does not repeat this is equivalent to calling time().

See also

setTime()

Definition at line 713 of file alarm.cpp.

bool Alarm::hasEndOffset

(

)

const

Returns whether the alarm is defined in terms of an offset relative to the end of the event.

See also

endOffset(), setEndOffset()

Definition at line 775 of file alarm.cpp.

bool Alarm::hasLocationRadius

(

)

const

Returns true if alarm has location radius defined.

See also

setLocationRadius()

Definition at line 832 of file alarm.cpp.

bool Alarm::hasStartOffset

(

)

const

Returns whether the alarm is defined in terms of an offset relative to the start of the parent Incidence.

See also

startOffset(), setStartOffset()

Definition at line 770 of file alarm.cpp.

bool Alarm::hasTime

(

)

const

Returns true if the alarm has a trigger date/time.

Definition at line 596 of file alarm.cpp.

int Alarm::locationRadius

(

)

const

Returns the location radius in meters.

See also

setLocationRadius()

Definition at line 848 of file alarm.cpp.

Person::List Alarm::mailAddresses

(

)

const

Returns the list of addresses for an Email alarm type.

Returns an empty list if the alarm is not an Email type.

See also

addMailAddress(), setMailAddress(), setMailAddresses()

Definition at line 386 of file alarm.cpp.

QStringList Alarm::mailAttachments

(

)

const

Returns the list of attachment filenames for an Email alarm type.

Returns an empty list if the alarm is not an Email type.

See also

addMailAttachment(), setMailAttachment(), setMailAttachments()

Definition at line 449 of file alarm.cpp.

QString Alarm::mailSubject

(

)

const

Returns the subject line string for an Email alarm type.

Returns an empty string if the alarm is not an Email type.

See also

setMailSubject()

Definition at line 404 of file alarm.cpp.

QString Alarm::mailText

(

)

const

Returns the body text for an Email alarm type.

Returns an empty string if the alarm is not an Email type.

See also

setMailText()

Definition at line 467 of file alarm.cpp.

KDateTime Alarm::nextRepetition

(

const KDateTime &

preTime

)

const

Returns the date/time of the alarm's initial occurrence or its next repetition after a given time.

Parameters

preTime

the date/time after which to find the next repetition.

Returns

the date/time of the next repetition, or an invalid date/time if the specified time is at or after the alarm's last repetition.

See also

previousRepetition()

Definition at line 654 of file alarm.cpp.

KDateTime Alarm::nextTime	(	const KDateTime &	preTime,
		bool	ignoreRepetitions = false
	)		const

Returns the next alarm trigger date/time after given date/time.

Takes recurrent incidences into account.

Parameters

preTime	date/time from where to start
ignoreRepetitions	don't take repetitions into account

See also

nextRepetition()

Definition at line 534 of file alarm.cpp.

bool Alarm::operator!=

(

const Alarm &

a

)

const

Compares two alarms for inequality.

Parameters

a	is the comparison alarm.

Definition at line 201 of file alarm.cpp.

Alarm & Alarm::operator=

(

const Alarm &

a

)

Copy operator.

Definition at line 120 of file alarm.cpp.

bool Alarm::operator==

(

const Alarm &

a

)

const

Compares two alarms for equality.

Parameters

a	is the comparison alarm.

Definition at line 156 of file alarm.cpp.

QString Alarm::parentUid

(

)

const

Returns the parent's incidence UID of the alarm.

See also

setParent()

Definition at line 803 of file alarm.cpp.

KDateTime Alarm::previousRepetition

(

const KDateTime &

afterTime

)

const

Returns the date/time of the alarm's latest repetition or, if none, its initial occurrence before a given time.

Parameters

afterTime

is the date/time before which to find the latest repetition.

Returns

the date and time of the latest repetition, or an invalid date/time if the specified time is at or before the alarm's initial occurrence.

See also

nextRepetition()

Definition at line 684 of file alarm.cpp.

QString Alarm::programArguments

(

)

const

Returns the program arguments string for a Procedure alarm type.

Returns an empty string if the alarm is not a Procedure type.

See also

setProcedureAlarm(), setProgramFile(), programFile(), setProgramArguments()

Definition at line 324 of file alarm.cpp.

QString Alarm::programFile

(

)

const

Returns the program file name for a Procedure alarm type.

Returns an empty string if the alarm is not a Procedure type.

See also

setProcedureAlarm(), setProgramFile(), setProgramArguments(), programArguments()

Definition at line 306 of file alarm.cpp.

int Alarm::repeatCount

(

)

const

Returns how many times an alarm may repeats after its initial occurrence.

See also

setRepeatCount()

Definition at line 643 of file alarm.cpp.

void Alarm::setAudioAlarm

(

const QString &

audioFile = QString()

)

Sets the Audio type for this alarm and the name of the audio file to play when the alarm is triggered.

Parameters

audioFile

is the name of the audio file to play when the alarm is triggered.

See also

setAudioFile(), audioFile()

Definition at line 249 of file alarm.cpp.

void Alarm::setAudioFile

(

const QString &

audioFile

)

Sets the name of the audio file to play when the audio alarm is triggered.

Ignored if the alarm is not an Audio type.

Parameters

audioFile

is the name of the audio file to play when the alarm is triggered.

See also

setAudioAlarm(), audioFile()

Definition at line 261 of file alarm.cpp.

void Alarm::setDisplayAlarm

(

const QString &

text = QString()

)

Sets the Display type for this alarm.

If text is specified non-empty, then it is used as the description text to display when the alarm is triggered.

Parameters

text	is the description to display when the alarm is triggered.

See also

setText(), text()

Definition at line 472 of file alarm.cpp.

void Alarm::setEmailAlarm	(	const QString &	subject,
		const QString &	text,
		const Person::List &	addressees,
		const QStringList &	attachments = QStringList()
	)

Sets the Email type for this alarm and the email subject, text, addresses, and attachments that make up an email message to be sent when the alarm is triggered.

Parameters

subject	is the email subject.
text	is a string containing the body of the email message.
addressees	is Person list of email addresses.
attachments	is a a QStringList of optional file names of email attachments.

See also

setMailSubject(), setMailText(), setMailAddresses(), setMailAttachments()

Definition at line 329 of file alarm.cpp.

void Alarm::setEnabled

(

bool

enable

)

Sets the enabled status of the alarm.

Parameters

enable

if true, then enable the alarm; else disable the alarm.

See also

enabled(), toggleAlarm()

Definition at line 736 of file alarm.cpp.

void Alarm::setEndOffset

(

const Duration &

offset

)

Sets the alarm offset relative to the end of the parent Incidence.

Parameters

offset

is a Duration to be used as a time relative to the end of the parent Incidence to be used as the alarm trigger.

See also

setStartOffset(), startOffset(), endOffset()

Definition at line 780 of file alarm.cpp.

void Alarm::setHasLocationRadius

(

bool

hasLocationRadius

)

Set if the location radius for the alarm has been defined.

Parameters

hasLocationRadius

if true, then this alarm has a location radius.

See also

setLocationRadius()

Definition at line 816 of file alarm.cpp.

void Alarm::setLocationRadius

(

int

locationRadius

)

Set location radius for the alarm.

This means that alarm will be triggered when user approaches the location. Given value will be stored into custom properties as X-LOCATION-RADIUS.

Parameters

locationRadius

radius in meters

See also

locationRadius()

Definition at line 837 of file alarm.cpp.

void Alarm::setMailAddress

(

const Person::Ptr &

mailAlarmAddress

)

Sets the email address of an Email type alarm.

Ignored if the alarm is not an Email type.

Parameters

mailAlarmAddress

is a Person to receive a mail message when an Email type alarm is triggered.

See also

setMailSubject(), setMailText(), setMailAddresses(), setMailAttachment(), setMailAttachments(), mailAddresses()

Definition at line 346 of file alarm.cpp.

void Alarm::setMailAddresses

(

const Person::List &

mailAlarmAddresses

)

Sets a list of email addresses of an Email type alarm.

Ignored if the alarm is not an Email type.

Parameters

mailAlarmAddresses

is a Person list to receive a mail message when an Email type alarm is triggered.

See also

setMailSubject(), setMailText(), setMailAddress(), setMailAttachments(), setMailAttachment(), mailAddresses()

Definition at line 360 of file alarm.cpp.

void Alarm::setMailAttachment

(

const QString &

mailAttachFile

)

Sets the filename to attach to a mail message for an Email alarm type.

Ignored if the alarm is not an Email type.

Parameters

mailAttachFile

is a string containing a filename to be attached to an email message to send when the Email type alarm is triggered.

See also

setMailSubject(), setMailText(), setMailAddress(), setMailAddresses(), setMailAttachments(), mailAttachments()

Definition at line 409 of file alarm.cpp.

void Alarm::setMailAttachments

(

const QStringList &

mailAttachFiles

)

Sets a list of filenames to attach to a mail message for an Email alarm type.

Ignored if the alarm is not an Email type.

Parameters

mailAttachFiles

is a QString list of filenames to attach to a mail message when an Email type alarm is triggered.

See also

setMailSubject(), setMailText(), setMailAttachment(), setMailAddress(), setMailAddresses()

Definition at line 423 of file alarm.cpp.

void Alarm::setMailSubject

(

const QString &

mailAlarmSubject

)

Sets the subject line of a mail message for an Email alarm type.

Ignored if the alarm is not an Email type.

Parameters

mailAlarmSubject

is a string to be used as a subject line of an email message to send when the Email type alarm is triggered.

See also

setMailText(), setMailAddress(), setMailAddresses(), setMailAttachment(), setMailAttachments(), mailSubject()

Definition at line 391 of file alarm.cpp.

void Alarm::setMailText

(

const QString &

text

)

Sets the body text for an Email alarm type.

Ignored if the alarm is not an Email type.

Parameters

text	is a string containing the body text of a mail message when an Email type alarm is triggered.

See also

setMailSubject(), setMailAddress(), setMailAddresses(), setMailAttachment(), setMailAttachments()

Definition at line 454 of file alarm.cpp.

void Alarm::setParent

(

Incidence *

parent

)

Sets the parent Incidence of the alarm.

Parameters

parent

is alarm parent Incidence to set.

See also

parentUid()

Definition at line 798 of file alarm.cpp.

void Alarm::setProcedureAlarm	(	const QString &	programFile,
		const QString &	arguments = QString()
	)

Sets the Procedure type for this alarm and the program (with arguments) to execute when the alarm is triggered.

Parameters

programFile	is the name of the program file to execute when the alarm is triggered.
arguments	is a string of arguments to supply to programFile.

See also

setProgramFile(), programFile(), setProgramArguments(), programArguments()

Definition at line 279 of file alarm.cpp.

void Alarm::setProgramArguments

(

const QString &

arguments

)

Sets the program arguments string when the alarm is triggered.

Ignored if the alarm is not a Procedure type.

Parameters

arguments

is a string of arguments to supply to the program.

See also

setProcedureAlarm(), setProgramFile(), programFile(), programArguments()

Definition at line 311 of file alarm.cpp.

void Alarm::setProgramFile

(

const QString &

programFile

)

Sets the program file to execute when the alarm is triggered.

Ignored if the alarm is not a Procedure type.

Parameters

programFile

is the name of the program file to execute when the alarm is triggered.

See also

setProcedureAlarm(), programFile(), setProgramArguments(), programArguments()

Definition at line 293 of file alarm.cpp.

void Alarm::setRepeatCount

(

int

alarmRepeatCount

)

Sets how many times an alarm is to repeat itself after its initial occurrence (w/snoozes).

Parameters

alarmRepeatCount

is the number of times an alarm may repeat, excluding the initial occurrence.

See also

repeatCount()

Definition at line 632 of file alarm.cpp.

void Alarm::setSnoozeTime

(

const Duration &

alarmSnoozeTime

)

Sets the snooze time interval for the alarm.

Parameters

alarmSnoozeTime

the time between snoozes.

See also

snoozeTime()

Definition at line 614 of file alarm.cpp.

void Alarm::setStartOffset

(

const Duration &

offset

)

Sets the alarm offset relative to the start of the parent Incidence.

Parameters

offset

is a Duration to be used as a time relative to the start of the parent Incidence to be used as the alarm trigger.

See also

setEndOffset(), startOffset(), endOffset()

Definition at line 752 of file alarm.cpp.

void Alarm::setText

(

const QString &

text

)

Sets the description text to be displayed when the alarm is triggered.

Ignored if the alarm is not a display alarm.

Parameters

text	is the description to display when the alarm is triggered.

See also

setDisplayAlarm(), text()

Definition at line 486 of file alarm.cpp.

void Alarm::setTime

(

const KDateTime &

alarmTime

)

Sets the trigger time of the alarm.

Parameters

alarmTime

is the KDateTime alarm trigger.

See also

time()

Definition at line 504 of file alarm.cpp.

void Alarm::setType

(

Alarm::Type

type

)

Sets the Type for this alarm to type.

If the specified type is different from the current type of the alarm, then the alarm's type-specific properties are re-initialized.

Parameters

type	is the alarm Type to set.

See also

type()

Definition at line 206 of file alarm.cpp.

void Alarm::shiftTimes	(	const KDateTime::Spec &	oldSpec,
		const KDateTime::Spec &	newSpec
	)

Shift the times of the alarm so that they appear at the same clock time as before but in a new time zone.

The shift is done from a viewing time zone rather than from the actual alarm time zone.

For example, shifting an alarm whose start time is 09:00 America/New York, using an old viewing time zone (oldSpec) of Europe/London, to a new time zone (newSpec) of Europe/Paris, will result in the time being shifted from 14:00 (which is the London time of the alarm start) to 14:00 Paris time.

Parameters

oldSpec	the time specification which provides the clock times
newSpec	the new time specification

Definition at line 601 of file alarm.cpp.

Duration Alarm::snoozeTime

(

)

const

Returns the snooze time interval.

See also

setSnoozeTime()

Definition at line 627 of file alarm.cpp.

Duration Alarm::startOffset

(

)

const

Returns offset of alarm in time relative to the start of the parent Incidence.

If the alarm's time is not defined in terms of an offset relative to the start of the event, returns zero.

See also

setStartOffset(), hasStartOffset()

Definition at line 765 of file alarm.cpp.

QString Alarm::text

(

)

const

Returns the display text string for a Display alarm type.

Returns an empty string if the alarm is not a Display type.

See also

setDisplayAlarm(), setText()

Definition at line 499 of file alarm.cpp.

KDateTime Alarm::time

(

)

const

Returns the alarm trigger date/time.

See also

setTime()

Definition at line 517 of file alarm.cpp.

void Alarm::toggleAlarm

(

)

Toggles the alarm status, i.e, an enable alarm becomes disabled and a disabled alarm becomes enabled.

See also

enabled(), setEnabled()

Definition at line 725 of file alarm.cpp.

Alarm::Type Alarm::type

(

)

const

Returns the Type of the alarm.

See also

setType()

Definition at line 244 of file alarm.cpp.

void Alarm::virtual_hook ( int  id, void *  data  )

protectedvirtual

IncidenceBase::virtual_hook()

Reimplemented from KCalCore::CustomProperties.

Definition at line 876 of file alarm.cpp.

Friends And Related Function Documentation

KCALCORE_EXPORT QDataStream& operator<< ( QDataStream &  s, const KCalCore::Alarm::Ptr &    )

friend

Alarm serializer.

Since

4.12

KCALCORE_EXPORT QDataStream& operator>> ( QDataStream &  s, const KCalCore::Alarm::Ptr &    )

friend

Alarm deserializer.

Since

4.12

---

The documentation for this class was generated from the following files:

• alarm.h
• alarm.cpp