31 Days of Mango | Day #3: Alarms and Reminders

Day3-RemindersDay2-DeviceStatusDay1-EmulatorTools

This article is Day #3 in a series called the 31 Days of Mango.

Today, we are going to discuss how we can set alarms and reminders on a user’s phone.  These reminders can be completely managed by our application, which means we can create, edit, and delete them as the need arises.

How Reminders Work

Reminders on Windows Phone are a way to alert your user that something needs to be done.  The obvious applications of a reminder are an alarm clock, a calendar, or a to-do list.  However, reminders can be used for a variety of applications, and are even a handy tool for reminding your user to jump back into your app.  Here’s a look at an example of a reminder you could launch on your user’s phone:

image

How To Create a Reminder

Creating a reminder is relatively simple.  You create a new Reminder object, tack on the properties that are important to you, and then add it to the ScheduledActionService that is running on your user’s phone.  Below is the source code for a fully-functioning reminder (the one in the screenshot above).  After the code, I’ll walk through each piece in detail.  Please note that I have added an additional using statement to the top of my page:  Microsoft.Phone.Scheduler.

using System;
using Microsoft.Phone.Controls;
using Microsoft.Phone.Scheduler;

namespace Day3_Reminders
{
    public partial class MainPage : PhoneApplicationPage
    {
        // Constructor
        public MainPage()
        {
            InitializeComponent();

            Reminder r = new Reminder("testreminder");
            r.Title = "A Special Reminder";
            r.Content = "Jeff Blankenburg’s Reminder";
            r.NavigationUri = new Uri("/ReminderPage.xaml", UriKind.Relative);
            r.BeginTime = DateTime.Now.AddSeconds(15);
            r.ExpirationTime = DateTime.Now.AddDays(7);
            r.RecurrenceType = RecurrenceInterval.Daily;

            ScheduledActionService.Add(r);
        }
    }
}
 

Naming Your Reminder

The first line of Reminder code requires you to name your Reminder.  In the example above, we named ours “testreminder.”  Each Reminder (and Alarm, which we cover later) must have a name, and we will use this name to manage our events in the future.  Each Reminder/Alarm must have a unique name, so keep this in mind as you’re building your app.  If the name doesn’t matter to you, or you don’t plan on managing these events, you can use a simple timestamp as your name, which should guarantee a unique name each time.

App Name, Title and Content

These two text values represent the messages you will see in the box that appears on the user’s screen.  In the image below, I have labeled each of the text values, so you know exactly how your text will appear.

textvalues

As you can see, we don’t really get any control over how the text is displayed, but we do get plenty of space to write it. If the user taps on any portion of these text values, we have the option to take them back into our application using the NavigationUri property.

NavigationUri

The NavigationUri is a relative path to a page of your application.  In our code sample above, we are sending the user to ReminderPage.xaml.  This concept is referred to as “deep linking,” and you will see it used in many of the new APIs that are available to us in Windows Phone 7.5.  The ability to launch your application to a specific page will prove incredibly valuable to both you and your users, and is using this ability is highly recommended.

BeginTime, ExpirationTime, and RecurrenceType

BeginTime is obviously a very important value, because it determines when our Reminder will launch on the user’s device. It takes a DateTime value, as does ExpirationTime.  The ExpirationTime value is not required, but becomes more relevant and useful when we add the concept of a recurrence to our reminders.  Perhaps you build an application that reminds your user to check their blood sugar levels at 1pm each day, but you only want to do it for one week.  You can set the ExpirationTme to be one week from the initial Reminder, and set the RecurrenceType = RecurrenceInterval.Daily.  This will send the same Reminder to the user at the same time each day.  For multiple Reminders per day, you can create several different Reminders at a time.  This will ultimately lead you to the next challenge: managing all of the different reminders on the device.

Managing Your Existing Reminders

Creating one reminder is a simple task.  Managing many reminders and alarms can get tricky fast, however.  If you’ve used the example code above in your own project, you’ve likely encountered an InvalidOperationException that tells you a Reminder with that name already exists.  This is why, when creating a Reminder on your user’s phone, it is important to check and make sure that you haven’t already created it for them.  To do this, we can search for an existing Reminder name, and delete it if it exists.  The following code is exactly the same as my earlier example, except that I check to see if a Reminder with that name already exists, and delete it.

using System;
using Microsoft.Phone.Controls;
using Microsoft.Phone.Scheduler;

namespace Day3_Reminders
{
    public partial class MainPage : PhoneApplicationPage
    {
        // Constructor
        public MainPage()
        {
            InitializeComponent();

            if (ScheduledActionService.Find("testreminder") != null)
                ScheduledActionService.Remove("testreminder");
            
            Reminder r = new Reminder("testreminder");
            r.Title = "A Special Reminder";
            r.Content = "Jeff Blankenburg’s Reminder";
            r.NavigationUri = new Uri("/ReminderPage.xaml", UriKind.Relative);
            r.BeginTime = DateTime.Now.AddSeconds(15);
            r.ExpirationTime = DateTime.Now.AddDays(7);
            r.RecurrenceType = RecurrenceInterval.Daily;

            ScheduledActionService.Add(r);
        }
    }
}
 

