Registering at the App Hub

Before you can submit an app to the market place, you first need to register for “App Hub” membership. You do this by going to http://create.msdn.com. This essentially is a vibrant community of app and game developers for both Windows Phone and XBOX live games. The hub provides free tools, information, and the community you need to create and publish beautiful apps and games that reach every Windows Phone user and XBOX live members worldwide. Here’s how the home screen looks before you sign up

You first need to register for an annual subscription of $99 USD that gives you the following privileges for both the world of phone apps and XBOX.

The registration itself is a 5 step process as noted below and is quite simple. I show some of the screens below as well

Once signed up, the App Hub home screen now looks like the following. Notice the advertisement for the next version of Windows Phone, code named Mango! I can’t wait to upgrade my phone, and have been waiting to finish this tutorial and getting my application published!. My next app will be on Mango!

Also notice that the action on the App Hub are different now – for example, you get the option of “Submitting for Windows Phone”

The App Submission flow

The following diagram captures the flow involved in the app submission process

We have of course so far been focusing on the first step of the process – creating the application in Visual Studio. I have also been developing using the Emulator. Before submitting the application it is of course also very important to test on an actual device. To do this however you will need to “Unlock” the phone. To do this, connect a phone device to your laptop using the USB (charging) cable, and the run the “Windows Phone Developer Registration” application from the Windows Start menu (this application gets installed on your system when you download the phone development tool kit). The application looks like the following – it takes in your Live ID and then “Unlocks” the phone device so that Visual Studio can deploy the phone application binary directly onto the phone device.

In Visual Studio you can select the “Windows Phone 7 Device” as the target for the publishing as shown in the Visual Studio Menu bar below. Now when you build and publish, the application will be deployed on the device and you can do your pre-certification device testing there. The application of course worked well for me there.

The Certification Process

The certification process is of course the most important part of the submission. The goal is to ensure that before any application or game is taken into the market place, it is certified that the application is reliable, it makes efficient use of device resources, the do not adversely interfere with the device functionality, and that they are free of any malicious software.

The full certification and submission process is as outlined below.

The flow through the certification process

The following screen shots show the flow, as I proceeded with each step of the certification process.

The submission process starts with the “Upload” step where you select the name of the application, give it a version number, and point to the .XAP file in the bin\release directory where Visual Studio builds the application. Note that the entire application is contained in single binary manifest file of extension XAP. This is shown below.

On hitting next on this screen, the submission process found one error – that my application did not have the locale information marked correctly. At this point I had to add the following lines to the MainPage.xaml.cs to mark the locale as “English”, recompile the application to regenerate the XAP file, test it, and redo the application submission process.

The next step is to describe the application by providing information that will later show up in the application market place.

This information will help potential buyers decide whether they want to try or buy your application or not. Here you choose to describe the category that best describes what the application does, a detailed description, and also key words that will lead an application search to your application. This essentially is your “marketing” collateral for your app.

As part of this step, you are also needed to provide various icons and art work that are used in various places in the market place. Here note that the Large Mobile Tile app is really a mandatory image (as I would learn later) though it is not marked as such. This icon is used when you pin your application to the start page. Likewise the “Background Art” image is mandatory too – it will be used when your application shows up in the market place. You can also submit a set of screen shots for the application and these will further describe and “market” your app when listed in the market place. The most convenient place to capture the screenshots of course is when you test your application on the Emulator. You can use the Windows Snipping tool to capture the screen shots – however, be sure to avoid including any of the Emulator “chrome” in the screen shot – this too I found out later.

