Skip to main content


Project description


Python package PyPI version

Visual keyboard for Pygame engine. Aims to be easy to use as highly customizable as well.

Vitual keyboard with AZERTY layout


pip install pygame-vkeyboard

Basic usage

VKeyboard only require a pygame surface to be displayed on and a text consumer function, as in the following example :

from pygame_vkeyboard import *

# Initializes your window object or surface your want
# vkeyboard to be displayed on top of.
surface = ...

def consumer(text):
    print('Current text : %s' % text)

# Initializes and activates vkeyboard
layout = VKeyboardLayout(VKeyboardLayout.AZERTY)
keyboard = VKeyboard(surface, consumer, layout)

Event managment

A VKeyboard object handles the following pygame event :


In order to process those events, keyboard instance event handling method should be called like in the following example:

for event in pygame.event.get():
   # Perform your other event handling here.

It will update key state accordingly as the keyboard buffer as well. Buffer modification will be notified through the keyboard text consumer function.

Customize layout

The keyboard layout is the model that indicates keys are displayed and how they are dispatched across the keyboard space. It consists in a VKeyboardLayout object which is built using list of string, each string corresponding to a keyboard key row. VkeyboardLayout constructor signature is defined as following :

def __init__(self, model, key_size=None, padding=5, allow_uppercase=True, allow_special_chars=True, allow_space=True)

If the key_size parameter is not provided, it will be computed dynamically regarding of the target surface the keyboard will be rendered into.

In order to only display a numerical Vkeyboard for example, you can use a custom layout like this :

model = ['123', '456', '789', '0']
layout = VKeyboardLayout(model)

Custom rendering using VKeyboardRenderer

If you want to customize keyboard rendering you could provide a VKeyboardRenderer instance at VKeyboardconstruction. A VKeyboardRenderer can be built using following constructor :

renderer = VKeyboardRenderer(
    # Key font.
    pygame.font.SysFont('arial', 20),
    # Keyboard background color.
    (50, 50, 50),
    # Key background color (one per state, 0 for released, 1 for pressed).
    ((255, 255, 255), (0, 0, 0)),
    # Text color for key (one per state as for the key background).
    ((0, 0, 0), (255, 255, 255)),
    # (Optional) special key background color.
    ((255, 255, 255), (0, 0, 0)),

Please note that the default renderer implementation require a unicode font.

You can also create your own renderer. Just override VKeyboardRendererclass and override any of the following methods :

  • draw_background(surface): Draws the background of the keyboard.
  • draw_character_key(surface, key, special=False): Draws a key based on character value.
  • draw_space_key(surface, key): Draws space bar.
  • draw_back_key(surface, key): Draws back key.
  • draw_uppercase_key(surface, key): Draw uppercase switch key.
  • draw_special_char_key(surface, key): Draw special character switch key.

Run examples

Several examples are provided with the pygame_vkeyboard library. To run the examples, simply execute these commands in a terminal:

python -m pygame_vkeyboard.examples.azerty
python -m pygame_vkeyboard.examples.numeric
python -m pygame_vkeyboard.examples.textinput


If you develop you own renderer please share it ! I will keep a collection of rendering class in this repository. Don't hesitate to report bug, feedback, suggestion into the repository issues section.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pygame-vkeyboard, version 2.0.3
Filename, size File type Python version Upload date Hashes
Filename, size pygame_vkeyboard-2.0.3-py2.py3-none-any.whl (384.6 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size pygame-vkeyboard-2.0.3.tar.gz (17.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page