KCalendarCore::Alarm

#include <alarm.h>

Inheritance diagram for KCalendarCore::Alarm:

Public Types

typedef QVector< PtrList
 
typedef QSharedPointer< AlarmPtr
 
enum  Type {
  Invalid, Display, Procedure, Email,
  Audio
}
 

Public Member Functions

 Alarm (Incidence *parent)
 
 Alarm (const Alarm &other)
 
 ~Alarm () override
 
void addMailAddress (const Person &mailAlarmAddress)
 
void addMailAttachment (const QString &mailAttachFile)
 
QString audioFile () const
 
Duration duration () const
 
bool enabled () const
 
Duration endOffset () const
 
QDateTime 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
 
QDateTime nextRepetition (const QDateTime &preTime) const
 
QDateTime nextTime (const QDateTime &preTime, bool ignoreRepetitions=false) const
 
bool operator!= (const Alarm &a) const
 
Alarmoperator= (const Alarm &)
 
bool operator== (const Alarm &a) const
 
QString parentUid () const
 
QDateTime previousRepetition (const QDateTime &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 &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 QDateTime &alarmTime)
 
void setType (Type type)
 
void shiftTimes (const QTimeZone &oldZone, const QTimeZone &newZone)
 
Duration snoozeTime () const
 
Duration startOffset () const
 
QString text () const
 
QDateTime time () const
 
void toggleAlarm ()
 
Type type () const
 
- Public Member Functions inherited from KCalendarCore::CustomProperties
 CustomProperties ()
 
 CustomProperties (const CustomProperties &other)
 
virtual ~CustomProperties ()
 
QMap< QByteArray, QStringcustomProperties () const
 
QString customProperty (const QByteArray &app, const QByteArray &key) const
 
QString nonKDECustomProperty (const QByteArray &name) const
 
QString nonKDECustomPropertyParameters (const QByteArray &name) const
 
