Version

Quick search

Table Of Contents

Text Input

New in version 1.0.4.

_images/textinput-mono.jpg _images/textinput-multi.jpg

The TextInput widget provides a box for editable plain text.

Unicode, multiline, cursor navigation, selection and clipboard features are supported.

The TextInput uses two different coordinate systems:

  • (x, y) - coordinates in pixels, mostly used for rendering on screen.

  • (col, row) - cursor index in characters / lines, used for selection and cursor movement.

Usage example

To create a multiline TextInput (the ‘enter’ key adds a new line):

from kivy.uix.textinput import TextInput
textinput = TextInput(text='Hello world')

To create a singleline TextInput, set the TextInput.multiline property to False (the ‘enter’ key will defocus the TextInput and emit an TextInput.on_text_validate() event):

def on_enter(instance, value):
    print('User pressed enter in', instance)

textinput = TextInput(text='Hello world', multiline=False)
textinput.bind(on_text_validate=on_enter)

The textinput’s text is stored in its TextInput.text property. To run a callback when the text changes:

def on_text(instance, value):
    print('The widget', instance, 'have:', value)

textinput = TextInput()
textinput.bind(text=on_text)

You can set the focus to a Textinput, meaning that the input box will be highlighted and keyboard focus will be requested:

textinput = TextInput(focus=True)

The textinput is defocused if the ‘escape’ key is pressed, or if another widget requests the keyboard. You can bind a callback to the focus property to get notified of focus changes:

def on_focus(instance, value):
    if value:
        print('User focused', instance)
    else:
        print('User defocused', instance)

textinput = TextInput()
textinput.bind(focus=on_focus)

See FocusBehavior, from which the TextInput inherits, for more details.

Selection

The selection is automatically updated when the cursor position changes. You can get the currently selected text from the TextInput.selection_text property.

Handles

One can enable TextInput.use_handles property to enable or disable the usage of selection handles. This property is True by default on mobiles.

Selection Handles uses the class Selector as the base class for the selection handles. You can customize the color for selection handles like so

<Selector>
    color: 0, 1, 0, 1
    # or <Textinput_instance>.selection_color or app.selection_color

TextInput instantiates the selection handles and stores it in the following properties. TextInput._handle_middle, TextInput._handle_left, TextInput._handle_right.

You should set the selection template before the Instantiating TextInput, so as to get the selection handles to take the changes you set to apply.

Filtering

You can control which text can be added to the TextInput by overwriting TextInput.insert_text(). Every string that is typed, pasted or inserted by any other means into the TextInput is passed through this function. By overwriting it you can reject or change unwanted characters.

For example, to write only in capitalized characters:

class CapitalInput(TextInput):

    def insert_text(self, substring, from_undo=False):
        s = substring.upper()
        return super().insert_text(s, from_undo=from_undo)

Or to only allow floats (0 - 9 and a single period):

class FloatInput(TextInput):

    pat = re.compile('[^0-9]')
    def insert_text(self, substring, from_undo=False):
        pat = self.pat
        if '.' in self.text:
            s = re.sub(pat, '', substring)
        else:
            s = '.'.join(
                re.sub(pat, '', s)
                for s in substring.split('.', 1)
            )
        return super().insert_text(s, from_undo=from_undo)

Default shortcuts

Shortcuts

Description

Left

Move cursor to left

Right

Move cursor to right

Up

Move cursor to up

Down

Move cursor to down

Home

Move cursor at the beginning of the line

End

Move cursor at the end of the line

PageUp

Move cursor to 3 lines before

PageDown

Move cursor to 3 lines after

Backspace

Delete the selection or character before the cursor

Del

Delete the selection of character after the cursor

Shift + <dir>

Start a text selection. Dir can be Up, Down, Left or Right

Control + c

Copy selection

Control + x

Cut selection

Control + v

Paste clipboard content

Control + a

Select all the content

Control + z

undo

Control + r

redo

Note

To enable Emacs-style keyboard shortcuts, you can use EmacsBehavior.

class kivy.uix.textinput.TextInput(**kwargs)

Bases: kivy.uix.behaviors.focus.FocusBehavior, kivy.uix.widget.Widget

TextInput class. See module documentation for more information.

Events:
on_text_validate

Fired only in multiline=False mode when the user hits ‘enter’. This will also unfocus the textinput.

on_double_tap

Fired when a double tap happens in the text input. The default behavior selects the text around the cursor position. More info at on_double_tap().

on_triple_tap

Fired when a triple tap happens in the text input. The default behavior selects the line around the cursor position. More info at on_triple_tap().

on_quad_touch

Fired when four fingers are touching the text input. The default behavior selects the whole text. More info at on_quad_touch().

Warning

When changing a TextInput property that requires re-drawing, e.g. modifying the text, the updates occur on the next clock cycle and not instantly. This might cause any changes to the TextInput that occur between the modification and the next cycle to be ignored, or to use previous values. For example, after a update to the text, changing the cursor in the same clock frame will move it using the previous text and will likely end up in an incorrect position. The solution is to schedule any updates to occur on the next clock cycle using schedule_once().

Note

Selection is cancelled when TextInput is focused. If you need to show selection when TextInput is focused, you should delay (use Clock.schedule) the call to the functions for selecting text (select_all, select_text).

Changed in version 1.10.0: background_disabled_active has been removed.

