WinryVirtualKeyboard 1.2 | Open-Source and Multi-Platform On-Screen Keyboard!


Version Archive Place    WinryVirtualKeyboard Model - Creator Store

Version: 1.2.0
Latest Patch Notes

Special Thanks to:
@Ebonhelm - EN-US Dictionary Proofreading & Assistance


Features

  • Default EN-US ANSI Keyboard Layout
    Developers can leverage an existing US English Keyboard Layout, with support for Shift, Caps Lock and Alt Modifier keys.

  • Region File Localization Support
    Multiple Localizations can be provided by developers, alongside the default en-us localization, for a wider reaching audience.

  • Keyboard Suggestions
    Localization Files can contain a dictionary module for suggesting words to players based on the partial word they’re currently typing. Built with Parallel Luau.

  • Integrated Gamepad Support
    Tested with XBOX, PlayStation and Nintendo Switch Pro Controllers via USB-C on Windows.


About

WinryVirtualKeyboard is a new On-Screen Keyboard developed with gamepad and mouse-only use in mind. Created for experiences that wish to extend the accessibility of various social features to all platforms, this new On-Screen Keyboard features full customization for your experience, including reg

This on-screen keyboard has been built from the ground up to dynamically resize to the user’s screen and work with UI Selection through the use of GuiService and UserInputService. Archives of previous versions can be found in the place provded at: ServerStorage/Versions.

Demo Video (Version 1.1)

Images



No-Attribution License

Developers are not required to credit or otherwise refer to WinryVirtualKeyboard. You are free to do anything, including (but not limited to) the modification and redistribution of WinryVirtualKeyboard. Use of WinryVirtualKeyboard as a direct-reference resource for source code is also permitted for any other assets without accreditation.

Disclaimer of Distribution

In return for the limitless use of WinryVirtualKeyboard, outside of the original format(s) supplied above, we do not retain any responsibility or liability as open-source developers for modifications to or redistributions of WinryVirtualKeyboard by third-parties and can in no way guarantee that every version will work as described in the original distributions’ documentation. If any problems occur with the original distribution, developers may notify us via this post or in direct messages and we will work with all reasonable action to resolve them as part of ongoing patches and updates if possible.

We are also not responsible for any changes to the standard en-us dictionary provided for keyboard suggestions, nor the addition of new locales provided by developers. While we have done our best to ensure the appropriate selection of words for all audiences, any text that is created or edited via Keyboard Suggestions should go through the proper text filtering process.


Information

Setting Up WinryVirtualKeyboard

The new On-Screen keyboard can be found at StarterGui.KeyboardUI.OnScreenKeyboard and can be copied anywhere without interference, and without the ScreenGui if desired. You can also customize the appearance and behaviour of WinryVirtualKeyboard using the list of attributes attached to the Keyboard UI - See the “Appearance and Behaviour Settings” tab for more.

To see an example of this keyboard integrated with a social feature, WinryChat 1.4 (or later) comes with WinryVirtualKeyboard for gamepad support. Please keep in mind, you need to download a copy of that place to preview it with an existing feature.

Appearance & Behaviour Settings

AudioFeedbackEnabled:
Whether or not to play audio when the Chat is opened and closed or a button is clicked.

ButtonActivatedColor:
The color of a virtual key while it is active (LeftShift, RightShift and CapsLock) or pressed.

ButtonBackgroundActivatedColor:
The color of a virtual key’s background outline while it is active (LeftShift, RightShift and CapsLock) or pressed.

ButtonBackgroundDefaultColor:
The color of a virtual key’s background outline while it is idle.

ButtonBackgroundRestrictedColor:
The color of a virtual key’s background outline while it is restricted. Used for the LeftSuper and RightSuper keys.

ButtonBackgroundSelectedColor:
The color of a virtual key’s background outline while it is being hovered over.

ButtonDefaultColor:
The color of a virtual key while it is idle.

ButtonFontColor:
The color of the font on each virtual key.

ButtonSelectdColor:
The color of a virtual key while it is being hovered over.

