# love.textinput

Available since LÖVE 0.9.0
This function is not supported in earlier versions.

Called when text has been entered by the user. For example if shift-2 is pressed on an American keyboard layout, the text "@" will be generated.

## Function

### Synopsis

    love.textinput( text )

### Arguments

`string text`
  The UTF-8 encoded unicode text.

### Returns

Nothing.

## Notes

Although Lua strings can store UTF-8 encoded unicode text just fine, many functions in Lua's string library will not treat the text as you might expect. For example, `#text` (and `string.len(text)`) will give the number of bytes in the string, rather than the number of unicode characters. The Lua wiki and a presentation by one of Lua's creators give more in-depth explanations, with some tips.

The utf8 library can be used to operate on UTF-8 encoded unicode text (such as the text argument given in this function.)

## Examples

Record and print text the user writes.

    function love.load()
        text = "Type away! -- "
    end

    function love.textinput(t)
        text = text .. t
    end

    function love.draw()
        love.graphics.printf(text, 0, 0, love.graphics.getWidth())
    end

Print text the user writes, and erase text when backspace is pressed.

    local utf8 = require("utf8")

    function love.load()
        text = "Type away! -- "

        -- enable key repeat so backspace can be held down to trigger love.keypressed multiple times.
        love.keyboard.setKeyRepeat(true)
    end

    function love.textinput(t)
        text = text .. t
    end

    function love.keypressed(key)
        if key == "backspace" then
            -- get the byte offset to the last UTF-8 character in the string.
            local byteoffset = utf8.offset(text, -1)

            if byteoffset then
                -- remove the last UTF-8 character.
                -- string.sub operates on bytes rather than UTF-8 characters, so we couldn't do string.sub(text, 1, -2).
                text = string.sub(text, 1, byteoffset - 1)
            end
        end
    end

    function love.draw()
        love.graphics.printf(text, 0, 0, love.graphics.getWidth())
    end

## See Also

- love
- love.keypressed
- love.keyboard.setTextInput
- love.keyboard.hasTextInput
- utf8

##

Category:

- Callbacks