Text Entry Element

An entry element provides allows users to enter a single line of text, optionally display a hint when no value has been provided.

A new entry can be created with the entry() function in the ui.

Functions

ui.entry(font)

Create a new uientry.

Parameters:

font (uifont)

Return type:

uientry

Version History

Version	Notes
0.3.0	Added

Classes

class ui.uientry

text([newtext])

Get or set the value of this text entry.

Parameters:

newtext (string) – (Optional)

Return type:

string

Version History

Version	Notes
0.3.0	Added

hint(text)

Set a text value to be shown in the entry when it is empty.

This is typically a hint or example that can help a user understand what to enter into the entry.

Parameters:

text (string)

Version History

Version	Notes
0.3.0	Added

prefwidth(pixels)

Set the preferred width of the text box.

Parameters:

pixels (integer)

Version History

Version	Notes
0.3.0	Added

addeventhandler(handler, event1[, event2, ...])

Add an event handler for the given events.

Multiple events can be specified, but at least one is required.

Events:

Event	Description
enter	Mouse cursor is now over the entry element.
leave	Mouse cursor is no longer over the entry element.
click-left	Left/primary mouse button clicked.
click-right	Right/secondary mouse button clicked.
click-middle	Middle mouse button clicked.
click-x1	4th mouse button clicked.
click-x2	5th mouse button clicked.
click-unk	A unsupported/unknown mouse button was clicked.
wheel-up	Mouse wheel moved up.
wheel-down	Mouse wheel moved down.
wheel-right	Mouse wheel moved right.
wheel-left	Mouse wheel moved left.
focus	The entry now has keyboard input focus.
unfocus	The entry no longer has keyboard input focus.

Note

click-* events are sent when the respective button is released, and only if the mouse cursor was within the entry on both press and release.

wheel-* events are sent multiple times, one for each value of the corresponding wheel event. In other words, a single large scroll event will result in multiple wheel-* events.

In addition to the events above, entries will also send key events. Key events are named in a {mod1}-{mod2}-{key}-{updown} format. For example: ctrl-v-down or ctrl-shift-a-up, etc.

An event handler added with this method can be removed later with removeeventhandler().

Parameters:

• handler (function)

• event1 (string)

Return type:

integer

Version History

Version	Notes
0.3.0	Added

removeeventhandler(handlerid)

Removes an event handler.

Parameters:

handlerid (integer) – An event handler id returned by addeventhandler()

Version History

Version	Notes
0.3.0	Added

readonly(value)

Sets if this entry should be read only or not.

A read only entry does not receive keyboard focus or events and the value can not be edited by the user.

Parameters:

value (boolean)

Version History

Version	Notes
0.3.0	Added

sendevent(event)

Send an event to event handlers of this entry.

Note

This is only intended to be used when sub-classing an entry.

Parameters:

event (string)

Version History

Version	Notes
0.3.0	Added

Note

The following methods are inherited from uielement

x([position])

Set or get the current position X.

Parameters:

position (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually position an element.

Version History

Version	Notes
0.3.0	Added

y([position])

Set or get the current position Y.

Parameters:

position (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually position an element.

Version History

Version	Notes
0.3.0	Added

width([value])

Get or set the element’s width.

Parameters:

width (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually set an element’s size.

Version History

Version	Notes
0.3.0	Added

height([value])

Get or set the element’s height.

Parameters:

width (integer) – (Optional)

Return type:

integer

Important

It is normally not necessary to manually set an element’s size.

Version History

Version	Notes
0.3.0	Added

bgcolor([color])

Get or set the element’s background color.

Parameters:

color (integer) – (Optional)

Return type:

integer

Version History

Version	Notes
0.3.0	Added