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