Windows Phone: adding a first run tutorial to your app
Mood: happy
Posted on 2014-02-05 21:33:00
Tags: windowsphone projects wpdev
Words: 512

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

• 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.


• 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!


• 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.


• 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.


• 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;UpdateFirstRunCanvas();

This backup was done by LJBackup.