Version

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)

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())
keycode_to_string(value)

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()

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)

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.

class kivy.core.window.WindowBase(**kwargs)

Bases: kivy.event.EventDispatcher

WindowBase is an abstract window widget for any window implementation.

Parameters:
borderless: str, one of (‘0’, ‘1’)

Set the window border state. Check the config documentation for a more detailed explanation on the values.

custom_titlebar: str, one of (‘0’, ‘1’)

Set to ‘1’ to uses a custom titlebar

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.

minimum_width: int

Minimum width of the window (only works for sdl3 window provider).

minimum_height: int

Minimum height of the window (only works for sdl3 window provider).

always_on_top: bool

When enabled, the window will be brought to the front and will keep the window above the rest. If disabled, it will restore the default behavior. Only works for the sdl3 window provider.

allow_screensaver: bool

Allow the device to show a screen saver, or to go to sleep on mobile devices. Defaults to True. Only works for sdl3 window provider.

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 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.

New in version 1.9.0.

on_cursor_enter:

Fired when the cursor enters the window.

New in version 1.9.1.

on_cursor_leave:

Fired when the cursor leaves the window.

New in version 1.9.1.

on_minimize:

Fired when the window is minimized.

New in version 1.10.0.

on_maximize:

Fired when the window is maximized.

New in version 1.10.0.

on_restore:

Fired when the window is restored.

New in version 1.10.0.

on_hide:

Fired when the window is hidden.

New in version 1.10.0.

on_show:

Fired when the window is shown.

New in version 1.10.0.

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, modifier

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_drop_begin: x, y, *args

Fired when text(s) or file(s) drop on the application is about to begin.

New in version 2.1.0.

on_drop_file: filename (bytes), x, y, *args

Fired when a file is dropped on the application.

New in version 1.2.0.

Changed in version 2.1.0: Renamed from on_dropfile to on_drop_file.

on_drop_text: text (bytes), x, y, *args

Fired when a text is dropped on the application.

New in version 2.1.0.

on_drop_end: x, y, *args

Fired when text(s) or file(s) drop on the application has ended.

New in version 2.1.0.

on_memorywarning:

Fired when the platform have memory issue (iOS / Android mostly) You can listen to this one, and clean whatever you can.

New in version 1.9.0.

on_textedit(self, text):

Fired when inputting with IME. The string inputting with IME is set as the parameter of this event.

New in version 1.10.1.

add_widget(widget, canvas=None)

Add a widget to a window

clear()

Clear the window with the background color

close()

Close the window

create_window(*largs)

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!

flip()

Flip between buffers

get_gl_backend_name()

Returns the gl backend that will or is used with this window.

get_system_theme()

Returns the current system theme as a string.

Returns:

str: The current system theme, which can be "light", "dark" or "unknown".

The example below demonstrates how to create a Python thread-based theme monitor that detects system theme changes and updates the interface in a thread-safe manner. It uses Clock.schedule_once to ensure that UI updates occur on the main application thread:

Note

This feature requires the SDL3 window provider.

New in version 3.0.0.

grab_mouse()

Grab mouse - so won’t leave window

New in version 1.10.0.

Note

This feature requires the SDL3 window provider.

hide()

Hides the window. This method should be used on desktop platforms only.

New in version 1.9.0.

Note

This feature requires the SDL3 window provider and is currently only supported on desktop platforms.

mainloop()

Called by the EventLoop every frame after it idles.

maximize()

Maximizes the window. This method should be used on desktop platforms only.

New in version 1.9.0.

Note

This feature requires the SDL3 window provider and is currently only supported on desktop platforms.

minimize()

Minimizes the window. This method should be used on desktop platforms only.

New in version 1.9.0.

Note

This feature requires the SDL3 window provider and is currently only supported on desktop platforms.

on_close(*largs)

Event called when the window is closed.

on_cursor_enter(*largs)

Event called when the cursor enters the window.

New in version 1.9.1.

Note

This feature requires the SDL3 window provider.

on_cursor_leave(*largs)

Event called when the cursor leaves the window.

New in version 1.9.1.

Note

This feature requires the SDL3 window provider.

on_drop_begin(x, y, *args)

Event called when a text or a file drop on the application is about to begin. It will be followed-up by a single or a multiple on_drop_text or on_drop_file events ending with an on_drop_end event.

Arguments x and y are the mouse cursor position at the time of the drop and you should only rely on them if the drop originated from the mouse.

Parameters:
x: int

Cursor x position, relative to the window left, at the time of the drop.

y: int

Cursor y position, relative to the window top, at the time of the drop.

*args: tuple

Additional arguments.

Note

This event works with sdl3 window provider.

New in version 2.1.0.

on_drop_end(x, y, *args)

Event called when a text or a file drop on the application has ended.

