Difference between revisions of "love.textinput"

m (See Also: added love.keyboard.setTextInput)
(See Also: Updated stale link to SDL2 textinput tutorial)
 
(12 intermediate revisions by 3 users not shown)
Line 13: Line 13:
 
== Notes ==
 
== 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, <code>#text</code> (and <code>string.len(text)</code>) will give the number of ''bytes'' in the string, rather than the number of unicode characters. The [http://lua-users.org/wiki/LuaUnicode Lua wiki] and a [http://www.lua.org/wshop12/Ierusalimschy.pdf presentation by one of Lua's creators] give more in-depth explanations, with some tips.
 
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, <code>#text</code> (and <code>string.len(text)</code>) will give the number of ''bytes'' in the string, rather than the number of unicode characters. The [http://lua-users.org/wiki/LuaUnicode Lua wiki] and a [http://www.lua.org/wshop12/Ierusalimschy.pdf 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.)
 +
 +
On Android and iOS, textinput is disabled by default; call [[love.keyboard.setTextInput]] to enable it.
  
 
== Examples ==
 
== Examples ==
Line 29: Line 33:
 
end
 
end
 
</source>
 
</source>
 +
 +
Print text the user writes, and erase text when backspace is pressed.
 +
<source lang="lua">
 +
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
 +
</source>
 +
 
== See Also ==
 
== See Also ==
 
* [[parent::love]]
 
* [[parent::love]]
Line 34: Line 72:
 
* [[love.keyboard.setTextInput]]
 
* [[love.keyboard.setTextInput]]
 
* [[love.keyboard.hasTextInput]]
 
* [[love.keyboard.hasTextInput]]
 +
* [[utf8]]
 +
* [https://wiki.libsdl.org/SDL2/Tutorials-TextInput textinput vs keypressed]
 
[[Category:Callbacks]]
 
[[Category:Callbacks]]
 
{{#set:Description=Called when text has been entered by the user.}}
 
{{#set:Description=Called when text has been entered by the user.}}
 +
{{#set:Subcategory=Keyboard}}
  
 
== Other Languages ==
 
== Other Languages ==
 
{{i18n|love.textinput}}
 
{{i18n|love.textinput}}

Latest revision as of 10:00, 2 October 2023

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

On Android and iOS, textinput is disabled by default; call love.keyboard.setTextInput to enable it.

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


Other Languages