keyboard — Utilities for the Pythonista Keyboard

Introduction

The keyboard module provides various functions for extending the custom Pythonista keyboard (“PyKeys”).

The Pythonista keyboard is a custom on-screen keyboard that you can use in pretty much any app on iOS that can edit text. You can extend this keyboard with your own scripts, e.g. for inserting text snippets, or even providing a fully custom UI (ui.View) in or above the QWERTY keyboard. This custom UI can show additional buttons etc., and also react to changes in the document or selection.

If you implement a custom view/UI for your keyboard script, you can also get notified when certain text input-related events happen, either by the user moving the cursor, or by keys on the built-in QWERTY layout being used. To do this, you can implement any of the following callback methods in a custom ui.View subclass:

import keyboard
import ui
from datetime import datetime
from random import uniform

class MyView (ui.View):
        def __init__(self, *args, **kwargs):
                self.label = ui.Label(frame=self.bounds, flex='wh')
                self.add_subview(self.label)
                super().__init__(*args, **kwargs)

        def kb_should_insert(self, text):
                self.label.text = f'Insert: {text}'
                # You can modify the inserted text here:
                return text

        def kb_text_changed(self):
                self.background_color = (uniform(0.5, 1.0), uniform(0.5, 1.0), uniform(0.5, 1.0))

        def kb_should_delete(self):
                return True


v = MyView()
keyboard.set_view(v)

Various examples of custom keyboard UIs are included with Pythonista in the keyboard examples folder.

Note

You can find more information on how to enable and use the keyboard on the Pythonista Shortcuts page.

Functions

keyboard.backspace(times=1)

Delete backwards in the current document (simulate the backspace key). The times parameter determines how many characters are deleted at once.

keyboard.get_appearance()

Return the current appearance of the keyboard (dark' or 'light').

keyboard.get_document_id()

Return a unique identifier (UUID) for the current document the keyboard is typing into. This identifier is arbitrary/random, and does not include any information about the document, but you can use it to detect when the user types into a different document.

keyboard.get_input_context()

Return a pair (2-tuple) of two strings with the text immediately before and after the cursor.

keyboard.get_selected_text()

Return the currently selected text or an empty string, if no text is selected.

Warning

If more than two lines, or about 1000 characters are selected, this function’s return value will be truncated in the middle. Unfortunately, it is not technically possible to prevent this (it’s a system limitation), and it’s also not possible to detect the truncation.

You should typically not use the return value of this function to replace selected text, if it contains more than one line.

keyboard.get_text_replacements()

Return a list of text replacements you’ve defined in the global keyboard settings (Settings app: General > Keyboard > Text Replacement). Every text replacement is a tuple of two strings (phrase, shortcut).

This function is only supported when running in the Pythonista Keyboard. In other contexts, None is returned.

keyboard.has_full_access()

Return True if the ‘Full Access’ option is enabled for the keyboard, False otherwise.

‘Full Access’ is required for a number of things, e.g. any network access, clipboard, writing files to the main app.

keyboard.has_text()

Return True if the document (text field) the keyboard is editing contains any text, False if it’s empty.

keyboard.insert_text(text)

Insert text in the current document (text field) the keyboard is editing.

keyboard.is_keyboard()

Return True if the script is running in the custom Pythonista keyboard, False otherwise.

This can be used for scripts that should behave differently, depending on whether they run in the keyboard or in the main app.

keyboard.move_cursor(offset)

Move the cursor by a specified offset (a positive or negative integer).

keyboard.play_input_click()

Play an input click sound, if this is enabled by the user (input clicks can be turned off in the global keyboard settings), and the device is not muted.

keyboard.set_view(view=None, mode='current')

Sets a custom ui.View as the keyboard’s UI, either above of the QWERTY layout (mode = 'minimized') or filling most of the keyboard’s area (mode = 'expanded'). With mode = 'current', the active mode is kept (you can switch manually by tapping the green “shortcuts” key).

You can pass None as the view to close the current view.

See the Introduction for information about callbacks you can implement in custom UIs to get notified about text input events.