Ubuntu.Components.Alarm

Alarm component is a representation of an alarm event. More...

Properties

• date : Date
• daysOfWeek : DaysOfWeek
• enabled : bool
• error : Error
• message : string
• sound : url
• status : Status
• type : AlarmType

Methods

• cancel()
• reset()
• save()

Detailed Description

The Alarm element encapsulates alarm event data. Supports one time and repeating alarms, where repeating can be either daily or weekly on one or several selected days.

The alarm data is validated upon save operation, which can be used to save a new alarm or update existing alarm's properties.

During data validation the alarm properties may suffer changes. These changes will be reported back to each changed property. See what changes can occurr at save function documentation.

Example usage:

import QtQuick 2.4
import Ubuntu.Components 1.2
Rectangle {
width: units.gu(40)
height: units.gu(20)
Alarm{
id: alarm
}
Column {
spacing: units.gu(1)
Row {
spacing: units.gu(1)
Label {
id: date
text: "Date:"
anchors.verticalCenter: parent.verticalCenter
}
TextField {
text: alarm.date.toString()
onAccepted: alarm.date = new Date(text)
}
}
Row {
spacing: units.gu(1)
Label {
id: msg
text: "Message:"
anchors.verticalCenter: parent.verticalCenter
}
TextField {
text: alarm.message
onAccepted: alarm.message = text
}
}
Button {
text: "Save"
onClicked: {
alarm.save();
if (alarm.error != Alarm.NoError)
print("Error saving alarm, code: " + alarm.error);
}
}
}
}

An alarm can be cancelled using cancel function but only if the event has previously been stored in the alarm collection.

The reset function clears the properties of the alarm bringing them to the default values. In this way the same alarm component can be used to save several alarms at the same time.

Note: Do not call reset function on an alarm event object when that was returned by the AlarmModel::get function, as that will reset the alarm cache data!

Property Documentation

The property holds the date the alarm will be triggered. The default value is the current date and time the alarm object was created. Further reset calls will bring the value back to the time the reset was called.

The property holds the days of the week the alarm is scheduled. This property can have only one day set for one time alarms and multiple days for repeating alarms. The following flags can be set:

The default value is Alarm.AutoDetect.

The property specifies whether the alarm is enabled or not. Disable dalarms are not scheduled. The default value is true;

The property holds the error code occurred during the last performed operation.

The property holds the message string which will be displayed when the alarm is triggered. The default value is the localized "Alarm" text.

The property holds the alarm's sound to be played when the alarm is triggered. An empty url will mean to play the default sound.

The defaul tvalue is an empty url.

The property holds the status of the last performed operation. It can take one of the following values:

The notification signal has a parameter specifying the operation the status refers to. The operation can take the following values:

For example an implementation which resets the alarm data whenever the save or cancel operations succeed would look as follows:

Alarm {
onStatusChanged: {
if (status !== Alarm.Ready)
return;
if ((operation > Alarm.NoOperation) && (operation < Alarm.Reseting)) {
reset();
}
}
}

The property holds the type of the alarm, which can have one of the following values:

The default value is Alarm.OneTime.

Method Documentation

The function removes the alarm from the collection. The function will fail for alarms which are not yet registered to the collection.

The operation is asynchronous, and its status is reported through the status property. Further operations should wait till the previous operation is completed. The operation result is stored in the error property.

The function resets the alarm properties to its defaults. After this call the object can be used to create a new alarm event.

Note: do not call this function on alarm objects retrieved from AlarmModel, as calling it will result in the model being out of sync from the alarm database.

Updates or adds an alarm to the alarm collection. The operation aligns properties according to the following rules:

• - the daysOfWeek will be set to the alarm day if the daysOfWeek was set to Alarm.AutoDetect.
• - if the daysOfWeek is set to a day other than the one specified in the date field, the date will be moved ahead to match the day from the daysOfWeek.

The function will fail if

• - the date property is invalid
• - for one time alarm, the date property falue is earlier than the current time
• - the daysOfWeek property is set to multiple days for one time alarm

The operation is asynchronous, and its status is reported through the status property. Further operations should wait till the previous operation is completed. The operation result is stored in the error property.