TextField类说明文档

TextField 是可能够放入 Form 中的可编辑的文本框组件。它可以通过一段文本初始化。

 

TextField 包含一个最大大小，该大小就是任何时候可以保存在其中的字符量（即容量）。当 TextField 实例构建时，当用户在 TextField 中编辑文本时，以及当应用程序调用 TextFiled 方法修改其内容时，大小都会受到限制。最大大小是最大的可存储大小并且和任何时候显示的字符数量大小无关。显示的字符数量和它们如果按行列安排是由设备决定的。

 

系统会为最大大小设定界限，实际设置的最大大小会比应用程序请求的要小。实际设置的值将由 getMaxSize() 反映出来。一个健全的应用程序应当把这个值和请求的最大大小值相比较并在它们不相等时进行处理。

 

输入限制

 

TextField 和 TextBox 共享输入限制的概念。不同的限制允许应用程序要求用户输入的限制不同。系统来执行应用程序请求的用户输入限制。比如，如果应用程序请求在 TextField 上设置 NUMERIC 的限制，系统必须只允许输入数字。

 

实际的文本对象的内容由应用程序设置和修改，并通过 TextBos 和 TextField 的 API 反馈给应用程序。显示的内容有可能和实际的内容有差别，如果系统选择用适合文本对象的特殊格式。比如，一个 PHONENUMBER 域根据电话号码的书写习惯，把国家号，区域号，前缀分组，通过混合显示分隔符和数字的方式显示。任何显示出来的空格或是分隔符不被认为是文本对象的实际内容。比如，一个 PHONENUMBER 限制的文本对象可能按如下方式显示：

（ 408 ） 555-1212

但是实际的通过 API 的应用程序可见的内容是字符串 ”4085551212” 。 Size 方法反映的是实际内容里的字符数量，不是被显示出来的字符数量，所以在这里 szie 方法将反回 10 。

 

一些限制，比如 DECIMAL ，需要系统对文本对象的内容执行语法有效性检查。语法检查将对实际内容执行，就像上面指出的和显示的内容会有所不同。语法检查还会对传递给构造函数的初始值起作用，同样对所有改变文本对象内容的方法起作用。方法和构造器抛出 IllegalArgumentException 如果它们造成文本框的内容不符合语法要求。

 

传递给 setConstraints() 的值由上面提到的限制集合组成，同样由不同的标志位来修正文本输入和显示行为。限制集的值是一个值的低 16 位，并且可以通过按位析取操作符（ & ）同一个 CONSTRAINT_MASK 常量组合。限制集合如下：

ANY

EMAILADDR

NUMERIC

PHONENUMBERURL

DECIMAL

修正标志排列在限制值的高 16 位上，就是说，那些在 CONSTRAINT_MASK 常量中的补充值。修正符可以通过把限制值和一个修正标志与（ & ）操作单独测试。修正标志如下：

PASSWORD

UNEDITABLE

SENSITIVE

NON_PREDICTIVE

INITIAL_CAPS_WORD

INITIAL_CAPS_SENTENCE

 

输入模式

 

TextField和TextBox共同拥有输入模式的概念。应用程序可以要求系统在用户编辑TextField或是TextBox 时执行特定的输入模式。输入模式是存在于特定设备上的文本输入的概念。应用程序不是直接请求一个输入模式，因为文本输入的用户界面在不同的设备上并不相同。取而代之，应用程序可以方便的请求特定的字符输入。这可以通过向setInitialInputMode()传递一个Unicode字符字集的名字来实现。对这个方法的调用会要求系统为下一个输入设置输入模式以方便用户输入那个字符子集中的字符。应用程序还可以通过设置限制值中的修正标志来要求输入模式包含特定的行为字符。

 

请求的输入模式应该在TextBox或是TextField对象被编辑的时候使用。如果用户在前一个交互过程中改变了输入模式，应用程序请求的用户模式将替代前一个用户设置的输入模式。然而，输入模式不是被限制的，用户可以在编辑的任何时候改变输入模式。如果编辑正在被处理，对setInitialInputMode的调用将不会影响当前的输入模式，但是将在下次用户编辑文本对象的时候起作用。

 

初始的输入模式是用系统内定的。如果系统不能提供一个合适的用户请求的模式，将使用默认的输入模式。

 

应用程序请求的用户输入模式并不是对用户可输入的字符的一种限制。用户必须被允许切换输入模式来输入符合输入限制的任何字符。输入限制比输入模式的优先级要高，而且系统可以拒绝提供一个特定的输入模式如果它合当前的输入限制不符。

 

比如，如果当前的输入限制是ANY，调用

setInitialInputMode(“MIDP_UPPERCASE_LATIN”);

将把输入模式设置成允许输入大定拉丁字符。这里不会限制这种输入，并且用户可以输入数字或是小写拉丁字母。但是，如果当前的限制是NUMERIC，系统就会忽略允许大写拉丁字符输入的请求，因为这些字符在NUMERIC限制下是不被允许输入的。这时，系统会用数字输入模式来代替，因为这样一个输入模式在NUMERIC限制下总是适用的。

 

