• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdepimlibs-4.8.3 API Reference
  • KDE Home
  • Contact Us
 

KCalCore Library

  • KCalCore
  • Alarm
Public Types | Public Member Functions | Protected Member Functions
KCalCore::Alarm Class Reference

#include <alarm.h>

Inheritance diagram for KCalCore::Alarm:
Inheritance graph
[legend]

List of all members.

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

Protected Member Functions

virtual void customPropertyUpdated ()
virtual void virtual_hook (int id, void *data)

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


Member Typedef Documentation

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

List of alarms.

Definition at line 81 of file alarm.h.

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

A shared pointer to an Alarm object.

Definition at line 76 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 65 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 103 of file alarm.cpp.

Alarm::Alarm ( const Alarm &  other)

Copy constructor.

Parameters:
otheris the alarm to copy.

Definition at line 108 of file alarm.cpp.

Alarm::~Alarm ( ) [virtual]

Destroys the alarm.

Definition at line 113 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:
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 357 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.

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

 @see setMailAttachment(), setMailAttachments(), mailAttachments()

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

void Alarm::customPropertyUpdated ( ) [protected, virtual]

The default implementation does nothing: override in derived classes to perform change processing.

Reimplemented from KCalCore::CustomProperties.

Definition at line 792 of file alarm.cpp.

Duration Alarm::duration ( ) const

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

Definition at line 632 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 731 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 777 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 697 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 759 of file alarm.cpp.

bool Alarm::hasLocationRadius ( ) const

Returns true if alarm has location radius defined.

See also:
setLocationRadius()

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

bool Alarm::hasTime ( ) const

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

Definition at line 580 of file alarm.cpp.

int Alarm::locationRadius ( ) const

Returns the location radius in meters.

See also:
setLocationRadius()

Definition at line 832 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 370 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 433 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 388 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 451 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:
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 638 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:
preTimedate/time from where to start
ignoreRepetitionsdon't take repetitions into account
See also:
nextRepetition()

Definition at line 518 of file alarm.cpp.

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

Compares two alarms for inequality.

Parameters:
ais the comparison alarm.

Definition at line 185 of file alarm.cpp.

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

Copy operator.

Definition at line 118 of file alarm.cpp.

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

Compares two alarms for equality.

Parameters:
ais the comparison alarm.

Definition at line 140 of file alarm.cpp.

QString Alarm::parentUid ( ) const

Returns the parent's incidence UID of the alarm.

See also:
setParent()

Definition at line 787 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:
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 668 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 308 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 290 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 627 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 233 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 245 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 456 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 313 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 720 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 764 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 800 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 821 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:
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 330 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 344 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 393 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.

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

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

Definition at line 407 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 375 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 438 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 782 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 263 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 295 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 277 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 616 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 598 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 736 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 470 of file alarm.cpp.

void Alarm::setTime ( const KDateTime &  alarmTime)

Sets the trigger time of the alarm.

Parameters:
alarmTimeis the KDateTime alarm trigger.
See also:
time()

Definition at line 488 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 190 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:
oldSpecthe time specification which provides the clock times
newSpecthe new time specification

Definition at line 585 of file alarm.cpp.

Duration Alarm::snoozeTime ( ) const

Returns the snooze time interval.

See also:
setSnoozeTime()

Definition at line 611 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 749 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 483 of file alarm.cpp.

KDateTime Alarm::time ( ) const

Returns the alarm trigger date/time.

See also:
setTime()

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

Alarm::Type Alarm::type ( ) const

Returns the Type of the alarm.

See also:
setType()

Definition at line 228 of file alarm.cpp.

void Alarm::virtual_hook ( int  id,
void *  data 
) [protected, virtual]

Parameters:
idis any integer unique to this class which we will use to identify the method to be called.
datais a pointer to some glob of data, typically a struct.

Reimplemented from KCalCore::CustomProperties.

Definition at line 837 of file alarm.cpp.


The documentation for this class was generated from the following files:
  • alarm.h
  • alarm.cpp
This file is part of the KDE documentation.
Documentation copyright © 1996-2012 The KDE developers.
Generated on Mon May 7 2012 23:54:02 by doxygen 1.8.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

KCalCore Library

Skip menu "KCalCore Library"
  • Main Page
  • Namespace List
  • Namespace Members
  • Alphabetical List
  • Class List
  • Class Hierarchy
  • Class Members
  • File List
  • File Members
  • Related Pages

kdepimlibs-4.8.3 API Reference

Skip menu "kdepimlibs-4.8.3 API Reference"
  • akonadi
  •   contact
  •   kmime
  • kabc
  • kalarmcal
  • kblog
  • kcal
  • kcalcore
  • kcalutils
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  •   nntp
  • kldap
  • kmbox
  • kmime
  • kontactinterface
  • kpimidentities
  • kpimtextedit
  •   richtextbuilders
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal