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¶: 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¶: Target that have requested the keyboard

widget¶: VKeyboard widget, if allowed by the configuration

window¶: 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:

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 sdl2 window provider).
minimum_height: int: Minimum height of the window (only works for sdl2 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 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 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)[source]¶: 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.

always_on_top¶

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.

This option can be toggled freely during the window’s lifecycle.

Only works for the sdl2 window provider. Check the config documentation for a more detailed explanation on the values.

New in version 2.2.0.

always_on_top is a BooleanProperty and defaults to False.

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

New in version 1.0.9.

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

Changed in version 2.1.0: Changed from AliasProperty to ColorProperty.

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!

custom_titlebar¶

When set to True, allows the user to set a widget as a titlebar. Check the config documentation for a more detailed explanation on the values.

New in version 2.1.0.

see set_custom_titlebar() for detailed usage custom_titlebar is a BooleanProperty and defaults to False.

dpi¶: Return the DPI of the screen as computed by the window. If the implementation doesn’t support DPI lookup, it’s 96.

Warning

This value is not cross-platform. Use kivy.metrics.Metrics.dpi instead.

event_managers = None¶

Holds a list of registered event managers.

Don’t change the property directly but use register_event_manager() and unregister_event_manager() to register and unregister an event manager.

Event manager is an instance of EventManagerBase.

New in version 2.1.0.

Warning

This is an experimental property and it remains so while this warning is present.

event_managers_dict = None¶

Holds a dict of type_id to list of event managers.

Don’t change the property directly but use register_event_manager() and unregister_event_manager() to register and unregister an event manager.

Event manager is an instance of EventManagerBase.

New in version 2.1.0.

Warning

This is an experimental property and it remains so while this warning is present.

flip()[source]¶: 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.

Warning

On iOS, setting fullscreen to False will not automatically hide the status bar.

To achieve this, you must set fullscreen to False, and then also set borderless to False.

get_gl_backend_name()[source]¶: Returns the gl backend that will or is used with this window.

gl_backends_allowed = []¶: A list of Kivy gl backend names, which if not empty, will be the exclusive list of gl backends that can be used with this window.

gl_backends_ignored = []¶: A list of Kivy gl backend names that may not be used with this window.

grab_mouse()[source]¶: 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()[source]¶: 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.

mainloop()[source]¶: Called by the EventLoop every frame after it idles.

managed_textinput = False¶: True if this Window class uses on_textinput to insert text, internal.

maximize()[source]¶: 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()[source]¶: 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 cursor within the window.

Position is relative to the left/bottom point of the window.

Note

Cursor position will be scaled by the pixel density if the high density mode is supported by the window provider.

New in version 1.2.0.

mouse_pos is an ObjectProperty and defaults to (0, 0).

native_handle¶

Read only property to get the native handle of the window.

Note

The value is platform-specific and is mostly meant to be passed to other libraries. This feature is currently only supported on Windows and Linux platforms.

New in version 3.0.0.

native_handle is an AliasProperty.

on_close(*largs)[source]¶: Event called when the window is closed.

on_cursor_enter(*largs)[source]¶: 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)[source]¶: Event called when the cursor leaves the window.

New in version 1.9.1.

Note

This feature requires the SDL2 window provider.

on_drop_begin(x, y, *args)[source]¶

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

New in version 2.1.0.

on_drop_end(x, y, *args)[source]¶

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

New in version 2.1.0.

on_drop_file(filename, x, y, *args)[source]¶

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 sdl2 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)[source]¶

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 sdl2 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()[source]¶: Flip between buffers (event)

on_hide(*largs)[source]¶: 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)[source]¶: 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)[source]¶: Event called when a joystick has a ball moved.

New in version 1.9.0.

on_joy_button_down(stickid, buttonid)[source]¶: Event called when a joystick has a button pressed.

New in version 1.9.0.

on_joy_button_up(stickid, buttonid)[source]¶: Event called when a joystick has a button released.

New in version 1.9.0.

on_joy_hat(stickid, hatid, value)[source]¶: 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)[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_maximize(*largs)[source]¶: Event called when the window is maximized.

New in version 1.10.0.

Note

This feature requires the SDL2 window provider.

on_memorywarning()[source]¶

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)[source]¶: 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)[source]¶

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)[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 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_restore(*largs)[source]¶: Event called when the window is restored.

New in version 1.10.0.

Note

This feature requires the SDL2 window provider.

on_rotate(rotation)[source]¶: Event called when the screen has been rotated.

on_show(*largs)[source]¶: Event called when the window is shown.

New in version 1.10.0.

Note

This feature requires the SDL2 window provider.

on_textedit(text)[source]¶: 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)[source]¶: 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)[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.

opacity¶

Opacity of the window. Accepts a value between 0.0 (transparent) and 1.0 (opaque).

Note

This feature requires the SDL2 window provider.

New in version 2.3.0.

opacity is an AliasProperty and defaults to 1.0.

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()[source]¶: 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.

register_event_manager(manager)[source]¶: 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()[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', keyboard_suggestions=True)[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 ‘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()[source]¶: 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')[source]¶: Save the actual displayed image to a file.

set_custom_titlebar(widget)[source]¶

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

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 SDL2 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)[source]¶: Set the icon of the window.

New in version 1.0.5.

set_system_cursor(cursor_name)[source]¶

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

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 ColorProperty instance and defaults to [1, 1, 1, 1].

Changed in version 2.0.0: Changed from ListProperty to ColorProperty.

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()[source]¶: 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¶

The rotated size of the window in drawable pixels. This is the actual pixel size of the drawable area of the window, and takes into account the window’s rotation and pixel density.

The pixel density is the ratio of the physical pixels to the size of the window in window coordinates. For example, on a Retina HiDPI display, the pixel density is typically 2.0, meaning that the window’s drawable size in pixels is twice the size in window coordinates.

Consider using system_size if you want to programmatically set the window size, as is more portable, and will give a nicer UX across different OSes and displays.

This property differs from unrotated_size as it also accounts for the window’s 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¶

Size in window coordinates of the window.

This property is used to set and retrieve the window size in window coordinates (which is different from the drawable size). The actual size of the window will be adjusted to account for the window’s rotation and pixel density.

Setting the window size in window coordinates is more portable and will give a nicer UX across different OSes and displays, therefore it is recommended to use this property to set the window size instead of size.

New in version 1.0.9.

system_size is an AliasProperty.

to_normalized_pos(x, y)[source]¶: Transforms absolute coordinates to normalized (0-1) coordinates using system_size.

New in version 2.1.0.

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.

transform_motion_event_2d(me, widget=None)[source]¶

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()[source]¶: Ungrab mouse

New in version 1.10.0.

Note

This feature requires the SDL2 window provider.

unregister_event_manager(manager)[source]¶: 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.

unrotated_size¶

The unrotated size of the window in drawable pixels. This is the actual pixel size of the drawable area of the window, and takes into account the window’s pixel density.

The pixel density is the ratio of the physical pixels to the size of the window in window coordinates. For example, on a Retina HiDPI display, the pixel density is typically 2.0, meaning that the window’s drawable size in pixels is twice the size in window coordinates.

New in version 3.0.0.

unrotated_size is a read-only AliasProperty.

width¶

Rotated window width.

width is a read-only AliasProperty.

« Video

Kivy module for binary dependencies. »

Version

Quick search

Table Of Contents

Window¶