Using Keyboard Accelerators in .NET MAUI

Keyboard accelerators, or keyboard shortcuts, are one of the latest .NET MAUI features, released with .NET 8. Let’s take a look!

📣 Attention, developers! On November 14, the Microsoft team made an important announcement: the release of the latest stable version of .NET MAUI, now integrated with .NET 8. 🎉 This is their third major update to .NET MAUI in just 18 months, showing a strong commitment to continuous improvement.

In this new version, the focus has been on making the platform more robust and reliable. 🛠️ They’ve tackled high-impact bugs, worked hard on finding and fixing memory leaks, and made notable improvements in hot reloading, making it more accurate and dependable.

In this article, we will focus on the new keyboard accelerator feature for .NET MAUI. I also encourage you to continue learning about .NET 8 by exploring this article.

And stay up to date with .NET MAUI with Sands of MAUI, a weekly newsletter-style collection of developer news.

What is a Keyboard Accelerator?

Keyboard accelerators, or keyboard shortcuts, enable users to access functionalities more efficiently using key combinations. These shortcuts prevent users from having to navigate through the application’s user interface to reach the desired functionality.

It’s worth noting that .NET MAUI keyboard accelerators are a functionality that can be connected to menu bar items on Mac Catalyst and Windows, and menu items in context menus on Windows. For more information on implementing menus in .NET MAUI, refer to this article.

Accelerator/Shortcut Anatomy

This guide illustrates the essential components of shortcuts. Initially, you’ll encounter a detailed example of the menu. Each critical field within this menu is numbered for easy identification and understanding, ensuring you know exactly what to look for and consider.

A keyboard accelerator is represented by the KeyboardAccelerator class. This serves as a shortcut key for a MenuFlyoutItem and defines the following properties:

Modifiers

Modifiers represent the modifier value. This key is of the type KeyboardAcceleratorModifiers, which enumerates modifier flags for keyboard accelerators. The available flags are as follows:

• None: Signifies the absence of any modifier key.
• Shift: Represents the Shift modifier, functional on both Mac Catalyst and Windows systems.
• Ctrl: Denotes the Control modifier, applicable in Mac Catalyst and Windows environments.
• Alt: Serves as the Option modifier in Mac Catalyst and the Menu modifier on Windows.
• Cmd: Specific to Mac Catalyst, indicating the Command modifier.
• Windows: Exclusive to Windows, representing the Windows key modifier.

Keys

Keys are a string that represents the key value for the shortcut. For instance, consider “Ctrl + K,” where “K” represents the designated key.

Keyboard Accelerator Formats Supported

Single Key

• Mac Catalyst: Utilizes a single key without modifiers, such as F5 for activating a menu item’s action.
• Windows: Can use a single key with or without modifiers, for example, F5 or ALT+F5.

Multi Key

For both platforms, keyboard accelerators can combine one or more modifiers with a single key, like CMD+SHIFT+S or CMD+S, to trigger a menu item’s action.

How to Do It in Code? 🤔

To link a KeyboardAccelerator with a MenuFlyoutItem (which enables us to craft menus), it’s a straightforward process. Just include the <MenuFlyoutItem.KeyboardAccelerators> tags and inside it include the KeyboardAccelerator with its Modifier and its Key.

While this article won’t delve deeply into the specifics of menus, I will provide a reference to their structure to aid your understanding of each step. For more detailed information on creating menus, I recommend the article "Adding Context Menus to Our Desktop Apps With .NET MAUI.”

Let’s see the code:

<MenuFlyoutItem Text="Go to Menu"
    Clicked="OnGoToMenuClicked">
                     
  <MenuFlyoutItem.KeyboardAccelerators> 
    <KeyboardAccelerator Modifiers="Ctrl" 
        Key="H" /> 
    </MenuFlyoutItem.KeyboardAccelerators> 
  </MenuFlyoutItem>

✍️ Additional Considerations

Adding More Than One Modifier

To indicate multiple modifiers, simply separate them with a comma. For example: Modifiers="Shift,Ctrl".

<KeyboardAccelerator Modifiers="Shift,Ctrl"
    Key="F" />

Keys & Modifiers Per Platform

You also have the option to set specific values for keys and modifiers by platform using the OnPlatform markup extension. (For more information about this extension, visit the article “8 Very Useful Markup Extensions in .NET MAUI.”)

<KeyboardAccelerator Modifiers="{OnPlatform MacCatalyst=Cmd, WinUI=Windows}"
    Key="{OnPlatform MacCatalyst=T, WinUI=C}" />

Using Special Keys

 On Windows:

There are special keys that can be represented either by a constant string or an integer. Take a look at the VirtualKey’s table.

 On Mac:

Mac also defines its special keys, which can be specified using a constant string. See the Input strings for special keys.

Code Example:

In this example, the keyboard accelerator is set to the F1 key, defined as a constant for both platforms. On Windows, you can also specify it using the integer value 112.

<MenuFlyoutItem.KeyboardAccelerators> 
  <KeyboardAccelerator Modifiers="None" 
      Key="{OnPlatform MacCatalyst=UIKeyInputF1, WinUI=F1}" />
</MenuFlyoutItem.KeyboardAccelerators>

Some Points to Highlight

Keyboard accelerators are attachable to MenuFlyoutItem objects in MenuBarItem on Mac Catalyst and Windows, and to MenuFlyout on Windows.

🚫 Limitations

Special keys: Virtual gamepad keys are not supported on Windows.

Conclusion

🚀 From now on, you’re all set to add Shortcuts to your application menus! Keep in mind to continually explore the exciting new features of .NET 8 in .NET MAUI! 👀 See you later! 🎉 💚💕

References

This article was based on the official documentation:

• https://learn.microsoft.com/en-gb/dotnet/maui/user-interface/keyboard-accelerators?view=net-maui-8.0