Skip to content

A lightweight MVVM framework for touch based Windows applications on top of the WPF framework.

License

Notifications You must be signed in to change notification settings

Pulselyre/UpbeatUI

Repository files navigation

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 - UpbeatUI: Basic implementation requiring manual setup and teardown.
  • Nuget - UpbeatUI.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 - UpbeatUI.Extensions.Hosting: An implementation integrated with Microsoft.Extensions.Hosting (IHostBuilder) for easy setup and automatic teardown.

Check the Releases page for pre-release/release-candidate versions with the latest bug fixes, features, and improvements.

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

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

  • Submission must be your own work and releasable under the MIT license.
  • Please follow existing formatting and naming conventions (some areas may currently be inconsisent, so please ask for clarification if necessary).
  • Please include unit tests in the UpbeatUI.Tests project using NUnit.
  • Patches should be submitted as GitHub Pull Requests.