Home

Awesome

<!-- This file is part of the UpbeatUI project, which is released under MIT License. See LICENSE.md or visit: https://github.com/pulselyre/upbeatui/blob/main/LICENSE.md -->

UpbeatUI

License: MIT Nuget

UpbeatUI is an open-source lightweight MVVM framework for quickly developing mobile-style touch based Windows applications using Windows Presentation Foundation (WPF). It provides a simple API for stacking Views in the Z-Axis where only the top View is active to the user. The user can close the active view (remove it from the top of the stack) by tapping/clicking the surrounding background area. UpbeatUI also includes versions of several standard MVVM objects and base classes.

UpbeatUI supports .NET Core 3.0, .NET Core 3.1, .NET 5, .NET 6, .NET 7, and .NET 8.

UpbeatUI is not widely used and thus may have unidentified bugs or performance inefficiencies. Please see the Contributing section for information on how to help make UpbeatUI better. See the To-Do List for planned future work.

UpbeatUI was originally split from the codebase for Pulselyre, a live MIDI sequencing application designed for touch input.

Installation

UpbeatUI implementations are available as NuGet packages:

Nuget
Nuget<br/>NugetUpbeatUI: Basic implementation requiring manual setup and teardown.
Nuget<br/>NugetUpbeatUI.Extensions.DependencyInjection: An implementation integrated with Microsoft.Extensions.DependencyInjection (IServiceProvider) that provides dependency injection capabilities and automatic Parameters-ViewModel-View mapping via naming convention.
Nuget<br/>NugetUpbeatUI.Extensions.Hosting: An implementation integrated with Microsoft.Extensions.Hosting (IHostBuilder) for easy setup and automatic teardown.

Examples

Three samples are included: one showing manual setup and teardown without dependency injection, one showing manual setup and teardown with dependency injection using an IServiceProvider, and one showing automatic setup and teardown using an IHostBuilder. All samples demonstrate the following capabilities:

UpbeatUI Sample

How UpbeatUI Works

There are two central components of UpbeatUI: The first is the UpbeatStack class. It is responsible for managing the stack of open ViewModels and also maintaining mappings between ViewModelParameters and ViewModels. The second is the IUpbeatService interface which provides ViewModels with methods and properties for interacting with their parent UpbeatStack. For example, the IUpbeatService has methods for opening a new ViewModel on top of the stack. The UpbeatStack provides a unique IUpbeatService to each ViewModel.

Opening a new ViewModel is done by passing a ViewModelParameters object to the OpenViewModel or OpenViewModelAsync method on the UpbeatStack or IUpbeatService. A ViewModelParameters object contains initialization data for a ViewModel. There must be a unique ViewModelParameters class for each ViewModel class, as the UpbeatStack relies on mappings between Types to create ViewModels and thus display Views.

How to use UpbeatUI

Please see the separate How To Use markdown file for a guide to the basic features in UpbeatUI.

To-Do List

<!-- - Publish new major release with deprecated classes and methods fully removed. - Remove the [`UpbeatControl`](source/UpbeatUI/View/UpbeatControl.cs) entirely, and rely on [`<DataTemplate DataType="{x:Type ...}">`](https://learn.microsoft.com/en-us/dotnet/desktop/wpf/data/data-templating-overview#the-datatype-property) instead to match _ViewModel_ instances on the [`UpbeatStack`](source/UpbeatUI/ViewModel/UpbeatStack.cs) with _Views_. Also, re-implement the percentage size and position behavior as a [WPF Decorator](https://learn.microsoft.com/en-us/dotnet/api/system.windows.controls.decorator). - Cleanup/improve [`.gitignore` file](.gitignore) (too many unnecessary items listed). - Deprecate the public [`ActionDeferrer`](source/UpbeatUI/ViewModel/ActionDeferrer.cs) (and move all functionality to [`UpbeatStack.UpbeatServiceDeferrer`](source/UpbeatUI/ViewModel/UpbeatStack.UpbeatServiceDeferrer.cs)). - Simplify [`HostedUpbeatBuilder`](source/UpbeatUI.Extensions.Hosting/HostedUpbeatBuilder.cs), [`HostedUpbeatSerivce`](source/UpbeatUI.Extensions.Hosting/HostedUpbeatService.cs), [`UpbeatApplicationService`](source/UpbeatUI.Extensions.Hosting/UpbeatApplicationService.cs), and [`ConfigureUpbeatHost`](source/UpbeatUI.Extensions.Hosting/Extensions.cs#L22) implementations. - Cleanup/improve [`.editorconfig` file](.editorconfig) and format all source files. -->

Contributing

Additions, bug fixes, and performance improvements are welcome. For larger modifications please open an issue to discuss the changes.

Editing

Recommended code editor is VS Code. If using VS Code, please open the repository through the upbeatui.code-workspace file. This will ensure that certain formatting settings are applied. The following VS Code extensions are recommended:

  1. EditorConfig for VS Code
  2. Prettier - Code formatter
  3. .NET Core Test Explorer
  4. C#
  5. PowerShell
  6. XML

Building/Running

This project defines tasks for executing builds, tests, and other common actions using the Invoke-Build tool for PowerShell. To install Invoke-Build, visit their GitHub page: nightroman/Invoke-Build.

Submitting Changes