Version: 1.2.0
Latest Patch Notes
Special Thanks to:
@Ebonhelm - EN-US Dictionary Proofreading & Assistance
-
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.
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.
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.
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.
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.
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. TheKeyAspectRatioproperty will determine how big the space is. This will not usedisplayStringorModifierHeldKeyValue. -
Enum.KeyCode.LeftSuperandEnum.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.
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.
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!
