TextField

• Related Topics:
• ChoiceTextField
• StringItem
• FilteredChoiceGroup
• FilteredList
• DateField
• GUI Concepts
• CSS Basics

The TextField allows you to enter data in your application in different modes:

• Native Input Mode: When the native mode is activated, a new input screen will pop up for the user and special input modes like native T9 or handwriting recognition can be used. This allows your user to utilize all native input mechanisms that the target device supports but it does interrupt the visual flow within the application. The Native Input Mode is used by default.
• Direct Input Mode: With the Direct Input Mode J2ME Polish accepts input directly without showing a new popup screen. Unless the device contains a full keyboard, the user has to press keys several times for accessing specific characters - for example press '2' twice for getting a 'b'.
• Predictive Input Mode: Use the Predictive Input Mode for allowing your users to enter words conveniently - for example enter 'hello' by pressing '43556'.

Design

Since J2ME Polish's TextFields internally extend StringItems you can use any StringItem design settings as well, for example text-effects.

The above TextField has been designed with the following styles:

.itemTextInput {
	font-color: black;
	text-effect: smiley;
}
.itemTextInput:hover {
	background-color: #7196B7;
}
info {
	font-color: gray;
}

Additionally, the following variables can be set:

<variable name="polish.TextField.useDirectInput" value="true"/>
<variable name="polish.TextField.usePredictiveInput" value="true"/>
<variable name="polish.TextField.includeInputInfo" value="true"/>
<variable file="configuration/smileys.properties" />

In the corresponding configuration/smileys.properties the following settings are made:

smileys={new Smiley(new String[]{":-)",":)"},"/smiley_1.png","smile"),new Smiley(new String[]{":-P",":P"},"/smiley_2.png","cheekie"),new Smiley(new String[]{":-(",":("},"/smiley_3.png","ouch")}

Specific CSS attributes:

CSS Attribute	Default	Values	Explanation
predictive-choice-orientation	bottom	bottom, top	Sets the orientation of a shadow for the shadow font-effect.
predictive-choicestyle	-	style	Defines the style for single possible matches of the curent user input.
predictive-containerstyle	-	style	Defines the style for the menu that contains the possible matches for the current user input.
predictive-type	trie	trie, array	Sets the type of the predictive field.
textfield-caret-color	-	color	Defines the color of the caret. This defaults to the color of the text (font-color).
textfield-caret-flash	true	true, false	Defines whether the cursor should blink.
textfield-direct-input	false	true, false	Defines whether input should be done with with J2ME Polish only instead of with the native input-system of the underlying OS.
textfield-show-length	false	true, false	Defines whether the current length of the input should be shown.
Further CSS Attribute	Default	Values	Explanation
after	-	imageurl	The URL of the image that should be shown after the item in question.
always-include	false	true, false	Defines if a style should always be included, even if not used.
background	-	background definition	The background of an item or screen. The default background for items is "none", the default background for screens is a simple white background.
before	-	imageurl	The URL of the image that should be shown before the item in question.
complete-border	-	border	A border reference from the borders section. The border includes the label of the item and is independent of the item's normal border.
complete-background	-	background	A background name from the backgrounds section. The background includes the label of the item and is independent of the item's normal background.
border	-	border definition	The border of an item or screen. The default border is "none".
complete-background-padding	-	integer	The padding that is added to the complete-background and/or complete-border. Note that this does not change the size of the item, so you might need to adapt margins or normal paddings for your design.
focused-style	focused	style	The name of the style for the currently focused item, usually applied with a [style-name]:hover construct.
font-bitmap	-	string	Defines which bitmap (bmf) font should be used.
include-label	false	true, false	Usually the label of an item is rendered separately of the item's content. You can expand the background and border over the label as well using this attribute.
inherit	true	true, false	Defines if a style that extends this style should inherit all attributes.
label-style	label	style	The name of the style for the label of the corresponding Item.
max-height	-	integer	The maximum height of an item.
max-width	-	integer	The maximum width of an item.
min-height	-	integer	The minimum height of an item.
min-width	-	integer	The minimum width of an item.
table-selected-background	-	background	The background for selected cells of a table.
colspan	1	integer	The number of columns wich are used by the item within a table.
table-selected-row-background	-	background	The background for selected rows of a table.
opacity	255	integer	The opacity of an item between 0 (fully transparent) and 255 (fully opaque).
pressed-style	-	style	The style which indicates that an item is being pressed, usually applied with a [style-name]:pressed construct.
table-selected-column-background	-	background	The background for selected columns of a table.
text-effect	-		Sets a text effect.
text-horizontal-adjustment	0	integer	Adjusts the text by the specified number of pixels horizontally. Negative values move the text to the left.
text-vertical-adjustment	0	integer	Adjusts the text by the specified number of pixels vertically. Negative values move the text to the top.
text-wrap	true	true, false	Determines wether the text should be wrapped or whether it should be kept on a single line, even when it is larger than the available width.
text-wrap-animate	true	true, false	You can deactivate animations for texts that should not be wrapped and which are too long for a single line.
text-wrap-animation-direction	both	both, left, right	The direction of the animation when the text is too wide and wrapping is deactivated.
text-wrap-animation-speed	1	integer	The speed of the animation when the text is too wide and wrapping is deactivated.
view-type	-	fade-in, fade-out, particle, size-decrease, size-increase	Defines another visualization for an Item or a Screen.
visible	true	true, false	Toggles the visibility of an item. When an item is invisible, it will not occupy any space.
x-adjust	0	integer	The horizontal position adjustment.

