Mike Hanson

In this first article on NavFx I am going a provide a quick reference for it's features by way of some basic documentation. Since posting the first version of this article I have started a project on CodePlex for NavFx and made the code available there, along with simple demo projects in C# and VB.NET.  I have also created VSI installers for templates that you can use to get up and running with NavFx very quickly.  The project is located at http://www.codeplex.com/NavFx.

Package Contents

NavFx includes four interfaces, five classes and seven custom exceptions, which are listed below and will be explained further in this article.

• IApplication
• IHostPage
• IPage
• ITransitor
• Navigator
• Application
• HostPage
• Page
• SimpleTransitor
• AssemblyLoadException
• InconsistentIndexException
• PageNotRegisteredException
• PageTypeNotSupportedException
• TargetNotSetException
• TargetNotSupportedException
• TransitorNotSetException
• NavFxApplication Template
• NavFxHostPage Template
• NavFxPage Template 

NavFx Navigator

At the heart of NavFx is a class called Navigator. Navigator provides all of the built in functionality provided by NavFx, but it relies on a page tranisition handler that you provide.  The diagram shows the methods provided by Navigator:

Method Description CurrentIndex  Index of the page currently being displayed.  This can become inconsistent when the basic GoToPage method is used CurrentPage  Path value of the page currently being displayed IsIndexConsistent Indicates if the CurrentIdex is consistent with the page currently being displayed.  This can become inconsistent if the basic GoToPage method is used.  If this reports false then calling NextPage or PreviousPage can give unexpected results Transitor Reference to the ITransitor you have set Navigator to use for handling page transitions ClearCache Removes pages from the internal cache maintained by Navigator.  By default this method does not remove any Pinned pages, set the clearPinned argument to true to have Navigator remove all pages.  Pages are also removed from the Forward and Backward history caches GetPage Retrieves a page from the cache.  The basic version of this method returns the IPage interface of the page.  Use the generic version to retrieve the page as a specific type GoBack Displays the last page in the backward history stack if available. It returns true if are more pages in the forward history stack, otherwise false. GoForward Displays the last page in the forward history stack if available. It returns true if there are more pages in the forward history stack, false otherwise. GoToPage Displays a page specified by its path. There is an overload that takes a Uri and if the page is not loaded in the page cache will load the pages from the library. IsPageRegistered Returns true if a page with the specified path is already in the page cache, false otherwise. IsPinned Returns true if the page with the specified path is Pinned in the cache, false otherwise LoadPages Accepts a Uri and loads all pages that implement the NavFx IPage interface into the page cache, optionally displaying a page specified by its path. NextPage Displays the next page in the page cache based on load order.  Intended to support Wizards it returns true if there are following pages in the page cache. PreviousPage Displays the previous page in the page cache based on load order.  Intended to support Wizards it returns true if there are preceding pages in the page cache. RegisterPage Adds a page implementing the NavFx IPage interface to the page cache RemovePage Removes the page witht he specified path from all caches.

 It is important to understand the differences between two pairs of methods.  GoForward, GoBack, NextPage and PreviousPage.  The difference between the pairs is what they navigate against.  Navigator maintains three internal caches of registred IPage objects, Pages, ForwardHistory and BackHistory.

Pages is a cache of all pages that have been registered with Navigator and is a navigable collection.  ForwardHistory is a stack on to which the current page is pushed when you use the GoBack method.  Back History is also a stack and the current page is pushed on to it whenever you navigate away from it.  GoForward will pop the page at the top of the ForwardHistory stack and GoBack will pop the page at the top of the BackHistory stack.

NextPage and PreviousPage on the other hand do not use the forward and backward history stacks.  Instead they allow you to navigate  through the Pages collection in page load order.

All four of these methods return true if there is another page available in the relevant direction, this is intended to make it easy to implement navigation buttons.  If you call one of these methods from a button and the method returns false, disable the button, better still assign the return value directly to the IsEnabled property of the button.

NavFx Transitions

Although Navigator provides all of the methods you need to navigate around your Silverlight 2.0 application it does not handle the transition from the current page to another.  Navigator relies on transition handlers or Transitors to do the work of changing between pages.  Transition handlers must implement the ITransitor interface, which defines a single method TransitionPage that accepts two intances of IPage previousPage and nextPage.  How the transition from one page takes place is entirely up to the Transitor, for example you might want to animate the transition from the current page to the next.  Navigator will call the TransitionPage method of the ITransitor that you provide it with.  Navigator takes care of maintining backward and forward history, but you have to take care of how the transition happens.

