RibbonSpace.Core 1.1.0

<p align="center"> <img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/build/icon.png" width="96" alt="RibbonSpace" /> </p>

<h1 align="center">RibbonSpace</h1>

<p align="center"> <b>A modern, Office-style Ribbon for Uno Platform and WinUI 3.</b><br/> Classic and simplified layouts, adaptive resizing, contextual tabs, backstage, Quick Access Toolbar, KeyTips, galleries with live preview, Office color pickers, ScreenTips, command search, customization, toolbars and full MVVM. </p>

<p align="center"> <a href="https://github.com/wieslawsoltes/RibbonSpace/actions/workflows/build.yml"><img src="https://github.com/wieslawsoltes/RibbonSpace/actions/workflows/build.yml/badge.svg" alt="Build" /></a> <a href="https://www.nuget.org/packages/RibbonSpace.Uno"><img src="https://img.shields.io/nuget/v/RibbonSpace.Uno.svg?label=RibbonSpace.Uno" alt="NuGet" /></a> <a href="https://www.nuget.org/packages/RibbonSpace.WinUI"><img src="https://img.shields.io/nuget/v/RibbonSpace.WinUI.svg?label=RibbonSpace.WinUI" alt="NuGet" /></a> <a href="https://www.nuget.org/packages/RibbonSpace.Core"><img src="https://img.shields.io/nuget/v/RibbonSpace.Core.svg?label=RibbonSpace.Core" alt="NuGet" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT" /></a> <a href="https://wieslawsoltes.github.io/RibbonSpace/"><img src="https://img.shields.io/badge/demo-WebAssembly-5B5FC7.svg" alt="Live demo" /></a> </p>

RibbonSpace is the shared command UI for the Uno "Space" applications (TextSpace, GridSpace, PresentationSpace, NoteSpace, DataSpace, CadSpace, and ImageSpace, VectorSpace and the other toolbar-based apps). It was designed after studying all seventeen of them and modern Word, Excel and PowerPoint (research).

It runs on every Uno Platform target: Windows, macOS, Linux, WebAssembly, iOS and Android. It also runs natively in WinUI 3 (Windows App SDK) apps that don't use Uno. Both packages compile the same sources, so they share every control, feature and fix.

Highlights

<table> <tr> <td colspan="2"><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/cad.png" alt="CAD workspace" /><br/>_{CAD: AutoCAD-class ribbon with the CAD theme, layer drop-down, floating and expanded panels (<a href="https://github.com/wieslawsoltes/RibbonSpace/blob/main/docs/cad.md">guide</a>)}</td> </tr> <tr> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/cad-appmenu.png" alt="CAD application menu" /><br/>_{Application menu with search, sub-commands and recent documents}</td> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/cad-tooltip.png" alt="Progressive tooltip" /><br/>_{Progressive tooltip with extended help}</td> </tr> <tr> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/excel.png" alt="Excel style MVVM ribbon" /><br/>_{Excel: 100% MVVM (<code>RibbonModel</code>)}</td> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/ppt.png" alt="PowerPoint simplified ribbon" /><br/>_{PowerPoint: simplified ribbon}</td> </tr> <tr> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/keytips-home.png" alt="KeyTips" /><br/>_{KeyTips (Alt → H)}</td> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/gallery.png" alt="Gallery" /><br/>_{Expanded gallery with categories, filter and footer}</td> </tr> <tr> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/backstage.png" alt="Backstage" /><br/>_Backstage</td> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/customize.png" alt="Customize dialog" /><br/>_{Customize the Ribbon}</td> </tr> <tr> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/color.png" alt="Color picker" /><br/>_{Office colour picker}</td> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/search.png" alt="Search" /><br/>_{Command search (Alt+Q)}</td> </tr> <tr> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/dark.png" alt="Dark theme" /><br/>_{Dark theme}</td> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/colorful.png" alt="Colorful chrome" /><br/>_{Colorful chrome, PowerPoint palette}</td> </tr> <tr> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/contextual.png" alt="Contextual tabs" /><br/>_{Contextual tabs (Table Tools)}</td> <td><img src="https://raw.githubusercontent.com/wieslawsoltes/RibbonSpace/main/docs/images/tools.png" alt="Toolbars" /><br/>_{Menu bar, option bar, tool palette, rail, floating command bar}</td> </tr> </table>

Packages

Package	NuGet	Use it for
RibbonSpace.Uno		Uno Platform 6 apps, on every head
RibbonSpace.WinUI		WinUI 3 (Windows App SDK) apps without Uno (guide)
RibbonSpace.Core		UI-agnostic models, commands, layout algorithms, KeyTips, search, state, palettes and strings, for view models that must not depend on a UI framework (net10.0, net9.0)

dotnet add package RibbonSpace.Uno     # Uno Platform apps
dotnet add package RibbonSpace.WinUI   # WinUI 3 apps

RibbonSpace.Uno and RibbonSpace.WinUI both depend on RibbonSpace.Core.

Supported platforms

Quick start (Uno Platform XAML)

No namespace declaration or prefix is needed: RibbonSpace registers its types in Uno.Sdk's global XAML namespace (implicit XAML namespaces are on by default), so <Ribbon> works like any built-in control. The prefixed forms (rs: without declaration, xmlns:rs="https://github.com/wieslawsoltes/RibbonSpace" or xmlns:rs="using:RibbonSpace.Controls") remain available, and XAML compiled by WinUI's XAML compiler (WinUI 3 apps, Windows App SDK heads) needs the using: form (see XAML namespaces).

