Quickstart

This quick start is intended to show you how easy it is to use Lakana in your application.

Assemblys : In order to use Lakana WPF Navigation, you will have to reference two assemblies : GasyTek.Lakana.Navigation.dll and GasyTek.Lakana.Common.dll. Prior to version 2, only GasyTek.Lakana.Navigation.dll was required.

Basics

INavigationService is the main interface that you will use to navigate through your application.
Typically, the navigation service will be instantiated as a singleton object, meaning there will be one and only one instance of this object during the lifetime of your application.

INavigationService _navigationService = GetSingletonNavigationService();
_navigationServie.Initialize(myContainerGrid);

Simple navigation

var navigationInfo = NavigationInfo.CreateSimple("myUniqueViewKey");
_navigationService.NavigateTo<MyView>(navigationInfo);

First, you create a NavigationInfo object to which you will provide the unique view key that you choose. For MVVM applications, you can provide the view model by using one overloads of NavigationInfo.CreateSimple.
Then you can navigate to your view by calling the NavigateTo method on INavigationService, giving it a NavigationInfo object and specifying the type of your view. Lakana will then instantiate your view, link the view with an eventual view model and then show it as the current view.
Furthermore, for views that were previously added, you can navigate to them simply by using their view key like below.

_navigationService.NavigateTo("myAlreadyAddedViewKey");

Stacking views

// navigate to the parent view
var parentNavigationInfo = NavigationInfo.CreateSimple("myParentViewKey");
_navigationService.NavigateTo<MyParentView>(parentNavigationInfo );
// ..
// stacks a child view on top the previous added parent
var childNavigationInfo = NavigationInfo.CreateComplex("myUniqueViewKey", "myParentViewKey"); 
_navigationService.NavigateTo<MyChildView>(childNavigationInfo );

Stacking views allow you to leverage a kind of “local” linear navigation.
To stack your view on top of existing one, the syntax is almost the same as in “Simple Navigation” section but instead of using NavigationInfo.CreateSimple method, you will use NavigationInfo.CreateComplex method and provide it, not only the view unique key but also the parent key.
Again, you can provide a view model to NavigationInfo.CreateComplex if you use MVVM.

Show modal views

var navigationInfo = NavigationInfo.CreateComplex("myUniqueViewKey", "myParentViewKey");
ModalResult<bool> modalResult = _navigationService.ShowModal<MyView, bool>(navigationInfo);

You can display your views as modal relative to another one by calling ShowModal method on INavigationService .
The modal view can return (or not) a value to its calling view, you can specify the result type on ShowModal method.
Modal views will not block your application as this is usually the case for classic modal windows, instead you can have many modal windows opened at the same time.
Lakana offers a particularly elegant manner to get the modal result  and it does so by leveraging C#5 (and VB 11) async/await pattern.

ModalResult<bool> modalResult = _navigationService.ShowModal<MyView, bool>(navigationInfo);
// awaits for the ShowModal to return
var actualModalResult = await modalResult.Result;
// then continue the flow
if (actualModalResult == ...)

Close view

_navigationService.Close("myViewToCloseKey");

Use Close method on INavigationService to close an opened view. However, you have to provide it the unique view key that identifies your view.
Implementing IViewKeyAware on your view or view models will provide them the associated and correct view key automatically. You can then use those view key to close the view.

// Make your view (or view model) implement IViewKeyAware
public class MyView : UserControl, IViewKeyAware
{
      private void CloseThisView()
     {
            // the ViewKey property was provided by IViewKeyAware
            _navigationService.Close(this.ViewKey);
     }
}

Note that if you use MVVM, it is enough to implement IViewKeyAware on your view models only.

Graceful application shutdown

_navigationService.CloseApplication();

When the user tries to close the application, sometimes there is need to prevent this to happen. A typical case is if there is still some tasks that necessitates user action to be stopped properly before closing the application.
Implementing ICloseable on your view or view models offers you a simple manner to define your custom logic that determines if your view or view model can be closed.

// Make your view (or view model) implement IViewKeyAware
public class MyView : UserControl, ICloseable
{
     // inherited from ICloseable
      public bool CanClose()
     {
            // define here your custom logic that determines if the view can be closed or not
     }
}

Again if you use MVVM, it is enough to implement ICloseable on your view models only.

Conclusion

From here, you should have now a more clear understanding of what you can do with the framework. Do not hesitate to download the sample source code to get deeper into the api.
Lakana is not an intrusive framework which forces you to inherit from view or view model base class for instance.
That characteristic makes it easy to use and to integrate in existing applications.

Last edited Sep 11, 2012 at 9:58 PM by gasytek, version 15

Comments

No comments yet.