Metadata-Version: 2.1
Name: pygame-vkeyboard
Version: 2.0.4
Summary: Visual
Home-page: https://github.com/Faylixe/pygame-vkeyboard
Author: Felix Voituret, Antoine Rousseaux
Author-email: felix@voituret.fr, anxuae-prog@yahoo.fr
License: Apache License 2.0
Download-URL: https://pypi.org/project/pygame-vkeyboard/#files
Keywords: pygame,keyboard
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: pygame
Requires-Python: >=2.7
Description-Content-Type: text/markdown
Requires-Dist: pygame

# pygame-vkeyboard

[![Python package](https://github.com/Faylixe/pygame_vkeyboard/workflows/Python%20package/badge.svg?branch=master)](https://github.com/Faylixe/pygame_vkeyboard/actions) [![PyPI version](https://badge.fury.io/py/pygame-vkeyboard.svg)](https://badge.fury.io/py/pygame-vkeyboard) [![PyPI downloads](https://img.shields.io/pypi/dm/pygame-vkeyboard?color=purple)](https://pypi.org/project/pibooth)

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

<div align="center">
    <table>
    <tr>
        <td><img src="https://raw.githubusercontent.com/Faylixe/pygame_vkeyboard/master/screenshot/vkeyboard_azerty.png">
        </td>
        <td><img src="https://github.com/Faylixe/pygame-vkeyboard/blob/master/screenshot/vkeyboard_numeric.gif?raw=true">
        </td>
        <td><img src="https://github.com/Faylixe/pygame-vkeyboard/blob/master/screenshot/vkeyboard_textinput.gif?raw=true">
        </td>
    </tr>
    </table>
</div>

## Install

```bash
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 :

```python
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)
keyboard.enable()
```

The keyboard has the following optional parameters:

- **show_text**: display a text bar with the current text
- **renderer** : define a custom renderer (see chapter below)
- **special_char_layout**: define a custom layout for special characters
- **joystick_navigation**: enable navigation using a joystick

## Event management

A ``VKeyboard`` object handles the following pygame event :

- **MOUSEBUTTONDOWN**
- **MOUSEBUTTONUP**
- **KEYDOWN**
- **KEYUP**

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

```python
while True:

    events = pygame.event.get()

    # Update internal variables
    keyboard.update(events)

    # Draw the keyboard
    rects = keyboard.draw(surface)

    #
    # Perform other tasks here
    #

    # Update the display
    pygame.display.update(rects) # Update only required dirty parts
```

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

**Note:** the ``surface`` parameter of the ``draw()`` method is optional, it is used to clear/hide the keyboard when it is necessary and may be mandatory if the surface has changed.

## 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 :

```python
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 :

```python
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 ``VKeyboard``construction.

```python
keyboard = VKeyboard(surface, consumer, layout, renderer=VKeyboardRenderer.DARK)
```

Here is the list of default renderers provided with ``pygame-vkeyboard``:

- VKeyboardRenderer.DEFAULT
- VKeyboardRenderer.DARK

A custom ``VKeyboardRenderer`` can be built using following constructor :

```python
renderer = VKeyboardRenderer(
    # Key font name/path.
    'arial',
    # Text color for key and text box (one per state: released, pressed).
    ((0, 0, 0), (255, 255, 255)),
    # Text box cursor color.
    (0, 0, 0),
    # Color to highlight the selected key.
    (20, 200, 98),
    # Keyboard background color.
    (50, 50, 50),
    # Key background color (one per state, as for the text color).
    ((255, 255, 255), (0, 0, 0)),
    # Text input background color.
    (220, 220, 220),
    # Optional special key text color (one per state, as for the text color).
    ((0, 250, 0), (255, 255, 255)),
    # Optional special key background color (one per state, as for the text 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 ``VKeyboardRenderer``class and override any of the following methods :

- **draw_background(surface)**: Draws the background of the keyboard.
- **draw_text(surface, text)**: Draws the text of the text input box.
- **draw_cursor(surface, cursor)**: Draws the cursor of the text input box.
- **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.


## Getting/Setting data

Several information can be retrieved from the keyboard:

```python
keyboard = VKeyboard(...)

# Get a pygame.Rect object in which the keyboard is included.
keyboard.get_rect()

# Get the current text.
keyboard.get_text()

# Set the current text (clear the existing one).
keyboard.set_text("Hello world!")

# Return True if the keyboard is enabled (thus displayed at screen).
keyboard.is_enabled()

# Disable and hide the keyboard (keyboard.update() and keyboard.draw() have no effect).
keyboard.disable()
```

## Run examples

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

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

## Contributing

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.


