June, 2011

With the Windows Phone (codenamed) Mango beta release, the Windows Phone team thrived to have great documentation and useful learning resources for WP7 developers.
I think they did a superb job and given it came after MIX (and we had lots of great video content) the docs have gone unnoticed a bit, so I want to highlight a couple of these resources to make sure developers are getting the most out of these.   Today, I will cover the documentation improvements and the new “Mango” training kit.

<shortcut>
If you rather watch videos, here are two that summarize this post:
Luke Nyswonger, lead for Windows Phone online documentation does a video walk through of all the new stuff in the docs.
Yours truly does a walk-through of tidy, one of the apps in the training kit. It is a scenario that we use for five labs: sql ce, background agents, tiles, background transfer, and reminders.
</shortcut> 

New Mango training kit:
With the new Windows Phone training kit for Mango release, we did a few things different:

• The kit is aimed at intermediate level developers. It goes straight into Mango features and the labs are shorter because we skipped a lot of the intro stuff.. Most of the readers for this blog will feel very comfortable and new developers will pick it up quickly and still have the prior Windows Phone Training Kit for introductory material.  
• The kit takes a scenario approach where instead of having ten or twelve disaggregate/unrelated labs, you have a few hands-on labs that show how multiple features come together to fulfill a scenario.

Here are some of the new samples you will find in the training kit:

• “Tidy” is a proof of concept to-do list application that takes advantages of Mango features to do smarter tasking. 
  Again, you can see Tidy in action in this video walk-through. If you do Mango presentations or demos, Tidy is a good demonstrator of how new Mango features make an existing application much better. 
  The hands-on labs map quite well to the features it showcases
  • Local database hands-on-Lab. Tidy uses SQL CE as its data store and the hands-on lab will show you how to attribute the object model to create LINQ to SQL mappings. How to create databases at run-time, and how to query the database.
  • Alerts and Reminders hands-on-lab.  Tidy allows you to create reminders for a task. The hands-on lab shows you how to query it a reminder exists, how to create and delete a reminder.
  • Start Tile pinning hands-On-Lab. Tidy allows you to pin every project so you can deep-link into a project. This way if your tasks are organized you can deep-link into project specific views and get the tasks for that specific project.
  • Background Transfer hands-On-Lab shows you how to use the new background transfer APIs to upload and download a backup of the database to your local machine.
  • Background agents hands-on-lab shows you how to create background agents in Mango.  The background agents check your location every 30 minutes and if you are nearby a location where tasks are due, it will prompt you a shell toast notification to remind you to complete the task while you are at that location. 
    The background agent also demonstrates how to update the tiles from an agent – it checks tasks that are overdue and it updates the tile for the project with the count-.
• The “Photofun”  hands-on lab demonstrates the new live camera stream APIs. It captures the live camera stream and applies effects to it; it integrates with the camera hardware button to capture images when the button is pressed.
• The XNA 3D Model Viewer hands-on-lab shows you how to use the new shared graphics model so you can visualize XNA-based 3D models in a Silverlight application.   It also demonstrates using the new background transfer APIs to download the models from an Azure store.
• The new device capabilities hands-on lab shows you how to use the new Mango APIs (and some 7.0 APIs) to query device capabilities.  With the new APIs you can detect if compass and gyro are supported, you can detect the type of network connection the device is using, and other generic device information.

Great improvements and additions to the documentation

The documentation team also did a few things different. 

• There is a great “What’s new” page that you can use to get to all the feature overviews, code-samples, etc..
• The samples and how-to walkthroughs are now a bit more scenario oriented. For example, their sockets demo is a full blown tic-tac-toe game.
  They have a lot of comprehensive how-tos on the new APIs. Including the profiler, camera APIs, Background APIs, etc.  If it’s new, you will find a how to! 
