Text Input

New in version 1.0.4.

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

The TextInput widget provides a box of editable plain text.

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

Note

Two different coordinate systems are used with TextInput:

  • (x, y) Coordinates in pixels, mostly used for rendering on screen
  • (row, col) Cursor index in characters / lines, used for selection and cursor movement.

Usage example

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

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

To create a monoline textinput, set the multiline property to false (‘enter’ key will defocus the textinput and emit 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)

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 ‘focus’ a textinput, meaning that the input box will be highlighted, and keyboard 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 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)

Selection

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

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, Right
Control + c Copy selection
Control + x Cut selection
Control + p Paste selection
Control + a Select all the content
Control + z undo
Control + r redo
class kivy.uix.textinput.TextInput(**kwargs)

Bases: 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.

background_color

Current color of the background, in (r, g, b, a) format.

New in version 1.2.0.

background_color is a ListProperty, default to [1, 1, 1, 1] #White

cancel_selection()

Cancel current selection (if any)

cursor

Tuple of (row, col) of the current cursor position. You can set a new (row, col) if you want to move the cursor. The scrolling area will be automatically updated to ensure that the cursor will be visible inside the viewport.

cursor is a AliasProperty.

This property is used to blink the cursor graphics. The value of cursor_blink is automatically computed, setting a value on it will have no impact.

cursor_blink is a BooleanProperty, default to False

cursor_col

Current column of the cursor.

cursor_col is a AliasProperty to cursor[0], read-only.

cursor_index()

Return the cursor index in the text/value.

cursor_offset()

Get the cursor x offset on the current line

cursor_pos

Current position of the cursor, in (x, y).

cursor_pos is a AliasProperty, read-only.

cursor_row

Current row of the cursor.

cursor_row is a AliasProperty to cursor[1], read-only.

delete_selection(from_undo=False)

Delete the current text selection (if any)

do_backspace(from_undo=False)

Do backspace operation from the current cursor position. This action might do lot of things like:

  • removing the current selection if available
  • removing the previous char, and back the cursor
  • do nothing, if we are at the start.
do_cursor_movement(action)

Move the cursor relative to it’s 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

Warning

Current page are 3 lines before/after

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 automaticlly 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.

focus

If focus is true, the keyboard will be requested, and you can start to write on the textinput.

focus is a BooleanProperty, default to False

font_name

Filename of the font to use, the path can be absolute or relative. Relative paths are resolved by the resource_find() function.

Warning

Depending of your text provider, the font file can be ignored. However you can mostly use this without trouble.

If the font used lacks the glyphs for the perticular language/symbols you are using, you will see ‘[]’ blank box characters instead of the actual glyphs. The solution is to use a font that has the glyphs you need to display. For example to display unicodechar, use a font like freesans.ttf that has the glyph.

font_name is a StringProperty, default to ‘DroidSans’.

font_size

Font size of the text, in pixels.

font_size is a NumericProperty, default to 10.

foreground_color

Current color of the foreground, in (r, g, b, a) format.

New in version 1.2.0.

foreground_color is a ListProperty, default to [0, 0, 0, 1] #Black

get_cursor_from_index(index)

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

get_cursor_from_xy(x, y)

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

insert_text(substring, from_undo=False)

Insert new text on the current cursor position

line_height

Height of a line. This property is automatically computed from the font_name, font_size. Changing the line_height will have no impact.

line_height is a NumericProperty, read-only.

multiline

If True, the widget will be able show multiple lines of text. If false, “enter” action will defocus the textinput instead of adding a new line.

multiline is a BooleanProperty, default to True

padding

Padding of the text, in the format (padding_x, padding_y)

padding is a ReferenceListProperty of (padding_x, padding_y) properties.

padding_x

Horizontal padding of the text, inside the widget box.

padding_x is a NumericProperty, default to 0. This might be changed by the current theme.

padding_y

Vertical padding of the text, inside the widget box.

padding_x is a NumericProperty, default to 0. This might be changed by the current theme.

password

If True, the widget will display its characters as the character*.

New in version 1.2.0.

password is a BooleanProperty, default to False

readonly

If True, the user will not be able to change the content of a textinput.

New in version 1.3.0.

readonly is a BooleanProperty, default to False

reset_undo()

Reset undo and redo lists from memory

New in version 1.3.0.

scroll_x

X scrolling value of the viewport. The scrolling is automatically updated when the cursor is moving or text is changing. If you are not doing any action, you can still change the scroll_x and scroll_y properties.

scroll_x is a NumericProperty, default to 0.

scroll_y

Y scrolling value of the viewport. See scroll_x for more information.

scroll_y is a NumericProperty, default to 0.

selection_color

Current color of the selection, in (r, g, b, a) format.

Warning

The color should always have “alpha” component different from 1, since the selection is drawed after the text.

selection_color is a ListProperty, default to [0.1843, 0.6549, 0.8313, .5]

selection_from

If a selection is happening, or finished, this property will represent the cursor index where the selection start.

selection_from is a NumericProperty, default to None

selection_text

Current content selection.

selection_text is a StringProperty, default to ‘’

selection_to

If a selection is happening, or finished, this property will represent the cursor index where the selection end.

selection_to is a NumericProperty, default to None

tab_width

By default, each tab will be replaced by the size of 4 spaces on the text input widget. You can set a lower or higher value.

tab_width is a NumericProperty, default to 4.

text

Text of the widget.

Creation of a simple hello world

widget = TextInput(text='Hello world')

If you want to create the widget with an unicode string, use

widget = TextInput(text=u'My unicode string')

text a StringProperty.