The following example shows the use of the TextField attributes:

.itemInput {
	padding: 2;
	background-color: silver;
	border-color: gray;
	textfield-direct-input: true;
	textfield-caret-color: red;
	textfield-show-length: true;
}
.itemInput:hover {
	background-color: white;
	border-color: black;
}

TextField-Commands

A TextField adds the "Clear" and "Delete" commands to the menu by default. The names of these commands can be changed easily. To suppress all commands, specify the polish.TextField.suppressCommands variable in your build.xml script:

<variable name="polish.TextField.suppressCommands" value="true"/>

You can also solely supress the "Delete" command, which you should only do for cases when the device in question has a known hardware clear key for deleting characters:

<variable name="polish.TextField.suppressDeleteCommand" value="true" if="polish.key.ClearKey:defined" />

The "Delete" command is removed in the default configuration when all characters are deleted from the TextField or when the user moves the input caret to the beginning of the TextField. It will then be shown again when input is added or the caret is moved by the user. You can choose to show the command all the time by specifying the polish.TextField.keepDeleteCommand variable:

<variable name="polish.TextField.keepDeleteCommand" value="true" />

When using the direct input mode and in case you allow the input of symbols, you can suppress the "Add Symbol" command as well:

<variable name="polish.TextField.supportSymbolsEntry" value="true"/>
<variable name="polish.TextField.suppressAddSymbolCommand" value="true" if="polish.key.AddSymbolKey:defined" />

Direct Input Mode

The direct input mode can be activated for TextFields as well as for TextBoxes using the CSS attribute textfield-direct-input:

.itemInput {
	padding: 2;
	background-color: silver;
	border-color: gray;
	textfield-direct-input: true;
	textfield-caret-color: red;
	textfield-show-length: true;
	textfield-direct-input: true;
}

Alternatively you can activate the direct input mode globally for all TextFields by defining the preprocessing variable polish.TextField.useDirectInput in your build.xml file:

<variable name="polish.TextField.useDirectInput" value="true"/>

When the direct input mode is used, no extra screen will be used for editing the text and all designing possibilities of J2ME Polish can be used. When the TextField is used within a Form, the associated ItemStateListener will be notified after each change of the text.

On stylus-based and Windows devices you should not use the direct input mode, since these devices often rely on native input methods like handwriting recognition. This can be ensured by setting the preprocessing variable only for devices which have no pointer-events and which are not Windows based:

<variable name="polish.TextField.useDirectInput" value="true" unless="polish.hasPointerEvents or isOS(Windows)"/>

The direct input should not be used for editing longs texts (i.e. TextBoxes), since T9 and similar input helpers cannot be used in this mode. You might want to use the predictive input mode for entering long texts.

When you use the direct input mode, J2ME Polish will map the numeric keys to the characters given in the following table. By pressing the key 2 twice you will get the character b, for example.

You can change the mappings by specifying the preprocessing variables polish.TextField.charactersKey1, polish.TextField.charactersKey2 etc in your build.xml script.

