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

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

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
 char convert(char character, AbstractString text, int position, int status)
          Retrieves filtered version of provided character.
abstract  char convert(char character, int status)
          Retrieves filtered version of provided character.
static TextFilter get(int type)
          Retrieve a filter of provided type.
 boolean validate(AbstractString text)
          Determines if provided string contains valid characters.
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.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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.ACCEPT_PAUSE PhoneTextFilter.ACCEPT_CONTROL PhoneTextFilter.ACCEPT_INTERNATIONAL)
Since:
JDE 4.0.0

DEFAULT

public static final int DEFAULT
Default filter type. Null returned

DEFAULT_SMART_PHONE

public static final int DEFAULT_SMART_PHONE
Default smart phone number edit field filter.
See Also:
PhoneTextFilter(PhoneTextFilter.ACCEPT_CONTROL PhoneTextFilter.ACCEPT_ALPHA PhoneTextFilter.ACCEPT_FORMATTING PhoneTextFilter.ACCEPT_INTERNATIONAL)
Since:
JDE 4.0.2

EMAIL

public static final int EMAIL
Email address filter.
See Also:
EmailAddressTextFilter()

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.ACCEPT_PAUSE PhoneTextFilter.ACCEPT_CONTROL PhoneTextFilter.ACCEPT_WILD_CARD PhoneTextFilter.ACCEPT_INTERNATIONAL)
Since:
JDE 4.0.2

FILENAME

public static final int FILENAME
Filename filter that accepts alphanumeric characters without special chars or accents.
See Also:
FilenameTextFilter
Since:
JDE 4.2.0

HEXADECIMAL

public static final int HEXADECIMAL
Hex character set filter.
See Also:
HexadecimalTextFilter()

INTEGER

public static final int INTEGER
Numeric filter that also allows for a minus sign.
See Also:
NumericTextFilter( NumericTextFilter.ALLOW_NEGATIVE )

IP

public static final int IP
IP Address filters out characters not used in IP\Port text strings
See Also:
IPTextFilter
Since:
JDE 4.2.1

LOWERCASE

public static final int LOWERCASE
Lowercase alpha character filter
See Also:
LowercaseTextFilter()

NUMERIC

public static final int NUMERIC
Common numeric filter.
See Also:
NumericTextFilter()

PHONE

public static final int PHONE
A generous phone number filter
See Also:
PhoneTextFilter(PhoneTextFilter.ACCEPT_EVERYTHING_EXCEPT_WILD_CARD)

PIN_ADDRESS

public static final int PIN_ADDRESS
PIN address filter type.
See Also:
PINAddressTextFilter()
Since:
JDE 4.0.0

REAL_NUMERIC

public static final int REAL_NUMERIC
Numeric filter that also allows for a minus sign and decimal point.
See Also:
NumericTextFilter(NumericTextFilter.ALLOW_DECIMAL NumericTextFilter.ALLOW_NEGATIVE)
Since:
JDE 4.0.2

SIM_PHONE

public static final int SIM_PHONE
Same as ADN_SIM_PHONE. This is kept for backwards compatibility
Since:
JDE 4.0.2

SMS_PHONE

public static final int SMS_PHONE
SMS (Short Message Service) phone number filter
See Also:
PhoneTextFilter(PhoneTextFilter.ACCEPT_INTERNATIONAL PhoneTextFilter.INTERNATIONAL_MUST_BE_FIRST)
Since:
JDE 4.0.2

STYLE_SHIFT

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

UPPERCASE

public static final int UPPERCASE
Uppercase alpha character filter
See Also:
UppercaseTextFilter()

URL

public static final int URL
URL (Universal Resource Locator) filter.
See Also:
URLTextFilter()

VOICEMAIL_PHONE

public static final int VOICEMAIL_PHONE
Default voicemail and call forwarding phone number edit field filter.
See Also:
PhoneTextFilter(PhoneTextFilter.ACCEPT_CONTROL PhoneTextFilter.ACCEPT_INTERNATIONAL PhoneTextFilter.INTERNATIONAL_MUST_BE_FIRST)
Since:
JDE 4.0.2
Constructor Detail

TextFilter

protected TextFilter()
Constructs a new TextFilter instance.
Method Detail

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 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:
JDE 4.2.0

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

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 DEFAULT for type, or an invalid type.

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

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:
JDE 4.2.0



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.