• They have moved the User experience Design guidelines from a PDF to an HTML format and they literally doubled the amount of content that went into the UX guidelines.
• They have moved the certification requirements from a PDF to an HTML format, and they have included the test steps so you can ensure you test ahead of time (or if you fail certification you have repro steps.
• They have a very nice “developer resources page” in the apphub that aggregates all the content that Windows phone developers will need

Again, if you want to see a brief video of these changes, Luke will give you a walk through in this video

With all the above changes, developers can find every thing easily, they get a very comprehensive (and deep) view into the features, and they can even have fun while doing it.
Thanks to the doc teams (and the PMs that reviewed it ) for all this goodness; I am sure I missed some; if you find it, comment on it please (or write your own blog post about it ).

Happy Windows Phone coding! Don’t forget to read the docs.

I hope I am not the only person who did not know this (apologies if that is the case).

<context>
A few weeks ago while at an event in Finland, my emulator did not detect an orientation change during a demo. Some one suggested I restart the emulator, I did, and it worked (against my instinct). Today, I found out what’s going on.
</context>

<answer>
When you use the Page Up/Page down button, the emulator let’s you toggle the Software Input Panel (SIP) on and off.  Also when you use the Pause/Break button the emulator disables the SIP and let’s you enter text via your keyboard.   All that works neatly as expected. I use that all the time.   The part I did not know is that the emulator does not support orientation changes when the keyboard is enabled. This is all well documented in the keyboard mapping page: http://msdn.microsoft.com/en-us/library/ff754352(v=VS.92).aspx but I did not know.
Not sure if it has always been documented and I missed it or it is new; either way, fooled me once.. but not again..
</answer>

Happy Windows Phone coding (and don’t forget to read the manual now and then !!)

In my last post, I teased that system tray in Mango is now customizable and data binding friendly  
On top of that, the SystemTray now has a ProgressIndicator  that you can use to replace your PerformantProgressBar and display progress on async operations.  

Here is everything you need to know (or everything I know) about ProgressIndicator.

It is a DependencyObject so  you can data bind to it.. 
You can use these properties to customize and manage the indicator:

• IsVisible (type boolean) to show/hide it.  This is separate from SystemTray.IsVisible. The SystemTray must be visible for the progress indicator to be visible too.
• IsIndeterminate (type boolean) property. When this property is set, you will see the infamous ‘dancing dots’ that we show for indeterminate progress every where on the phone.
• Value property (type double) that you can use to show value (normalized 0 to 1) when your indicator is not indeterminate.
  It also
• Text property is used to display a message in the progress indicator.

A few small quirks and tips :

• The Text has a margin that you can’t control.  Not a huge deal, I assume consistent with OS.
• The progress indicator’s text does pickup the Foreground color you are using for the SystemTray, but the indeterminate dancing dots (or the progress bar) do not pickup the color though. They are using PhoneAccentBrush.
• I found out that I could not access (programmatically) the SystemTray.ProgressIndicator property until page is loaded. I got an InvalidOperationException saying “To get SystemTray ProgressIndicator the RootVisual must be a PhoneApplicationFrame and its Content must be a PhoneApplicationPage”. Not a huge deal, you can listen to loaded and check if you have initialized it before (since Loaded can fire multiple times in a page instance).
• Use BindingOperations.SetBinding ()  to bind to DependencyObjects (where you normally use FrameworkElement.SetBinding).

The screenshot to the right  shows you all of SystemTray’s properties in action.   It has a white foreground and green background with 60% opacity, indeterminate progress indicator and (obviously) custom text in the indicator.
You can turn everything on and off to see the impact as you tweak each property.
It is all data bound; there is no manual setting of any properties.  I am running on light theme with orange highlight.

You can get the source  from my skydrive.

Happy Windows Phone “Mango” coding.

A missing feature from Windows phone 7.0 was the ability to set the Background and Foreground color in the SystemTray.
For branded apps (like Facebook) this was a problem cause the tray looked ugly, so most of these apps had to hide it, hiding important notifications (like clock, battery indicator ) from the user..

In Mango, you can finally set Foreground (of type System.Windows.Media.Color ), and Background (type Color too) on SystemTray. 
I hope that going forward, all apps start setting IsVisible=”true” on the system tray. There is no excuse now for hiding it any more.

I just looked at the API and found two other nice surprises:

1. SystemTray has an Opacity property.   The reason this is nice is because PhoneApplicationFrame applies the same logic to SystemTray than it does to ApplicationBar:
   If your SystemTray is not 100% opaque (that means if Opacity < 1.0) , the space for the tray is not reserved in layout, so you can get a few pixels back… Your page gets full height and it is up to you to reserve space for the tray).
   If your SystemTray is opaque (Opacity = 1.0) and visible,  then frame reserves the space, and your page loses 32 pixels at the top when in portrait and
   
2. SystemTray is a DependencyObject and since we are now running on SL4, DependencyObject can be data bound;  hooray for SL4 on phone.

Of course, there is one more nicety in SystemTray (ProgressIndicator).  I will share my code on that in the next post (hopefully tomorrow)..

Happy Windows Phone “Mango” coding!!

if you try using RichTextBox in the recently released Mango Beta tools, you might notice the control does not have a default control template applied to it.  [That means when you try to use it, you will see nothing but not get an error either]. 

This is a known issue for the beta.  To get around it, simply apply this current Style to the page (or the App.xaml) for your project .

<Style TargetType="RichTextBox">
      <Setter Property="FontSize" Value="{StaticResource PhoneFontSizeNormal}" />
      <Setter Property="Foreground" Value="{StaticResource PhoneForegroundBrush}" />
      <Setter Property="Background" Value="Transparent" />
      <Setter Property="BorderBrush" Value="Transparent" />
      <Setter Property="BorderThickness" Value="0"/>
      <Setter Property="HorizontalContentAlignment" Value="Stretch" />
      <Setter Property="VerticalContentAlignment" Value="Center" />
      <Setter Property="Padding" Value="0" />
      <Setter Property="Template">
        <Setter.Value>
          <ControlTemplate TargetType="RichTextBox">
            <Grid Background="Transparent">
              <Border Background="{TemplateBinding Background}" 
            BorderBrush="{TemplateBinding BorderBrush}"
            BorderThickness="{TemplateBinding BorderThickness}"
            Margin="{StaticResource PhoneHorizontalMargin}">
                <ContentControl x:Name="ContentElement"
              HorizontalContentAlignment="{TemplateBinding HorizontalContentAlignment}"
              VerticalContentAlignment="{TemplateBinding VerticalContentAlignment}"
              Padding="{TemplateBinding Padding}"/>
              </Border>
            </Grid>
          </ControlTemplate>
        </Setter.Value>
      </Setter>
    </Style>

Notice we are using an implicit style (yay for Silverlight 4 on the phone!! )

Another known issue with the current beta build is that images are not showing up in the rich textbox (they show up in the designer in Visual Studio/Blend )but not at run-time.  This is also fixed in later builds.  Still, the template above should be enough to get you rolling with RichTextBox.

Happy Windows Phone coding!!