<Grid RowDefinitions="Auto,Auto,*">
  <RibbonTitleBar Title="Report" AppIcon="&#xE8A5;" Ribbon="{x:Bind Ribbon}" />
  <Ribbon x:Name="Ribbon" Grid.Row="1" ItemInvoked="OnItemInvoked">
    <RibbonTab Id="home" Header="Home">
      <RibbonGroup Id="clipboard" Header="Clipboard" IsDialogLauncherVisible="True">
        <RibbonSplitButton Id="paste" Label="Paste" Icon="&#xE77F;" SizeDefinition="Large" Shortcut="Ctrl+V">
          <MenuFlyout><MenuFlyoutItem Text="Keep Text Only" /></MenuFlyout>
        </RibbonSplitButton>
        <RibbonButton Id="cut" Label="Cut" Icon="&#xE8C6;" Command="{x:Bind ViewModel.CutCommand}" />
        <RibbonButton Id="copy" Label="Copy" Icon="&#xE8C8;" />
      </RibbonGroup>
      <RibbonGroup Id="font" Header="Font" ItemsLayout="Rows" RowCount="2">
        <RibbonStackPanel>
          <RibbonFontComboBox Text="Aptos" />
          <RibbonFontSizeComboBox Text="11" />
        </RibbonStackPanel>
        <RibbonStackPanel>
          <RibbonButtonGroup>
            <RibbonToggleButton Id="bold" Label="Bold" Icon="&#xE8DD;" Shortcut="Ctrl+B" IsChecked="{x:Bind ViewModel.IsBold, Mode=TwoWay}" />
            <RibbonToggleButton Id="italic" Label="Italic" Icon="&#xE8DB;" Shortcut="Ctrl+I" />
          </RibbonButtonGroup>
          <RibbonColorPicker Id="fontColor" Label="Font Color" />
        </RibbonStackPanel>
      </RibbonGroup>
    </RibbonTab>
  </Ribbon>
</Grid>

Quick start (WinUI 3)

WinUI's XAML compiler resolves using: namespaces only, so WinUI 3 apps declare a prefix. Everything else (MVVM, commands, KeyTips, QAT, backstage, theming, state) works as on Uno:

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:rs="using:RibbonSpace.Controls">
  <Grid RowDefinitions="Auto,Auto,*">
    <rs:RibbonTitleBar Title="Report" Ribbon="{x:Bind Ribbon}" />
    <rs:Ribbon x:Name="Ribbon" Grid.Row="1" ItemInvoked="OnItemInvoked">
      <rs:RibbonTab Id="home" Header="Home">
        <rs:RibbonGroup Id="clipboard" Header="Clipboard">
          <rs:RibbonButton Id="paste" Label="Paste" Icon="&#xE77F;" Size="Large" />
          <rs:RibbonButton Id="cut" Label="Cut" Icon="&#xE8C6;" />
        </rs:RibbonGroup>
      </rs:RibbonTab>
    </rs:Ribbon>
  </Grid>
</Window>

The WinUI guide covers requirements, theme resources, title bar integration and how the port shares the Uno sources.

Quick start (MVVM)

var ribbon = new RibbonModel { CommandCatalog = catalog };
ribbon.Tabs.Add(new RibbonTabModel("home", "Home")
{
    Groups =
    {
        new RibbonGroupModel("clipboard", "Clipboard", RibbonIcons.Paste)
        {
            Items =
            {
                new RibbonSplitButtonModel("paste", "Paste", RibbonIcons.Paste) { CommandId = "paste" },
                new RibbonToggleButtonModel("bold", "Bold", RibbonIcons.Bold) { Shortcut = "Ctrl+B" },
                new RibbonColorPickerModel("fontColor", "Font Color", RibbonIcons.FontColor),
            },
        },
    },
});

<Ribbon Model="{x:Bind ViewModel.Ribbon}" />

Checked states, values, selection, display modes, contextual groups, the QAT and the backstage stay in two-way sync. See MVVM.

Documentation

Getting started · WinUI 3 · WinUI and Uno differences · Architecture · XAML · MVVM · Commands and keyboard · Controls reference · Layout · Tabs · QAT · Backstage · KeyTips · Search · Galleries and pickers · Toolbars and chrome · Theming · Localization · Customization and state · Accessibility · Migration · Testing · Releasing

Gallery app

dotnet run --project samples/RibbonSpace.Demo -f net10.0-desktop

It has Word (XAML), Excel (MVVM), PowerPoint (simplified), toolbars and palettes, CAD, and settings (theme, palette, chrome, density, layout, language, state JSON, event log). It also runs in the browser: wieslawsoltes.github.io/RibbonSpace, and as a WinUI 3 app (dotnet run --project samples/RibbonSpace.WinUI.Demo on Windows).

Build and test

dotnet build RibbonSpace.slnx
dotnet test tests/RibbonSpace.Core.Tests
dotnet run --project tests/RibbonSpace.Uno.RuntimeTests -f net10.0-desktop   # runtime UI tests in a real window

Requirements: .NET 10 SDK, and Uno.Sdk 6.7 (resolved from global.json). Building for WebAssembly needs the wasm-tools workload, and building every target needs android and ios too (-p:RibbonSpaceAllTargets=true). On Windows that also adds the WinAppSDK target, which must be built with Visual Studio's msbuild /restore rather than dotnet build.

WinUI 3 (on Windows; plain dotnet build works):

dotnet build RibbonSpace.WinUI.slnx
dotnet run --project samples/RibbonSpace.WinUI.Demo
dotnet run --project tests/RibbonSpace.WinUI.RuntimeTests

License

MIT © Wiesław Šoltés