一个字符串用来命名传递给setInitialInputMode()方法参数的Unicode字符子集。字符串是大小写相关的。

 

Unicode字符块通过向J2SE中java.lang.Character.UnicodeBlock类定义的表示Unicode字符块的字符串添加前缀”UCB_”来表示。所有Unicode字符块可以用这种方式命名。为了方便，把最常用的Unicode字符块列在下面：

UCB_BASIC_LATIN
UCB_GREEK
UCB_CYRILLIC
UCB_ARMENIAN
UCB_HEBREW
UCB_ARABIC
UCB_DEVANAGARI
UCB_BENGALI
UCB_THAI
UCB_HIRAGANA
UCB_KATAKANA
UCB_HANGUL_SYLLABLES

输符子集可以通过向J2SE中java.awt.im.InputSubset类定义的字符串添加”IS_”来定义。所有定义过的子集都可以使用。为了 方便，把最常用的Unicode字符块列在下面：

IS_FULLWIDTH_DIGITS
IS_FULLWIDTH_LATIN
IS_HALFWIDTH_KATAKANA
IS_HANJA
IS_KANJI
IS_LATIN
IS_LATIN_DIGITS
IS_SIMPLIFIED_HANZI
IS_TRADITIONAL_HANZI

MIDP也定义了下列的字符子集

MIDP_UPPERCASE_LATIN -IS_LATIN中符合大写拉丁字符的子集

MIDP_LOWERCASE_LATIN –IS_LATIN中符合小写拉丁字符的子集

最后，系统特定的字符子集可以通过向字符串添加”X_”的方法定义。为了必免名字空间冲突，建议系统特定名字在”X_”后包含定义者的公司或是组织名称。

 

比如，一个日语应用程序可能特定的TextField，应用程序在这里主要用来输入日语中的外来字。应用程序可以通过下面的方法请求一个容易使用的平假名输入：

textfield.setInitialInputMode(“UCB_HIRAGANA”);

 

系统提示

 

系统不需要编译上面显示的所有字符串。它们只需要编译它们能够支持的Unicode字符子集的字符串。如果应用程序传递的子集名称和已知的子集名称不同，请求只是简单的被忽略而不产生错误，而且默认输入模式会被使用。这使得系统很便宜的支持这种特性。然而，这会造成应用程序不能确定它的请求是否被接受，也不能确定它请求的Unicode字符是否是一个有效的子集。

 

public class TextField extends Item

A TextField is an editable text component that may be placed into a Form. It can be given a piece of text that is used as the initial value.

A TextField has a maximum size, which is the maximum number of characters that can be stored in the object at any time (its capacity). This limit is enforced when the TextField instance is constructed, when the user is editing text within the TextField, as well as when the application program calls methods on the TextField that modify its contents. The maximum size is the maximum stored capacity and is unrelated to the number of characters that may be displayed at any given time. The number of characters displayed and their arrangement into rows and columns are determined by the device.

The implementation may place a boundary on the maximum size, and the maximum size actually assigned may be smaller than the application had requested. The value actually assigned will be reflected in the value returned by getMaxSize(). A defensively-written application should compare this value to the maximum size requested and be prepared to handle cases where they differ.

Input Constraints

The TextField shares the concept of input constraints with the TextBox class. The different constraints allow the application to request that the user's input be restricted in a variety of ways. The implementation is required to restrict the user's input as requested by the application. For example, if the application requests the NUMERIC constraint on a TextField, the implementation must allow only numeric characters to be entered.

The actual contents of the text object are set and modified by and are reported to the application through the TextBox and TextField APIs. The displayed contents may differ from the actual contents if the implementation has chosen to provide special formatting suitable for the text object's constraint setting. For example, a PHONENUMBER field might be displayed with digit separators and punctuation as appropriate for the phone number conventions in use, grouping the digits into country code, area code, prefix, etc. Any spaces or punctuation provided are not considered part of the text object's actual contents. For example, a text object with the PHONENUMBER constraint might display as follows:

     (408) 555-1212    

but the actual contents of the object visible to the application through the APIs would be the string "4085551212". The size method reflects the number of characters in the actual contents, not the number of characters that are displayed, so for this example the size method would return 10.

Some constraints, such as DECIMAL, require the implementation to perform syntactic validation of the contents of the text object. The syntax checking is performed on the actual contents of the text object, which may differ from the displayed contents as described above. Syntax checking is performed on the initial contents passed to the constructors, and it is also enforced for all method calls that affect the contents of the text object. The methods and constructors throw IllegalArgumentException if they would result in the contents of the text object not conforming to the required syntax.

The value passed to the setConstraints() method consists of a restrictive constraint setting described above, as well as a variety of flag bits that modify the behavior of text entry and display. The value of the restrictive constraint setting is in the low order 16 bits of the value, and it may be extracted by combining the constraint value with the CONSTRAINT_MASK constant using the bit-wise AND (&) operator. The restrictive constraint settings are as follows:

ANY
EMAILADDR
NUMERIC
PHONENUMBER
URL
DECIMAL


