http://docs.kde.org/
PrevD-Bus InterfaceNext

Name

scheduleMessage — schedule a new alarm message.

Synopsis

bool scheduleMessage(const QString& name,
                     const QString& message,
                     const QString& startDateTime,
                     int lateCancel,
                     unsigned flags, 
                     const QString& bgColor, 
                     const QString& fgColor, 
                     const QString& font, 
                     const QString& audioURL, 
                     int reminderMins, 
                     const QString& recurrence,
                     int subRepeatInterval, 
                     int subRepeatCount)

bool scheduleMessage(const QString& name,
                     const QString& message,
                     const QString& startDateTime, 
                     int lateCancel,
                     unsigned flags, 
                     const QString& bgColor, 
                     const QString& fgColor, 
                     const QString& font, 
                     const QString& audioURL, 
                     int reminderMins, 
                     int recurType, 
                     int recurInterval, 
                     int recurCount)

bool scheduleMessage(const QString& name,
                     const QString& message,
                     const QString& startDateTime, 
                     int lateCancel, 
                     unsigned flags, 
                     const QString& bgColor, 
                     const QString& fgColor, 
                     const QString& font, 
                     const QString& audioURL, 
                     int reminderMins, 
                     int recurType, 
                     int recurInterval, 
                     const QString& endDateTime)

Parameters

name

Specifies an optional name for the alarm.

message

Specifies the text of the message to be scheduled, or if flags has the DISPLAY_COMMAND bit set, specifies the command line to execute to generate the message text.

startDateTime

Specifies the scheduled date, or date and time, at which the message should be displayed. For a date-only alarm, the string should be in the format YYYY-MM-DD[ TZ] (as returned by QDate::toString(Qt::ISODate)). For an alarm with a date and time, the string should be in the format YYYY-MM-DDTHH:MM[:SS][ TZ] (as returned by QDateTime::toString(Qt::ISODate)) or HH:MM[:SS] (as returned by QTime::toString(Qt::ISODate)). If no date is specified, today's date is used. Note that any seconds value is ignored.

If no time zone is specified, the local system time zone is assumed. If a time zone specifier TZ is present, it may be the name of a system time zone (e.g. Europe/London), or UTC representing the UTC time zone.

lateCancel

Causes the alarm to be canceled if it cannot be triggered within the specified number of minutes after the alarm's scheduled time. If the value is 0, the alarm will not be canceled no matter how late it is triggered.

flags

Specifies the logical OR of the desired alarm flags. The flag bits are those defined in class KAlarmIface in kalarmiface.h. Note that not all flag bits are applicable to message alarms.

bgColor

Specifies the background color for displaying the message. The string may be in the format “#RRGGBB” (as returned by QColor::name()) where RR, GG and BB are two-digit hexadecimal values for red, green and blue. Alternatively the string may be in any of the other formats accepted by QColor::setNamedColor(), such as a name from the X color database (e.g. “red” or “steelblue”). Set the string to null to specify the current default background color.

fgColor

Specifies the foreground color for displaying the message. The format of the string is the same as for bgColor, or alternatively set the string to null to specify the current default foreground color.

font

Specifies the font for displaying the message. The format of the string is that output by QFont::toString(). Set the string to null to use the default message font current at the time the message is displayed.

audioURL

Specifies the audio file which is to be played when the message is displayed. Set the value to null if no audio file is to be played.

reminderMins

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 a negative value for a reminder to be displayed after the main alarm. 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.

recurType

Specifies the recurrence type for the alarm. The permissible values are MINUTELY, DAILY, WEEKLY, MONTHLY, YEARLY. These are defined in class KAlarmIface in kalarmiface.h. Monthly recurrences are of the day of the month type, and yearly recurrences are of the date in the year type, with the date in both cases taken from the startDateTime parameter.

recurInterval

Specifies the number of periods (minutes/days/weeks/months/years as specified by recurType) between recurrences of the alarm.

recurCount

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

endDateTime

Specifies the end date, or date and time, for recurrences of the alarm. If startDateTime includes a time, this parameter must also include a time; if startDateTime contains only a date, this parameter must also contain only a date. It must not contain a time zone specifier; the same time zone as for startDateTime is used to interpret this parameter's value.

subRepeatInterval

Specifies the number of minutes between sub-repetitions of the alarm. Specify 0 for no sub-repetition. Ignored if no recurrence is specified.

subRepeatCount

Specifies the number of sub-repetitions of the alarm, including the initial occurrence.

Description

scheduleMessage() is a D-Bus call to schedule the specified alarm message for display at the specified date and time. It has three forms. The most general form allows an arbitrary recurrence to be specified – use this also for non-repeating alarms. 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.

If the scheduled time (including any repetitions) has already passed, KAlarm immediately displays the message (unless the lateCancel value indicates that it is now too late to display the alarm, in which case KAlarm ignores the request). If the scheduled time (or a repetition) is in the future, KAlarm adds the alarm message to the default active alarm calendar for later display.