Changed in version 1.9.0: TextInput now inherits from FocusBehavior. keyboard_mode, show_keyboard(), hide_keyboard(), focus(), and input_type have been removed since they are now inherited from FocusBehavior.

Changed in version 1.7.0: on_double_tap, on_triple_tap and on_quad_touch events added.

Changed in version 2.1.0: keyboard_suggestions is now inherited from FocusBehavior.

cancel_selection()

Cancel current selection (if any).

copy(data='')

Copy the value provided in argument data into current clipboard. If data is not of type string it will be converted to string. If no data is provided then current selection if present is copied.

New in version 1.8.0.

cursor_index(cursor=None)

Return the cursor index in the text/value.

cursor_offset()

Get the cursor x offset on the current line.

cut()

Copy current selection to clipboard then delete it from TextInput.

New in version 1.8.0.

delete_selection(from_undo=False)

Delete the current text selection (if any).

do_backspace(from_undo=False, mode='bkspc')

Do backspace operation from the current cursor position. This action might do several things:

  • removing the current selection if available.

  • removing the previous char and move the cursor back.

  • do nothing, if we are at the start.

do_cursor_movement(action, control=False, alt=False)

Move the cursor relative to its current position. Action can be one of :

  • cursor_left: move the cursor to the left

  • cursor_right: move the cursor to the right

  • cursor_up: move the cursor on the previous line

  • cursor_down: move the cursor on the next line

  • cursor_home: move the cursor at the start of the current line

  • cursor_end: move the cursor at the end of current line

  • cursor_pgup: move one “page” before

  • cursor_pgdown: move one “page” after

In addition, the behavior of certain actions can be modified:

  • control + cursor_left: move the cursor one word to the left

  • control + cursor_right: move the cursor one word to the right

  • control + cursor_up: scroll up one line

  • control + cursor_down: scroll down one line

  • control + cursor_home: go to beginning of text

  • control + cursor_end: go to end of text

  • alt + cursor_up: shift line(s) up

  • alt + cursor_down: shift line(s) down

Changed in version 1.9.1.

do_redo()

Do redo operation.

New in version 1.3.0.

This action re-does any command that has been un-done by do_undo/ctrl+z. This function is automatically called when ctrl+r keys are pressed.

do_undo()

Do undo operation.

New in version 1.3.0.

This action un-does any edits that have been made since the last call to reset_undo(). This function is automatically called when ctrl+z keys are pressed.

get_cursor_from_index(index)

Return the (col, row) of the cursor from text index.

get_cursor_from_xy(x, y)

Return the (col, row) of the cursor from an (x, y) position.

get_max_scroll_x()

Return how many pixels it needs to scroll to the right to reveal the remaining content of a text that extends beyond the visible width of a TextInput

insert_text(substring, from_undo=False)

Insert new text at the current cursor position. Override this function in order to pre-process text for input validation.

keyboard_on_key_down(window, keycode, text, modifiers)

The method bound to the keyboard when the instance has focus.

When the instance becomes focused, this method is bound to the keyboard and will be called for every input press. The parameters are the same as kivy.core.window.WindowBase.on_key_down().

When overwriting the method in the derived widget, super should be called to enable tab cycling. If the derived widget wishes to use tab for its own purposes, it can call super after it has processed the character (if it does not wish to consume the tab).

Similar to other keyboard functions, it should return True if the key was consumed.

keyboard_on_key_up(window, keycode)

The method bound to the keyboard when the instance has focus.

When the instance becomes focused, this method is bound to the keyboard and will be called for every input release. The parameters are the same as kivy.core.window.WindowBase.on_key_up().

When overwriting the method in the derived widget, super should be called to enable de-focusing on escape. If the derived widget wishes to use escape for its own purposes, it can call super after it has processed the character (if it does not wish to consume the escape).

See keyboard_on_key_down()

on_cursor(instance, value)

When the cursor is moved, reset cursor blinking to keep it showing, and update all the graphics.

trigger blink event reset to switch blinking while focused

on_double_tap()

This event is dispatched when a double tap happens inside TextInput. The default behavior is to select the word around the current cursor position. Override this to provide different behavior. Alternatively, you can bind to this event to provide additional functionality.

on_quad_touch()

This event is dispatched when four fingers are touching inside TextInput. The default behavior is to select all text. Override this to provide different behavior. Alternatively, you can bind to this event to provide additional functionality.

on_touch_down(touch)

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.

Returns:

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.

on_touch_move(touch)

Receive a touch move event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_touch_up(touch)

Receive a touch up event. The touch is in parent coordinates.

See on_touch_down() for more information.

on_triple_tap()

This event is dispatched when a triple tap happens inside TextInput. The default behavior is to select the line around current cursor position. Override this to provide different behavior. Alternatively, you can bind to this event to provide additional functionality.

paste()

Insert text from system Clipboard into the TextInput at current cursor position.

New in version 1.8.0.

property pgmove_speed

how much vertical distance hitting pg_up or pg_down will move

reset_undo()

Reset undo and redo lists from memory.

New in version 1.3.0.

select_all()

Select all of the text displayed in this TextInput.

New in version 1.4.0.

select_text(start, end)

Select a portion of text displayed in this TextInput.

New in version 1.4.0.

Parameters:
start

Index of textinput.text from where to start selection

end

Index of textinput.text till which the selection should be displayed

« TabbedPanel Toggle button »