WinryVirtualKeyboard - Open Source (No License) 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 which keys are accessible to users.
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.
- ANSI-Style Default Layout
- No License Required
- No Attribution Required
- No Forum Reply Required
- Feedback Optional (but helpful)
Version: 1.1
This is a client-side only on-screen keyboard. The server has no direct access to user inputs.
Demo Video
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.
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:
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 Support for WinryVirtualKeyboard
WinryVirtualKeyboard provides four BindableEvents within WinryVirtualKeyboard.OnScreenKeyboard, named FocusKeyboard, OnKeyDown, OnBackspacePressed and OnEnterPressed. These are the main source of communication with the on-screen keyboard and provide the following:
Events for Invoking (BindableEvent:Fire(...))
-
FocusKeyboard - Invoked by external UIs to bring the On-Screen Keyboard up, if hidden, and focus it with
GuiService.Select(...). CallFocusKeyboard.Fire()to bring this keyboard up. This also 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.
-
Events for Bindining (BindableEvent.Event)
- OnKeyDown - Fired by the On-Screen Keyboard when non-special (Escape, Enter, Backspace) and non-modifier (CapsLock, Shift) are pressed. WinryVirtualKeyboard sends the following data to listeners, so that listeners may use any and all of it as desired for gameplay:
-
-
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 alt key modifier active when this key was pressed?
-
-
-
WasCapsLockActive : boolean- Was the CapsLock key modifier active when this key was pressed?
-
-
OnBackspacePressed - Fired by the On-Screen Keyboard when the Backspace key is pressed. Useful for removing the last input character placed in a Text Box.
-
OnEnterPressed - Fired by the On-Screen Keyboard when the Enter key is pressed. Useful for disconnecting any connections to
OnKeyDownandOnBackspacePressedcreated when using the keyboard as an input device for a Text Box.
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 will not be supported due to the accessibility BindableEvents provide to a wide range of developers.
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 ModuleScript called RowMappings that allow developers to extensively modify the complete layout and structure of the Keyboard for the five-row layout.
You can find this MoudleScript here:
StarterGui.KeyboardUI.OnScreenKeyboard.VirtualKeyboardManager.RowMappings
The first 20 lines are reserved for Intellisense Types, so that developers can hover over the module in other scripts and write with relevant information while scripting. Though, from the image below, only the VirtualKey type matters for most use.
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 RowMappings module (or don’t make one), here is every default binding provided in the base configuration of WinryVirtualKeyboard.
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!
