Single-line editable text entry with text selection and copy/paste support.

rtk.Entry implements most (all?) of the usual keyboard shortcuts and UX idioms for cursor (caret) navigation, selection, and clipboard management, and so it should feel relatively intuitive for most users.

Undo is also supported, both programmatically as well as via the default user-accessible context menu.

Example

local entry = box:add(rtk.Entry{icon='search', placeholder='Search', textwidth=15})
entry.onkeypress = function(self, event)
    if event.keycode == rtk.keycodes.ESCAPE then
        self:clear()
        self:animate{'bg', dst=rtk.Attribute.DEFAULT}
    elseif event.keycode == rtk.keycodes.ENTER then
        self:animate{'bg', dst='hotpink'}
    end
end

Attributes

rtk.Entry.value string read/write ¶

The current (or desired if setting) value of the text entry (default is the empty string). As the user interacts with the entry, this value is updated to reflect current state, or you can set the value programmatically via attr() one of the rtk.Entry-specific methods below.

The value is never nil. If no text is inputted, it is represented by the empty string.

This attribute may be passed as the first positional argument during initialization. (In other words, rtk.Entry{'Foo'} is equivalent to rtk.Entry{value='Foo'}.)

rtk.Entry.textwidth number or nil read/write ¶

Defines the width of the entry widget to hold this many characters based on the current font when w is not defined (default nil). The w attribute will override textwidth.

rtk.Entry.icon rtk.Image, string or nil read/write ¶

Optional icon for the left edge of the entry box (default nil). If a string is provided, rtk.Image.icon() will be called to fetch the image, otherwise an rtk.Image object can be used directly.

rtk.Entry.icon_alpha number read/write ¶

The opacity of icon (default 0.6).

rtk.Entry.spacing number read/write ¶

The amount of space in pixels between the icon and the text (default 5).

rtk.Entry.placeholder string read/write ¶

Placeholder text that is drawn with a low opacity as long as value is empty (default nil). If nil, the placeholder text is not drawn. The color (including opacity) of the placeholder is defined by the current theme's entry_placeholder.

rtk.Entry.textcolor colortype or nil read/write ¶

Color of text value, which defaults to the theme's text value.

rtk.Entry.border_hover colortype or nil read/write ¶

Color of border when the mouse is hovering over the rtk.Entry region, which defaults to the theme's entry_border_hover. To disable hover border, set this attribute to nil (via rtk.Attribute.NIL)

rtk.Entry.border_focused colortype or nil read/write ¶

Color of border when the widget is focused, which defaults to the theme's entry_border_focused value. To disable focused border, set this attribute to nil (via rtk.Attribute.NIL)

rtk.Entry.blink boolean read/write ¶

Controls whether the cursor will blink when the widget is focused (default true).

rtk.Entry.caret number read/write ¶

The current caret (or cursor) position which is immediately in front of the character defined by this index (default 1).

rtk.Entry.font string or nil read/write ¶

The name of the font face (e.g. 'Calibri'), which uses the global text entry font by default.

rtk.Entry.fontsize number or nil read/write ¶

The pixel size of the entry font (e.g. 18), which uses the global text entry font size by default.

rtk.Entry.fontscale number read/write ¶

Scales fontsize by the given multiplier (default 1.0). This is a convenient way to adjust the relative font size without specifying the exact size.

rtk.Entry.fontflags number or nil read/write ¶

A bitmap of font flags to alter the text appearance (default nil). Nil (or 0) does not style the font.

Methods

rtk.Entry(attrs, ...) ¶

Create a new text entry widget with the given attributes.

rtk.Entry:select_all() ¶

Selects all text.

rtk.Entry:select_range(a, b) ¶

Selects a region of text between two character positions.

Each parameter refers to an index within the value string, where the first character in value is index 1, as usual for Lua.

The range works like Lua's native string.sub() in that the range is inclusive (i.e. includes the characters at both a and b indexes), and also suports negative end indices, such that -1 refers to the end of the string, -2 is the second last character, etc.

Parameters

a	(number)	the starting character index
b	(number)	the ending character index (inclusive within the region), or negative to slice from the end of the string, where -1 will extend to the end of value.

rtk.Entry:get_selection_range() ¶

Returns the selection range.

Return Values

1.	(number)	the index within value of the start of the selection, or nil if nothing was selected.
2.	(number)	the index within value of the end of the selection (inclusive), or nil if nothing was selected.

rtk.Entry:delete_range(a, b) ¶

Deletes a specific range from the text entry.

The original value is added to undo history.

Parameters

a	(number)	the starting character index
b	(number)	the ending character index (inclusive within the region)

rtk.Entry:delete() ¶

Deletes the current selected range from value and resets the selection.

The original value is added to undo history.

Return Values

(number)

the number of characters that were deleted from value, or 0 if there was no selection.

rtk.Entry:clear() ¶

Erases all contents from the entry.

This is different from directly setting the value attribute to the empty string in that it also pushes the current value onto the undo history.

rtk.Entry:copy() ¶

Copies the selected range to the system clipboard.

The original value is added to undo history.

This uses rtk.clipboard.set() and so requires the SWS extension to work properly.

Return Values

(string or nil)

the text that was copied to clipboard, or nil if nothing was selected, or if the SWS extension isn't available.

rtk.Entry:cut() ¶

Copies the selected text to the clipboard and deletes it from value, resetting the selection.

The original value is added to undo history.

Return Values

(string or nil)

the string that was cut from value, or nil if nothing was selected, or if the SWS extension wasn't available.

rtk.Entry:paste() ¶

Pastes text from the clipboard into the text entry at the current caret position.

The original value is added to undo history.

Parameters

rtk.Entry:insert(text) ¶

Inserts the given text at the current caret position.

The original value is added to undo history.

Parameters

text

(string)

the text to insert at caret

rtk.Entry:undo() ¶

Reverts to the last state in the undo history.

All APIs that mutate value add undo state to the undo history. However, individual character presses by the user within the entry do not generate undo state.

Return Values

(boolean)

true if undo state was restored, or false if there was no undo state.

rtk.Entry:push_undo() ¶

Pushes current state to the undo history for future undo().

See also handlers for rtk.Widget.

rtk.Entry:onchange(event) ¶

Called whenever value has changed, either by the user changing the value in the UI, or when it changes programmatically via the API.

Parameters

event

(rtk.Event or nil)

an rtk.Event.KEY event if available, or nil if the entry was changed programmatically.

Return Values

(nil)

Return value has no significance. This is a notification event only.