Edittext

An edittext item is used to place an editable text field where the user can type and edit text.

The syntax is:

edittext <name> [ <caption> ] [text:<string>] [fieldWidth:<integer>] [height:<integer>] [bold:<boolean>] [labelOnTop:<boolean>] [readOnly:<boolean>]

The default alignment of edittext items is #left.

Parameters

text:

The text string in the edit box. To specify a multiline text as parameter, both carriage return \r and new line \n sequences should be specified, for example "First Line \r\nSecond Line".

fieldWidth:

The width in pixels of the edit box. By default, the width is set to be from just after the caption text to the right margin of the rollout.

height:

If an explicit height: parameter is supplied on an editText item definition that specifies a pixel height greater than one line of text (18 pixels), that editText item becomes a multi-line edit box, allowing multiple lines of text to be entered.

WARNING: If you specify the height of the edittext to be 18 pixels or more, the on entered event handler will not be called since the edittext will be in multi-line mode!

 

bold:

If set to true, the text string in the edit box is displayed in bold format, if set to false, in normal, non-bold format. The default value is false.

lableOnTop:

If set to true, the caption is placed above the edit text box. If false or not specified, the caption is placed to the left of the edit text box.

readOnly:

When set to true, the user cannot copy and paste or enter text in the editText control. When false or not specified, the user can enter, copy and paste text in the editText control.

Properties

<edittext>.text String

The text in the edit box. To specify a multiline text as parameter, both carriage return \r and new line \n sequences should be specified, for example "First Line \r\nSecond Line".

<edittext>.caption String

The text of the optional caption next to the edit box.

<edittext>.bold Boolean

If true, the text is displayed in bold format, if false, in normal, non-bold format.

<edittext>.width Integer

Get/set the width of the edittext window in pixels.

<edittext>.height Integer

Get/set the height of the edittext window in pixels.

<edittext>.readOnly

When set to true, the user cannot copy and paste or enter text in the editText control. When false or not specified, the user can enter, copy and paste text in the editText control.

Events

on <edittext> changed <arg> do <expr>

Called each time the user changes the text in the edit box; the <arg> argument will contain the new text in the edit box.

 

on <edittext> entered <arg> do <expr>

Called when the user enters text in the edit box and then presses ENTER or TAB to move the cursor out of the field. The <arg> argument will contain the new text in the edit box.

ONCE AGAIN: If you specify the height of the edittext to be 18 pixels or more, the on entered event handler will not be called since the edittext will be in multi-line mode!

 

In single-line mode (default height, or less or equal to 18 pixels), if you enter a string in the edit box and then press ENTER, the on changed handler is called once per character and once for the ENTER. The on entered handler is just called once, for the ENTER.

When in multi-line mode, ENTER keystrokes no longer cause the 'on entered' handler to be called, but are inserted into the edit box as new lines.

They do, of course, cause 'on changed' handlers to be called. These are called on every keystroke.

For multi-line editText items, 'on entered' handlers are called when the edit box loses keyboard focus, such as if you tab or click out of the edit box.

 

EditText Example:

rollout boxCreator "Box Creator"

(

--define an edittext with width 100 and the label on top:

edittext prefix_txt "Name prefix:" fieldWidth:200 labelOnTop:true

 

--If the user entered a new name...

on prefix_txt entered txt do

(

--And the name is not the empty string,

if txt != "" do

(

--Create a new box at a random position

--somewhere between the given coordinates:

new_obj = box pos:(random [-100,-100,-100] [100,100,100])

 

--Set the name of the new object to the prefix entered,

--but add unique suffix to avoid duplicate names:

new_obj.name = (uniquename txt)

 

--And finally clear the editText for a new entry

--by assigning an empty string to the text property:

prefix_txt.text = ""

)

)

)

createDialog boxCreator 300 30 --create a Dialog from the rollout

 

Testing_Edittext_UI_01.gif

See also

Rollout User-Interface Items Common Properties

Rollout User-Interface Items Common Layout Parameters

Rollout User-Interface Control Types