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 : - 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.
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.
- borderless¶
When set to True, this property removes the window border/decoration.
New in version 1.9.0.
borderless is a BooleanProperty, defaults to False.
- 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.
- 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).
- 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.
- 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.
Note
The ‘fake’ option has been deprecated, use the borderless property instead.
- 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 works with the SDL2 window provider only.
Warning
This code is still experimental, and its API may be subject to change in a future version.
- 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.
- maximize()[source]¶
Maximizes the window. This method should be used on desktop platforms only.
New in version 1.9.0.
Note
This feature works with the SDL2 window provider only.
Warning
This code is still experimental, and its API may be subject to change in a future version.
- minimize()[source]¶
Minimizes the window. This method should be used on desktop platforms only.
New in version 1.9.0.
Note
This feature works with the SDL2 window provider only.
Warning
This code is still experimental, and its API may be subject to change in a future version.
- modifiers¶
List of keyboard modifiers currently active.
- mouse_pos¶
2d position of the mouse within the window.
New in version 1.2.0.
- on_dropfile(filename)[source]¶
Event called when a file is dropped on the application.
Warning
This event currently works with sdl2 window provider, on pygame window provider and MacOSX 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_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, value)[source]¶
Event called when a joystick has a ball moved
New in version 1.9.0.
Event called when a joystick has a button pressed
New in version 1.9.0.
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_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_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_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.
- 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.
- 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 works with the SDL2 window provider only.
Warning
This code is still experimental, and its API may be subject to change in a future version.
- rotation¶
Get/set the window content rotation. Can be one of 0, 90, 180, 270 degrees.
- 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.
- show()[source]¶
Shows the window. This method should be used on desktop platforms only.
New in version 1.9.0.
Note
This feature works with the SDL2 window provider only.
Warning
This code is still experimental, and its API may be subject to change in a future version.
- 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 between fullscreen and windowed mode.
Deprecated since version 1.9.0: Use fullscreen instead.
- width¶
Rotated window width.
width is a read-only AliasProperty.
- kivy.core.window.Window = None¶
Instance of a WindowBase implementation