The next step is to select the price for your application, and also decide which market placed the app would be listed in. There are three different geographical regions as you see in the image below. Select carefully and check out the defaults – or your application may not show up in the right marketplaces. (Note, each phone user provides a Live ID when they configure their phone for us. The country the Live ID is associated with then becomes the default market place for the “Marketplace” application on the phone.

The next step is to call out a set of testing instructions that will be carried out in the “backend” to make a final validation that the application works as designed. You can also select the publishing option – for example, you can select that the app be published as soon as the validation and certification is done, without any further interventions from you.

The last step then is to click the “Submit” button and submit the application.

You can track the state of the submission on the “My Dashboard” page at “App Hub”. For example, a couple of days later I noticed that my submission had run into issues.

As shown above, the certification had run into errors, and clicking on the “View Error” page leads you to a PDF file with details about the errors. The PDF files looked as follows

In my case all of the errors were related to the images and iconography. I was missing the large mobile tile app, and the background art image, and the application screenshot included the chrome of the Emulator. Also, it called out that one of the icons in my application was still the generic Windows Sunburst icon. I then proceeded to fix the errors and in the process created my own custom icon and images (using Microsoft Paint, and saving them as .PNG files of the different dimensions necessary, as called out in the submission process).

I also had to select the “United States” market place, as apparently in the last submission I had not selected it.

The submission goes through

This time the submission went through without errors – a couple of days later, it was nice to see on the “Dashboard” that the process had worked, the app was in the Marketplace and it showed there were a few downloads too. The dashboard provides you several reports and statistics of your application.

The App shows up in the Marketplace

It was exciting to then checkout the Marketplace on my phone, search for “AmitC”, and have the app show up – and I could install it from there! To capture an image of the app in the market place, I launched the Zune application and searched for the app there – and there it was!

It felt great to build, blog, and publish about this simple Windows Phone application. I hope it has spurred some of the readers to write and publish your own application. I really liked the Visual Studio tooling experience and felt proud of my team which has developed this tooling!

On now to the Mango version of Windows Phone!

Cheers!

A functional change first – clearing the history

However, before I get to unit testing, I would like to add a small feature to the application. This is about clearing the history of the events that get displayed in the Stopwatch page. I do this by adding a “Clear History” menu item to the AppBar and then add a handler for the menu item to do the job.

Here is the change in the XAML to add the menu item – notice the new ApplicationBar.MenuItem – the auto-completion intellisense feature when editing the XAML directly makes is very easy to add these UI elements.

The code for the click handler looks as follows:

The screens below capture how the menu item shows up, and (on clicking) clears up the event list history captured till that point.

Using Jeff Wilcox’s unit testing framework …

For unit testing Windows Phone (and other Silverlight) applications, I recommend using Jeff Wilcox’s framework for unit testing. I highly recommend you watch Jeff’s MIX10 session on this topic from this link. There are some limitations in the here – for example, you cannot unit test controls in the AppBar – but this is a pretty nice framework, and served my purpose of unit testing the application.

Jeff Wilcox’s blog explains the framework and you can also use this link to download the bits needed from the bottom of his blog page. Another useful link that helped me in setting up the framework was this Cheat Sheet.

As explained in the cheat sheet, I add a new Windows Phone project to the solution called WP7ChronomterUT, add a dll folder where I download the unit testing framework (and unblock the files), add references to the two dlls there, and create a new file call MainPageUT.cs where I will add the unit test. I also add a reference to the WP7Chronometer project. Below is a snapshot of how the new project looks – observe the references added.

Few more housekeeping things …

I need to do a few more things before I get to the unit testing.

First, I move the TimeSpanPicker1 style definition from app.xaml (application scope) to MainPage.xaml (main page scope). Please note that this needs to be included in the  <phone:PhoneApplicationPage.Resources> section and that entire section needs to be ahead of the Grid definition in MainPage.XAML. This scope change is being done to avoid some limitations of the unit testing framework.

Second, we need to add a reference to the Coding4Fun.Phone.Controls.Toolkit that we installed via NuGet, to the new unit test project. To do this, you simply click on “Add Library Package Manager Reference” option for adding a new reference, and simply “install” the reference for the above toolkit from the list presented (note, the toolkit will already be listed there since we have installed is as part of the solution).

Third, I need to allow the unit test project access to the internal UI elements in the main application. To allow this, I add the following line at the end of the AssemblyInfo.cs file under ‘Properties’ node of the WP7Chronometer project (the main application)

Launching the unit test framework …

Since the project we are working on is specifically for unit testing, I would like “application” in this case to straightaway launch the unit testing framework and run the unit tests that I will write. To do this, I add the following code to the MainPage.xaml.cs file:

The above code instantiates the unit test framework, sets the root visual of the page to it (that is, what ever it will display), and also hooks up the back button to allow you to return back from drilling into test results.

Note, I also hide the system tray, otherwise it will hide the top of the test results screen.

I have also changed the page title and the application title in the MainPage.xaml file as follows:

Now we can write the actual unit tests …

The framework, once launched as above, will look for a TestClass and TestMethods in the dll as is normal for unit testing. Below I have a set of simple unit tests written up, to verify some of the initial states of the Chronometer application

The code above is pretty self-explanatory, and we are now ready to run the tests

Running the unit tests …

Simply set the WP7ChoronometerUT project as the start up project in the solution, build the solution, and launch it. The unit test framework loads, based on the above start up code, and presents the initial page of instructions as shown on the left below. It allows you the option of choosing the set of tests you want to run via tags (and gives instructions on how the tags work), and also counts down five seconds to choose the default option of running all tests. The screen on the right shows that all of the tests have been run, and all have passed (the green bar at the top). Also note the statistics at the bottom where it says 5 out 5 tests have passed (BTW, to allow this display to come through we disabled the SystemTray earlier).

You can drill down into the tests by clicking on the name MainPageUT (which is the file which has the tests), and you see the lists of tests in that set on the screen below left. You can drill down into each of the tests – for example, clicking on the “CheckifTimerDisplayisZero” shows the screen on the bottom left. It tells you more information about the test, including pass/fail status, and start/end/duration for that test. Also notice that the back button on the phone allows you to navigate back to the previous screen.

Just to give you a sense of how failing tests get reported, I can deliberately make one of the tests fails – for example, changing the Assert.AreEqual in the ‘CheckifTimerDisplayisZero” to Assert.AreNotEqual, and then on building and running the application you get the screens below. The framework calls out the overall status as fail, calls out the test that has failed, and allows you to drill down into why it has failed.

This is all pretty neat! It felt great to experiment with the unit test framework for the phone!

I am almost done with this set of blogs – what remains is to create an account in the marketplace and actually deploy the app! I will come back shortly with that.

Cheers!

As you know, we have been working on great tooling for ALM since 2005, and the last big release was Visual Studio 2010, released in April 2010. The next release that we are working on will continue to build on the strength of the past releases. Our tooling encompasses the entire lifecycle for application development, as shown in the graphic below

With each release, our focus has been on reducing the major sources of failure and waste in the lifecycle. Continuing on that journey, we have major investments in TFS, Test, and advanced tooling coming in the next version. Jason showcased some of these in his keynote at TechEd 2011 Atlanta – please read his blog post on the vNext announcement. We have also put together a whitepaper which provides a great overview of the motivation for vNext and captures some of the highlights and screenshots!

We are continuing to refine the experiences that Jason talked about, and I look forward to writing more about vNext soon!

Cheers!

I have used Expressions Blend in couple of places in the Chronometer application that I have been building. You will find a series of blog posts on the topic, starting here. I find that Blend is a great way to get the styles for the user interface controls just right – rather than simply using the properties of the control, or hand coding the XAML. For example, in the last post, I had introduced the TimeSpanPicker control for the countdown timer feature of the application. The heart of the control is a TextBox control for the input of the initial value of the timer. If you remember, the default definition, and the default look of the control looked as below:

To make the display of the control consistent with the Stopwatch control, I need to change the background color to black, the font to Courier New, font size to 64, and font color to yellow. I could set most of these properties from the properties toolbox of the control in Visual Studio. However, the font size simply would not take effect. This is likely a bug in the phone toolkit, and I will look into it later. However, this led me to Expression Blend, and I found that you can create user interface styling in a really effective manner in there!

To use Expression Blend for designing the UI, simply right click on the MainPage.xaml file and click the “Open in Expression Blend …” menu as shown below.

This launches  Blend in the full design mode for the xaml, as shown below.

You can then navigate to the control you want, by expanding the Objects hierarchy in the bottom left of the tool. Below, I have navigated to the TimeSpanPicker control and have selected it. You can now see the properties of the control in the tool.

Right click on the control, select “Edit Template” and then “Edit a Copy…”, as shown below

Note that in the dialog box on the right you have two options – to define a new style in the context of the application, or just for the page in question. This determines whether the style definition will go into the App.xaml file or in the MainPage.xaml file. I would really like to define the style so that it is available for the entire application, so I will select the “Application” radio button as shown below.

Notice above that the Object hierarchy on the left now shows the components of the TimeSpanPicker control, and I have selected the DateTimeButton control to really select the specific control I want to change properties of. At this point, the properties palette on the right hand side makes it really easy to change the properties. In the screen below I show how I have changed the font to “Courier New” and the size to “48 points”. (I needed to resize the control size to accommodate the larger size).

Next, I change the text foreground to yellow. For this I select the “Foreground” field in the “Brushes” section at the top right of Blend, and then click the little square button next to “foreground”, select “Custom Expressions” and type “yellow” as shown below. As you see, the text changes to yellow.

To change the background, I click the button next to “Background” and this time I choose “System Resource” and then select “PhoneBackroundBrush” to ensure that the background of the control will match the background of the phone. At this point the control looks exactly the way I wanted it to be!

That’s all we needed to do in Expression Blend. We simply hit “File.Save All” in Expression Blend and exit out of Blend. You will now get a pop-up i informing you that the xaml file was edited outside of Visual Studio, as shown below. We will of course accept this change by clicking “Yes to All”.

Notice that the designer in Visual Studio immediately displays the control in the new style.

Also, notice that the definition of the TimeSpanPicker control has also been automatically changed to reference the new static resource TimeSpanPickerStyle1 that we had created in Expression Blend!

If you remember, we had chosen to define the new style in the context of the full application. Hence the definition of the above new style is automatically incorporated in the App.xaml file – as shown below

That’s all. We now compile the application and a quick test shows that the timer functionality is working just fine, and the count down timer display shows correctly, and in the intended style, in both portrait and landscape modes

Expression Blend is very powerful designer tool, and it was fun dabbling with it a bit in building the Windows Phone 7 application!

Cheers!

The concept of the Timer is of course very simple – you put in a text box with a value of hour : minute : second, and then put in some logic to change the values, and count it down to zero. However, I was looking for a control that would allow me to edit the countdown value with a nice experience – like you get when you set the alarm on the Windows phone 7!. I looked around, and found that there is control built by the community – called the TimeSpanPicker – which has the exact functionality I need. However, I would need to load the package, copy down the files, get any dependent packages (if any), add references to my project – and that is a lot of work!

This then provided me the opportunity to talk about the NuGet extension to Visual Studio. NuGet is a beautiful thing! You can read more about it here. It solves exactly the problem I have alluded to above, and I simply include an excerpt from the above link that explains the basic functionality.

Let’s install the Library Package Manager (NuGet) extension. Click Tools and the Extension Manager – you can see below the packages I currently have installed.  

Now, click the Online Gallery tab. Visual Studio now searches the gallery and presents a list of packages, based on their ranking (the community rates the packages). The view on my system is displayed below, and you notice that the NuGet Package Manager is already listed at the top, with a 5-star rating from 70 voters!

Simply click on the Download button to download and install the NuGet Package Manager package. It will download and install (once you accept the license agreement). After the installation you will be prompted to restart Visual Studio. If you now get back to the Extension Manager, you can see that the NuGet Package Manager is now installed.

Now we want to install the WP7 TimeSpanPicker control. For this, we go to the Tool, Library Package Manager, Add Library Package Reference option, and then select the Online tab to be able to pick from a list of packages out there. In the Search box now type “TimeSpan”. I got the following search results

I select the second one in the list (where the description says – “Just the timespan selector …”).

That’s all! The NuGet Package manager now downloads the package and adds references to the control into our project automatically, making it very simple to use the package.

I can now add the following line to the MainPage.xaml file to use the control in my layout – notice the last line in the xaml snippet below

Adding a Countdown timer to the Chronometer

We will now add a Countdown timer to the Chronometer. The way I want this to work is that the Stopwatch will still be the default functionality. However, I would like to slide the Stopwatch page out and get a new “page” where I will have a countdown timer functionality – that is, a control where I can set a time duration (hh : mm : ss), allow the user to start the timer, and then count it down to 00 : 00 : 00 and sound an alert.

Introducing a Pivot Control, and making the Stopwatch a PivotItem

Once I add the Countdown timer, the Chronometer application will have two discrete features – the Stopwatch and the Countdown timer. On the Windows Phone 7, we have two different controls – the Pivot Control and the Panorama Control – that will allow me to arrange these two discrete features horizontally in a virtual space that is several times wider than the width of the phone. I can then move through the controls – and hence the two feature areas – by simply sweeping the application surface with the fingers. Each control allows you to have a collection of items called PivotItem and PanoramaItem, respectively, to define the discrete feature areas

I will use the Pivot control rather than the Panorama control for two specific reasons:

• The Pivot control sweeps each control completely to the next, where as the Panorama allows the items to overlap on the display as they sweep them in. For this application, allowing each of the features the full viewing surface will give a better user experience
• More importantly, the Panorama control does not allow the Application Bar (at least, that is my understanding at this time), and I want that functionality. In fact, I will let each of the two features to have their own Application Bar

So far, the structure of the MainPage.xaml file looks like the following – with the fully expanded tree of controls shown on the right

I will now introduce the Pivot Control and Pivot Items, and move the earlier definition of the Stopwatch Layout inside it. This is done, by adding the following xaml code for the Pivot control and the PivotItem

Note, that the name of the Pivot control has been set as the Name of the Application, and the PivotItem has the name of the first feature – the Stopwatch. The rest of the original layout of the Stopwatch feature is now included within the PivotItem definition, and the definition is then closed off with the following tags. (The only other change I did was to move the Stopwatch display time TextBlock control a bit to the left, as it had gotten moved because of the above embedding)

Also, as the application will have one of two ApplicationBar controls, I am moving the definition of ApplicationBar items into a resource block as shown below, and will programmatically select the one that is the right one for the context. This is done by the following xaml code snippet

With this, the definition of the layout now looks as follow – contrast that with the one shown above.

A

Also, since we will now explicitly need to set the ApplicationBar. To do this, we first create a handler for the SelectionChanged event of the Pivot control. The code that sets the event handler and the code for the handler is shown below.

A quick compilation of the code and running of the application shows that all of the functionality is intact – as shown below.

Adding a second PivotItem for the Countdown timer

We will now introduce the Countdown timer as a second feature, by adding another PivotItem and including the TimeSpanPicker control that we have installed above. This is very simply done with the following xaml code for adding a second PivotItem in the Pivot control xaml that was shown above.

We then add a second ApplicationBar resource as shown below

Here we have a two buttons – the play button to start the timer, and a cancel button to cancel the timer before it counts down. We have defined a handlers named “countdown_play_Click” and “countdown_cancel_Click”. We will add code for it soon, but for now, we will simply add the handler as an empty function (likewise for the other handler too).

Note that the cancel button is disabled by default. Also, we have copied down the cancel icon into the images folder and have set the build action to content.

Changing the properties of the TimeSpanPicker control

It is now time to beautify the TimeSpanPicker control and set some properties so that it is consistent with the properties we had set for the Stopwatch display timer TextBlock. If you click on the PivotItem in the xaml file that represents the TimeSpanPicker control, you will get it displayed in the designer mode as shown below

To beautify the control, I would like to set the background color to black, the text color to yellow (just to add a bit of color, like we set Stopwatch display to blue), set the font to be a fixed width font (courier new), and set the font size to 64.

As in the case of the Stopwatch Display Timer, I found the most effective way to do this is to create a style in Expression Blend and apply it to the control. Here is the style that I have created and saved in App.xaml file

I simply apply the style – TimeSpanPickerStyle2 to the TimeSpanPicker control, as shown below, and you can also see the control now looks a lot nicer in the design view. I have also adjusted the location of the TimeSpanPikcer control to be around the same place as the Stopwatch Display Timer control.

The beautiful editing capability of the TimeSpanPicker control

The TimeSpanPicker control has a very nice built-in editing capability for changing the hour, minute, second portions of the display. The display is a TextBox, but when the user selects it, you can change the values using the infinite scrolling capability that it provides, keeping in mind the range of the values for hour, minute and second!

Notice below, how it looks like in real time. The picture on the left shows the display mode of the control. When you click on any of the three fields, it brings up the infinite scrolling control and you can get it scrolling by swiping it and then selecting the value you want. In this mode, the bottom of the screen shows the save and cancel buttons which can be used to save the new value. Thus, by clicking the save button, you get the new value for the control as shown in the right most image.,

However, note that to get the save and cancel images to show properly, you have to few steps explicitly (I presume this is an issue with the control – it should really have done all of these at the time of the package installation time).

You have to create a folder at the top level of the solution called "Toolkit.Content" and put the icons in there. You will need to copy the icons from the Coding4Fun.Phone.TestApplication project. They need be named "ApplicationBar.Cancel.png" and "ApplicationBar.Check.png", and the build action must be "Content"!

Finally, the logic for the Countdown timer

To keep the logic for the Countdown timer simple, here is what I will do:

• Introduce a new DispatchTimer, let’s call it countdowntimer and a stopwatch called the countdownstopwatch.
• When the “play” button on the Timer screen is hit, we will
• Convert the value in the timer to number of ticks, saving it, and setting that as the timespan interval for the counter
• Set an event handler for the timer
• Start the timer and the stopwatch
• Disable the play button and enable the cancel button
• In the event handler of the timer
• We will get the elapsed timer time from the stopwatch, subtract it from the total number of ticks saved above to get the remaining time
• If the remaining time is still positive, we will set the value of the TimespanPicker control to the remaining time
• If the value has reached zero, we will stop the timer (we will soon sound a beep too)
• We will also enable the play button and disable the cancel button
• When the cancel button is clicked, it simply resets the remaining time to zero and the event handlers take care of the rest

The code looks as follows:

Sounding a beep when the Countdown reaches zero

Playing a sound when the countdown goes down to zero turned out to be harder than I thought. I will investigate if there is an easier way, however, for now I am accomplishing this using XNA.

First, I add couple of XNA class library references

Next, I add a audio file - Piano.wav - to the root of the Application. I also changed the “Piano.wav” as Content and “Always copy to Output Directory” in the properties of the .wav file. Finally, I add the code below when the countdown reaches zero.

How does the application looks?

It is time now to build and show-off the features we have added. First notice the main screen of the application in the image shown on the left. You will notice that next to the “StopWatch” title, you will see a portion of the “Timer” feature shown in gray. This is a view of the Pivot control. It shows that there is another feature in the application! If you swipe the surface of the phone, it brings the second feature into view – as shown in the image on the right. Notice how the titles of the features are positioned – the Timer is now active, and the Stopwatch title shows partially and is grayed.

I can use the TimeSpanPicker editing capabilities discussed earlier and set a countdown value – as shown on the left below. When we save the value, you get the second image from the left – notice that the play button is enabled and the cancel is disabled. I then hit the play button and the third picture shows the countdown in progress and I also show it in a flipped view. Notice that the cancel button is now enabled, and when I click that the count goes to zero, as shown in the last picture below, and the piano sound plays as well!

That was truly a lot of fun! I have touched upon a ton of functionality, and I really enjoyed getting the application into shape and posting this!

Cheers!

In this post I will incrementally refine the application in a few different areas. The first one is to make the code for saving / loading the timings to and from the file lot simpler, by leveraging the power of .NET serialization.

If you remember, I had stored the timings from the Stopwatch in an in-memory data structure defined as follows:

This is essentially an ObservableCollection object which represents the collection of timings. The object itself takes care of providing notifications when items get added, removed, or when the whole list is refreshed. The definition above takes a template for the class <Timings> which represents individual elements in the collections.  The definition of the “Timings” class is shown below. Each element essentially is a tuple of two strings “EventName” for the name of the Stopwatch event, and “timingsinms” representing the time for the event.

The code to then save and load the in-memory collection object into a persisting file was explicitly written as:

Leveraging .NET Serialization

.NET provides the System.Xml.Serialization namespace that contains objects to help serialize objects into XML documents which can then be saved in files. Likewise, it provides classes for the deserialization too. You can read all of the details about .NET serialization here.

There are two options I can take - either to do an XMLSerialization or BinarySerialization. I am choosing XML since I could have a look at the file I need to and also tweak to choose the elements to be stored.

Since we are using an ObservableCollection which is part of System.Collection and types in System.Collection and System.Collection.Generic are by default Serializable. So it’s east just to serialize the entire collection with one line of code.

We first add System.Xml.Serialization as a reference, and include the name space in our project

We then create an instance of the XmlSerializer class using the type of the object we want to serialize.

With this, the saving and loading of the in memory collection to the file become a lot easier.

To serialize to the file, the code now looks like the snippet shown below. We simply create a StreamWriter object for the file we have opened or created, and then serialize the instance of the XmlSerializer object (which has already been created of the write type), by calling the Serialize method, passing in the writer and the actual in memory collection as the parameters.

Loading the collection back in to memory is equally simple.

Note that the ObservableCollection does not fire the NotifyPropertyChanged when the whole collection is deserialized. So we overcome that by setting the Itemsource of the TextBox to the Collection once again.

Handling the Application state during Deactivate and Closed events

For the Main Application you will see there are four events that need to be handled and you can see the event handlers stubs already written for you in App.Xaml.cs. In our case we want to handle the case where when the user presses the back button or when the Windows button is pressed or when the user powers off the mobile when the app is in use, we want to store what we have in in memory list.

Currently we just have one screen and we will handle the Deactivated and Closed events when the main screen is being tombstoned.

Let’s first add the event for handling the de-activation. This is also an opportune time to show off a Visual Studio short cut mechanism to define and add these event handlers. Simply type:

“PhoneApplicationService.Current.Deactivated +=”

Then hit the <tab> key twice. The code automatically expands to defining a default handler and setting the above event to the handler. See below

We will replace the default implementation with a call to “saveTimings” and likewise define and do the same for the Current.Closing event. The code for both is shown below.

Since we are loading the timings when the application loads, and saving them when the application is deactivated, we no longer need to save the timings when the “Save” button is clicked – we will simply let the data structure build up in memory.

Formatting the time

Earlier we were calculating the time down to seconds and milliseconds by dividing the elapsedmilliseconds. We will now write it to the TImeSpan class and find out the Hours, minutes, seconds and milliseconds in one line of code.

Fixing the font size and color of the timings

Finally some aesthetic changes. I had noticed that the display style of the event name and that of the timings string were not quite the same. I have fixed that by appropriately defining the foreground brush for the TextBlock and its font size too – as shown in the XAML snippet below

That completes the Stopwatch functionality.

A quick test shows that the displays are looking much better, and the functionality is all intact

Hitting the back button or hitting the “windows” button to tombstone button and getting back to the application also shows that the timings data is correctly being persisted and restored back

My goal for the next session and next post is to add another feature to the Stopwatch – that of a count down timer. That will need me to add another page to the application or perhaps a panoramic view – that will be fun!

Cheers!

It is time to add some new functionality and new concepts to the Chronometer application I have been building. I have posted a set of three blogs so far on it, with the first one being here.

The new functionality that I will add

In this post, I want to add the support of the “Save” functionality to the Stopwatch. If you remember, in the second post I had introduced the “Save” button in the Application Bar – however, I had not added any code for it. In this post I will add the following functionality.

• The “Save” button will be enabled only when the Stopwatch is in paused state (disabled with the watch is running)
• When you hit “Save” it will do the following:

• “Copy” the time on the Stopwatch to a new line below the Stopwatch
• Any existing lines will be pushed down one row
• Each new line will have a default name, and the Stopwatch time against it
• The name of the line should be editable 
• The list of lines should be scrollable
• The “Save” button should also reset the Stopwatch to “00:00:00:00”

Persistence and data binding too

It is important to mention here that, in the current release of the Windows Phone 7 only one application runs at a time. When you back out of your application, it gets suspended which is known as the “Tombstone” notion. While you get notifications of when the application gets tombstoned, but there is no guarantee that the application will be resumed from the same state when you go back to it. It may have gotten terminated (you would know that in the notification) and restarted. Hence it is important to take care of data persistence explicitly across tombstoning and restart.

I would like to save the list of timings displayed above from session to session.

For this, I will introduce the concept of persistence of the data in file, and I will also introduce the concept of data binding so that it makes it easy to associate and bind the data in the application screen to the file it is persisted in.

I am looking forward to learning a lot as I do this!

Creating the visualization of the area where timings are saved

I want the timings to be displayed as below:

<default timing name>     <hh1:mm1:ss1:ttt1>

<default timing name>     <hh2:mm2:ss1:ttt2>

……..

<default timing name>     <hhn:mmn:ssn:tttn>

While the name on each line starts with a default name (say “timing”), I want the name to be editable – so it needs to be TextBox. The actual value of the time however will be read-only (that value when save was hit) and hence it will be a TextBlock.

First, a basic education in data binding to a control

Let us first understand how data binding to a control works. There is already an excellent MSDN article here.  Please study the article, especially the following concepts that we will use in our application.

• You have source and targets for binding, and a target is setup for binding using the “{Binding}” attribute value
• There are two modes for binding – one way, and two way – via the BindingMode.OneWay (default) and BindingMode.TwoWay settings
• The DataContext property of a framework or ui element allows it to participate in binding
• The ObservableCollection<T> class that represents a dynamic data collection that provides notifications when items get added, removed, or when the entire list is refreshed
• The INotifyPropertyChanged interface that notifies clients that a property value had changed
• A DataTemplate that enables to customize how lists are displayed in a control, and ItemsControl.ItemTemplate that gets or sets the DataTemplate
• The ItemsControl that can be used to represent a collection of items

At this point we are ready for create the new visualization that we need for our feature

The main content display XAML

I have created the design for the new content, and the XAML for that is shown below. You will notice that we have the “TimerDisplay” TextBlock at the top – this is the main display for the Stopwatch which we had introduced in the earlier posts – nothing has changed, I have however taken it out of the Grid which defines the new visualization that I will introduce now (and adjusted it’s margins to re-align it to where it was in the earlier posts.

The new <Grid /> now introduces the new display. Notice the following carefully:

• For the make the entire Grid databound by marking DataContext=”{Binding}”.
• The Grid essentially contains a ListBox “MainListBox”, and note the ItemSource property and it is bound to “inmemList” which will be an in memory list
• The ListBox has a StackPanel which essentially stacks up a TextBox for the name of the timings, and the TextBlock to save the time
• The “Text” property of the TextBox and TextBlock are set to data bound to EventName and timingsms variables.
• Both of the above are set to TwoWay data binding

The data structure that will hold the list of timings in memory

As described earlier, the list of timings that the application will display is essentially a collection of tuples – with each tuple holding a string that represents the name of the event for which the Stopwatch was being used, and another string representing the timing value for that event.

We want to represent this as an ObservableCollection object with a class that holds the above tuple strings. This object will also fire the INotifyPropertyChanged event when any of the strings are changed. The data structure is simply the following:

Persisting the timings collection into a file

Now lets get to the code that saves the above data structure – the timings collection – into a file, which essentially will be our backing store

The code for this is pretty simple and almost self explanatory. Here it is:

Note, in the above code GetUserStoreForApplication essentially obtains a user-scoped isolated storage corresponding to the calling codes application identity. I will simply use a flat text file in the above storage for serializing and deserializing the timings collection data structure.

Here is the code which saves the data structure into a file, one line per timing tuple. It creates the file “acstopwatch.txt” if it is not already on the device, or opens it if it is there. The function is called with the collection. It then simply enumerates each element in the collection and writes out a line with the EventName and the timingsinms strings, separated by a comma.

The loading of the data structure from the file is likewise pretty simple. It opens the file, clears out the in-memory collection, reads one line at a time, and then splits the string at a comma to get the two texts stings that it creates a new Timing structure in the collection.

We will now do the initialization – where we will read the file, loading the in memory data structure, and set it as the data bound source for the MainListBox in our display that we created earlier in XAML. Note the last three lines in the code snipped below.

The application visibly looks no different yet

At this point we will build and run the application – and as expected, the application is visibly no different. The screen shot is shown below, and is really still where we had left off in the last blog. This is because while we aren’t really creating items in the MainListBox yet – that is the logic we now need to build into the play and save buttons. That comes up next.

Wiring in the new play/pause and save logic

First we add the save handler to the save button in the application bar. At this point I also take the opportunity to rename the handler for the play button to what I had in the previous post to the following:

The play_click logic keeps the save button disabled while the stopwatch is in play mode, and enables it when in the pause or stop mode

The save logic is pretty simple – it adds a new item to the timings collection, gives it a default name based on the number of items in the collection, and resets the Stopwatch

Now we see the new UI and the Stopwatch logic is in place

We are now ready to run the application. The screen below shows the Stopwatch running – see the save button displayed, then the pause mode where the save button is enabled, and on clicking the save notice the new line which shows up below the display.

Notice, since the event name is a text box, you can simply type in it to change the default name – as shown below

Improving the style of the TextBox

I don’t like the default look of the TextBox – the gray object – shown above. I would really like it to be like the TextBlock shown to the right. Perhaps there is a way to do this in the default designer –  but this can also be done easily be designers who use Expression Blend.

My colleague at work is very handy with Blend – and he has a style which matches what I want and I would use that. For the purpose of this blog I will simply show the XAML generated by Blend for the style in question – and perhaps explore Blend at another time.

I am only showing a part of the XAML for the style, as it is a lot of XAML code (please let me know if you need the full style). I am putting this in the App.XAML file.

Next, I change the TextBox XAML definition to include the newly defined style

With that, when I run the application, the TextBox looks a lot nicer!

Some final screen shots

We are done. Here are some final screen shots. The screen shows the state after a set of timings have been added, with some event names changed. The one on right shows that scrolling works just fine!

Next we hit the back button to tombstone the application, and when we launch it again, we see that it has reloaded all of the saved timings showing that persistence is working just fine too

Finally I test to see that portrait mode works well and it does!

That completes a few hours of coding this afternoon, and the cricket match is still on! I hope this blog is useful to someone out there who wants to add data binding and persistence to their application.

Cheers!

The application that we have built, so far, does not respond to flipping the phone on to it’s side. For example, below are two views of the phone held upright and on its side respectively

While this behavior may be fine for some applications, for our application, the display is hard to read when the phone is turned on its side, and I would really like the display to always be “upright” irrespective of whether the phone is held upright or flipped on it side.

This is easy to do!

You can find the default settings for the “orientation” for the application in the default XAML file for the application. I am including below this part of the XAML for the PhoneApplication page

Notice the last line above. It essentially says that the “Orientation” to start with will be in “Portrait” mode, and the “Supported Orientation” is also “Portrait” only. It is this setting which is making the application behave as shown above.

You can also notice this setting in the properties window for the PhoneApplicationPage object – see this in the image on the left below – notice the values of the “Orientation” and “SupportedOrientations” properties. To support both portrait and landscape orientations, all you need to do is change the value of the “SupportedOrientations” property to “PortraitOrLandscape” – see the image on the right below.

As you change the above property, note that the XAML file automatically changed to reflect the change.

That’s all!

We can now build the application, run it, and we can now see the following results when the phone is flipped on its side.

Notice, how the button icons in the application bar also change to match the corresponding orientation.

I should also call out that, you can just as well change these properties in the code. For example, you can achieve the same result by leaving the default properties (and hence the XAML) unchanged, but add the following line in the code behind file, during application initialization.

This of course gives you full flexibility in controlling this property however you want to!

That’s all for this night! I have a few other things to add to this application, related to the “Save” button I have introduced but haven’t coded to. This will allow me to play with a few more controls and also experiment with how data/state can be persisted across sessions of the application. I hope to get to those soon.

Cheers!

My goal today is to add the Application Bar functionality to the application, to use a different timer construct, and also to clean up the code a bit.

Getting the ‘official’ icons

Let me start first by using some professional icons for the application instead of the self-made ones in version 1.

You will find most of the important icons used on the Windows 7 phone already on the system. These come with the Windows Phone 7 developer toolkit, and you will them in the following locations:

• On 32 bit computers – C:\Program Files\Microsoft SDKs\Windows Phone\v7.0\Icons
• On 64 bit computers – C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v7.0\Icons

You have both “dark” and “light” versions, I will be using the “dark” versions, as I have the default dark background for my Stop Watch page. I have copied over the following icons and add them to the project for the “save”, “pause”, and “play” functionality in the application, saving them in the “Images” folder

Also, click on each of the icons, and in the properties window, change the “BuildAction” to “Content” from “Resource”

Using a DispatchTimer

In the last post I had used a Timer object. With this object, the callback happens on a different thread. Hence, to access the UI elements of the application, I had to use the Dispatcher.BeginInvoke mechanism on the object to access it. In this post, I will use the DispatchTimer object instead. For this class, the event callback happens on the UI thread itself, and I can access the UI elements directly.

To add the DispatchTimer, I add the following lines

At this point, it is opportune to point out an useful short cut in Visual Studio. To add the event handler for the DispatchTimer object all you do is simply type

timer.Tick += <tab> <tab>

Visual Studio automatically completes the rest of the last instruction shown in the snippet above, and also add the event handler code, below, automatically! I like this short cut!

Changing the display font to a fixed-width type

At this time, I will also make a few clean up changes. I clean up some of the static variables I had introduced earlier. I will also change the font type of the TimerDisplay TextBlock  to “Courier New”. This is a “fixed width” font, and it will prevent the perceptible wobbling of the numbers in the timer display for the earlier version – that is, the total width of the displayed text will stay constant with this font, irrespective of the digits displayed. This requires me to change the width of the display block a bit, and I also take the opportunity to change the font color to a shade of blue to add a bit of color!

With this, the main part of the UI, and the properties of the TextBlock are the following

Introducing the Application Bar

In this version I will also introduce the “Application Bar”. It is the bar that sits at the bottom of the screen. The bar supports four icons, and have additional menu items at the bottom. The bar displays just the icons and a “…” symbol on the right (bottom left of the screen) to expand the display bar and display the additional menu items.

The Visual Studio development environment makes it easy to make to bring the application bar into play! Double click on the MainPage.xaml file and check out the bottom of the xaml code – you will see the following xaml code in a comment block

Uncomment the comment block, and you see the Application Bar show up in the XAML designer view, as shown below

I have also cleaned up some of the old timer code and removed the old button that I had in version 1. At this time, you can build the application and run it. You can now see the Application Bar on the screen. The left image below shows the default display, and you can click the “…” icon at the bottom right of the screen and you can see the application bar expand, now showing the names of the two icons used, and also the additional menu items that are included in the XAML code above.

I want to use the first of the icons in the application bar for the “start / pause” toggle for the Stop Watch, and the second one for a “save” functionality that I will introduce a bit later.

To do this, I update the XAML code in the Application Bar segment to change the icons for the first two icons to the play and save icons, comment out the extra menu items which I will not be using in this version, and also add the handler code for the two icon buttons. The XAML code for the Application Bar now looks as follows:

If you use the IntelliSense feature in Visual Studio to add the “Click” property, it will also add the handler code in the backing code file. I have changed the name to the one shown above/below

Building the solution and running it, we can now see the Application Bar displayed with the two icons we have selected.

When you click on the buttons, nothing happens yet, as I have not hooked up the code in the above handler to do the main stop watch logic. However, you will notice that the system automatically provides all of the functionality to “invert” the color of the icon when it is hit, and the subtle up-down motion showing the buttons are clicked.

Putting back the logic for updating the display

We can now put back the code we had in version 1 to update the display, taking care to put the logic in the appropriate event handlers, and accessing the new icons to update the application bar icons.

First I show below the code for clicking the first button in the Application Bar. It simply starts the DispatchTimer and Stopwatch, and simply toggles the icon images for the button from play to pause and vice-versa, and updates the icon text accordingly.

Next, I show the code in the DispatchTimer callback. It simply updates the stopwatch components, and simply updates the Application’s TextBlock display directly from the thread (without having to use Dispatcher.BeginInvoke, as explained earlier in this post).

With this, we have are now back at the functional state we had in Version 1, but with the buttons in the Application Bar. Below are snapshots of the starting, running, and paused states of the application.

Finishing up version 2 for now …

The cricket match is at a very interesting stage now – it is quite tense, the last quarter of the match remains and India seems to be in a bit of discomfort and Sri Lanka has the upper hand. I better get back to paying complete attention and supporting Team India! I will keep evolving the application with further posts …

Cheers!

Get Visual Studio 2010, and download Silverlight for Windows Phone

I am assuming you already have a developer edition Visual Studio 2010 (you can get more details about the product here). You also need to download the Silverlight for Windows Phone package – Silverlight being the application development platform for Windows Phone 7. You can get it here. From there you also need to download the Windows Phone 7 developer toolkit, that plugs into Visual Studio.

I am now set to create the first Windows phone application.

I will start with building a simple Stopwatch application. This type of application is already readily available in many forms in the Windows Marketplace – but as I said, the goal for this post is to just get started with a simple application. I will call this application a Chronometer – maybe I will add more functionality later.

Creating a new project, leveraging the template

Creating the shell of the application is real easy – simple create a new project in Visual Studio and choose to create a Windows Phone Application – that’s all! Check out some screen shots below.

You can just build and run the application. The application comes up in the simulator, and is pretty functional already – see the screens below! The one of the left gives you a default view of the application we are building – it has a default title for the application, and a default name for the starting page of the application. The simulator also includes fully functional buttons that you’d have on the phone. Clicking on the "windows” button shows you the start screen of the phone, complete with a tile for internet explorer (and that tile/app is fully functional too). Clicking on the navigation button next to the IE tile, you see the third screen which shows the applications already on the phone – and here you see that our chronometer application has also shown up (we should change the tile of the application here – it has simply picked up the title of the solution we have created in Visual Studio. Finally, you can click on the search button on the phone, and it brings up the Bing search application – once again, fully functional including the current day’s Bing picture and fully functional voice search capability. I love the Windows Phone 7 simulator in Visual Studio – it not only makes building your application really easy, but allows you to get a feel for it in an actual environment by giving a pretty functional feel of the Windows Phone 7 device!

Few easy modifications to begin with – change the application name and titles

Getting back to Visual Studio, you can see the XAML representation for the UI and the actual view displayed in the designer mode. You can simply click on the controls, check out their properties on the bottom-right of the screen, and change the texts. For example, I have changed the title of the application and the title of the main page below. I will build a stopwatch application for the main page.

Let us also change the name of the application that shows up in the list of applications on the phone. Click on the name of the solution in the solutions explorer, and bring up the properties page. Click on the applications tab in the properties and change both the title in the “deployment” as well as the “Tile” options property sets – see below.

Simply build and run the application again, and you can see all of the changes have been effected. Including the tilt of the application in the tile view (I simply double clicked on the application in the list on the left screen and pinned it to the start page).

It is worth reflecting on how easy Visual Studio makes developing Windows Phone applications too! With just a few very simple steps we have created the structure of the application.

Creating the Stopwatch display

Let’s now get to the core of our application. I will first add the main display for the Stopwatch page. I intend to be in the format of “DD:HH:MM:SS:mmm” displaying days, hours, minutes, and milliseconds.

Back in Visual Studio, bring down the toolbox of controls that you can choose from (via View.Toolbox menu) – see below. You have a rich set of controls to choose from.

I am choosing the “Textbox” control for the main display – it allows me to display a rich text on the page. You simply double click the control from the Toolbox to get it on to the application page. Next, simply change the properties (I have changed the display text to be 00:00:00:000 by default, and have changed the font size to 64), resize the control to the desired size, and drag and position it to the location you want.

The application display now looks as shown below. I now would like to add a start/pause button to finalize my first page for my simple Stopwatch application. For this, I simply create two icons – for play (or start) and pause – and create two JPG files for them. I used Windows Paint to create these two icons – each being a 60x60 in pixel size. I then add those two files to my solution via “Project.Add Existing Item…” menu

Next, I add a button from the Toolbox to the application screen, position it and size it appropriately. At this point this is a simple button, and the page and the backing XAML looks as follows.

However, instead of the Button being a simple Text button, I want the button to use an image – say the “play” image that I have created above. To do this, I simply add the “Image” tag to the Button definition directly in the XAML file shown above. The reworked XAML looks as follows – notice the <Image /> tag in the XML inserted in the definition of the <Button /> tag, and also that the play icon now shows up in the Button – we have transformed it into a an image based button.

With this, we have really completed our application layout! Now we need to add a bit of code for the Stopwatch logic.

Adding the code for the Stopwatch

As you can imagine, all of the action will be initiated by the clicking of the play button. To create an event handler for the button, simply double click on the button in the display view for the XAML for the main page. It creates the following code in the backing code file.

Now we will simply add the code in the event handler framework that has been created by Visual Studio.

My focus here is not to write the most efficient code, but will rather focus on simplicity.

Adding class references

We will be using few special class from the System name space – namely Media for updating the image of the button, Threading to get a timer going, and Diagnostics to use the Stopwatch object built into .NET. I start of by adding these references in the MainPage.xaml.cs file

A few member variables

I next introduce a few member variables. These will store the day/hour/minute/second/millisecond values that I will display; the state of the stopwatch (started or paused) , a Stopwatch object, and a Timer object ;

It also created two BitmapImage objects for the start and pause images that the button will display.

The start/pause click logic

Now, we move onto the code which executes when the play button is clicked. Note, this button is going to toggle between “start” and “pause” modes.

When in the stopped state (the initial state), it toggles the state, sets the image in the button to the pause button, creates a new Timer object, and also starts the stopwatch timer in code.

The Timer object is created with a callback method (updateDisplay) which we will discuss shortly. It also sets up the callback to be called with a reference to our TimerDisplay TextBlock so that we can update it. The penultimate parameter of 0 starts the timer straightway, and the last parameter of 100 sets it up to call the callback function at intervals of 100 milliseconds.

The logic is similar and simple when the stopped state is false – it changes the image of the button to play, disposes the timer, and stops the stopwatch. Note that in our application, the stopwatch can be resumed from the point of pausing by clicking play again.

The code is shown below.

The Timer callback

Finally, we are ready to plug in the last piece of code – the callback function – which will update the applications display.

The code is shown below.

We simply calculate the elapsed time from Stopwatch object, convert it into the appropriate formatted display string for the application

The application is ready!

With that, our app is ready! Simply build and run the application, to check it out on the Simulator. I show four screens below – the application listed in the list of applications, the starting screen, once the start button is clicked, and once the pause button is clicked

What’s next?

That was fun – and not bad, for a Saturday afternoon’s worth of coding. Visual Studio really does make building Windows 7 Phone applications quite easy.

So, what’s next?

There are many different ways I could extend this work – I could add more functionality to the stopwatch, or perhaps I could add another page to the application and add another functionality to the chronometer (may be a count down timer?). A demonstration of an application with two pages would be a good learning! And then of course there is the task of actually deploying the application to the app store, Perhaps I could also go into testing of phone applications. So, there are lots of ways I could take this – will wait for another lazy afternoon.

Cheers!