The trick in writing a first Windows Phone application is to build something interesting enough to be meaningful, yet simple enough to actually get underway. Toward that end, I’ll walk you through creating a simple utility that I use every day: NoteToMe. The idea is that you can enter a message and send it to yourself by pressing one button, as shown in Figure 1.
Figure 1 The NoteToMe Interface
Note that this article will touch on a number of topics, each of which will be expanded upon at some length in subsequent articles. These topics include:
Before you can begin, you’ll need to download the tools from create.msdn.com. If you’ve already unlocked your phone but not yet upgraded to Windows Phone 7.5 (“Mango”), now is the time to do so; Mango brings hundreds of new features to the Windows Phone OS.
Like many Windows Phone developers, I’ve come to believe that the best tool for creating Windows Phone applications is a combination of Visual Studio (for code) and Expression Blend (for everything else). Thus, we’ll begin by opening Expression Blend and creating a new application named NoteToMe, based on the Windows Phone SDK 7.1.
Let’s start by changing the application title. Click on the title, and in the Properties window find the Text property for that control. The Metro design guidelines (the design guidelines for Windows Phone) call for the title to be in all caps, so change the title to NOTE TO ME.
Click on the page title and hit Delete to remove it.
To create the layout, you’ll need a small row near the top of the page. Click in the margin to bring up a guideline that helps you visually select where to place the row, as shown in Figure 2.
Figure 2 Placing the Top Row of the Layout
Of course, you can set the row size by hand directly in the XAML:
The asterisk after the value indicates relative sizing—in this case 1:9. That is, the first row will be one-ninth of the size of the second row.
The top row will have three controls in it, side by side:
This design is shown in Figure 3.
Figure 3 Three Controls in the Top Row
You can’t put three controls into a single column of a row without putting them inside some sort of organizing container. I’ll use a StackPanel whose orientation has been set to horizontal—StackPanels stack on top of each other or next to each other.
To create a StackPanel, click on the tiny white arrow next to the Layout control on the toolbar as shown in Figure 4.
Figure 4 Adding a StackPanel
Click on the StackPanel to select the control. Now drag a StackPanel into the row and set its vertical and horizontal alignment to stretch and its margins to zero in the Layout window as shown in Figure 5.
Figure 5 Placing the StackPanel
Add the TextBlock, setting its font size to 32, and its text to To. Now drag a TextBox onto the StackPanel. (Note the important but subtle difference between a TextBlock, for displaying text, and a TextBox, for text input.) Name this TextBox Address. Finally, add a button to the StackPanel, name it Send and set its Content to Send.
The XAML this produces is shown in Figure 6.
Figure 6 Designing the StackPanel with XAML
Notice the Send button has a Click=“Send_Click” property. You create this by clicking on the button, then in the Properties window, you click on the Events button, as shown in Figure 7.
Figure 7 The Events Button
This opens all the events for the button. Find the click event and double-click. The button is updated with the event, and you’re placed in the code editor (either in Blend or in Visual Studio, depending on how you have Blend set up) for that event handler. For now, you can leave this event handler as is:
Click on the TextBox control in the toolbar and then drag a TextBox out to fill half of the remaining page (we’re leaving the other half for the keyboard, which will appear when it’s time to enter something in the TextBox). Set the HorizontalAlignment to Stretch, the VerticalAlignment to Top, the margins to 0. Set the Width to Automatic and the height to 244. You can do all this by eye as you resize the TextBox, or you can draw the TextBox roughly in place and set the properties in the Properties window as shown in Figure 8.
Figure 8 Adding the TextBox
With the controls in place, you’re ready to work on the logic of the program. You should see a tab called Projects in the upper left corner. After saving all your changes, click the Projects tab, then right-click on MainPage.xaml.cs and select Edit In Visual Studio, as shown in Figure 9.
Figure 9 Getting Ready to Write the Code
My (self-imposed) specification says you shouldn’t have to fill in the To field each time you use the program; the To field should be prepopulated with whatever was in the To field the previous use.
Moreover, when you click Send, a new e-mail message should be prepared for your e-mail program, with all the fields prepopulated so that you can just press Send or, optionally, edit the message and then press Send.
To preserve the contents of the To field across usages of the application, you need to store the contents somewhere on the phone. This is what Isolated Storage is for: persisting data when the application is closed. As its name implies, Isolated Storage allows your application to store data isolated and protected from data stored by other applications. Using Isolated Storage is fairly straightforward.
First, add the using statement:
Declare a member variable of type IsolatedStorageSettings and a constant string to act as a key into the Isolated Storage dictionary so you can store and retrieve the e-mail address:
The two tasks related to Isolated Storage are storing the string and retrieving it. Storing it is best done as you leave the page. When you leave any Windows Phone page, the method OnNavigatedFrom is called. You’re free to override it, and one good reason to do so is to store data in Isolated Storage, like this:
Now you have the e-mail address stored in the _isoSettings dictionary under the IsoKey key. When you return to the page, you can restore this setting. I do this by calling the private helper method RestoreEmailAddress from the constructor:
Notice that I test for the existence of the key in Isolated Storage before trying to restore it—this averts a KeyNotFound exception the first time I run the program. Remember, the first time you run the program you haven’t yet stored anything in Isolated Storage.
When the program is first started, there’s nothing in the Address field. Once the user puts an e-mail address in the address field, that address is stored in Isolated Storage and restored the next time the program is run. If the user changes the address, that new address is the one restored.
Windows Phone 7.5 supports a number of tasks for interacting with built-in phone applications (mail, contact list, the camera and so forth). There are two types of tasks: Launchers and Choosers. Choosers are used to select information and return it to your program (to obtain an e-mail address from the contact list, for example). Launchers are used to launch a program that doesn’t return data.
In this case, you have everything you need to send the message, so you can call the e-mail Launcher and supply the required fields. When you call Show on the e-mail Launcher, the e-mail application will be launched with your data, but you won’t get any data back (which is fine; you don’t need any).
After the e-mail is sent, you’re returned to the program in case you want to send another message.
All of the work of creating the Launcher is encapsulated within the click event handler for the Send button. Let’s begin by creating an instance of the EmailComposeTask (the Launcher). Fill in the fields and call Show. That’s all there is to it:
When you call Show, the subject, address and body of the message are passed to your e-mail application. If you have more than one e-mail application, you’re asked which one you’d like to use. A properly addressed and formatted e-mail message is created, ready for you to send.
If users could be relied on to never interrupt their use of your application until they sent the message, you’d be done. In reality, though, users will stop right in the middle of composing a message and launch a different application. When they return, they won't be happy if the work they did is gone.
To know how to protect against this, you need to understand a bit about the lifecycle of an application, and how you can preserve state while still supporting one of the most powerful features of Mango: Fast Application Switching.
When your application is launched (say from the Start menu), the Application Launching event is fired. Once the application is started, and every time the user navigates to your page, the OnNavigatedTo method is called, after which your page will be in the Running state. If the user starts a new application, your application receives the Application Deactivated event and is put in the dormant state. If the phone runs low on memory, your application may be tombstoned.
From either tombstoned or dormant, your application may be terminated or it may be restored. What we care about right now is what happens when your application is restored.
If your application is dormant, you not only don’t have to take any action when it’s restored, but you also don’t want to take any action; the state was preserved when the application was dormant, and it’s ready to go.
If your application was tombstoned, though, then you do want to restore your page state when the application returns so that it appears to the user that the application was running (or at least dormant) while it was switched away.
You therefore face two tasks:
Because you can’t know, when the page receives the OnNavigatedFrom, what state it will be in when it’s restored, you must store the state in case it will be needed. This is very easy to do: you use a State dictionary that’s very much like the Isolated Storage dictionary in its syntax, though you want to remember that the State dictionary is not written to permanent storage and is in fact destroyed when you exit the program or turn off the phone.
Let’s start by creating a constant string StateKey, which you’ll use as the offset into the State dictionary:
In the OnNavigatedFrom method, you’ll store the state (in this case, the contents of the MessageBox) into the State dictionary:
When the OnNavigatedTo method is called, you don’t want to take any action to restore State if the app was dormant, but you do want to take action if it was tombstoned.
You can distinguish between the dormant or tombstoned state by setting a flag to false, and then setting it to true in the constructor. If the app is dormant, the constructor will not be called; if it was tombstoned, the constructor will be called (because it will be the first time it’s constructed), like so:
You can check that flag in OnNavigatedTo:
This test saves the time it would otherwise take to restore the value from the State dictionary. You can test this by first running your program normally (in which case when you switch to another application your program will go dormant) and then forcing the program to be tombstoned. You can force your program to be tombstoned by right-clicking on the project, choosing Properties, choosing the Debug tab and checking the checkbox Tombstone upon deactivation while debugging.
When you run with this checked, you’ll see a noticeable pause when returning to the page because the state must be restored.
In this brief article, I’ve shown you how to write your first non-trivial Windows Phone application. I began by creating the application in Expression Blend, where I created a row and used a StackPanel to lay out the controls.
I then switched to Visual Studio to write the logic for the button’s event handler, and used Isolated Storage to persist the e-mail address. I used State memory to ensure that the application would restart properly after being tombstoned.
As noted, there’s much more to say on each of these topics, and they’ll be covered in detail in future articles.
Jesse Liberty is a senior developer-community evangelist on the Windows Phone team. Liberty hosts the popular Yet Another Podcast (jesseliberty.com/podcast), and his blog (jesseliberty.com/) is required reading. He’s the author of numerous best-selling books, including “Programming Reactive Extensions and LINQ” (Apress, 2011) and “Migrating to Windows Phone,” (Apress, 2011). You can follow Liberty on Twitter at twitter.com/JesseLiberty.
Thanks to the following technical experts for reviewing this article: Drew Batchelor and Cheryl Simmons
Why are the code snippets no longer on this page?
Hello I am trying to develop an application with a Passcode page as authentication into the app. I believe this thread will help me achieve that, however I am not sure where exactly to insert the code snippets mentioned above. Please let me know if it is possible to share the code associated with the above application. Regards, Kartheek Pathuri
No, you cannot run this application in the emulator. It needs to be ran on an actual phone.
Apologies for a dumb question from a noob WinPhone developer. I created this app and ran it in the WinPhone 7.5 emulator. But when I press the Send button, I just get a message saying that I need to set up an "account". I presume this means an email account. But I can't find any instructions in how to do this in the emulator. One website I found says that email is not supported in the emulator. Is that correct? This app cannot be tested with the emulator?
More MSDN Magazine Blog entries >
Browse All MSDN Magazines
Subscribe to MSDN Flash newsletter
Receive the MSDN Flash e-mail newsletter every other week, with news and information personalized to your interests and areas of focus.