KCalendarCore::Alarm

Search for usage in LXR

#include <alarm.h>

Inheritance diagram for KCalendarCore::Alarm:

Public Types

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

Public Member Functions

 Alarm (const Alarm &other)
 
 Alarm (Incidence *parent)
 
 ~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 ()
 

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 50 of file alarm.h.

Member Typedef Documentation

◆ List

List of alarms.

Definition at line 72 of file alarm.h.

◆ Ptr

A shared pointer to an Alarm object.

Definition at line 67 of file alarm.h.

Member Enumeration Documentation

◆ 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 56 of file alarm.h.

Constructor & Destructor Documentation

◆ Alarm() [1/2]

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() [2/2]

Alarm::Alarm ( const Alarm & other)

Copy constructor.

Parameters
otheris the alarm to copy.

Definition at line 82 of file alarm.cpp.

◆ ~Alarm()

Alarm::~Alarm ( )
override

Destroys the alarm.

Definition at line 88 of file alarm.cpp.

Member Function Documentation

◆ addMailAddress()

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 344 of file alarm.cpp.

◆ addMailAttachment()

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 407 of file alarm.cpp.

◆ audioFile()

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 248 of file alarm.cpp.

◆ customPropertyUpdated()

void Alarm::customPropertyUpdated ( )
overrideprotectedvirtual

◆ duration()

Duration Alarm::duration ( ) const

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

Definition at line 618 of file alarm.cpp.

◆ enabled()

bool Alarm::enabled ( ) const

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

See also
setEnabled(), toggleAlarm()

Definition at line 714 of file alarm.cpp.

◆ endOffset()

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 760 of file alarm.cpp.

◆ endTime()

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 680 of file alarm.cpp.

◆ hasEndOffset()

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 742 of file alarm.cpp.

◆ hasLocationRadius()

bool Alarm::hasLocationRadius ( ) const

Returns true if alarm has location radius defined.

See also
setLocationRadius()

Definition at line 799 of file alarm.cpp.

◆ hasStartOffset()

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 737 of file alarm.cpp.

◆ hasTime()

bool Alarm::hasTime ( ) const

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

Definition at line 567 of file alarm.cpp.

◆ locationRadius()

int Alarm::locationRadius ( ) const

Returns the location radius in meters.

See also
setLocationRadius()

Definition at line 815 of file alarm.cpp.

◆ mailAddresses()

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 357 of file alarm.cpp.

◆ mailAttachments()

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 420 of file alarm.cpp.

◆ mailSubject()

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 375 of file alarm.cpp.

◆ mailText()

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 438 of file alarm.cpp.

◆ nextRepetition()

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 623 of file alarm.cpp.

◆ nextTime()

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 505 of file alarm.cpp.

◆ operator!=()

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

Compares two alarms for inequality.

Parameters
ais the comparison alarm.

Definition at line 173 of file alarm.cpp.

◆ operator=()

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

Copy operator.

Definition at line 93 of file alarm.cpp.

◆ operator==()

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

Compares two alarms for equality.

Parameters
ais the comparison alarm.

Definition at line 129 of file alarm.cpp.

◆ parentUid()

QString Alarm::parentUid ( ) const

Returns the parent's incidence UID of the alarm.

See also
setParent()

Definition at line 770 of file alarm.cpp.

◆ previousRepetition()

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 652 of file alarm.cpp.

◆ programArguments()

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.

◆ programFile()

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.

◆ repeatCount()

int Alarm::repeatCount ( ) const

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

See also
setRepeatCount()

Definition at line 613 of file alarm.cpp.

◆ setAudioAlarm()

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 223 of file alarm.cpp.

◆ setAudioFile()

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 235 of file alarm.cpp.

◆ setDisplayAlarm()

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 443 of file alarm.cpp.

◆ setEmailAlarm()

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.

◆ setEnabled()

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 703 of file alarm.cpp.

◆ setEndOffset()

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

◆ setHasLocationRadius()

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 783 of file alarm.cpp.

◆ setLocationRadius()

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 804 of file alarm.cpp.

◆ setMailAddress()

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 317 of file alarm.cpp.

◆ setMailAddresses()

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 331 of file alarm.cpp.

◆ setMailAttachment()

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 380 of file alarm.cpp.

◆ setMailAttachments()

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 394 of file alarm.cpp.

◆ setMailSubject()

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 362 of file alarm.cpp.

◆ setMailText()

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 425 of file alarm.cpp.

◆ setParent()

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 765 of file alarm.cpp.

◆ setProcedureAlarm()

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 253 of file alarm.cpp.

◆ setProgramArguments()

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.

◆ setProgramFile()

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.

◆ setRepeatCount()

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 602 of file alarm.cpp.

◆ setSnoozeTime()

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 584 of file alarm.cpp.

◆ setStartOffset()

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 719 of file alarm.cpp.

◆ setText()

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 457 of file alarm.cpp.

◆ setTime()

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 475 of file alarm.cpp.

◆ setType()

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 178 of file alarm.cpp.

◆ shiftTimes()

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 572 of file alarm.cpp.

◆ snoozeTime()

Duration Alarm::snoozeTime ( ) const

Returns the snooze time interval.

See also
setSnoozeTime()

Definition at line 597 of file alarm.cpp.

◆ startOffset()

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 732 of file alarm.cpp.

◆ text()

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 470 of file alarm.cpp.

◆ time()

QDateTime Alarm::time ( ) const

Returns the alarm trigger date/time.

See also
setTime()

Definition at line 488 of file alarm.cpp.

◆ toggleAlarm()

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 692 of file alarm.cpp.

◆ type()

Alarm::Type Alarm::type ( ) const

Returns the Type of the alarm.

See also
setType()

Definition at line 218 of file alarm.cpp.

◆ virtual_hook()

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

IncidenceBase::virtual_hook()

Definition at line 847 of file alarm.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:13:47 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.