EnableVisibilityAnimations:
Whether animations of the keyboard appearing and hiding are used, instead of enabling and disabling keyboard visibility…

EnterClosesKeyboard:
Whether selecting the Enter Key closes the keyboard.

ExitKeyboardKeyCode:
The key to press on a physical Keyboard to exit the virtual keyboard.

GamepadExitKeyboardKeyCode:
The key to press on a gamepad to exit the virtual keyboard.

KeyboardBackgroundColor:
The background color of the Keyboard UI itself.

ExitKeyboardKeyCode :
The key on a physical keyboard to close the virtual keyboard. Provided for testing in ROBLOX Studio and ROBLOX Desktop Clients.

GamepadExitKeyboardKeyCode :
The key on a gamepad to close the virtual keyboard. Provided for testing in ROBLOX Studio and ROBLOX Desktop Clients.

Localization:
The locale files to load from OnScreenKeyboard/VirtualKeyboardManager/Locales. en-us is set as the default.

MaximumSuggestionsInList:
The maximum amount of word suggestions that the keyboard can provide to the player. This can be set to -1 for every possible suggestion found or a custom limit.

ShowGamepadHints:
Whether to show gamepad hints at the bottom of the keyboard at first. This changes if FocusKeyboard:Fire() is called with at least one boolean value.

Default Theme

This is the default theme setup for WinryVirtualKeyboard. If you forget what settings you had, this can be a useful reference point.

Settings:
image

Appearance:

Modifier Key Behaviour

Please note that while using modifier keys:

  • If Shift and Caps Lock are both active, then the first key press appears in lower-case, with subsequent presses appearing in upper-case.

  • If only Shift is active, then the first key press appears in upper-case, with subsequent presses appearing in lower-case.

  • If only Caps lock is active, then all key presses will appear in upper-case.

Scripting API for WinryVirtualKeyboard

WinryVirtualKeyboard provides several BindableEvents for implementing the virtual keyboard as part of Text Input areas. BindableEvents were selected for their greater presence and understanding of use. Signal libraries/modules can be used instead as a replacement in your own fork, but these are not currently supported due to the accessibility that BindableEvents provide to a wide range of developers.

These are all direct descendants of OnScreenKeyboard.


Input Events - Uses BindableEvent:Fire

FocusKeyboard - Bring up the On-Screen Keyboard.

  • locale - A string for which locale to load if a locale file can be found. You can use Player.LocaleId for this. Default: en-us, if no valid locale file can be found.

  • displayGamepadHints - A boolean for whether to display the gamepad input hint icons.

  • displaySuggestionsList - A boolean for whether to display keyboard suggestions.

OnSuggestMatchingWords - Bring up Word Suggestions.

  • partialWord - A string of a partial (or complete) word to find matches for. E.G.

  • suggestPlayerNames - Whether to suggest player names instead of words from the loaded locale’s dictionary.


Output Events - Uses BindableEvent.Event:Connect(...)

OnBackspacePressed - Fired when the Backspace Button is activated on the Virtual Keyboard.

  • No Arguments Passed.

OnEnterPressed - Fired when the Enter Button is activated on the Virtual Keyboard.

  • No Arguments Passed.

OnKeyDown - Fired when a non-special key is activated on the Virtual Keyboard.

  • returnedKey - A string value representing the key. This may be depending on if CapsLock, Shift and/or Alt were active.

  • key - The Enum.KeyCode value of the key pressed.

  • shiftModifierActive - Was the shift modifier active when this key was pressed. (Boolean)

  • altModifierActive - Was the alt modifier active when this key was pressed. (Boolean)

  • capslockModifierActive - Was the caps lock modifier active when this key was pressed. (Boolean)

OnSuggestedWordSeletced - Fired when a non-special key is activated on the Virtual Keyboard.

  • word - A string value of the suggested word that was seletced.

Example Implementation: WinryChat's use of WinryVirtualKeyboard

Setup
As WinryChat can’t explicitly rely on the On Screen Keyboard remaining a constant (due to developers removing the keyboard after forking the chat), It assumes at first that the Virtual Keybaord is not present, unless it can find the FocusKeyboard event.

