Text Input¶
New in version 1.0.4.


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.
- cursor_blink¶
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
, 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_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')