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

Fired when the event loop wants to close the window, or if the escape key is pressed and exit_on_escape is True. If a function bound to this event returns True, the window will not be closed. If the the event is triggered because of the keyboard escape key, the keyword argument source is dispatched along with a value of keyboard to the bound functions.

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.

Changed in version 1.9.0: on_request_close has been added.

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

This property sets the fullscreen mode of the window. Available options are: True, False, ‘auto’, ‘fake’. Check the config documentation for a more detailed explanation on the values.

New in version 1.2.0.

height

Rotated window height.

height is a read-only AliasProperty.

keyboard_height

Rerturns the height of the softkeyboard/IME on mobile platforms. Will return 0 if not on mobile platform or if IME is not active.

..versionadded:: 1.9.0

keyboard_height is a read-only AliasProperty defaults to 0.

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_request_close(*largs, **kwargs)[source]

Event called before we close the window. If a bound function returns True, the window will not be closed. If the the event is triggered because of the keyboard escape key, the keyword argument source is dispatched along with a value of keyboard to the bound functions.

Warning

When the bound function returns True the window will not be closed, so use with care because the user would not be able to close the program, even if the red X is clicked.

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.

Changed in version 1.9.0: The touch pos is now transformed to window coordinates before this method is called. Before, the touch pos coordinate would be (0, 0) when this method was called.

on_touch_move(touch)[source]

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

Changed in version 1.9.0: The touch pos is now transformed to window coordinates before this method is called. Before, the touch pos coordinate would be (0, 0) when this method was called.

on_touch_up(touch)[source]

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

Changed in version 1.9.0: The touch pos is now transformed to window coordinates before this method is called. Before, the touch pos coordinate would be (0, 0) when this method was called.

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.

Note

The behavior of this function is heavily influenced by the current keyboard_mode. Please see the Config’s configuration tokens section for more information.

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.

softinput_mode

This specifies the behavior of window contents on display of soft keyboard on mobile platform. Can be one of ‘’, ‘pan’, ‘scale’, ‘resize’.

When ‘’ The main window is left as it is allowing the user to use keyboard_height to manage the window contents the way they want.

when ‘pan’ The main window pans moving the bottom part of the window to be always on top of the keyboard.

when ‘resize’ The window is resized and the contents scaled to fit the remaining space.

..versionadded::1.9.0

softinput_mode is a OptionProperty defaults to None.

system_size

Real size of the window ignoring rotation.

toggle_fullscreen()[source]

Toggle fullscreen on window

width

Rotated window width.

width is a read-only AliasProperty.

kivy.core.window.Window = None

Instance of a WindowBase implementation