If the FocusKeyboard event can be found, then WinryChat assumes that all other events exist correctly. Because of this, once the Text Field is focused by a gamepad device, the TextField creates bindings to KeyPressed, BackspacePressed and EnterPressed if none exist currently.

Connections can only linger after the initial focus occur if the player uses the Esc key on the keyboard, instead of Enter which will disconnect all existing connections.

KeyPressed uses only the first argument passed through OnKeyDown, KeyValue, in order to append the value to the text box string and then change the cursor position.

BackspacePressed gets either the substring of the current text (1 → Len - 1) or a blank string, depending on the length of the text in the TextField.

EnterPressed will send the channel message to the server, clear the text field and disconnect any existing connections.


Layout Customiaztion for WinryVirtualKeyboard

While WinryVirtualKeyboard tries to make it possible for multiple layouts to work, there are definitely times where a hard-coded layout for non-ANSI keyboards may be preferred by foreign developers. For this purpose, WinryVirtualKeyboard has a Locales folder as a child of VirtualKeyboardManager, where each module script represents a locale layout. A region file, like the en-us one by default, allows developers to extensively modify the complete layout and structure of the Keyboard for the five-row layout. As long as ROBLOX’s UI can display a character, you can use it with the keyboard.

You can find the example EN-US locale in the place file here: StarterGui/KeyboardUI/OnScreenKeyboard.VirtualKeyboardManager/Locales/en-us

Intellisense types are defined here:
StarterGui/KeyboardUI/OnScreenKeyboard.VirtualKeyboardManager/TypeData

Virtual Key

VirtualKey consists of four pieces of information:

  • KeyValue : Enum.KeyCode - What does this key represent by default?

  • ShiftHeldKeyValue: Enum.KeyCode? - An optional alternate key to display when shift is held, instead of the default.

  • AltHeldKeyValue: Enum.KeyCode? - An optional alternate key to display when alt is held, instead of the default.

  • KeyAspectRatio : number - The width of the key when displayed.

  • displayString : string - An alternate string of text to display if the key has no ASCII character that ROBLOX returns normally (i.e. Esc, Backspace, Tab, Return)

Afterwards comes a generally complete map, based on a mix of the RK98 Keyboard in ANSI-Layout and the Windows 10 On-Screen Keyboard. The keyboard is currently divded into 5 prominent rows, starting from the alpha-numeric keys (Row1), and descending towards the Modifier Keys, OS Keys and Spacebar (all on Row5).

Each Row can be tweaked to developer preferences, with three keys having special reserved behaviours. These being:

  • Enum.KeyCode.Unknown - This is used as a fake character to create a “space” in between two existing characters, if desired. The KeyAspectRatio property will determine how big the space is. This will not use displayString or ModifierHeldKeyValue.

  • Enum.KeyCode.LeftSuper and Enum.KeyCode.RightSuper - These will create a dark “restricted” key that acts as a gap between two keyboards, while communicating to a user that a key would normally be there for Windows and MacOS keyboards.

In case you lose a backup of the reference locale (or don’t make one), here is the default bindings provided in the base configuration of WinryVirtualKeyboard.

Default Bindings - ANSI





Custom Dictionaries / Keyboard Suggestions

Custom dictionaries can be provided for a locale, by adding a ModuleScript called “dicitonary” as a child of a Locale ModuleScript. A dictionary simply contains an array of arrays that get string matched by the virtual keyboard for you. As long as Luau can recognize and match a character with it’s string library, any character can be used for starting a dictionary section.

As an example, the EN-US dictionary has an array of words that can be searched through to find applicable word matches to the character a. 26 arrays exist, and developers can fill out the dictionary with arrays like the example, return it (with or without strict typing applied) and the keyboard will handle the rest on it’s own.

Please make sure that any dictionary words are appropriate for all ages. We aren’t responsible for any moderation action created by third-party dictionaries and cannot provide support for dictionaries or locales made for other languages.


Alternatives

This section will be updated over time, as more resources are brought to my attention.

