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)

The textinput’s text is stored on 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 ‘focus’ 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)

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_active

Background image of the TextInput when it’s in focus’.

New in version 1.4.1.

background_active is a StringProperty, default to ‘atlas://data/images/defaulttheme/textinput_active’

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

background_normal

Background image of the TextInput when it’s not in focus’.

New in version 1.4.1.

background_normal is a StringProperty, default to ‘atlas://data/images/defaulttheme/textinput’

border

Border used for BorderImage graphics instruction. Used with background_normal and background_active. Can be used for a custom background.

New in version 1.4.1.

It must be a list of four values: (top, right, bottom, left). Read the BorderImage instruction for more information about how to use it.

border is a ListProperty, default to (16, 16, 16, 16)

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, 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 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 has three 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

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

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 on 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 particular 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.

hint_text

Hint text of the widget.

Shown if text is ‘’ and focus is False.

New in version 1.6.0.

hint_text a StringProperty.

hint_text_color

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

New in version 1.6.0.

hint_text_color is a ListProperty, default to [0.5, 0.5, 0.5, 1.0] #Grey

insert_text(substring, from_undo=False)

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

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 there is no action, the scroll_x and scroll_y properties may be changed.

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.

select_all()

Select all of the text displayed in this TextInput

New in version 1.4.0.

select_text(start, end)

Select portion of text displayed in this TextInput

New in version 1.4.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 drawn 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 started.

Changed in version 1.4.0.

selection_from is a AliasProperty, default to None, readonly.

selection_text

Current content selection.

selection_text is a StringProperty, default to ‘’, readonly.

selection_to

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

Changed in version 1.4.0.

selection_to is a AliasProperty, default to None, readonly.

tab_width

By default, each tab will be replaced by four 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.