Towards the end of last year I started playing with the concept of using states to manage more than just visual states on a page. States are already used to manage the internal states of a control (eg Pressed state of a button). If you think about the pages that make up an application, they also represent, at some level, the states of an application. As I discussed in my post, States v’s Regions for Multi-Window Applications, there is also a need for regions to accommodate for platforms where there are multiple windows and/or secondary screens. In this post I’m going to show how to get started with an incubatory framework that uses states as the primary mechanism to determine navigation.
We’re going to start with a UWP application based on the Blank App (Universal Windows) new project template.
Next, we’ll add a Core library based on the Class Library (Portable for iOS, Android and Windows) new project template.
Before writing code, I’ll add a NuGet reference to BuildIt.Lifecycle to the both projects, and then an additional reference to BuildIt.Lifecycle.UWP package to the UWP project. I’ll also add a reference to the SimpleStates.Core PCL project to the SimpleStates UWP project.
To get started I’m just going to wire up three pages, Home, Settings and About. Note that the BuildIt.Lifecycle library uses the term View in place of Page, to be more consistent with the non-XAML platforms. For this reason I often interchange between them. More importantly though, we need to step back and put these pages into the context of states within the app. Once the app has launched it will transition to the Home state. From there the user can transition the app to either the Settings or the About state. The user must then return to the Home state before going to a different state. If you feel overly enthusiastic you could actually create a state diagram that represents this. I’ll represent this using an enum to define what the state values are.
public enum AppStates
{
Base,
Home,
Settings,
About
}
Each state is to be associated with both a Page and a corresponding ViewModel. To this end, I’ll create three pages, HomePage, SettingsPage and AboutPage in the UWP project, and I’ll create three ViewModels, HomeViewModel, SettingsViewModel and AboutViewModel in the PCL. The association between the AppStates enumeration values and their corresponding ViewModel will be done in a minute when I use an instance of the StateManager to define the states of the application. Some frameworks, like MvvmCross, rely on a convention to associate the page with the viewmodel (and implicitly the state of the application). To avoid reflection, this framework requires manual association between the page and the corresponding state. So I need to add the following calls to the beginning of the constructor in the App.xaml.cs file.
public App()
{
LifecycleHelper.RegisterView<Pages.MainPage>().ForState(AppStates.Home);
LifecycleHelper.RegisterView<SettingsPage>().ForState(AppStates.Settings);
LifecycleHelper.RegisterView<AboutPage>().ForState(AppStates.About);
As I mentioned I need to create an instance of the StateManager which will track the states of the application, including what the current state is (ie what page is currently being displayed). In order to do this I need an entity that holds the instance of the StateManager, and will effectively manage the current state of the main window of the application.
public class PrimaryRegion : ApplicationRegion, IHasStates
{
public IStateManager StateManager { get; }
public PrimaryRegion()
{
var ssm = new StateManager();
var sm = ssm.GroupWithViewModels<AppStates>().Item2;
sm.DefineViewModelState<MainViewModel>(AppStates.Home);
sm.DefineViewModelState<SettingsViewModel>(AppStates.Settings);
sm.DefineViewModelState<AboutViewModel>(AppStates.About);
StateManager = ssm;
}
}
You’ll notice that I refer to this as a region. This is because this framework understands about application regions, such as multiple windows, and whilst it’s not a topic for this post, it allows you to be able to manage those windows. What we do need to do is create a region manager that knows about the PrimaryRegion class, and in fact will set that region to be the default region:
public class SimpleStatesApplication : RegionAwareBaseApplication<PrimaryRegion>
{
protected override void DefineApplicationRegions()
{
// We don’t need to do anything as the PrimaryRegion automatically gets defined
// use “RegionManager.DefineRegion<AnotherRegion>();” to register other regions
}
}
The primary region needs to override the CompleteStartup task to force an initial transition to the Home state.
protected override async Task CompleteStartup()
{
await base.CompleteStartup();
await StateManager.GoToState(AppStates.Home, false);
}
This application can now be run and the Home page will be presented, and actually will have the corresponding MainViewModel set as its DataContext. In the next post I’ll discuss navigating between pages (ie transitioning to different states).