Arguments x and y are the mouse cursor position at the time of the drop and you should only rely on them if the drop originated from the mouse.

Parameters:
x: int

Cursor x position, relative to the window left, at the time of the drop.

y: int

Cursor y position, relative to the window top, at the time of the drop.

*args: tuple

Additional arguments.

Note

This event works with sdl3 window provider.

New in version 2.1.0.

on_drop_file(filename, x, y, *args)

Event called when a file is dropped on the application.

Arguments x and y are the mouse cursor position at the time of the drop and you should only rely on them if the drop originated from the mouse.

Parameters:
filename: bytes

Absolute path to a dropped file.

x: int

Cursor x position, relative to the window left, at the time of the drop.

y: int

Cursor y position, relative to the window top, at the time of the drop.

*args: tuple

Additional arguments.

Warning

This event currently works with sdl3 window provider. This event is left in place for further evolution (ios, android etc.)

Note

On Windows it is possible to drop a file on the window title bar or on its edges and for that case mouse_pos won’t be updated as the mouse cursor is not within the window.

Note

This event doesn’t work for apps with elevated permissions, because the OS API calls are filtered. Check issue #4999 for pointers to workarounds.

New in version 1.2.0.

Changed in version 2.1.0: Renamed from on_dropfile to on_drop_file.

on_drop_text(text, x, y, *args)

Event called when a text is dropped on the application.

Arguments x and y are the mouse cursor position at the time of the drop and you should only rely on them if the drop originated from the mouse.

Parameters:
text: bytes

Text which is dropped.

x: int

Cursor x position, relative to the window left, at the time of the drop.

y: int

Cursor y position, relative to the window top, at the time of the drop.

*args: tuple

Additional arguments.

Note

This event works with sdl3 window provider on x11 window.

Note

On Windows it is possible to drop a text on the window title bar or on its edges and for that case mouse_pos won’t be updated as the mouse cursor is not within the window.

New in version 2.1.0.

on_flip()

Flip between buffers (event)

on_hide(*largs)

Event called when the window is hidden.

New in version 1.10.0.

Note

This feature requires the SDL3 window provider.

on_joy_axis(stickid, axisid, value)

Event called when a joystick has a stick or other axis moved.

New in version 1.9.0.

on_joy_ball(stickid, ballid, xvalue, yvalue)

Event called when a joystick has a ball moved.

New in version 1.9.0.

on_joy_button_down(stickid, buttonid)

Event called when a joystick has a button pressed.

New in version 1.9.0.

on_joy_button_up(stickid, buttonid)

Event called when a joystick has a button released.

New in version 1.9.0.

on_joy_hat(stickid, hatid, value)

Event called when a joystick has a hat/dpad moved.

New in version 1.9.0.

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

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

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

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

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

Event called when keyboard is used.

Warning

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

on_maximize(*largs)

Event called when the window is maximized.

New in version 1.10.0.

Note

This feature requires the SDL3 window provider.

on_memorywarning()

Event called when the platform have memory issue. Your goal is to clear the cache in your app as much as you can, release unused widgets, do garbage collection etc.

Currently, this event is fired only from the SDL3 provider, for iOS and Android.

New in version 1.9.0.

on_minimize(*largs)

Event called when the window is minimized.

New in version 1.10.0.

Note

This feature requires the SDL3 window provider.

on_motion(etype, me)

Event called when a motion event is received.

Parameters:
etype: str

One of “begin”, “update” or “end”.

me: MotionEvent

The motion event currently dispatched.

Changed in version 2.1.0: Event managers get to handle the touch event first and if none of them accepts the event (by returning True) then window will dispatch me through “on_touch_down”, “on_touch_move”, “on_touch_up” events depending on the etype. All non-touch events will go only through managers.

on_mouse_down(x, y, button, modifiers)

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

on_mouse_move(x, y, modifiers)

Event called when the mouse is moved with buttons pressed.

on_mouse_up(x, y, button, modifiers)

Event called when the mouse is moved with buttons pressed.

on_request_close(*largs, **kwargs)

Event called before we close the window. If a bound function returns True, the window will not be closed. If 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)

Event called when the window is resized.

on_restore(*largs)

Event called when the window is restored.

New in version 1.10.0.

Note

This feature requires the SDL3 window provider.

on_rotate(rotation)

Event called when the screen has been rotated.

on_show(*largs)

Event called when the window is shown.

New in version 1.10.0.

Note

This feature requires the SDL3 window provider.

on_textedit(text)

Event called when inputting with IME. The string inputting with IME is set as the parameter of this event.

New in version 1.10.1.

on_textinput(text)

Event called when text: i.e. alpha numeric non control keys or set of keys is entered. As it is not guaranteed whether we get one character or multiple ones, this event supports handling multiple characters.

