net.rim.device.api.ui.text
Class TextFilter

java.lang.Object
  extended by net.rim.device.api.ui.text.TextFilter
Direct Known Subclasses:
EmailAddressTextFilter, FilenameTextFilter, HexadecimalTextFilter, IPTextFilter, LowercaseTextFilter, NumericTextFilter, PhoneTextFilter, URLTextFilter, UppercaseTextFilter

public abstract class TextFilter
extends Object

Defines fundamental functionality for a text filtering object. Objects are cached upon creation.

A filter has two functions: first, it can validate whether a character or string is valid, and second it can map characters onto ones more likely to be valid.


Field Summary
static int ADN_SIM_PHONE
          ADN stands for Abbreviated Dialing Number, the standard SIM phone book.
static int DEFAULT
          Default filter type.
static int DEFAULT_SMART_PHONE
          Default smart phone number edit field filter.
static int EMAIL
          Email address filter.
static int FDN_SIM_PHONE
          FDN stands for Fixed Dialing Number, the secure SIM phone book.
static int FILENAME
          Filename filter that accepts alphanumeric characters without special chars or accents.
static int HEXADECIMAL
          Hex character set filter.
static int INTEGER
          Numeric filter that also allows for a minus sign.
static int IP
          IP Address filters out characters not used in IP\Port text strings
static int LOWERCASE
          Lowercase alpha character filter
static int NUMERIC
          Common numeric filter.
static int PHONE
          A generous phone number filter
static int PIN_ADDRESS
          PIN address filter type.
static int REAL_NUMERIC
          Numeric filter that also allows for a minus sign and decimal point.
static int SIM_PHONE
          Same as ADN_SIM_PHONE.
static int SMS_PHONE
          SMS (Short Message Service) phone number filter
static byte STYLE_SHIFT
          Defines where filters get placed in the style parameter of EidtField.
static int UPPERCASE
          Uppercase alpha character filter
static int URL
          URL (Universal Resource Locator) filter.
static int VOICEMAIL_PHONE
          Default voicemail and call forwarding phone number edit field filter.
 
Constructor Summary
protected TextFilter()
          Constructs a new TextFilter instance.
 
Method Summary
abstract  char convert(char character, int status)
          Retrieves filtered version of provided character.
 char convert(char character, AbstractString text, int position, int status)
          Retrieves filtered version of provided character.
static TextFilter get(int type)
          Retrieve a filter of provided type.
abstract  boolean validate(char character)
          Validates character for use with this filter.
 boolean validate(char character, AbstractString text, int position)
          Validates character for use with this filter.
 boolean validate(AbstractString text)
          Determines if provided string contains valid characters.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

DEFAULT

public static final int DEFAULT
Default filter type. Null returned

See Also:
Constant Field Values

NUMERIC

public static final int NUMERIC
Common numeric filter.

See Also:
NumericTextFilter.NumericTextFilter(), Constant Field Values

UPPERCASE

public static final int UPPERCASE
Uppercase alpha character filter

See Also:
UppercaseTextFilter.UppercaseTextFilter(), Constant Field Values

LOWERCASE

public static final int LOWERCASE
Lowercase alpha character filter

See Also:
LowercaseTextFilter.LowercaseTextFilter(), Constant Field Values

HEXADECIMAL

public static final int HEXADECIMAL
Hex character set filter.

See Also:
HexadecimalTextFilter.HexadecimalTextFilter(), Constant Field Values

INTEGER

public static final int INTEGER
Numeric filter that also allows for a minus sign.

See Also:
NumericTextFilter.NumericTextFilter(), NumericTextFilter.ALLOW_NEGATIVE, Constant Field Values

PHONE

public static final int PHONE
A generous phone number filter

See Also:
PhoneTextFilter.PhoneTextFilter(), PhoneTextFilter.ACCEPT_EVERYTHING_EXCEPT_WILD_CARD, Constant Field Values

URL

public static final int URL
URL (Universal Resource Locator) filter.

See Also:
URLTextFilter.URLTextFilter(), Constant Field Values

EMAIL

public static final int EMAIL
Email address filter.

See Also:
EmailAddressTextFilter.EmailAddressTextFilter(), Constant Field Values

PIN_ADDRESS

public static final int PIN_ADDRESS
PIN address filter type.

See Also:
PINAddressTextFilter#PINAddressTextFilter(), Constant Field Values
Since:
BlackBerry API 4.0.0

ADN_SIM_PHONE

public static final int ADN_SIM_PHONE
ADN stands for Abbreviated Dialing Number, the standard SIM phone book.

See Also:
PhoneTextFilter.PhoneTextFilter(int), PhoneTextFilter.ACCEPT_PAUSE, PhoneTextFilter.ACCEPT_CONTROL, PhoneTextFilter.ACCEPT_INTERNATIONAL, Constant Field Values
Since:
BlackBerry API 4.0.0

SIM_PHONE

public static final int SIM_PHONE
Same as ADN_SIM_PHONE. This is kept for backwards compatibility

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.2

FDN_SIM_PHONE

public static final int FDN_SIM_PHONE
FDN stands for Fixed Dialing Number, the secure SIM phone book.

