Table Of Contents

• Window

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

callback = None

Callback that will be called when the keyboard is released

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.

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)

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.

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 sdl2 window provider).

minimum_height: int

Minimum height of the window (only works for sdl2 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 sdl2 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 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 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_dropfile: str

Fired when a file is dropped on the application.

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.

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

allow_screensaver

Whether the screen saver is enabled, or on mobile devices whether the device is allowed to go to sleep while the app is open.

New in version 1.10.0.

allow_screensaver is a BooleanProperty and defaults to True.

borderless

When set to True, this property removes the window border/decoration. Check the config documentation for a more detailed explanation on the values.

New in version 1.9.0.

borderless is a BooleanProperty and defaults to False.

center

Center of the rotated window.

New in version 1.0.9.

center is an 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()

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

New in version 1.0.9.

clearcolor is an AliasProperty and defaults to (0, 0, 0, 1).

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!

dpi()

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

Flip between buffers

focus

Check whether or not the window currently has focus.

New in version 1.9.1.

focus is a read-only AliasProperty and defaults to True.

fullscreen

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

fullscreen is an OptionProperty and defaults to False.

New in version 1.2.0.

Note

The ‘fake’ option has been deprecated, use the borderless property instead.

grab_mouse()

Grab mouse - so won’t leave window

New in version 1.10.0.

Note

This feature requires the SDL2 window provider.

height

Rotated window height.

height is a read-only AliasProperty.

hide()

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

New in version 1.9.0.

Note

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

icon

A path to the window icon.

New in version 1.1.2.

icon is a StringProperty.

keyboard_anim_args = {'d': 0.5, 't': 'in_out_quart'}

The attributes for animating softkeyboard/IME. t = transition, d = duration. This value will have no effect on desktops.

New in version 1.10.0.

keyboard_anim_args is a dict and defaults to {‘t’: ‘in_out_quart’, ‘d’: .5}.

keyboard_height

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

Note

This property returns 0 with SDL2 on Android, but setting Window.softinput_mode does work.

New in version 1.9.0.

keyboard_height is a read-only AliasProperty and defaults to 0.

keyboard_padding

The padding to have between the softkeyboard/IME & target or bottom of window. Will have no effect on desktops.

New in version 1.10.0.

keyboard_padding is a NumericProperty and defaults to 0.

left

Left position of the window.

Note

It’s an SDL2 property with [0, 0] in the top-left corner.

Changed in version 1.10.0: left is now an AliasProperty

New in version 1.9.1.

left is an AliasProperty and defaults to the position set in Config.

maximize()

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

New in version 1.9.0.

Note

This feature requires the SDL2 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 SDL2 window provider and is currently only supported on desktop platforms.

minimum_height

The minimum height to restrict the window to.

New in version 1.9.1.

minimum_height is a NumericProperty and defaults to 0.

minimum_width

The minimum width to restrict the window to.

New in version 1.9.1.

minimum_width is a NumericProperty and defaults to 0.

modifiers

List of keyboard modifiers currently active.

New in version 1.0.9.

modifiers is an AliasProperty.

mouse_pos

2d position of the mouse within the window.

New in version 1.2.0.

mouse_pos is an ObjectProperty and defaults to [0, 0].

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 SDL2 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 SDL2 window provider.

on_dropfile(filename)

Event called when a file is dropped on the application.

Warning

This event currently works with sdl2 window provider, on pygame window provider and OS X with a patched version of pygame. This event is left in place for further evolution (ios, android etc.)

New in version 1.2.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 SDL2 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 SDL2 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 SDL2 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 SDL2 window provider.

on_motion(etype, me)

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)

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

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.

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 SDL2 window provider and is currently only supported on desktop platforms.

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

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.

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 SDL2 window provider and is currently only supported on desktop platforms.

rotation

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

New in version 1.0.9.

rotation is an AliasProperty.

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

Save the actual displayed image to a file.

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

shape_color_key

Color key of the shaped window - sets which color will be hidden from the window shape_image (only works for sdl2 window provider).

New in version 1.10.1.

shape_color_key is a ListProperty instance and defaults to [1, 1, 1, 1].

shape_cutoff

The window shape_image cutoff property (only works for sdl2 window provider).

New in version 1.10.1.

shape_cutoff is a BooleanProperty and defaults to True.

shape_image

An image for the window shape (only works for sdl2 window provider).

Warning

The image size has to be the same like the window’s size!

New in version 1.10.1.

shape_image is a StringProperty and defaults to ‘data/images/defaultshape.png’. This value is taken from Config.

shape_mode

Window mode for shaping (only works for sdl2 window provider).

• can be RGB only

  • default - does nothing special

  • colorkey - hides a color of the shape_color_key

• has to contain alpha channel

  • binalpha - hides an alpha channel of the shape_image

  • reversebinalpha - shows only the alpha of the shape_image

Note

Before actually setting the mode make sure the Window has the same size like the shape_image, preferably via Config before the Window is actually created.

If the shape_image isn’t set, the default one will be used and the mode might not take the desired visual effect.

New in version 1.10.1.

shape_mode is an AliasProperty.

shaped

Read only property to check if the window is shapable or not (only works for sdl2 window provider).

New in version 1.10.1.

shaped is an AliasProperty.

show()

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

New in version 1.9.0.

Note

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

show_cursor

Set whether or not the cursor is shown on the window.

New in version 1.9.1.

show_cursor is a BooleanProperty and defaults to True.

size

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

New in version 1.0.9.

size is an AliasProperty.

softinput_mode

This specifies the behavior of window contents on display of the soft keyboard on mobile platforms. It can be one of ‘’, ‘pan’, ‘scale’, ‘resize’ or ‘below_target’. Their effects are listed below.

Value	Effect
‘’	The main window is left as is, allowing you to use the keyboard_height to manage the window contents manually.
‘pan’	The main window pans, moving the bottom part of the window to be always on top of the keyboard.
‘resize’	The window is resized and the contents scaled to fit the remaining space.
‘below_target’	The window pans so that the current target TextInput widget requesting the keyboard is presented just above the soft keyboard.

softinput_mode is an OptionProperty and defaults to ‘’.

Note

The resize option does not currently work with SDL2 on Android.

New in version 1.9.0.

Changed in version 1.9.1: The ‘below_target’ option was added.

system_size

Real size of the window ignoring rotation.

New in version 1.0.9.

system_size is an AliasProperty.

toggle_fullscreen()

Toggle between fullscreen and windowed mode.

Deprecated since version 1.9.0: Use fullscreen instead.

top

Top position of the window.

Note

It’s an SDL2 property with [0, 0] in the top-left corner.

Changed in version 1.10.0: top is now an AliasProperty

New in version 1.9.1.

top is an AliasProperty and defaults to the position set in Config.

ungrab_mouse()

Ungrab mouse

New in version 1.10.0.

Note

This feature requires the SDL2 window provider.

width

Rotated window width.

width is a read-only AliasProperty.

« Video

Kivy module for binary dependencies. »