Class rtk.Entry

Class Hierarchy

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

Synopsis

Attributes
value string

read/write

The current (or desired if setting) value of the text entry (default is the empty string)

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)

icon rtk.Image, string or nil

read/write

Optional icon for the left edge of the entry box (default nil)

icon_alpha number

read/write

The opacity of icon (default 0.6)

spacing number

read/write

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

placeholder string

read/write

Placeholder text that is drawn with a low opacity as long as value is empty (default nil)

textcolor colortype or nil

read/write

Color of text value, which defaults to the theme's text value if nil (default)

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 value if nil (default)

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 if nil (default)

blink boolean

read/write

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

caret number

read/write

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

font string or nil

read/write

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

fontsize number or nil

read/write

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

fontscale number

read/write

Scales fontsize by the given multiplier (default 1.0)

fontflags number or nil

read/write

A bitmap of font flags to alter the text appearance (default nil)

Methods
rtk.Entry()

Create a new text entry widget with the given attributes

select_all()

Selects all text

select_range()

Selects a region of text between two character positions

get_selection_range()

Returns the selection range

delete_range()

Deletes a specific range from the text entry

delete()

Deletes the current selected range from value and resets the selection

clear()

Erases all contents from the entry

copy()

Copies the selected range to the system clipboard

cut()

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

paste()

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

insert()

Inserts the given text at the current caret position

undo()

Reverts to the last state in the undo history

push_undo()

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

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 if nil (default).

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 value if nil (default).

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 if nil (default).

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 default if nil (default nil).

rtk.Entry.fontsize number or nil read/write

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

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

Event Handlers

See also handlers for rtk.Widget.

Synopsis

Methods
onchange()

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

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.