Table Of Contents
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.
- on_double_tap
Fired when a double tap happen in the text input. The default behavior select the text around the cursor position. More info at on_double_tap().
- on_triple_tap
Fired when a triple tap happen in the text input. The default behavior select 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 select the whole text. More info at on_quad_touch()
Changed in version 1.7.0: on_double_tap, on_triple_tap and on_quad_touch events added.
- auto_indent¶
Automatically indent multiline text.
New in version 1.7.0.
- 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
- on_double_tap()¶
This event is dispatched when a double tap happens inside TextInput. The default behavior is to select the word around current cursor position. Override this to provide a separate functionality. Alternatively you can bind to this event to provide additional functionality.
- on_quad_touch()¶
This event is dispatched when a four fingers are touching inside TextInput. The default behavior is to select all text. Override this to provide a separate functionality. Alternatively you can bind to this event to provide additional functionality.
- 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 a separate functionality. Alternatively you can bind to this event to provide additional functionality.
- padding¶
Padding of the text: [padding_left, padding_top, padding_right, padding_bottom].
padding also accepts a two argument form [padding_horizontal, padding_vertical] and a one argument form [padding].
Changed in version 1.7.0.
Replaced AliasProperty with VariableListProperty.
padding is a VariableListProperty, default to [6, 6, 6, 6].
- padding_x¶
Horizontal padding of the text: [padding_left, padding_right].
padding_x also accepts a one argument form [padding_horizontal].
padding_x is a VariableListProperty, default to [0, 0]. This might be changed by the current theme.
Deprecated since version 1.7.0: Use padding instead
- padding_y¶
Vertical padding of the text: [padding_top, padding_bottom].
padding_y also accepts a one argument form [padding_vertical].
padding_y is a VariableListProperty, default to [0, 0]. This might be changed by the current theme.
Deprecated since version 1.7.0: Use padding instead
- 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.
Parameters : - start
Index of textinput.text from where to start selection
- end
Index of textinput.text till which the selection should be displayed
- 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')
- use_bubble¶
Indicates whether the cut copy paste bubble is used
New in version 1.7.0.
use_bubble is a BooleanProperty, default to True, and deactivated by default on “desktop”.