CustomPropertiesoperator= (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

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

Friends

KCALENDARCORE_EXPORT QDataStreamoperator<< (QDataStream &s, const KCalendarCore::Alarm::Ptr &)
 
KCALENDARCORE_EXPORT QDataStreamoperator>> (QDataStream &s, const KCalendarCore::Alarm::Ptr &)
 

Additional Inherited Members

- Static Public Member Functions inherited from KCalendarCore::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 51 of file alarm.h.

Member Typedef Documentation

List of alarms.

Definition at line 73 of file alarm.h.

A shared pointer to an Alarm object.

Definition at line 68 of file alarm.h.

Member Enumeration Documentation

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 57 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
parentis the Incidence this alarm will belong to.

Definition at line 76 of file alarm.cpp.

Alarm::Alarm ( const Alarm other)

Copy constructor.

Parameters
otheris the alarm to copy.

Definition at line 81 of file alarm.cpp.

Alarm::~Alarm ( )
override

Destroys the alarm.

Definition at line 86 of file alarm.cpp.

Member Function Documentation

void Alarm::addMailAddress ( const Person 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
mailAlarmAddressis 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 346 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
mailAttachFileis 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 409 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 247 of file alarm.cpp.

void Alarm::customPropertyUpdated ( )
overrideprotectedvirtual
Duration Alarm::duration ( ) const

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

Definition at line 620 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 719 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 765 of file alarm.cpp.

QDateTime 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 685 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 747 of file alarm.cpp.

bool Alarm::hasLocationRadius ( ) const

Returns true if alarm has location radius defined.

See also
setLocationRadius()

Definition at line 804 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 742 of file alarm.cpp.

bool Alarm::hasTime ( ) const

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

Definition at line 569 of file alarm.cpp.

int Alarm::locationRadius ( ) const

Returns the location radius in meters.

See also
setLocationRadius()

Definition at line 820 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 359 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 422 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 377 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 440 of file alarm.cpp.

QDateTime Alarm::nextRepetition ( const QDateTime preTime) const

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

Parameters
preTimethe 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 626 of file alarm.cpp.

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

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

Takes recurrent incidences into account.

Parameters
preTimedate/time from where to start
ignoreRepetitionsdon't take repetitions into account
See also
nextRepetition()

Definition at line 507 of file alarm.cpp.

bool Alarm::operator!= ( const Alarm a) const

Compares two alarms for inequality.

Parameters
ais the comparison alarm.

Definition at line 172 of file alarm.cpp.

Alarm & Alarm::operator= ( const Alarm a)

Copy operator.

Definition at line 91 of file alarm.cpp.

bool Alarm::operator== ( const Alarm a) const

Compares two alarms for equality.

Parameters
ais the comparison alarm.

Definition at line 127 of file alarm.cpp.

QString Alarm::parentUid ( ) const

Returns the parent's incidence UID of the alarm.

See also
setParent()

Definition at line 775 of file alarm.cpp.

QDateTime Alarm::previousRepetition ( const QDateTime afterTime) const

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

Parameters
afterTimeis 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 656 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 297 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 279 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 615 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
audioFileis the name of the audio file to play when the alarm is triggered.
See also
setAudioFile(), audioFile()

Definition at line 222 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
audioFileis the name of the audio file to play when the alarm is triggered.
See also
setAudioAlarm(), audioFile()

Definition at line 234 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
textis the description to display when the alarm is triggered.
See also
setText(), text()

Definition at line 445 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
subjectis the email subject.
textis a string containing the body of the email message.
addresseesis Person list of email addresses.
attachmentsis a a QStringList of optional file names of email attachments.
See also
setMailSubject(), setMailText(), setMailAddresses(), setMailAttachments()

Definition at line 302 of file alarm.cpp.

void Alarm::setEnabled ( bool  enable)

Sets the enabled status of the alarm.

Parameters
enableif true, then enable the alarm; else disable the alarm.
See also
enabled(), toggleAlarm()

Definition at line 708 of file alarm.cpp.

void Alarm::setEndOffset ( const Duration offset)

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

Parameters
offsetis 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 752 of file alarm.cpp.

void Alarm::setHasLocationRadius ( bool  hasLocationRadius)

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

Parameters
hasLocationRadiusif true, then this alarm has a location radius.
See also
setLocationRadius()

Definition at line 788 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
locationRadiusradius in meters
See also
locationRadius()

Definition at line 809 of file alarm.cpp.

void Alarm::setMailAddress ( const Person mailAlarmAddress)

Sets the email address of an Email type alarm.

Ignored if the alarm is not an Email type.

Parameters
mailAlarmAddressis 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 319 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
mailAlarmAddressesis 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 333 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
mailAttachFileis 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 382 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
mailAttachFilesis 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 396 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
mailAlarmSubjectis 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 364 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
textis 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 427 of file alarm.cpp.

void Alarm::setParent ( Incidence parent)

Sets the parent Incidence of the alarm.

Parameters
parentis alarm parent Incidence to set.
See also
parentUid()

Definition at line 770 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
programFileis the name of the program file to execute when the alarm is triggered.
argumentsis a string of arguments to supply to programFile.
See also
setProgramFile(), programFile(), setProgramArguments(), programArguments()

Definition at line 252 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
argumentsis a string of arguments to supply to the program.
See also
setProcedureAlarm(), setProgramFile(), programFile(), programArguments()

Definition at line 284 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
programFileis the name of the program file to execute when the alarm is triggered.
See also
setProcedureAlarm(), programFile(), setProgramArguments(), programArguments()

Definition at line 266 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
alarmRepeatCountis the number of times an alarm may repeat, excluding the initial occurrence.
See also
repeatCount()

Definition at line 604 of file alarm.cpp.

void Alarm::setSnoozeTime ( const Duration alarmSnoozeTime)

Sets the snooze time interval for the alarm.

Parameters
alarmSnoozeTimethe time between snoozes.
See also
snoozeTime()

Definition at line 586 of file alarm.cpp.

void Alarm::setStartOffset ( const Duration offset)

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

Parameters
offsetis 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 724 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
textis the description to display when the alarm is triggered.
See also
setDisplayAlarm(), text()

Definition at line 459 of file alarm.cpp.

void Alarm::setTime ( const QDateTime alarmTime)

Sets the trigger time of the alarm.

Parameters
alarmTimeis the QDateTime alarm trigger.
See also
time()

Definition at line 477 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
typeis the alarm Type to set.
See also
type()

Definition at line 177 of file alarm.cpp.

void Alarm::shiftTimes ( const QTimeZone oldZone,
const QTimeZone newZone 
)

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 (oldZone) of Europe/London, to a new time zone (newZone) 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
oldZonethe time zone which provides the clock times
newZonethe new time zone

Definition at line 574 of file alarm.cpp.

Duration Alarm::snoozeTime ( ) const

Returns the snooze time interval.

See also
setSnoozeTime()

Definition at line 599 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 737 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 472 of file alarm.cpp.

QDateTime Alarm::time ( ) const

Returns the alarm trigger date/time.

See also
setTime()

Definition at line 490 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 697 of file alarm.cpp.

Alarm::Type Alarm::type ( ) const

Returns the Type of the alarm.

See also
setType()

Definition at line 217 of file alarm.cpp.

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

IncidenceBase::virtual_hook()

Definition at line 863 of file alarm.cpp.

Friends And Related Function Documentation

KCALENDARCORE_EXPORT QDataStream& operator<< ( QDataStream s,
const KCalendarCore::Alarm::Ptr  
)
friend

Alarm serializer.

Since
4.12
KCALENDARCORE_EXPORT QDataStream& operator>> ( QDataStream s,
const KCalendarCore::Alarm::Ptr  
)
friend

Alarm deserializer.

Since
4.12

The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Dec 3 2020 22:51:45 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.