Quick search

Table Of Contents

Window

Core class for creating the default Kivy window. Kivy supports only one window per application: please don’t try to create more than one.

class kivy.core.window.Keyboard(**kwargs)[source]

Bases: kivy.event.EventDispatcher

Keyboard interface that is returned by WindowBase.request_keyboard(). When you request a keyboard, you’ll get an instance of this class. Whatever the keyboard input is (system or virtual keyboard), you’ll receive events through this instance.

Events :
on_key_down: keycode, text, modifiers

Fired when a new key is pressed down

on_key_up: keycode

Fired when a key is released (up)

Here is an example of how to request a Keyboard in accordance with the current configuration:

import kivy
kivy.require('1.0.8')

from kivy.core.window import Window
from kivy.uix.widget import Widget


class MyKeyboardListener(Widget):

    def __init__(self, **kwargs):
        super(MyKeyboardListener, self).__init__(**kwargs)
        self._keyboard = Window.request_keyboard(
            self._keyboard_closed, self, 'text')
        if self._keyboard.widget:
            # If it exists, this widget is a VKeyboard object which you can use
            # to change the keyboard layout.
            pass
        self._keyboard.bind(on_key_down=self._on_keyboard_down)

    def _keyboard_closed(self):
        print('My keyboard have been closed!')
        self._keyboard.unbind(on_key_down=self._on_keyboard_down)
        self._keyboard = None

    def _on_keyboard_down(self, keyboard, keycode, text, modifiers):
        print('The key', keycode, 'have been pressed')
        print(' - text is %r' % text)
        print(' - modifiers are %r' % modifiers)

        # Keycode is composed of an integer + a string
        # If we hit escape, release the keyboard
        if keycode[1] == 'escape':
            keyboard.release()

        # Return True to accept the key. Otherwise, it will be used by
        # the system.
        return True

if __name__ == '__main__':
    from kivy.base import runTouchApp
    runTouchApp(MyKeyboardListener())
callback = None

Callback that will be called when the keyboard is released

keycode_to_string(value)[source]

Convert a keycode number to a string according to the Keyboard.keycodes. If the value is not found in the keycodes, it will return ‘’.

release()[source]

Call this method to release the current keyboard. This will ensure that the keyboard is no longer attached to your callback.

string_to_keycode(value)[source]

Convert a string to a keycode number according to the Keyboard.keycodes. If the value is not found in the keycodes, it will return -1.

target = None

Target that have requested the keyboard

widget = None

VKeyboard widget, if allowed by the configuration

window = None

Window which the keyboard is attached too

class kivy.core.window.WindowBase(**kwargs)[source]

Bases: kivy.event.EventDispatcher

WindowBase is an abstract window widget for any window implementation.

Parameters :
fullscreen: str, one of (‘0’, ‘1’, ‘auto’, ‘fake’)

Make the window fullscreen. Check the config documentation for a more detailed explanation on the values.

width: int

Width of the window.

height: int

Height of the window.

Events :
on_motion: etype, motionevent

Fired when a new MotionEvent is dispatched

on_touch_down:

Fired when a new touch event is initiated.

on_touch_move:

Fired when an existing touch event changes location.

on_touch_up:

Fired when an existing touch event is terminated.

on_draw:

Fired when the Window is being drawn.

on_flip:

Fired when the Window GL surface is being flipped.

on_rotate: rotation

Fired when the Window is being rotated.

on_close:

Fired when the Window is closed.

on_keyboard: key, scancode, codepoint, modifier

Fired when the keyboard is used for input.

Changed in version 1.3.0: The unicode parameter has been deprecated in favor of codepoint, and will be removed completely in future versions.

on_key_down: key, scancode, codepoint

Fired when a key pressed.

Changed in version 1.3.0: The unicode parameter has been deprecated in favor of codepoint, and will be removed completely in future versions.

on_key_up: key, scancode, codepoint

Fired when a key is released.

Changed in version 1.3.0: The unicode parameter has be deprecated in favor of codepoint, and will be removed completely in future versions.

on_dropfile: str

Fired when a file is dropped on the application.

add_widget(widget)[source]

Add a widget to a window

center

Center of the rotated window.

center is a AliasProperty.

children

List of the children of this window.

children is a ListProperty instance and defaults to an empty list.

Use add_widget() and remove_widget() to manipulate the list of children. Don’t manipulate the list directly unless you know what you are doing.

clear()[source]

Clear the window with the background color

clearcolor

Color used to clear the window.

from kivy.core.window import Window

# red background color
Window.clearcolor = (1, 0, 0, 1)

# don't clear background at all
Window.clearcolor = None

Changed in version 1.7.2: The clearcolor default value is now: (0, 0, 0, 1).

close()[source]

Close the window

create_window(*largs)[source]

Will create the main window and configure it.

Warning

This method is called automatically at runtime. If you call it, it will recreate a RenderContext and Canvas. This means you’ll have a new graphics tree, and the old one will be unusable.

