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

java.lang.Object
  extended by net.rim.device.api.ui.text.TextFilter
      extended by 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.

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





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