Currently, no known alternatives exist outside of the native platform keyboards (and supposedly ROBLOX’s built in one). If you have an alternative solution, please send a message with a direct link.


Final Notes
If you have any features to suggest, or find any bugs, please leave a comment and we’ll try to respond with either a fix or update for you. We want to keep open-sourcing and maintaining reliable systems that anyone can use in their experiences!

ASSET ATTRIBUTIONS

Currently, the only sound effect used is created by InceptionTime, “Type Writer”, as a placeholder sound effect for public use.

Asset Id: rbxassetid://147982968

If this asset requires a unique license, and you wish to use it, you may need to contact the individual owners.

17 Likes

Winry Virtual Keyboard - Update Log for Version 1.1

Within 24 hours of the initial public release (Version 1.0.1), a few new features have been added and user experience improvements have been made. This also comes with some slight API changes for using WinryVirtualKeyboard, however none that are drastic enough to warrant large edits to existing code.

One of the features that was missing were Gamepad Hints for the gamepad you were actively using. By using UserInputService:GetImageForKeyCode(), we have added a new optional section below the major rows of keys which display four shortcuts for the virtual keyboard (with room for more), Additionally, Alt Key support has been added and RowMappings slightly reworked to account for it. However, there are no current alternate graphics or keys available.

In the future of WVK (1.2 and beyond), we’re aiming to roll out auto-complete for at least the 25 most common user-friendly words in the english language, as well as building a file structure and format that allows for multiple languages to make use of the Shift key, Alt key and their own individual keyboard layouts in place of RowMappings as a single ModuleScript.

We hope to build an on-screen keyboard that can support multiple languages, with the help of linguists around the world.


New Features / Behaviours


  • Gamepads can now scroll horizontally between both sides of a row through Joystick and D-Pad navigation. This does not have vertical support, as we do not want to trap UI Selection to just the virtual keyboard.

  • Gamepad Hint Icons now sync when players switch gamepads while in ROBLOX Studio or the ROBLOX Client.

  • LeftAlt and RightAlt Keys now works as modifier keys. These take priority over Shift keys in alternate character searches.

  • Pressing a Shift Key now deactivates the Alt Modifier, and pressing an Alt Key now deactivates the Shift Modifier.

  • Players can now exit out of the virtual keyboard using a gamepad or keyboard key code. This is only detected while the keyboard is visible.


New Settings (Attribtues)


ShowGamepadHints : boolean
Whether to show gamepad hints at the bottom of the keyboard at first. This changes if FocusKeyboard:Fire() is called with at least one boolean value. Default: false

ExitKeyboardKeyCode : Enum.KeyCode
The key to press on a physical Keyboard to exit the virtual keyboard. Default: Enum.KeyCode.Escape

GamepadExitKeyboardKeyCode : Enum.KeyCode
The key to press on a gamepad to exit the virtual keyboard. Default: Enum.KeyCode.ButtonB


API Changes


  • OnKeyDown now sends the following parameters:
    • KeyValue : string - The ASCII character represented by the key pressed, based on the modifier keys (Shift and/or CapsLock).
    • KeyCode : Enum.KeyCode - The direct KeyCode that WinryVirtualKeyboard interpreted as being pressed, based on the modifier keys (Shift and/or CapsLock).
    • WasShiftActive : boolean - Was the shift key modifier active when this key was pressed?
    • WasAltActive : boolean - Was the altkey modifier active when this key was pressed?
    • WasCapsLockActive : boolean - Was the CapsLock key modifier active when this key was pressed?
  • FocusKeyboard now takes the following parameters:
    • ShowGamepadHints: boolean? - Whether to show the gamepad hints at the bottom of the keyboard. If left blank, or if nil is presented, then this keeps the previous value of the ShowGamepadHints attribute.

Closing Notes


Most of the things that happened, which weren’t listed above, were actually bugs or issues with the integration of WinryVirtualKeyboard in WinryChat 1.4. So those notes will be present in WinryChat 1.4.1 shortly.

However, we also have a demo video of WinryVirtualKeyboard in action too!

2 Likes

