Windows Phone: adding a first run tutorial to your app [Feb. 5th, 2014|09:33 pm] Greg

In the Austin area? Come to the Austin Code-a-thon and have a chance to win a JBL Wireless Charging Speaker!



--



My Marriage Map app has gotten some bad reviews complaining about missing features that were actually present in the app. So, I decided to make a quick tutorial that would point out how to use the app the first time the user ran it. I did a quick search for some sample code but couldn't find any, so I rolled my own. (download the latest version of the app to try it out!) It features

graying out and disabling of controls under it



detecting first launch



ability to launch the tutorial again (from the About page in my case)



back button goes back



nice fading in and out of tutorial steps



ability to highlight buttons, etc. in different steps



suspend/tombstone support



looks correct in dark or light theme



if taps are too close together, will ignore the second one None of these were particularly difficult, but adding them all took a bit of work. So I made a sample project with the same system to make it easier to add to your apps.



FirstRunTutorial.wp.zip



Some notes on the code:

Search for TODO to find places you need to make changes.



The _firstRunActive and _firstRunIndex keep track of whether we're showing the tutorial and what step it's on.

and keep track of whether we're showing the tutorial and what step it's on.

Most of the work happens in UpdateFirstRunCanvas() - this is where you have to add new steps. Don't forget to update MAX_FIRSTRUNINDEX when you do!

- this is where you have to add new steps. Don't forget to update when you do!

The fading is done by a bunch of Storyboard objects in MainPage.xaml. (see the Animation Overview for Windows Phone for more info) Unfortunately, the best way I could find to make things fade was to set their opacity to 0.0, make them visible, and then run the Storyboard to transition the opacity to 1.0 (or whatever you want). This means you have to make two different calls to make this work. On fading out, you have to do the opposite - transition the opacity to 0.0 and then make it collapsed, but the HideWhenDone() method that gets run when the Storyboard is done takes care of making it collapsed.

method that gets run when the Storyboard is done takes care of making it collapsed.

Making the button blink is also handled by a Storyboard - you can try different EasingFunctions to make it blink differently!



Disabling controls under the tutorial is handled in SetFirstRunActive() . I was hoping that just putting the FirstRunCanvas with a high z-index would make it be on top of everything and intercept their clicks, but for some reason that didn't work.

. I was hoping that just putting the FirstRunCanvas with a high z-index would make it be on top of everything and intercept their clicks, but for some reason that didn't work.

The code to start the tutorial again is in the About.xaml page - you just have to navigate to /MainPage.xaml?RemoveBackAll=1&Tutorial=1 , and OnNavigatedTo() in MainPage.xaml starts the tutorial. If you want to start it from the MainPage.xaml code, just do SetFirstRunActive(true);_firstRunIndex=0;U pdateFirstRunCanvas();

--



See all my Windows Phone development posts.



I'm planning on writing more posts about Windows Phone development - what would you like to hear about? Reply here, on twitter at @gregstoll, or by email at greg@gregstoll.com.