1	2	3
.,!?¿/()@_-+1'\";	abc2àáâãäåæç	def3èéêë
polish.TextField.charactersKey1	polish.TextField.charactersKey2	polish.TextField.charactersKey3
4	5	6
ghi4ąĆćĈ	jkl5	mno6ĊċČčĎď
polish.TextField.charactersKey4	polish.TextField.charactersKey5	polish.TextField.charactersKey6
7	8	9
pqrs7ø	tuv8ĒēĔĕ	wxyz9Ė
polish.TextField.charactersKey7	polish.TextField.charactersKey8	polish.TextField.charactersKey9
*	0	#
.,!?¿/()@_-+1'\";	0	(none)
polish.TextField.charactersKeyStar	polish.TextField.charactersKey0	polish.TextField.charactersKeyPound

The Input Mode Information Indicator

The user can change the input mode from lowercase ("abc"), to initial-letter uppercase ("Abc"), to uppercase ("ABC") and to numeric ("123"). The current input mode is shown below the title in an extra StringItem. This item can be designed using the predefined CSS-style "info":

info {
	padding-right: 10;
	background: none;
	border-color: black;
	font-style: plain; 
	font-face: proportional; 
	font-size: small; 
	font-color: fontColor; /* a color defined in the "colors" section */
	layout: right;
}

You can include the info item in the TextField instead of showing it at the top of the screen by specifying polish.TextField.includeInputInfo in your build.xml script:

<variable name="polish.TextField.includeInputInfo" value="true" />

The info item can be deactivated globally by setting the "polish.TextField.showInputInfo" variable to "false":

<variable name="polish.TextField.showInputInfo" value="false" />

Next to using the CSS-attributes "textfield-caret-color" and "textfield-show-length" you can adjust the behavior of the direct input mode with several preprocessing variables.

Adding Symbols in the TextField

The user can also add special symbols into a TextField, when the polish.TextField.supportSymbolsEntry preprocessing variable is set to true:

<variable name="polish.TextField.supportSymbolsEntry" value="true" />

You can define your own set of symbols by defining the variable polish.TextField.Symbols.

Predictive Input Mode

The predictive input mode can be activated by setting the variable polish.TextField.usePredictiveInput to true.
NOTE: On BlackBerry phones native EditFields are used which provide predictive input.

<variable name="polish.TextField.usePredictiveInput" value="true" />

Installation

To use the predictive input in the application, the dictionary must be installed first. To do this, please select "Install Predictive" from the menu of the application using predictive input:

There are two different installation modes depending on the device using the application:

• The first mode installs the dictionary in a shared record store for all applications to use the same unique dictionary. This mode is available to most of the devices supporting MIDP2 (exceptions are listed in the second mode). The dictionary is contained within a setup that will be downloaded and installed as an j2me application to the user's device. The user just needs to follow the instructions. (NOTE : Some devices will download the application but will not automatically launch the setup. In this case, just start the setup manually)
• The second mode is used for devices that need signing or are just not capable to use a shared record store. These devices include all MIDP1 and Motorola devices. In this case, the dictionary is downloaded directly to the application without a setup and installed in a local record store. Every application using the predictive mode has to install its own dictionary.

Usage

After the installation of the dictionary has finished, the predictive mode can be used. The user just types the numbers equivalent to the letters of the word he would like to see in the textfield. For each typed number the predictive mode will display the matching words. For example, the combination 668437 will return the results "mother" and "videos" to choose from.

To choose one of the possibilities, just press UP and select the desired word by pressing FIRE. The dictionary remembers the most used selected words and resorts the list the next time the results are shown. For example, if you choose "videos" in the example above, the next time you type 668437 "videos" will be the first option.

The user can choose different input modes the enter the words, like "abc", "ABC" ... To indicate the predictive mode a double arrow is heading the input mode in the info box.

To disable and enable the predictive input of a single textfield, the commands "Disable Predicitive Input" and "Enable Predicitive Input" can be used. The user can also add new words to the dictionary by using the "Add Word" command in the menu. The added words will be available in all applications using the predictive input unless the second installation mode was used (see above).

Design

There are predefined styles to design the list of your predictive results in a textfield.

CSS Attribute	Explanation
predictive-containerstyle	Points to a style to design the list of predictive results itself.
predictive-choicestyle	Points to a style to design the entry in a list of predictive results.
predictive-choice-orientation	Sets the orientation of the list of predictive results. Two values are permitted: "top" and "bottom". The default is "bottom" which draw the list in an descending order below the textfield. "top" draws the list in an ascending order above the textfield. This can be useful for textfields that don't provide enough space below them to display the list.