This method exist to permit the creation of a new OpenGL context AFTER closing the first one. (Like using runTouchApp() and stopTouchApp()).

This method has only been tested in a unittest environment and is not suitable for Applications.

Again, don’t use this method unless you know exactly what you are doing!

dpi()[source]

Return the DPI of the screen. If the implementation doesn’t support any DPI lookup, it will just return 96.

Warning

This value is not cross-platform. Use kivy.base.EventLoop.dpi instead.

flip()[source]

Flip between buffers

fullscreen

If True, the window will be put in fullscreen mode, “auto”. That means the screen size will not change and will use the current size to set the app fullscreen.

New in version 1.2.0.

height

Rotated window height.

height is a AliasProperty.

modifiers

List of keyboard modifiers currently active.

mouse_pos

2d position of the mouse within the window.

New in version 1.2.0.

on_close(*largs)[source]

Event called when the window is closed

on_dropfile(filename)[source]

Event called when a file is dropped on the application.

Warning

This event is currently used only on MacOSX with a patched version of pygame, but is left in place for further evolution (ios, android etc.)

New in version 1.2.0.

on_flip()[source]

Flip between buffers (event)

on_key_down(key, scancode=None, codepoint=None, modifier=None, **kwargs)[source]

Event called when a key is down (same arguments as on_keyboard)

on_key_up(key, scancode=None, codepoint=None, modifier=None, **kwargs)[source]

Event called when a key is released (same arguments as on_keyboard)

on_keyboard(key, scancode=None, codepoint=None, modifier=None, **kwargs)[source]

Event called when keyboard is used.

Warning

Some providers may omit scancode, codepoint and/or modifier!

on_motion(etype, me)[source]

Event called when a Motion Event is received.

Parameters :
etype: str

One of ‘begin’, ‘update’, ‘end’

me: MotionEvent

The Motion Event currently dispatched.

on_mouse_down(x, y, button, modifiers)[source]

Event called when the mouse is used (pressed/released)

on_mouse_move(x, y, modifiers)[source]

Event called when the mouse is moved with buttons pressed

on_mouse_up(x, y, button, modifiers)[source]

Event called when the mouse is moved with buttons pressed

on_resize(width, height)[source]

Event called when the window is resized.

on_rotate(rotation)[source]

Event called when the screen has been rotated.

on_touch_down(touch)[source]

Event called when a touch down event is initiated.

on_touch_move(touch)[source]

Event called when a touch event moves (changes location).

on_touch_up(touch)[source]

Event called when a touch event is released (terminated).

parent

Parent of this window.

parent is a ObjectProperty instance and defaults to None. When created, the parent is set to the window itself. You must take care of it if you are doing a recursive check.

release_all_keyboards()[source]

New in version 1.0.8.

This will ensure that no virtual keyboard / system keyboard is requested. All instances will be closed.

release_keyboard(target=None)[source]

New in version 1.0.4.

Internal method for the widget to release the real-keyboard. Check request_keyboard() to understand how it works.

remove_widget(widget)[source]

Remove a widget from a window

request_keyboard(callback, target, input_type='text')[source]

New in version 1.0.4.

Internal widget method to request the keyboard. This method is rarely required by the end-user as it is handled automatically by the TextInput. We expose it in case you want to handle the keyboard manually for unique input scenarios.

A widget can request the keyboard, indicating a callback to call when the keyboard is released (or taken by another widget).

Parameters :
callback: func

Callback that will be called when the keyboard is closed. This can be because somebody else requested the keyboard or the user closed it.

target: Widget

Attach the keyboard to the specified target. This should be the widget that requested the keyboard. Ensure you have a different target attached to each keyboard if you’re working in a multi user mode.

New in version 1.0.8.

input_type: string

Choose the type of soft keyboard to request. Can be one of ‘text’, ‘number’, ‘url’, ‘mail’, ‘datetime’, ‘tel’, ‘address’.

Note

input_type is currently only honored on mobile devices.

New in version 1.8.0.

Return :

An instance of Keyboard containing the callback, target, and if the configuration allows it, a VKeyboard instance attached as a .widget property.

rotation

Get/set the window content rotation. Can be one of 0, 90, 180, 270 degrees.

screenshot(name='screenshot{:04d}.png')[source]

Save the actual displayed image in a file

set_icon(filename)[source]

Set the icon of the window.

New in version 1.0.5.

set_title(title)[source]

Set the window title.

New in version 1.0.5.

set_vkeyboard_class(cls)[source]

New in version 1.0.8.

Set the VKeyboard class to use. If set to None, it will use the kivy.uix.vkeyboard.VKeyboard.

size

Get the rotated size of the window. If rotation is set, then the size will change to reflect the rotation.

system_size

Real size of the window ignoring rotation.

toggle_fullscreen()[source]

Toggle fullscreen on window

width

Rotated window width.

width is a AliasProperty.

kivy.core.window.Window = None

Instance of a WindowBase implementation