VKeyboard¶
New in version 1.0.8.
VKeyboard is an onscreen keyboard for Kivy. Its operation is intended to be transparent to the user. Using the widget directly is NOT recommended. Read the section Request keyboard first.
Modes¶
This virtual keyboard has a docked and free mode:
docked mode ( VKeyboard.docked = True) Generally used when only one person is using the computer, like a tablet or personal computer etc.
free mode: ( VKeyboard.docked = False) Mostly for multitouch surfaces. This mode allows multiple virtual keyboards to be used on the screen.
If the docked mode changes, you need to manually call VKeyboard.setup_mode() otherwise the change will have no impact. During that call, the VKeyboard, implemented on top of a Scatter , will change the behavior of the scatter and position the keyboard near the target (if target and docked mode is set).
Layouts¶
The virtual keyboard is able to load a custom layout. If you create a new layout and put the JSON in /keyboards/ .json , you can load it by setting VKeyboard.layout to your layoutid.
The JSON must be structured like this:
Then, you need to describe the keys in each row, for either a “normal”, “shift” or a “special” (added in version 1.9.0) mode. Keys for this row data must be named normal_ , shift_ and special_ . Replace row with the row number. Inside each row, you will describe the key. A key is a 4 element list in the format:
Here are example keys:
Finally, complete the JSON:
Request Keyboard¶
The instantiation of the virtual keyboard is controlled by the configuration. Check keyboard_mode and keyboard_layout in the Configuration object .
If you intend to create a widget that requires a keyboard, do not use the virtual keyboard directly, but prefer to use the best method available on the platform. Check the request_keyboard() method in the Window .
If you want a specific layout when you request the keyboard, you should write something like this (from 1.8.0, numeric.json can be in the same directory as your main.py):
VKeyboard is an onscreen keyboard with multitouch support. Its layout is entirely customizable and you can switch between available layouts using a button in the bottom right of the widget.
Events on_key_down : keycode, internal, modifiers
Fired when the keyboard received a key down event (key press).
on_key_up : keycode, internal, modifiers
Fired when the keyboard received a key up event (key release).
Dictionary of all available layouts. Keys are the layout ID, and the value is the JSON (translated into a Python object).
Filename of the background image.
background is a StringProperty and defaults to atlas://data/images/defaulttheme/vkeyboard_background .
Background image border. Used for controlling the border property of the background.
background_border is a ListProperty and defaults to [16, 16, 16, 16]
Background color, in the format (r, g, b, a). If a background is set, the color will be combined with the background texture.
Changed in version 2.0.0: Changed from ListProperty to ColorProperty .
Filename of the background image when the vkeyboard is disabled.
New in version 1.8.0.
background_disabled is a StringProperty and defaults to atlas://data/images/defaulttheme/vkeyboard__disabled_background .
Callback can be set to a function that will be called if the VKeyboard is closed by the user.
target is an ObjectProperty instance and defaults to None.
Do a collision test, and return True if the (x, y) is inside the vkeyboard margin.
Indicate whether the VKeyboard is docked on the screen or not. If you change it, you must manually call setup_mode() otherwise it will have no impact. If the VKeyboard is created by the Window, the docked mode will be automatically set by the configuration, using the keyboard_mode token in [kivy] section.
docked is a BooleanProperty and defaults to False.
font_size, specifies the size of the text on the virtual keyboard keys. It should be kept within limits to ensure the text does not extend beyond the bounds of the key or become too small to read.
New in version 1.10.0.
Key background color, in the format (r, g, b, a). If a key background is set, the color will be combined with the key background texture.
Changed in version 2.0.0: Changed from ListProperty to ColorProperty .
Filename of the key background image for use when a touch is active on the widget.
key_background_down is a StringProperty and defaults to atlas://data/images/defaulttheme/vkeyboard_key_down .
Filename of the key background image for use when no touches are active on the widget.
key_background_normal is a StringProperty and defaults to atlas://data/images/defaulttheme/vkeyboard_key_normal .
Key image border. Used for controlling the border property of the key.
key_border is a ListProperty and defaults to [16, 16, 16, 16]
Filename of the key background image for use when no touches are active on the widget and vkeyboard is disabled.
New in version 1.8.0.
key_disabled_background_normal is a StringProperty and defaults to atlas://data/images/defaulttheme/vkeyboard_disabled_key_normal .
Key margin, used to create space between keys. The margin is composed of four values, in pixels:
key_margin is a ListProperty and defaults to [2, 2, 2, 2]
Layout to use for the VKeyboard. By default, it will be the layout set in the configuration, according to the keyboard_layout in [kivy] section.
Changed in version 1.8.0: If layout is a .json filename, it will loaded and added to the available_layouts.
layout is a StringProperty and defaults to None.
Path from which layouts are read.
layout is a StringProperty and defaults to /keyboards/
Margin hint, used as spacing between keyboard background and keys content. The margin is composed of four values, between 0 and 1:
The margin hints will be multiplied by width and height, according to their position.
margin_hint is a ListProperty and defaults to [.05, .06, .05, .06]
Receive a touch down event.
Parameters touch : MotionEvent class
Touch received. The touch is in parent coordinates. See relativelayout for a discussion on coordinate systems.
bool If True, the dispatching of the touch event will stop. If False, the event will continue to be dispatched to the rest of the widget tree.
Receive a touch up event. The touch is in parent coordinates.
See on_touch_down() for more information.
refresh ( force = False ) [source] ¶
(internal) Recreate the entire widget and graphics according to the selected layout.
Call this method when you want to readjust the keyboard according to options: docked or not, with attached target or not:
If docked is False, it will call setup_mode_free()
Feel free to overload these methods to create new positioning behavior.
Setup the keyboard in docked mode.
Dock mode will reset the rotation, disable translation, rotation and scale. Scale and position will be automatically adjusted to attach the keyboard to the bottom of the screen.
Don’t call this method directly, use setup_mode() instead.
Setup the keyboard in free mode.
Free mode is designed to let the user control the position and orientation of the keyboard. The only real usage is for a multiuser environment, but you might found other ways to use it. If a target is set, it will place the vkeyboard under the target.
Don’t call this method directly, use setup_mode() instead.
Target widget associated with the VKeyboard. If set, it will be used to send keyboard events. If the VKeyboard mode is “free”, it will also be used to set the initial position.
target is an ObjectProperty instance and defaults to None.
Источник
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] ¶
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
Fired when a key is released (up)
Here is an example of how to request a Keyboard in accordance with the current configuration:
Callback that will be called when the keyboard is released
Convert a keycode number to a string according to the Keyboard.keycodes . If the value is not found in the keycodes, it will return ‘’.
Call this method to release the current keyboard. This will ensure that the keyboard is no longer attached to your callback.
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 that have requested the keyboard
VKeyboard widget, if allowed by the configuration
Window which the keyboard is attached too
class kivy.core.window. WindowBase ( ** kwargs ) [source] ¶
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 of the window.
Height of the window.
Minimum width of the window (only works for sdl2 window provider).
Minimum height of the window (only works for sdl2 window provider).
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
Fired when a new touch event is initiated.
Fired when an existing touch event changes location.
Fired when an existing touch event is terminated.
Fired when the Window is being drawn.
Fired when the Window GL surface is being flipped.
Fired when the Window is being rotated.
Fired when the Window is closed.
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.
Fired when the cursor enters the window.
New in version 1.9.1.
Fired when the cursor leaves the window.
New in version 1.9.1.
Fired when the window is minimized.
New in version 1.10.0.
Fired when the window is maximized.
New in version 1.10.0.
Fired when the window is restored.
New in version 1.10.0.
Fired when the window is hidden.
New in version 1.10.0.
Fired when when the window is shown.
New in version 1.10.0.
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.
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.
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.
Fired when a file is dropped on the application.
This event doesn’t work for apps with elevated permissions, because the OS API calls are filtered. Check issue #4999 for pointers to workarounds.
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.
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 a widget to a window
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.
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 of the rotated window.
New in version 1.0.9.
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 the window with the background color
Color used to clear the window.
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 the window
Will create the main window and configure it.
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!
Return the DPI of the screen. If the implementation doesn’t support any DPI lookup, it will just return 96.
This value is not cross-platform. Use kivy.base.EventLoop.dpi instead.
Flip between buffers
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.
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.
The ‘fake’ option has been deprecated, use the borderless property instead.
Returns the gl backend that will or is used with this window.
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.
A list of Kivy gl backend names that may not be used with this window.
Grab mouse — so won’t leave window
New in version 1.10.0.
This feature requires the SDL2 window provider.
Rotated window height.
Hides the window. This method should be used on desktop platforms only.
New in version 1.9.0.
This feature requires the SDL2 window provider and is currently only supported on desktop platforms.
A path to the window icon.
New in version 1.1.2.
The attributes for animating softkeyboard/IME. t = transition , d = duration . This value will have no effect on desktops.
New in version 1.10.0.
Returns the height of the softkeyboard/IME on mobile platforms. Will return 0 if not on mobile platform or if IME is not active.
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.
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.
Left position of the window.
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 .
Called by the EventLoop every frame after it idles.
Maximizes the window. This method should be used on desktop platforms only.
New in version 1.9.0.
This feature requires the SDL2 window provider and is currently only supported on desktop platforms.
Minimizes the window. This method should be used on desktop platforms only.
New in version 1.9.0.
This feature requires the SDL2 window provider and is currently only supported on desktop platforms.
The minimum height to restrict the window to.
New in version 1.9.1.
The minimum width to restrict the window to.
New in version 1.9.1.
List of keyboard modifiers currently active.
New in version 1.0.9.
2d position of the mouse within the window.
New in version 1.2.0.
Event called when the window is closed.
Event called when the cursor enters the window.
New in version 1.9.1.
This feature requires the SDL2 window provider.
Event called when the cursor leaves the window.
New in version 1.9.1.
This feature requires the SDL2 window provider.
Event called when a file is dropped on the application.
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.
Flip between buffers (event)
Event called when the window is hidden.
New in version 1.10.0.
This feature requires the SDL2 window provider.
Event called when a joystick has a stick or other axis moved.
New in version 1.9.0.
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.
Event called when a joystick has a hat/dpad moved.
New in version 1.9.0.
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.
Some providers may omit scancode , codepoint and/or modifier .
Event called when the window is maximized.
New in version 1.10.0.
This feature requires the SDL2 window provider.
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.
Event called when the window is minimized.
New in version 1.10.0.
This feature requires the SDL2 window provider.
Event called when a Motion Event is received.
Parameters etype : str
One of ‘begin’, ‘update’, ‘end’
The Motion Event currently dispatched.
on_mouse_down ( x , y , button , modifiers ) [source] ¶
Event called when the mouse is used (pressed/released).
on_mouse_move ( x , y , modifiers ) [source] ¶
Event called when the mouse is moved with buttons pressed.
on_mouse_up ( x , y , button , modifiers ) [source] ¶
Event called when the mouse is moved with buttons pressed.
on_request_close ( * largs , ** kwargs ) [source] ¶
Event called before we close the window. If a bound function returns True , the window will not be closed. If the the event is triggered because of the keyboard escape key, the keyword argument source is dispatched along with a value of keyboard to the bound functions.
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.
Event called when the window is resized.
Event called when the window is restored.
New in version 1.10.0.
This feature requires the SDL2 window provider.
Event called when the screen has been rotated.
Event called when the window is shown.
New in version 1.10.0.
This feature requires the SDL2 window provider.
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.
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.
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.
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.
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 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 the window. This method should be used on desktop platforms only.
New in version 1.9.1.
This feature requires the SDL2 window provider and is currently only supported on desktop platforms.
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 a widget from a window
request_keyboard ( callback , target , input_type = ‘text’ ) [source] ¶
New in version 1.0.4.
Internal widget method to request the keyboard. This method is rarely required by the end-user as it is handled automatically by the TextInput . We expose it in case you want to handle the keyboard manually for unique input scenarios.
A widget can request the keyboard, indicating a callback to call when the keyboard is released (or taken by another widget).
Parameters callback : func
Callback that will be called when the keyboard is closed. This can be because somebody else requested the keyboard or the user closed it.
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.
Choose the type of soft keyboard to request. Can be one of ‘text’, ‘number’, ‘url’, ‘mail’, ‘datetime’, ‘tel’, ‘address’.
input_type is currently only honored on mobile devices.
New in version 1.8.0.
An instance of Keyboard containing the callback, target, and if the configuration allows it, a VKeyboard instance attached as a .widget property.
The behavior of this function is heavily influenced by the current keyboard_mode . Please see the Config’s configuration tokens section for more information.
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.
This feature requires the SDL2 window provider and is currently only supported on desktop platforms.
Get/set the window content rotation. Can be one of 0, 90, 180, 270 degrees.
New in version 1.0.9.
screenshot ( name = ‘screenshot<:04d>.png’ ) [source] ¶
Save the actual displayed image to a file.
Set the icon of the window.
New in version 1.0.5.
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:
Источник
