J2ME Polish
J2ME Polish 2.4 Documentation
Enough Software

TextField

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.
A textfield in action

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:

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.

123
.,!?¿/()@_-+1'\"; abc2àáâãäåæç def3èéêë
polish.TextField.charactersKey1 polish.TextField.charactersKey2 polish.TextField.charactersKey3
456
ghi4ąĆćĈ jkl5 mno6ĊċČčĎď
polish.TextField.charactersKey4 polish.TextField.charactersKey5 polish.TextField.charactersKey6
789
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;
}

Embedded Input Indicator

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" />

For aligning the input indicator to the right side of the textfield, just specify a 'right' layout within the "info" style.

External Input Indicator

Some requirements need to display the current input info in another place. For these cases you can call TextField.setInfoItem(StringItem) or UiAccess.setTextfieldInfoItem(TextField, StringItem):

//#style externalInputIndicator
StringItem external = new StringItem( null, null );
UiAccess.setTextfieldInfoItem( textField, external);

You simply create a StringItem, add it to your screen layout and call the method with the given StringItem. To use the method the following variable has to be set to true:

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

Note: On BlackBerry platforms this feature is not available.

Deactivate Input Indicator

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

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

Help text

To display a text to an empty TextField to indicate the required input (e.g. "Enter username here ...") you can use TextField.setHelpText(String) or UiAccess.setTextfieldHelp(TextField, String):

UiAccess.setTextfieldHelp( textField,  Locale.get("input.help.userName" ) );

To use the method the following variable has to be set:

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

To style the help text you can set the style .help which will apply to help texts in all TextField instances:

.help { 
	font-color: grey; 
	font-size: normal; 
} 

Alternatively you can call TextField.setHelpStyle(Style) for specifying a custom style.

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.

Fixed Point Decimal Constraint

J2ME Polish textfields with activated direct input mode can make use of a cash register like input constraint. With that constraint the result will always be a decimal number with a fixed number of digital places behind the point. Entering a "1" results in "0.01", "123" in "1.23", and so on. You can create such a TextField with the help of de.enough.polish.ui.UiAccess:

TextField field = new TextField("Price: ", null, 6, UiAccess.CONSTRAINT_FIXED_POINT_DECIMAL );
// allow 3 decimal places (2 is the default):
UiAccess.setNumberOfDecimalFractions(field, 3);

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

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

Virtual keyboard

To ease the input of text to TextField on touch device the virtual keyboard can be used. This is basically an on-screen keyboard which can be styled and suited to the developers needs. To activate the keyboard simply add the following variable to the variables section of your projects build.xml:

polish.TextField.useVirtualKeyboard

When you know select a TextField it will create and display a simple virtual keyboard with default key layouts. The layouts displayed are chosen by the type of a text field. Currently these types are supported:

TextField.ANY
TextField.NUMERIC
TextField.PHONENUMBER

For each of these modes, the suitable default layouts are selected and displayed.

Layouts

While the default layouts should be sufficient for most tasks when writing an english-based application, you might want to create your own layouts to support i.e. other languages.

Here's a simple example of how the default layout of the type TextField.NUMBER is created:

0,0=1
0,1=2
0,2=3
1,0=4
1,1=5
1,2=6
2,0=7
2,2=8
2,2=9
3,0=[]
3,1=0
3,2=[]

The layouts are written in the syntax of a Java .properties file. Each line represents a key. The first part (e.g. 0,0) defines the position of the key inside the layout. The second part defines the value. The value can be any UTF8 character.

Special Keys

At the position 3,2 in the above example there is one of the placeholders to use special keys in your layouts. Here's an overview of the placeholders you can use:

PlaceholderDescription
[SPACE] inserts a space bar to your layout.
[SHIFT] inserts a shift key to your layout.
[MODE] inserts a mode key to your layout. This is used e.g. for the TextField.ANY type where two layouts are present and the user needs to switch between these two
[DELETE] inserts a delete key to your layout which will remove the last character of the written text
[CLEAR] inserts a clear key to your layout which will clear the written text
[] inserts a blank to your layout

Using your own layouts

To use your own layouts you need to overwrite the default mappings for the TextField types you wish to use with another layout. There are 3 variables that can be set to a path of a layout .properties file within your JAR file.

NameDescription
virtualKeyboard.KeyMap.Any.Alpha the URL of a .properties file that describes the layout of the alphabetic (abcdef) section of the TextField.ANY type
virtualKeyboard.KeyMap.Any.Numeric the layout of the numeric (0123.,()) section of the TextField.ANY type
virtualKeyboard.KeyMap.Numeric the layout for the TextField.NUMERIC type
virtualKeyboard.KeyMap.Phonenumber the layout for the TextField.PHONENUMBER type

Styling

To style your keyboard there are several styles that can be overwritten:

StyleDescription
keyDimension serves as the base style for general key styles. It defines the minimum width of a key which defaults to 15% of the screen
keySpaceDimension serves as the base style for the space key style. It defines the minimum width of the space key which defaults to 45% of the screen
key serves as the style for all standard style.
key serves as the style for all standard style.
keySpace
keyShift
keyClear
keyDelete
keyMode
keyBlank
the styles for the spcial keys
keyRow the style for a row of keys inside a keyboard layout. Defaults to a horizontal list which should be inherited
keyboard the overall style of the keyboard
keyboardView the style of the screen which hold the keyboard, the text display and the submit button
keyboardViewHeader the style of the header of the keyboard view which holds the text display and the submit button. Defaults to a 2-column layout which should be inherited
keyboardViewDisplay the style of the text display of the keyboard view
keyboardViewSubmit the style of the submit button of the keyboard view

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.
  • UiAccess.CONSTRAINT_FIXED_POINT_DECIMAL: constant for applying a fixed point decimal constraint on TextFields with direct input mode.
  • UiAccess.setNumberOfDecimalFractions( TextField field, int number ): for allowing a different number than 2 decimal places for fixed point decimal fields.
  • int UiAccess.getNumberOfDecimalFractions( TextField field ): for retrieving the number of decimal places of fixed point decimal field.

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.clear.type Command.ITEM Type 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.delete.type Command.CANCEL | Command.ITEM Type of the delete command. On devices with a return/back key or when the device supports pointer events and you use popup screens this is Command.ITEM, otherwise its Command.CANCEL.
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

back to top