Ubuntu.Components.Alarm

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

Import Statement: import Ubuntu.Components 1.3

Properties

Methods

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

date : Date

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.


daysOfWeek : DaysOfWeek

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:

Alarm.DayOfWeek enum:
TypeValueDescription
Alarm.Monday0x01The alarm will kick on Mondays.
Alarm.Tuesday0x02The alarm will kick on Tuesdays.
Alarm.Wednesday0x04The alarm will kick on Wednesdays.
Alarm.Thursday0x08The alarm will kick on Thursdays.
Alarm.Friday0x10The alarm will kick on Fridays.
Alarm.Saturday0x20The alarm will kick on Saturdays.
Alarm.Sunday0x40The alarm will kick on Sundays.
Alarm.AutoDetect0x80The alarm day will be detected from the alarm date at the time the alarm is saved.

The default value is Alarm.AutoDetect.


enabled : bool

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


error : Error

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

Error codeValueDescription
NoError0Successful operation completion.
InvalidDate1The date specified for the alarm was invalid.
EarlyDate2The date specified for the alarm is an earlier date than the current one.
NoDaysOfWeek3The daysOfWeek parameter of the alarm was not specified.
OneTimeOnMoreDays4The one-time alarm was set to be kicked in several days.
InvalidEvent5The alarm event is invalid.
AdaptationError100The error occurred in alarm adaptation layer. Adaptations may define additional behind this value.

message : string

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


sound : http://doc.qt.io/qt-5/qml-url.html">url

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.


status : Status

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

Status codeValueDescription
Ready1Specifies either that the Alarm object is ready to perform any operation or that the previous operation has been successfully completed.
InProgress2Specifies that there is an operation pending on Alarm object.
Fail3Specifies that the last alarm operation has failed. The failure code is set in error property.

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

Operation codeDescription
NoOperationThere is no operation pending. This may be set when an error occured in the alarm adapters and the operation cannot be determined.
SavingThe status reported refers to an operation requested through save().
CancelingThe status reported refers to an operation requested through cancel().
ResetingThe status reported refers to an operation requested through reset().

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();
}
}
}

type : AlarmType

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

Alarm.AlarmType enum:
TypeDescription
Alarm.OneTimeThe alarm occurs only once.
Alarm.RepeatingThe alarm is a repeating one, either daily, weekly on a given day or on selected days.

The default value is Alarm.OneTime.


Method Documentation

cancel()

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.


reset()

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.


save()

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.