VKeyboard

_images/vkeyboard.jpg

New in version 1.0.8.

Warning

This is experimental and subject to change as long as this warning notice is present.

VKeyboard is a onscreen keyboard for Kivy. It’s made to be transparent to the user. Using that widget directly is highly not recommanded. Read the section Request keyboard first.

Modes

This virtual keyboard have a dock and free mode:

  • dock 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 allow to have more than one virtual keyboard on the screen.

If you change the docked mode, 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 dock mode is set.)

Layouts

Virtual keyboard are able to load custom layouts. If you create a new layout, put the json in <kivy_data_dir>/keyboards/<layoutid>.json. Then you can 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 rows, for a “normal” mode, and “shift” mode. The keys 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 represent the keycode>, <size of cols> ]

Here is some example of keys:

# f key
["f", "f", "f", 1]
# capslock
["\u21B9", "        ", "tab", 1.5]

At the end, you can 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 instanciation 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 require a keyboard, don’t use directly the virtual keyboard, but prefer to use the best method available on the user platform. Check 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.

available_layouts

Dictionnary of all available layouts. Keys is 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. It’s used for controling 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 multiply 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 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 call manually setup_mode(). Otherwise, it will have no impact. If the VKeyboard is created by the Window, the dock 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 multiply 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 one touch is on it.

key_background_down a StringProperty, default to atlas://data/images/defaulttheme/vkeyboard_key_down.

key_background_normal

Filename of the key background image when no touch are on it.

key_background_normal a StringProperty, default to atlas://data/images/defaulttheme/vkeyboard_key_normal.

key_border

Key image border. It’s used for controling 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 4 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 to read layouts from.

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 4 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 whole widgets and graphics according to the selected layout.

setup_mode(*largs)

Call this method when you want to reajust the keyboard according to his options: docked or not, with attached target or not:

Fell free to overload theses methods in order to create a new positioning behavior.

setup_mode_dock(*largs)

Setup the keyboard in dock 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 multi users environment, but you might found others 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 keys events, and if the VKeyboard mode is “free”, it will be also used to set the initial position.

target is a ObjectProperty instance, default to None.