Name

scheduleMessage — schedule a new alarm message.

Synopsis

bool scheduleMessage(const QString& message, const QDateTime& dateTime, const QColor& bg, const QColor& fg, int flags, const QString& audioURL, int reminder, const QString& recurrence)
bool scheduleMessage(const QString& message, const QDateTime& dateTime, const QColor& bg, const QColor& fg, const QFont& font, int flags, const QString& audioURL, int reminder, const QString& recurrence)
bool scheduleMessage(const QString& message, const QDateTime& dateTime, const QColor& bg, const QColor& fg, int flags, const QString& audioURL, int reminder, int simpleRepeatType, int interval, int repeatCount)
bool scheduleMessage(const QString& message, const QDateTime& dateTime, const QColor& bg, const QColor& fg, int flags, const QString& audioURL, int reminder, int simpleRepeatType, int interval, const QDateTime& endTime)

Parameters

message

Specifies the text of the message to be scheduled.

dateTime

Specifies the scheduled date and time at which the message should be displayed.

bg

Specifies the background color for displaying the message.

fg

Specifies the foreground color for displaying the message.

font

Specifies the font for displaying the message.

flags

Specifies the logical OR of the desired alarm message flags. The flag bits are those defined in class KAEvent in alarmevent.h

audioURL

Specifies the name or URL of an audio file which is to be played when the message is displayed.

reminder

Specifies the number of minutes in advance of the main alarm and of each of its recurrences (if any) at which a reminder alarm should be displayed. Specify 0 if no reminder is required.

recurrence

Specifies a regular recurrence for the alarm, using iCalendar syntax as defined in RFC2445. For example, “FREQ=MONTHLY;COUNT=4;INTERVAL=3;BYDAY=-1MO” would specify 4 repetitions at 3-monthly intervals on the last Monday of the month. For a non-recurring alarm, specify an empty string.

simpleRepeatType

Specifies the recurrence type for the alarm. The permissible values are MINUTELY, DAILY, WEEKLY, MONTHLY_DAY, ANNUAL_DATE. These are defined in class KAEvent in alarmevent.h.

interval

Specifies the number of periods (minutes/days/weeks/months/years) between repetitions of the alarm message.

repeatCount

Specifies the number of times that the alarm message should be displayed. Specify -1 to repeat the alarm indefinitely.

Description

scheduleMessage() is a DCOP call to schedule the specified alarm message for display at the specified date and time. It has several forms. The two most general forms allow an arbitrary recurrence to be specified - use these also for non-repeating alarms. Either specify a font parameter, or none to use KAlarm's default font. The other forms provide convenient access to a restricted set of alarm recurrence types, one specifying a repetition count and the other an end time; both of these use the default font.

If the scheduled time (including any repetitions) has already passed, KAlarm immediately displays the message or, if the LATE_CANCEL flag bit is set, ignores the request. If the scheduled time (or a repetition) is in the future, KAlarm adds the alarm message to the calendar file for later display.

Use a code sequence similar to the following to set up the parameter data for the DCOP call to scheduleMessage() for a non-recurring alarm, or for a regularly recurring alarm using iCalendar syntax to specify its recurrence:

QString message, audioFile, recurrence;
QDateTime dateTime;
QColor bgColor, fgColor;
Q_UINT32 flags;
Q_INT32 reminder;
. . .
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << message;
arg.writeRawBytes((char*)&dateTime, sizeof(QDateTime));
arg.writeRawBytes((char*)&bgColor, sizeof(QColor));
arg.writeRawBytes((char*)&fgColor, sizeof(QColor));
arg << flags << audioFile << reminder << recurrence;

Use a code sequence similar to the following to set up the parameter data for the DCOP call to scheduleMessage() for a regularly recurring alarm without using iCalendar syntax:

QString message, audioFile;
QDateTime dateTime;
QColor bgColor, fgColor;
Q_UINT32 flags;
Q_INT32 reminder, repeatType, repeatCount, repeatInterval;
. . .
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << message;
arg.writeRawBytes((char*)&dateTime, sizeof(QDateTime));
arg.writeRawBytes((char*)&bgColor, sizeof(QColor));
arg.writeRawBytes((char*)&fgColor, sizeof(QColor));
arg << flags << audioFile << reminder << repeatType << repeatCount << repeatInterval;