See Also:
PhoneTextFilter.PhoneTextFilter(int), PhoneTextFilter.ACCEPT_PAUSE, PhoneTextFilter.ACCEPT_CONTROL, PhoneTextFilter.ACCEPT_WILD_CARD, PhoneTextFilter.ACCEPT_INTERNATIONAL, Constant Field Values
Since:
BlackBerry API 4.0.2

SMS_PHONE

public static final int SMS_PHONE
SMS (Short Message Service) phone number filter

See Also:
PhoneTextFilter.PhoneTextFilter(int), PhoneTextFilter.ACCEPT_INTERNATIONAL, Constant Field Values
Since:
BlackBerry API 4.0.2

DEFAULT_SMART_PHONE

public static final int DEFAULT_SMART_PHONE
Default smart phone number edit field filter.

See Also:
PhoneTextFilter.PhoneTextFilter(int), PhoneTextFilter.ACCEPT_CONTROL, PhoneTextFilter.ACCEPT_CONTROL, PhoneTextFilter.ACCEPT_ALPHA, PhoneTextFilter.ACCEPT_FORMATTING, PhoneTextFilter.ACCEPT_INTERNATIONAL, Constant Field Values
Since:
BlackBerry API 4.0.2

VOICEMAIL_PHONE

public static final int VOICEMAIL_PHONE
Default voicemail and call forwarding phone number edit field filter.

See Also:
PhoneTextFilter.PhoneTextFilter(int), PhoneTextFilter.ACCEPT_CONTROL, PhoneTextFilter.ACCEPT_INTERNATIONAL, Constant Field Values
Since:
BlackBerry API 4.0.2

REAL_NUMERIC

public static final int REAL_NUMERIC
Numeric filter that also allows for a minus sign and decimal point.

See Also:
NumericTextFilter.NumericTextFilter(int), NumericTextFilter.ALLOW_DECIMAL, NumericTextFilter.ALLOW_NEGATIVE, Constant Field Values
Since:
BlackBerry API 4.0.2

FILENAME

public static final int FILENAME
Filename filter that accepts alphanumeric characters without special chars or accents.

See Also:
FilenameTextFilter, Constant Field Values
Since:
BlackBerry API 4.2.0

IP

public static final int IP
IP Address filters out characters not used in IP\Port text strings

See Also:
IPTextFilter, Constant Field Values
Since:
BlackBerry API 4.2.1

STYLE_SHIFT

public static final byte STYLE_SHIFT
Defines where filters get placed in the style parameter of EidtField.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0


Constructor Detail

TextFilter

protected TextFilter()
Constructs a new TextFilter instance.



Method Detail

convert

public abstract char convert(char character,
                             int status)
Retrieves filtered version of provided character.

This method may not return a character valid for this filter; however, it may return 0 to indicate that the provided character is not valid.

For example, an UppercaseTextFilter would convert any lower case character to its upper case equivalent. However, if passed a number it could either leave the number unchanged to be filtered by TextFilter.validate(char), or convert it to \u0000.

Parameters:
character - Character to convert.
status - Indicates how the character was generated: some filters use this to affect the conversion performed; * this will be a bitwise-or combination of the STATUS_ constants defined in KeypadListener.
Returns:
Filtered version of provided character.

convert

public char convert(char character,
                    AbstractString text,
                    int position,
                    int status)
Retrieves filtered version of provided character.

This method may not return a character valid for this filter; however, it may return 0 to indicate that the provided character is not valid.

For example, an UppercaseTextFilter would convert any lower case character to its upper case equivalent. However, if passed a number it could either leave the number unchanged to be filtered by TextFilter.validate(char), or convert it to \u0000.

This method is overridden in NumericTextFilter for more precise validation.

Parameters:
character - Character to convert.
text - Text in the current edit field.
position - Current position of cursor in text.
status - Indicates how the character was generated: some filters use this to affect the conversion performed; * this will be a bitwise-or combination of the STATUS_ constants defined in KeypadListener.
Returns:
Filtered version of provided character.
Since:
BlackBerry API 4.2.0

get

public static final TextFilter get(int type)
Retrieve a filter of provided type.

Factory method that produces a text filter of your specified type.

Parameters:
type - Type of filter you want.
Returns:
Text filter object of your specified type, or null if you specify either TextFilter.DEFAULT for type, or an invalid type.

validate

public abstract boolean validate(char character)
Validates character for use with this filter.

This only considers if it is in the correct set of characters.

Parameters:
character - Character to test.
Returns:
True if this character would pass through this filter unaltered; otherwise, false.

validate

public boolean validate(char character,
                        AbstractString text,
                        int position)
Validates character for use with this filter.

By default this only considers if it is in the correct set of characters. It is overwritten in NumericTextFilter for more precise validation.

Parameters:
character - Character to test.
text - Text in the current edit field.
position - Current position of cursor in text.
Returns:
True if this character would pass through this filter unaltered; otherwise, false.
Since:
BlackBerry API 4.2.0

validate

public boolean validate(AbstractString text)
Determines if provided string contains valid characters.

The default implementation of this method returns true if each character is valid within the field (determined by invoking TextFilter.validate(char). This is useful for upper case or lower case filters, for example, but filters that rely on character position must override this method.

Parameters:
text - String to test.
Returns:
True if each character in the string passes a validity check; otherwise, false.





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal