VKeyboard¶

New in version 1.0.8.
Warning
This is experimental and subject to change as long as this warning notice is present.
VKeyboard is an onscreen keyboard for Kivy. Its operation is intended to be transparent to the user. Using the widget directly is NOT recommended. Read the section Request keyboard first.
Modes¶
This virtual keyboard has a docked and free mode:
- docked mode (VKeyboard.docked = True) Generally used when only one person is using the computer, like tablet, personal computer etc.
- free mode: (VKeyboard.docked = False) Mostly for multitouch table. This mode allows more than one virtual keyboard on the screen.
If the docked mode changes, you need to manually call VKeyboard.setup_mode(). Otherwise the change will have no impact. During that call, the VKeyboard, implemented in top of scatter, will change the behavior of the scatter, and position the keyboard near the target (if target and docked mode is set).
Layouts¶
The virtual keyboard is able to load a custom layout. If you create a new layout, put the JSON in <kivy_data_dir>/keyboards/<layoutid>.json. Load it by setting VKeyboard.layout to your layoutid.
The JSON must be structured like this:
{
"title": "Title of your layout",
"description": "Description of your layout",
"cols": 15,
"rows": 5,
...
}
Then, you need to describe keys in each row, for either a “normal” mode or a “shift” mode. Keys for this row data must be named normal_<row> and shift_<row>. Replace row with the row number. Inside each row, you will describe the key. A key is a 4 element list in the format:
[ <text displayed on the keyboard>, <text to put when the key is pressed>,
<text that represents the keycode>, <size of cols> ]
Here are example keys:
# f key
["f", "f", "f", 1]
# capslock
["\u21B9", " ", "tab", 1.5]
Finally, complete the JSON:
{
...
"normal_1": [
["`", "`", "`", 1], ["1", "1", "1", 1], ["2", "2", "2", 1],
["3", "3", "3", 1], ["4", "4", "4", 1], ["5", "5", "5", 1],
["6", "6", "6", 1], ["7", "7", "7", 1], ["8", "8", "8", 1],
["9", "9", "9", 1], ["0", "0", "0", 1], ["+", "+", "+", 1],
["=", "=", "=", 1], ["\u232b", null, "backspace", 2]
],
"shift_1": [ ... ],
"normal_2": [ ... ],
...
}
Request Keyboard¶
The instantiation of the virtual keyboard is controlled by the configuration. Check keyboard_mode and keyboard_layout in the Configuration object.
If you intend to create a widget that requires a keyboard, do not use the virtual keyboard directly, but prefer to use the best method available on the platform. Check the request_keyboard() method in the Window.
- class kivy.uix.vkeyboard.VKeyboard(**kwargs)¶
Bases: kivy.uix.scatter.Scatter
VKeyboard is an onscreen keyboard with multitouch support. Its layout is entirely customizable and you can switch between available layouts using a button in the bottom right of the widget.
Events : - on_key_down: keycode, internal, modifiers
Fired when the keyboard received a key down event (key press).
- on_key_up: keycode, internal, modifiers
Fired when the keyboard received a key up event (key release).
- available_layouts¶
Dictionary of all available layouts. Keys are the layout ID, and the value is the JSON (translated in Python object).
available_layouts is a DictProperty, default to {}
- background¶
Filename of the background image.
background a StringProperty, default to atlas://data/images/defaulttheme/vkeyboard_background.
- background_border¶
Background image border. Used for controlling the border property of the background.
background_border is a ListProperty, default to [16, 16, 16, 16]
- background_color¶
Background color, in the format (r, g, b, a). If a background is set, the color will be combined with the background texture.
background_color is a ListProperty, default to [1, 1, 1, 1].
- callback¶
Callback can be set to a function that will be called if the VKeyboard is closed by the user.
target is a ObjectProperty instance, default to None.
- collide_margin(x, y)¶
Do a collision test, and return True if the (x, y) is inside the vkeyboard margin.
- docked¶
Indicate if the VKeyboard is docked on the screen or not. If you change it, you must manually call setup_mode(). Otherwise, it will have no impact. If the VKeyboard is created by the Window, the docked mode will be automatically set by the configuration, with keyboard_mode token in [kivy] section.
docked is a BooleanProperty, default to False.
- key_background_color¶
Key background color, in the format (r, g, b, a). If a key background is set, the color will be combined with the key background texture.
key_background_color is a ListProperty, default to [1, 1, 1, 1].
- key_background_down¶
Filename of the key background image for use when a touch is active on the widget.
key_background_down a StringProperty, default to atlas://data/images/defaulttheme/vkeyboard_key_down.
- key_background_normal¶
Filename of the key background image for use when no touches are active on the widget.
key_background_normal a StringProperty, default to atlas://data/images/defaulttheme/vkeyboard_key_normal.
- key_border¶
Key image border. Used for controlling the border property of the key.
key_border is a ListProperty, default to [16, 16, 16, 16]
- key_margin¶
Key margin, used to create space between keys. The margin is composed of four values, in pixels:
key_margin = [top, right, bottom, left]
key_margin is a ListProperty, default to [2, 2, 2, 2]
- layout¶
Layout to use for the VKeyboard. By default, it will be the layout set in the configuration, according to the keyboard_layout in [kivy] section.
layout is a StringProperty, default to None.
- layout_path¶
Path from which layouts are read.
layout is a StringProperty, default to <kivy_data_dir>/keyboards/
- margin_hint¶
Margin hint, used as spacing between keyboard background and keys content. The margin is composed of four values, between 0 and 1:
margin_hint = [top, right, bottom, left]
The margin hints will be multiplied by width and height, according to their position.
margin_hint is a ListProperty, default to [.05, .06, .05, .06]
- refresh(force=False)¶
(internal) Recreate the entire widget and graphics according to the selected layout.
- setup_mode(*largs)¶
Call this method when you want to readjust the keyboard according to options: docked or not, with attached target or not:
- If docked is True, it will call setup_mode_dock()
- If docked is False, it will call setup_mode_free()
Feel free to overload theses methods to create a new positioning behavior.
- setup_mode_dock(*largs)¶
Setup the keyboard in docked mode.
Dock mode will reset the rotation, disable translation, rotation and scale. Scale and position will be automatically adjusted to attach the keyboard in the bottom of the screen.
Note
Don’t call this method directly, use setup_mode() instead.
- setup_mode_free()¶
Setup the keyboard in free mode.
Free mode is designed to let the user control the position and orientation of the keyboard. The only real usage is for a multiuser environment, but you might found other ways to use it. If a target is set, it will place the vkeyboard under the target.
Note
Don’t call this method directly, use setup_mode() instead.
- target¶
Target widget associated to VKeyboard. If set, it will be used to send keyboard events, and if the VKeyboard mode is “free”, it will also be used to set the initial position.
target is a ObjectProperty instance, default to None.