The modifier flags reside in the high order 16 bits of the constraint value, that is, those in the complement of the CONSTRAINT_MASK constant. The modifier flags may be tested individually by combining the constraint value with a modifier flag using the bit-wise AND (&) operator. The modifier flags are as follows:

PASSWORD
UNEDITABLE
SENSITIVE
NON_PREDICTIVE
INITIAL_CAPS_WORD
INITIAL_CAPS_SENTENCE


Input Modes

The TextField shares the concept of input modes with the TextBox class. The application can request that the implementation use a particular input mode when the user initiates editing of a TextField or TextBox. The input mode is a concept that exists within the user interface for text entry on a particular device. The application does not request an input mode directly, since the user interface for text entry is not standardized across devices. Instead, the application can request that the entry of certain characters be made convenient. It can do this by passing the name of a Unicode character subset to the setInitialInputMode() method. Calling this method requests that the implementation set the mode of the text entry user interface so that it is convenient for the user to enter characters in this subset. The application can also request that the input mode have certain behavioral characteristics by setting modifier flags in the constraints value.

The requested input mode should be used whenever the user initiates the editing of a TextBox or TextField object. If the user had changed input modes in a previous editing session, the application's requested input mode should take precedence over the previous input mode set by the user. However, the input mode is not restrictive, and the user is allowed to change the input mode at any time during editing. If editing is already in progress, calls to the setInitialInputMode method do not affect the current input mode, but instead take effect at the next time the user initiates editing of this text object.

The initial input mode is a hint to the implementation. If the implementation cannot provide an input mode that satisfies the application's request, it should use a default input mode.

The input mode that results from the application's request is not a restriction on the set of characters the user is allowed to enter. The user MUST be allowed to switch input modes to enter any character that is allowed within the current constraint setting. The constraint setting takes precedence over an input mode request, and the implementation may refuse to supply a particular input mode if it is inconsistent with the current constraint setting.

For example, if the current constraint is ANY, the call

    setInitialInputMode("MIDP_UPPERCASE_LATIN");    

should set the initial input mode to allow entry of uppercase Latin characters. This does not restrict input to these characters, and the user will be able to enter other characters by switching the input mode to allow entry of numerals or lowercase Latin letters. However, if the current constraint is NUMERIC, the implementation may ignore the request to set an initial input mode allowing MIDP_UPPERCASE_LATIN characters because these characters are not allowed in a TextField whose constraint is NUMERIC. In this case, the implementation may instead use an input mode that allows entry of numerals, since such an input mode is most appropriate for entry of data under the NUMERIC constraint.

A string is used to name the Unicode character subset passed as a parameter to the setInitialInputMode() method. String comparison is case sensitive.

Unicode character blocks can be named by adding the prefix "UCB_" to the the string names of fields representing Unicode character blocks as defined in the J2SE class java.lang.Character.UnicodeBlock. Any Unicode character block may be named in this fashion. For convenience, the most common Unicode character blocks are listed below.

UCB_BASIC_LATIN
UCB_GREEK
UCB_CYRILLIC
UCB_ARMENIAN
UCB_HEBREW
UCB_ARABIC
UCB_DEVANAGARI
UCB_BENGALI
UCB_THAI
UCB_HIRAGANA
UCB_KATAKANA
UCB_HANGUL_SYLLABLES


"Input subsets" as defined by the J2SE class java.awt.im.InputSubset may be named by adding the prefix "IS_" to the string names of fields representing input subsets as defined in that class. Any defined input subset may be used. For convenience, the names of the currently defined input subsets are listed below.

IS_FULLWIDTH_DIGITS
IS_FULLWIDTH_LATIN
IS_HALFWIDTH_KATAKANA
IS_HANJA
IS_KANJI
IS_LATIN
IS_LATIN_DIGITS
IS_SIMPLIFIED_HANZI
IS_TRADITIONAL_HANZI


MIDP has also defined the following character subsets:

MIDP_UPPERCASE_LATIN - the subset of IS_LATIN that corresponds to uppercase Latin letters

MIDP_LOWERCASE_LATIN - the subset of IS_LATIN that corresponds to lowercase Latin letters

Finally, implementation-specific character subsets may be named with strings that have a prefix of "X_". In order to avoid namespace conflicts, it is recommended that implementation-specific names include the name of the defining company or organization after the initial "X_" prefix.

For example, a Japanese language application might have a particular TextField that the application intends to be used primarily for input of words that are "loaned" from languages other than Japanese. The application might request an input mode facilitating Hiragana input by issuing the following method call:

    textfield.setInitialInputMode("UCB_HIRAGANA");       

Implementation Note

Implementations need not compile in all the strings listed above. Instead, they need only to compile in the strings that name Unicode character subsets that they support. If the subset name passed by the application does not match a known subset name, the request should simply be ignored without error, and a default input mode should be used. This lets implementations support this feature reasonably inexpensively. However, it has the consequence that the application cannot tell whether its request has been accepted, nor whether the Unicode character subset it has requested is actually a valid subset.

 

 

Since: MIDP 1.0                                               翻译：lori.wang