New in version 1.9.0.

on_touch_down(touch)

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)

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)

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.

raise_window()

Raise the window. This method should be used on desktop platforms only.

New in version 1.9.1.

Note

This feature requires the SDL3 window provider and is currently only supported on desktop platforms.

register_event_manager(manager)

Register and start an event manager to handle events declared in type_ids attribute.

New in version 2.1.0.

Warning

This is an experimental method and it remains so until this warning is present as it can be changed or removed in the next versions of Kivy.

release_all_keyboards()

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)

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)

Remove a widget from a window

request_keyboard(callback, target, input_type='text', keyboard_suggestions=True)

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 ‘null’, ‘text’, ‘number’, ‘url’, ‘mail’, ‘datetime’, ‘tel’, ‘address’.

Note

input_type is currently only honored on Android.

New in version 1.8.0.

Changed in version 2.1.0: Added null to soft keyboard types.

keyboard_suggestions: bool

If True provides auto suggestions on top of keyboard. This will only work if input_type is set to text, url, mail or address.

New in version 2.1.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.

restore()

Restores the size and position of a maximized or minimized window. This method should be used on desktop platforms only.

New in version 1.9.0.

Note

This feature requires the SDL3 window provider and is currently only supported on desktop platforms.

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

Save the actual displayed image to a file.

set_custom_titlebar(widget)

Sets a Widget as a titlebar

widget:

The widget you want to set as the titlebar

New in version 2.1.0.

This function returns True on successfully setting the custom titlebar, else false

How to use this feature

1. first set Window.custom_titlebar to True
2. then call Window.set_custom_titlebar with the widget/layout you want to set as titlebar as the argument

If you want a child of the widget to receive touch events, in that child define a property draggable and set it to False

If you set the property draggable on a layout, all the child in the layout will receive touch events

If you want to override default behavior, add function in_drag_area(x,y) to the widget

The function is call with two args x,y which are mouse.x, and mouse.y the function should return

True if that point should be used to drag the window
False if you want to receive the touch event at the point

Note

If you use in_drag_area() property draggable will not be checked

Note

This feature requires the SDL3 window provider and is currently only supported on desktop platforms.

Warning

custom_titlebar must be set to True for the widget to be successfully set as a titlebar

set_icon(filename)

Set the icon of the window.

New in version 1.0.5.

set_system_cursor(cursor_name)

Set type of a mouse cursor in the Window.

It can be one of ‘arrow’, ‘ibeam’, ‘wait’, ‘crosshair’, ‘wait_arrow’, ‘size_nwse’, ‘size_nesw’, ‘size_we’, ‘size_ns’, ‘size_all’, ‘no’, or ‘hand’.

On some platforms there might not be a specific cursor supported and such an option falls back to one of the substitutable alternatives:

Windows

MacOS

Linux X11

Linux Wayland

arrow

arrow

arrow

arrow

arrow

ibeam

ibeam

ibeam

ibeam

ibeam

wait

wait

arrow

wait

wait

crosshair

crosshair

crosshair

crosshair

hand

wait_arrow

arrow

arrow

wait

wait

size_nwse

size_nwse

size_all

size_all

hand

size_nesw

size_nesw

size_all

size_all

hand

size_we

size_we

size_we

size_we

hand

size_ns

size_ns

size_ns

size_ns

hand

size_all

size_all

size_all

size_all

hand

no

no

no

no

ibeam

hand

hand

hand

hand

hand

New in version 1.10.1.

Note

This feature requires the SDL3 window provider and is currently only supported on desktop platforms.

set_title(title)

Set the window title.

New in version 1.0.5.

set_vkeyboard_class(cls)

New in version 1.0.8.

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

show()

Shows the window. This method should be used on desktop platforms only.

New in version 1.9.0.

Note

This feature requires the SDL3 window provider and is currently only supported on desktop platforms.

to_normalized_pos(x, y)

Transforms absolute coordinates to normalized (0-1) coordinates using system_size.

New in version 2.1.0.

transform_motion_event_2d(me, widget=None)

Transforms the motion event me to this window size and then if widget is passed transforms me to widget’s local coordinates.

Raises:

AttributeError: If widget’s ancestor is None.

Note

Unless it’s a specific case, call push() before and pop() after this method’s call to preserve previous values of me’s attributes.

New in version 2.1.0.

ungrab_mouse()

Ungrab mouse

New in version 1.10.0.

Note

This feature requires the SDL3 window provider.

unregister_event_manager(manager)

Unregister and stop an event manager previously registered with register_event_manager().

New in version 2.1.0.

Warning

This is an experimental method and it remains so until this warning is present as it can be changed or removed in the next versions of Kivy.

« Video Kivy module for binary dependencies. »