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

java.lang.Object
  net.rim.device.api.ui.text.TextFilter
      net.rim.device.api.ui.text.IPTextFilter

public class IPTextFilter
extends TextFilter

Filters out characters not used in IP/Port text strings

Since:

BlackBerry API 3.6.0

Field Summary
static int	NO_PORTS A constant indicating that no ports are allowed in the string.
static int	NUMERIC_IP_ONLY A constant indicating that if set, IP addresses can only consist of numeric characters.

Fields inherited from class net.rim.device.api.ui.text.TextFilter

ADN_SIM_PHONE, DEFAULT, DEFAULT_SMART_PHONE, EMAIL, FDN_SIM_PHONE, FILENAME, HEXADECIMAL, INTEGER, IP, LOWERCASE, NUMERIC, PHONE, PIN_ADDRESS, REAL_NUMERIC, SIM_PHONE, SMS_PHONE, STYLE_SHIFT, UPPERCASE, URL, VOICEMAIL_PHONE

Constructor Summary

IPTextFilter()
Constructs new IPTextFilter object with no parameters.

IPTextFilter(int flag)
Constructs new IPTextFilter object.

Method Summary
char	convert(char character, int status) Converts a valid character to its lower case form and an invalid character to its alternate version.
void	convert(StringBuffer characters, int status, StringBuffer result) Convert a user input character to its appropriate alternate version if it is invalid for the current text field.
boolean	validate(char character) Validates a character for use with this filter.
boolean	validate(AbstractString text) Determines if the provided string contains valid characters.

Methods inherited from class net.rim.device.api.ui.text.TextFilter

convert, get, validate

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_PORTS

public static final int NO_PORTS

A constant indicating that no ports are allowed in the string.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

NUMERIC_IP_ONLY

public static final int NUMERIC_IP_ONLY

A constant indicating that if set, IP addresses can only consist of numeric characters.

See Also:

Constant Field Values

Since:

BlackBerry API 3.6.0

Constructor Detail

IPTextFilter

public IPTextFilter()

Constructs new IPTextFilter object with no parameters.

Since:

BlackBerry API 3.6.0

IPTextFilter

public IPTextFilter(int flag)

Constructs new IPTextFilter object.

Takes an argument that specifies if UDP ports are allowed.

Parameters:

flag - Flag to specify if UDP ports are allowed.

Since:

BlackBerry API 3.6.0

Method Detail

convert

public char convert(char character,
                    int status)

Converts a valid character to its lower case form and an invalid character to its alternate version.

Specified by:

convert in class TextFilter

Parameters:

character - The character to convert.

status - Indicates how the character was generated: some filters use this to affect the conversion performed.

Returns:

The lower-case form of the given alphabet character for valid characters, whether the character was lower-case or upper-case originally. For invalid characters - returns the result of Keypad.getAltedChar(char).

Since:

BlackBerry API 3.6.0

convert

public void convert(StringBuffer characters,
                    int status,
                    StringBuffer result)

Convert a user input character to its appropriate alternate version if it is invalid for the current text field. Also used to filter key labels to help create desired (reduced) keyboard layout for the current text field.

This function works in three different scenarios indicated by the current input field type (see private field _flags) and whether virtual keyboard is supported.

• case 1: virtual keyboard is supported and the input field is IP address.
• case 2: virtual keyboard is supported and the input field is not IP address.
• case 3: virtual keyboard is not supported.

In case 3, only a single character is converted by using the following rules:

   if the char is not valid
          if the field is IP address  
                  return the alternative char
          else if the _toLower bit is set 
                  return the lowercase char

Note that the alternative char may still be an invalid char for the current field. After calling this function, users still need to call this class' validate function to check each char.

For a device with a virtual keyboard, if a text field is IP address or hostname, this method is used both to filter keyboard input and filter keys' labels to create keyboard layout desired for the current text field. For example, on a reduced keyboard for IP address editing the number sign key (#) can be mapped to the period key (.) and the asterisk key (*) can be mapped to the colon key (:).

In case 2, for both keyboard input and key labels, the conversion is carried out in the same way as in case 3 except that there might be multiple chars to convert. The multiple chars occur when a device with a virtual keyboard is in a portrait view and the device has a SureType™ keyboard, such as the keyboard on the BlackBerry® Pearl™ Flip 8220 smartphone, where each key has a multiple char label.

In case 1, the function works on a single char and it filters both keyboard labels and keyboard input. When a device with a virtual keyboard is in a portrait view, if the current field is IP address, different from case 2, and the keyboard is a reduced multi-tap style keyboard where only the number (0-9), period (.), colon (:), Del, and Enter keys are displayed (the Alt and Sym keys are also shown but are disabled), a lot of key mapping work must occur.

1. Filtering primary labels.
   To disable Alt key, all the primary labels must be null. For an input char, if KeypadListener.STATUS_ALT is set in status, it is a primary label and returns null.
2. Mapping secondary labels to digits (0-9)
   Retrieve the first char of the secondary label. Through the key layout, find out its primary label. Retrieve the first char of the primary label, if it is valid, return it.
3. Special mapping
   After step 2, key mapping might not look like what is expected. To fix that, some special mappings must be added here. For example, the number key (#) is mapped to the period key (.), and the asterisk key (*) is mapped to the colon key (:).
4. A period (.) is the most special char.
   As on a multi-tap keyboard, a period (.) is on the same key as 1 and 1 must be mapped to that key. In this case, a period (.) is mapped to the number sign key (#) instead. In addition, since a period (.) is a valid character for an IP address, it is specially dealt with to distinguish the two cases.

Overrides:

convert in class TextFilter

Parameters:

characters - The character to convert.

status - Indicates how the character was generated, the type of the text field and how the conversion should be performed.

result - The converted result. For case 2 and 3, return the lowercase form of the given alphabet character(s) for invalid character(s) - returns the result of Keypad.getAltedChar(char). For case 1, the result is dependent on the running context

Since:

BlackBerry API 4.7.0

validate

public boolean validate(AbstractString text)

Determines if the provided string contains valid characters.

Overrides:

validate in class TextFilter

Parameters:

text - The string with characters to validate.

Returns:

true If each character in the text parameter is valid, or if the text parameter is an empty String or null.

Since:

BlackBerry API 3.6.0

validate

public boolean validate(char character)

Validates a character for use with this filter. If NO_PORTS flag is not set, then ':' is valid. If NUMERIC_IP_ONLY flag is not set, then lower case characters, '-' and '.' are valid. Upper-case alphabet characters are considered invalid.

Specified by:

validate in class TextFilter

Parameters:

character - The character to validate.

Returns:

true If the character parameter is a valid IP string character. Return false if the character parameter is an upper-case alphabet character.

Since:

BlackBerry API 3.6.0