This ability to find specific Reminders and Alarms becomes very handy when you need to edit or change an existing reminder that you have created.  To edit a Reminder, you just need to use the Find() method to create a new reference to it, and the Replace() method to save it, like the example below:

if (ScheduledActionService.Find("testreminder") != null)
{
    Reminder r = ScheduledActionService.Find("testreminder") as Reminder;
    r.Title = "This has been edited.";
    r.Content = "This is updated content.";
    r.BeginTime = DateTime.Now.AddSeconds(15);

    ScheduledActionService.Replace(r);
}
 

How To Create an Alarm

Alarms are nearly identical to Reminders, with a couple of exceptions.  First, Alarms can’t specify a Title property, and they also can’t use the NavigationUri property.  What they can do, however, is play a custom sound, something Reminders can’t do.  In every other way, Alarms and Reminders are identical.  We manage them the same way (using the ScheduledActionService), which allows us to add, edit, and delete them as needed.  Here’s some sample code for creating an Alarm, using the lessons we’ve already learned about Reminders:

if (ScheduledActionService.Find("testalarm") != null)
ScheduledActionService.Remove("testalarm");

Alarm a = new Alarm("testalarm");
a.Content = "Jeff Blankenburg’s Alarm";
a.Sound = new Uri("button-8.mp3", UriKind.Relative);
a.BeginTime = DateTime.Now.AddSeconds(15);
a.ExpirationTime = DateTime.Now.AddDays(7);
a.RecurrenceType = RecurrenceInterval.Daily;

ScheduledActionService.Add(a);
 

As you can see, even the syntax is identical to a Reminder.  For the Sound property, I am referencing an MP3 file that I included in my project.  Day #20 of my 31 Days of Silverlight series covers exactly how to include an audio file in your project, and even how to call it from click events.  Make sure to give that read if you need more information on this.

Summary

To wrap up, Reminders and Alarms are a great way to notify your user that the time has come to do something.  While very similar, it’s important to remember that Reminders allow you to provide a link back into your application, even to a specific page, if you need.  This is an important and effective way to get your user back into your app, and it makes it much easier for your user to find what they need.

To see a complete working application that uses all of the code and concepts from this article, click the “Download the Code” image below.

download

Tomorrow, I am going to walk through a newly available sensor in Windows Phones: the Compass.  I’ll even show how magnets can affect it dramatically. See you then!

toolsbutton

19 thoughts on “31 Days of Mango | Day #3: Alarms and Reminders

  1. Pingback: Mango开发31日谈#3:Alarms和Reminders « Tmango

  2. Pingback: 31 Days of Mango | Day #4: Compass « Blankenblog

  3. hello, I don’t understand when does this code loads the screen uri ReminderPage.xaml
    when I click the ‘reminder button’ it loads the reminder popup, and if I click anywhere inside the reminder it doesn’t open the ReminderPage.xaml uri-window
    Thanks
    Manu

    • Manuel, did you create a page in your application called ReminderPage.xaml? It won’t work if you don’t have a page with that name.

      • hello Jeff, yes, I used the project from the ‘download code’ link available here,…. the app works well, shows the reminder on my phone but it never shows the window ‘ReminderPage.xaml (You’ve been reminded!)’ … I click everywhere/buttons inside the reminder and it returns to the app with the 3 buttons and that’s all it does

      • Manual, The ReminderPage.Xaml will only show up when the app is not active.

      • oh yes, you’re right Marinus, thanks!

  4. Pingback: The Morning Brew - Chris Alcock » The Morning Brew #974

  5. Pingback: 31 Days of Mango « Blankenblog

  6. Pingback: 31 Tage Mango | Tag #3: Alarme und Erinnerungen | leitning.de

  7. Pingback: 31 Days of Mango | Day #5: Gyroscope « Blankenblog

  8. Pingback: День #3 « Rybin Dmitry's Blog

  9. Pingback: День #3 « Rybin Dmitry's Blog

  10. Pingback: Osman Gafarov : 31 день с Mango. День #3. Сигналы и напоминания

  11. Pingback: La Liga Silverlight | Día 3: Alarmas y Reminders

  12. Pingback: WP Astuces » Compte rendu des 31 jours de Windows Phone Mango – Partie 1

  13. Hi jeff,

    How to achieve single alarm for random days in a week . Can we able to override recurrence type class. please suggest on this

  14. How can we set multiple reminders without removing the already created reminder?

  15. I think you can create and add multiple reminders at the same time having different titles, using the code given in this blog repeatedly.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s