UnoKeyboard

Joan Magnet — Thu, 22 Aug 2024 16:48:38 +0000

UnoKeyboard is an on-screen keyboard control designed to run on Desktop, WASM, and Windows platforms. It's primarily intended for touch-screen devices.

Features

Cross-platform
Customizable design
Theming support
Custom appearance

Adding the Control to Your Project

The control is available as a NuGet package Nuget package or can be integrated from the GitHub source code.

How should I use the Control?

The keyboard can be used in two different ways:

Using the AddKeyboard extension method
Using a XAML control

If your project uses the default frame navigation, I would recommend using the AddKeyboard extension method. This method automatically shows and hides the keyboard when a TextBox gains or loses focus. On the other hand, if you prefer more control over the keyboard or if you are using other navigation methods, use the XAML control instead.

Using the AddKeyboard Extension Method

The library provides an extension method for the Window class to automatically add the control to your project.

The AddKeyboard method injects a two-row grid. The first row contains a ScrollViewer, and the second row displays the virtual keyboard. The content of the ScrollVieweris assigned to the RootFrameproperty of the McWindowExclass.

Add a reference to McWindowEx.RootFrame in your App.xaml.cs file:

    public static Frame RootFrame => McWindowEx.RootFrame;

Comment out the code that creates the main Frame in the OnLaunched method:

    // Do not repeat app initialization when the Window already has content,
    // just ensure that the window is active
    //if (MainWindow.Content is not Frame rootFrame)
    //{
    //    // Create a Frame to act as the navigation context and navigate to the first page
    //    rootFrame = new Frame();

    //    // Place the frame in the current Window
    //    MainWindow.Content = rootFrame;
    //    rootFrame.NavigationFailed += OnNavigationFailed;
    //}

    //if (rootFrame.Content == null)
    //{
    //    // When the navigation stack isn't restored navigate to the first page,
    //    // configuring the new page by passing required information as a navigation
    //    // parameter
    //    rootFrame.Navigate(typeof(MainPage), args.Arguments);
    //}

Call the AddKeyboardmethod and navigate to the main page:

    // Add UnoKeyboard to the Window
    MainWindow.AddKeyboard(height: 300);

    // Navigate using McWindowEx.RootFrame
    if (RootFrame.Content == null)
    {
        RootFrame.Navigate(typeof(MainPage), args.Arguments);
        RootFrame.NavigationFailed += OnNavigationFailed;
    }

From this point on, the virtual keyboard will automatically appear whenever a TextBoxgains focus.

Using an XAML Control:

Add a reference to the xmlns:ukc="using:UnoKeyboard.Controls" namespace and then add a new control to your file

<ukc:UnoKeyboard x:Name="MyKeyboard"
                 Height="300"
                 Visibility="Collapsed"
                 HandleFocusManager="True" />

Properties

Here are some of the properties. For a complete list, refer to the control's documentation.

Height

This property defines the height of the virtual keyboard. It's important to note that the height of each key depends on the keyboard's height. For example, if the keyboard is 300px high and has 4 rows, each row will be::

(300 - (Padding.Top + Padding.Bottom)) / 4

Similarly, the width of each key is calculated based on the number of keys per row.

HandleFocusManager

If the HandleFocusManagerproperty is set to True, the control will automatically show and hide the virtual keyboard when a TextBox gains or loses focus. Otherwise, the keyboard must be shown and hidden manually.

Keyboard Type

The McWindowExextension class introduces a new attached property: KeyboardType, which allows for keyboard selection. Two default keyboards are available, but you can add more custom keyboards:

en-alfa
numeric

To use a specific keyboard, set the KeyboardTypeattached property on your TextBoxcontrol. The default keyboard is en-alfa:

<Page 
    xmlns:mck="using:UnoKeyboard" />

<TextBox Width="200"
         VerticalAlignment="Center"
         FontSize="30"
         mck:McWindowEx.KeyboardType="numeric" />

Customization

Two static dictionaries are used to define the keyboard and its keys. You can add more keys and keyboard layouts by adding new entries to these dictionaries.

VirtualKeys

The VirtualKeys.Key dictionary dictionary defines the keys that will be displayed on the keyboard. Each key is defined by a VirtualKeyModel.

That is a reduced version of the dictionary:

public static class VirtualKeys
{
    public static Dictionary<string, VirtualKeyModel> Key = new()
    {
        { "N1", new VirtualKeyModel("N1", KeyType.Text, "1", "1", 0x0031, 0x0031, null) },
        { "N2", new VirtualKeyModel("N2", KeyType.Text, "2", "2", 0x0032, 0x0032, null) },
    }
}

For example, to add the | key to your custom keyboard layout:

VirtualKeys.Key.Add("|",                // Dictionary key
    new VirtualKeyModel("|",            // Key ID
                        KeyType.Text,   // Type
                        "|",            // Uppercase
                        "|",            // Lowercase
                        0x007C,         // Unicode uppercase
                        0x007C,         // Unicode lowercase
                        null));         // A Func<Microsoft.UI.Xaml.Shapes.Path>? that returns a Path
                                        // used to draw special keys.

Keyboards

The Keyboards.Keyboard dictionary defines the keyboard layouts. Each keyboard is defined by a KeyboardModel.

Let's add the new key to the keyboard layout:

Keyboards.Keyboard.Add("my_keyboard",   // Dictionary key
    new KeyboardModel("my_keyboard"     // Keyboard Id
                      "1",              // Number of pages.
                      "3",              // Number of rows.
                      "10",             // Max. keys per row.
                      [
                        new KeyModel(0,                     // Page 0
                                     0,                     // Row 0
                                     1,                     // Column 1
                                     1,                     // Column span
                                     VirtualKeys.Get("|")), // Key
                      ]));

For any questions or suggestions, feel free to contact me in the Discussions section or open an Issue on the GitHub repository. You can also find me active in the Uno Platform Discord server.

Everyone is welcome to contribute to the project. Thank you for your interest!

Joan Magnet Sabata

Forem: Joan Magnet