NavFx includes a concrete class called SimpleTransitor, which ignores the previousPage and replaces the content of a container you specify with whatever you pass as the nextPage.  The Target property of SimpleTransitor can be an Application, UserControl or Panel.  The demo project uses the SimpleTransitor exclusively so there are plenty of examples of using it available.

NavFx Interfaces

ITransitor was explained in the previous section, the following diagram presents the three additional interfaces defined by NavFx.  NavFx provides concrete implementations of these interfaces that will suffice for most Silverlight applications that you create, but if you prefer to stick to defining your pages as standard UserControls or need to add NavFx to an existing application with minimal changes these interfaces are the way to go.

IPage

Implementing IPage is required to enable your Silverlight pages to be registered with Navigator.  It ensures a path is available as a key for accessing the page in the internal caches of Navigator.  The IsPinned property supports pinning selected pages in the cache so that ClearCache will ignore them when cleaning up.

IHostPage

Implements IPage and is intentended for implemenation by pages that host other pages.  The main thing it ensures is the convenience of a local reference of a Navigator to use for navigation between the hosted pages.  The demo project contains several examples of this scnerio, for example the Wizard example is a host that enables you to navigage between its three pages.

IApplication

Implementing IAppication is optional, it defnes simply that an application must provide a method to get a Navigator.  This is an important interface for pages implemented in external libraries, it enables them to get a reference to the Navigator from the current application something like this:

Navigator nav = ((IApplication)Application.Current).GetNavigator();

or

Dim nav as Navigator = CType(Application.Current, IApplication)

Concrete NavFx

"So interfaces and all that are really good but I just want something I can use" I hear you saying.  Well NavFx has you covered as it includes concrete classes that implement the interfaces introduced in the previous section.  The following class diagram presents the concrete classes that you can use instead of the built in Application and UserControl provided by Silverlight.

The usage of these classes should be fairly obvious from the explanations of the interfaces because they are direct implmentations.  For completeness and to hightlight some noteworthy points the classes are covered in the following sections.   To create your Silverlight application using these classes simply install the templates with the VSI avaiable from the CodePlex releases page of the project.

Application

This is a subclass of the System.Windows.Application that instantiates a Navigator and makes it available via the GetNavigator method.  You still need to prepare and wire up a tranistion handler (ITransitor), I did not want to couple things too tightly so left that piece of work to you.  The demo project includes an example of how to do this and you can simply copy and paste the code.  GetNavigator does not instantiate the Navigator until you first call it.

HostPage

This is a concrete implemenation of IHostPage ready for you to add content and a container for your pages.  The SetContent method simply sets the protected Content propery to whatever you pass.  SetContent is intended to allow your ITransitor implemenations to set the Content property of a page, which is Protected so can't normally be set except by subclasses.  You should override SetContent particularly in HostPages so that Navigator displays pages in the right container.

The Navigator property of HostPage checks the the current application for the IApplication interface and calls GetNavigator.  If IApplication is not implemented it throws a NotImplementedException.  Similarly the setter for the Navigator property throws a NotImplementedException.  The property is virtual so you can override it if you wish.

Page

Is a concrete implemenation of IPage and provides a default implemenation of the Path property that returns the name of the class.  In simple applications like the demo this will be all you need, the pages are all named for their purpose and using the name of the class as the key for retrieval from the page cache works fine.  HostPage inherits this behaviour.

IsPinned returns false by default but you can set it otherwise in application code or override the property to return true.

Templates

The demo project download includes three templates that will help you get started with new Silverlight 2 applications using NavFx.  NavFxApplication.zip is a Project template that will create a new application with a page structure that matches the demo project.  NavFxHostPage.zip is an Item template for adding new HostPages to a project.  NavFxPage.zip is an Item template for adding new Pages to a project.

Download an execute the VSI from the releases page at http://www.codeplex.com/NavFx and the templates will be added to the My Templates section of the New Project and New Item dialogs in the Silverlight category.

Well that is it for this article.  I have commented the demo project throughout so you should have no problems getting started.  I will continue this series with a set of walkthroughs for different scenarios and how to implement them with NavFx.

Next Article - Setting Up