Chinook.BackButtonManager 2.1.0

dotnet add package Chinook.BackButtonManager --version 2.1.0
NuGet\Install-Package Chinook.BackButtonManager -Version 2.1.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Chinook.BackButtonManager" Version="2.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Chinook.BackButtonManager --version 2.1.0
#r "nuget: Chinook.BackButtonManager, 2.1.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Chinook.BackButtonManager as a Cake Addin
#addin nuget:?package=Chinook.BackButtonManager&version=2.1.0

// Install Chinook.BackButtonManager as a Cake Tool
#tool nuget:?package=Chinook.BackButtonManager&version=2.1.0

Chinook.BackButtonManager

License Version Downloads

The Chinook.BackButtonManager packages provide recipes to ease the handling of back buttons in .Net applications. It was designed for MVVM applications, but should work with other patterns too.

Cornerstones

  • Highly Extensible
    • Everything is interface-based to easily allow more implementations.
    • A single framework can't cover everything. Our architecture is designed in a way that allows you to extend this foundation to support more use-cases.
  • Simple
    • The recipes from these packages are ultra-simple but are still complete enough to support edge cases.

More like this

The Chinook namespace has other recipes for .Net MVVM applications.

Getting Started

Uno projects

BackButtonManager is especially well-integrated with Uno. Here is how to use it in a project which includes the Uno platform:

  1. Add a package reference to Chinook.BackButtonManager.Uno.WinUI (for WinUI or MAUI apps).

  2. Create a single instance of a BackButtonManager which you will use throughout your project.

    var manager = new BackButtonManager();
    
  3. In your app's Startup, add the source that the manager uses to detect back button presses:

    // This must be executed on the dispatcher
    var source = new SystemNavigationBackButtonSource();
    manager.AddSource(source);
    

    ❗ Note that SystemNavigationManager no longer works on Windows applications that are not UWP. On WinUI, you can no longer have a global back button in the title bar of the application.

  4. Add handlers for each action you want to take when the back button is pressed:

    manager.AddHandler(new BackButtonHandler(
        name: "TODO handler name",
     canHandle: () => CanYourMethodBeCalled(),
     handle: async ct => await YourMethod(ct)
    ));
    

Other projects

If your project does not use Uno, you can certainly use BackButtonManager! Here's how:

  1. Add a package reference to Chinook.BackButtonManager.

  2. Create a single instance of a BackButtonManager which you will use throughout your project.

    var manager = new BackButtonManager();
    
  3. You will need to create a source which implements the IBackButtonSource interface. In your app's Startup, add this source so that BackButtonManager can use it to detect back button presses.

    var source = new MyBackButtonSource();
    manager.AddSource(source);
    
  4. Add handlers for each action you want to take when the back button is pressed:

    manager.AddHandler(new BackButtonHandler(
      name: "TODO handler name",
      canHandle: () => CanYourMethodBeCalled(),
      handle: async ct => await YourMethod(ct)
    ));
    

Features

Create back button sources

Using IBackButtonSource, you can implement a back button source. You can see that as an abstraction of a button. You could create sources for things like the following.

  • The hardware back button on Android.
  • The escape key from your keyboard.
  • The back button from your mouse.

Once you have a back button source, simply add it to a IBackButtonManager using AddSource.

Create a back button source for XButton1

This is a source for the XButton1, which is the back button on a mouse. This is useful for desktop applications.

Microsoft.UI.Xaml.Window window;
// (Make sure you initialize the window and its content.)
var source = new XButton1BackButtonSource(window.Content);
Create a custom back button source

The interface IBackButtonSource is very simple. You can implement your own sources easily.

Create back button handlers

Using IBackButtonHandler, you can create the objects that react to back requests. Handlers can be added to (or removed from) a IBackButtonManager at any point.

Create global handlers

That's one of the main use-case of this recipe. You likely want to create a default action to perform when a back is requested.

Here is some code showing how to setup a IBackButtonManager with a default handler in a context using Microsoft.Extensions.DependencyInjection and Chinook.Navigation.

public static IServiceCollection AddDefaultBackHandler(this IServiceCollection services)
{
  return services
    .AddSingleton<IBackButtonManager>(s =>
    {
      var manager = new BackButtonManager();

      var sectionsNavigator = s.GetRequiredService<ISectionsNavigator>();
      manager.AddHandler(new BackButtonHandler(
        name: "DefaultSectionsNavigatorHandler",
        canHandle: () => sectionsNavigator.CanNavigateBackOrCloseModal(),
        handle: async ct => await sectionsNavigator.NavigateBackOrCloseModal(ct)));

      return manager;
    });
}
Create temporary handlers

This can be useful when your page has advances states or secondary views. Imagine having a drawer or side menu. When that secondary view is active, it is likely that you want your back button to dismiss that secondary view rather than navigating to the previous page.

public MainPageViewModel(IBackButtonManager manager)
{
	var customHandler = new BackButtonHandler("CustomBackHandler",
		// The handler will only be invoked when the side panel is open.
		canHandle: () => IsSidePanelOpen,
		
		// Close the side panel when a back is requested.
		handle: async ct => IsSidePanelOpen = false
	);
	var subscription = manager.RegisterHandler(customHandler);

	// Automatically remove the handler when this page gets disposed.
	this.AddDisposable(subscription);
}

public bool IsSidePanelOpen
{
	get => this.Get<bool>(initialValue: false);
	set => this.Set(value);
}

💡 This sample shows a ViewModel written using Chinook.DynamicMvvm.

Specify an handler's priority

It is possible to specify a priority when calling IBackButtonManager.AddHandler. The highest priority handlers will be evaluated first.

Legacy

Create a source from SystemNavigationManager

This can be useful for UWP or Uno.UI applications. The source is based on the SystemNavigationManager.BackRequested event.

// This must be executed on the dispatcher
var source = new SystemNavigationBackButtonSource();

Breaking Changes

Please consult BREAKING_CHANGES.md for more information about migration.

License

This project is licensed under the Apache 2.0 license - see the LICENSE file for details.

Contributing

Please read CONTRIBUTING.md for details on the process for contributing to this project.

Be mindful of our Code of Conduct.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.1.0 1,744 2/8/2024
2.0.0 3,889 12/22/2023
2.0.0-feature.Uno5Update.8 146 12/6/2023
2.0.0-feature.Uno5Update.4 1,107 11/28/2023
1.1.5-feature.Uno5Update.2 79 11/2/2023
1.1.4 5,871 10/17/2023
1.1.3 29,283 11/1/2022
1.1.2 19,942 10/12/2022
1.1.1 2,312 9/21/2022
1.1.0 420 9/16/2022
1.0.0 1,202 8/24/2022
0.5.3 399 8/24/2022
0.5.2 409 8/23/2022
0.5.1 380 8/23/2022
0.5.0-dev.33 55,067 5/18/2022
0.5.0-dev.31 179 5/3/2022
0.5.0-dev.29 5,882 3/31/2022
0.4.0-dev.27 320 3/15/2022
0.3.0-dev.22 67,683 3/16/2021
0.2.0-dev.17 1,589 12/17/2020
0.2.0-dev.15 943 10/30/2020
0.2.0-dev.13 12,530 8/13/2020
0.2.0-dev.11 289 8/13/2020
0.2.0-dev.9 1,107 6/26/2020