An Interesting Note… ROBLOX has a keyboard, but doesn’t advertise it.

So I was testing for a TextBox bug, as one does, and noticed ROBLOX has a native keyboard solution built in but…

A) It doesn’t even appear.

B) It doesn’t even work on multiple platforms from my device tests.

C) It’s not mentioned anywhere but here or the TextBox API…

D) ROBLOX doesn’t seem to use it.


This leaves me with one question…

WHY?

(Oh and WVK won’t be discontinued because of this discovery, nor the existance of Console Chat being in development, It’s still got valid use and reason to exist. ROBLOX is just not doing the best job of showing stuff like this to their developers).

2 Likes

WinryVirtualKeyboard - Update Log for Version 1.2

Developed in tandem with WinryChat 1.5 to support a feature requested by @athar_adv, WinryVirtualKeyboard 1.2 brings a few key changes. Developers now have improved feature support for creating locales as well.

The original post will be updated soon with new visuals.


Changes


  • Keyboard Suggestions via Dictionary
    As part of the update to WinryChat, WinryVirtualKeyboard 1.2 includes a complete rework with an EN-US Dictionary. The initial version of our EN-US dictionary has been a collaboration with @Ebonhelm to ensure that appropriate suggestions are given for an all-ages audience.

  • Reworked Keyboard Layout
    Describe regional layouts and modifier key behaviour with a single module script. Developers can make custom keyboards for any language and, with the addition of Keyboard Suggestions, an additional “dictionary” module can be provided to describe word suggestions.


New Settings (Attributes)


ExitKeyboardKeyCode : Enum.KeyCode
The key on a physical keyboard to close the virtual keyboard. Provided for testing in ROBLOX Studio and ROBLOX Desktop Clients. Default: Enum.KeyCode.Escape.

GamepadExitKeyboardKeyCode : Enum.KeyCode
The key on a gamepad to close the virtual keyboard. Provided for testing in ROBLOX Studio and ROBLOX Desktop Clients. Default: Enum.KeyCode.ButtonB.

Localization : string
The locale files to load from OnScreenKeyboard/VirtualKeyboardManager/Locales. The en-us files are provided as the default. You can change this to match the player’s locale by using Player.LocaleId. Default: "en-us".

MaximumSuggestionsInList: number
The maximum amount of word suggestions that the keyboard can provide to the player. This can be set to -1 for every possible suggestion found or a custom limit. Default: 12.

ShowGamepadHints : boolean
Whether to show gamepad hints by default for the keyboard. This has no effect on the second parameter of the FocusKeyboard event. Default: False.


API Changes


  • API Endpoint Added: OnSuggestMatchingWords
    partialWord - A string of a partial (or complete) word to find matches for. E.G.
    suggestPlayerNames - Whether to suggest player names instead of words from the loaded locale’s dictionary.

  • API Endpoint Added: OnSuggestedWordSelected
    word - A string value of the suggested word that was seletced.

  • API Endpoint Changed: FocusKeyboard
    locale - A string for which locale to load if a locale file can be found. You can use Player.LocaleId for this. Default: [EN-US] if no valid locale file can be found.
    displayGamepadHints - A boolean for whether to display the gamepad input hint icons. displaySuggestionsList - A boolean for whether to display keyboard suggestions.


These changes should be live now! The post will be updated to reflect the changes temporarily, and a rewrite to the original post will happen in the next 24 hours, including proper credits to all contributors and players who suggested features.

Additional Notes:

  • WinryVirtualKeyboard 1.1 has been re-added back to the list of archived verisons available in the example place. This was missing by mistake, but was able to be restored due to the archival version of WinryChat 1.4.1.

  • No alternatives exist outside of platform-provided keyboards, that I know of, as of writing. This section will still be present in the original forum post’s edit for when alternatives are found and shared.

  • WinryVirutalKeyboard will follow the exact same updated NO-ATTRIBUTION REDISTRIBUTABLE Open-Source license as WinryChat 1.5.0 and later.

1 Like

It is truly amazing what youv’ve done!!! I’m gonna use this in games tytytytytytyyy :heart:

1 Like