Here's an example how to style a predictive textfield:

.myTextfield {
	font-color: blue;
	font-size: small;
	predictive-containerstyle: myTextFieldContainer;
	predictive-choicestyle:	myTextFieldChoice;
	predictive-choicestyle: top;	
}
	

.myTextFieldContainer {
	border-color: blue;
	border-size: 1;
}
	

.myTextfieldChoice {
	font-color: blue;
	font-size: small;
	font-style: bold;
}
	

Array mode

Rather than using the dictionary the predictive input can be used with a simple array of words. These words are checked if they match the predictive input of the user and the matches are returned with a method call.

To initialize the array mode, the method setPredictiveDictionary(TextField field, String[] words) of UIAccess must be called. The method takes two arguments : the array of String objects and the textfield that should be used to provide the input to filter strings. A call with null as the array resets the source for the given textfield to the RMS dictionary.

TextField myField = new TextField("city: ","",100,TextField.ANY);

String[] cities = new String[] {
 "Amsterdam",
 "Bombay",
 "Bremen",
 "London",
 "Paris",
 "New York"
 };

UIAccess.setPredictiveDictionary(myField,cities);

If the user enters a sequence of numbers (similar to the normal dictionary mode) the predictive input mode internally filters out the strings that don't match. To obtain the results the method getResults() of the UiAccess must be called which returns an ArrayList of strings.

ArrayList results = UiAccess.getPredictiveMatchingWords(mytextfield);

The method to obtain the results is usually called in the itemStateChanged() callback of the interface ItemStateListener so that everytime the user enters a number the results are obtained and processed. The source set of strings for the array mode can be changed everytime by calling UiAccess.setPredictiveDictionary(TextField field, String[] words).

Programming

You can use UiAccess for accessing J2ME Polish specific functionalities of the TextField:

• UiAccess.setCaretPosition( TextField field, int position ): Sets the position of the input caret.
• UiAccess.setInputMode( javax.microedition.lcdui.TextField field, int inputMode ): Sets the input mode to either UiAccess.MODE_NUMBERS, UiAccess.MODE_LOWERCASE, UiAccess.MODE_UPPERCASE, UiAccess.MODE_FIRST_UPPERCASE, or UiAccess.MODE_NATIVE.
• int UiAccess.getInputMode( TextField field ): Gets the current input mode.
• String UiAccess.getDotSeparatedDecimalString( TextField field ): Retrieves the contents of a DECIMAL TextField as a number with floating numbers separated by a dot, no matter what locale is being used.
• UiAccess.setPredictiveDictionary(TextField field, String[] words): Allows the user only to enter any of the given words - can only be used when the predictive mode has been anabled.
• UiAccess.setTextfieldHelp(TextField field, String text): Sets the helper text that is being shown when the text of a TextField is empty - can only be used when polish.TextField.showHelp is true.
• UiAccess.setTextfieldInfo(TextField field, String info): Sets the strings that should be displayed to guide the user what to do with the textfield (like "type text here"). A value of null shows no info in the field.
• UiAccess.setSuppressCommands(TextField field, boolean suppress): Suppresses the textfields standard and predictive commands like Clear, Add Word etc.
• UiAccess.setWordNotFound(TextField field, Alert alert): Sets an custom alert to show the "Word not found" message of the predictive input.

Configuration

As explained in the above sections, following configurations can be done within the <variables> variables section of your build.xml script:

Variable	Default	Explanation
polish.command.clear	Clear	Command text for deleting the complete text.
polish.command.clear.priority	8	Priority of the clear command.
polish.command.delete	Delete	Command text for deleting a single character.
polish.command.delete.priority	1	Priority of the delete command.
polish.command.entersymbol	Add Symbol	Command text for adding symbols, only applicable when polish.TextField.supportSymbolsEntry is true.
polish.command.entersymbol.priority	9	Priority of the command for adding symbols.
polish.key.AddSymbolKey, polish.key.AddSymbolKey2	Device dependent	Device key that triggers the symbols entry screen when pressed longer.
polish.key.backspace	Device dependent	Alternativ key for deleting a character.
polish.key.ChangeInputModeKey	Device dependent	The key which is used for changing the input mode between lowercase ("abc"), uppercase ("ABC"), initial-letter uppercase ("Abc") and numeric ("123"). On Sony-Ericsson devices Canvas.KEY_STAR (42), on Motorola devices Canvas.KEY_NUM0 (48) and on all other devices Canvas.KEY_POUND (35) is used.
polish.key.ChangeNumericalAlphaInputModeKey	Device dependent	Device key for switching between numerical and alphabet input, usually only used on Motorola handsets.
polish.key.ClearKey	Device dependent	Device key for deleting a character, it is often -8.
polish.key.enter	Device dependent	Device key for entering new lines.
polish.key.shift	Device dependent	Device key for entering upper case character.
polish.key.supportsAsciiKeyMap	Device dependent	If true the user can use a keyboard for entering characters.
polish.TextField.allowNativeModeSwitch	false	Allows to switch back to the native mode when the polish.TextField.useDirectInput is being used.
polish.TextField.charactersKey1	.,!?¿/()@_-+1'\";	The characters which are available when the key "1" is pressed.
polish.TextField.charactersKey2	abc2àáâãäåæç	The characters which are available when the key "2" is pressed. It might be useful to add local specific umlauts here.
polish.TextField.charactersKey3	def3èéêë	The characters which are available when the key "3" is pressed.
polish.TextField.charactersKey4	ghi4ąĆćĈ	The characters which are available when the key "4" is pressed.
polish.TextField.charactersKey5	jkl5	The characters which are available when the key "5" is pressed.
polish.TextField.charactersKey6	mno6ĊċČčĎď	The characters which are available when the key "6" is pressed.
polish.TextField.charactersKey7	pqrs7ø	The characters which are available when the key "7" is pressed.
polish.TextField.charactersKey8	tuv8ĒēĔĕ	The characters which are available when the key "8" is pressed.
polish.TextField.charactersKey9	wxyz9Ė	The characters which are available when the key "9" is pressed.
polish.TextField.charactersKey0	0	The characters which are available when the key "0" is pressed. On Motorola devices this key is used for switching the input mode.
polish.TextField.charactersKeyStar	.,!?¿/()@_-+1'\";	The characters which are available when the key "*" is pressed. On Motorola devices this key is used for entering spaces (" ").
polish.TextField.charactersKeyPound	(none)	The characters which are available when the key "#" is pressed. On Sony-Ericsson devices this key is used for entering spaces (" ").
polish.TextField.help	type text here	Text that is being shown when the TextField is empty - the polish.TextField.showHelpText variable needs to be set as well.
polish.TextField.includeInputInfo	false	Includes the input mode indicator into the TextField instead of showing it at the top of the screen, only applicable when the polish.TextField.useDirectInput is active.
polish.TextField.InputTimeout	"1000"	The timeout in milliseconds after which a chosen character is inserted into the text automatically.
polish.TextField.showInputInfo	"true"	Defines whether the box showing the current input mode (e.g. "123", "Abc", "abc", "ABC") should be shown at all. You can deactivate the box globally by setting the "polish.TextField.showInputInfo" variable to "false".
polish.TextField.suppressAddSymbolCommand	false	Surpresses the command for adding symbols when polish.TextField.supportSymbolsEntry is true.
polish.TextField.suppressAutoInputModeChange	false	If true the TextField will not change the input mode automatically, e.g. after the user enters a dot (in that case the TextField switches into the 'Abc' mode by default.
polish.TextField.suppressCommands	false	Deactivates all TextField commands.
polish.TextField.suppressDeleteCommand	false	Deactivates the "Delete" command of a TextField.
polish.TextField.supportSymbolsEntry	false	Allows users to enter special symbols from within a TextField, only applicable when the direct input mode is activated using polish.TextField.useDirectInput.
polish.TextField.Symbols	&@/\<>(){}[].,+-*:_\#$%	A string with of symbols that the user can select when symbol entry has been activated using polish.TextField.supportSymbolsEntry.
polish.TextField.showHelpText	false	Displays a text for empty TextFields - defaults to "type text here".
polish.TextField.useDirectInput	false	Activates the direct input mode.
polish.TextField.usePredictiveInput	false	Enables the predictive input mode, the polish.TextField.useDirectInput mode needs to be active, too.
polish.TextField.keepCaretPosition	false	Keeps the caret position when a TextField is focused - by default the cursor jumps to the end of the text.
polish.TextField.jumpToStartOnFocus	false	Jumps to the beginning of the text when a TextField is focused - by default the cursor jumps to the end of the text.

JavaDoc

• TextField
• UiAccess