net.rim.device.api.ui.component
Class KeywordFilterField

java.lang.Object
  extended by net.rim.device.api.ui.Field
      extended by net.rim.device.api.ui.component.ListField
          extended by net.rim.device.api.ui.component.KeywordFilterField
All Implemented Interfaces:
FieldChangeListener

public class KeywordFilterField
extends ListField
implements FieldChangeListener

Consists of a single keyword input field and a list of selectable elements. The elements are filtered when keywords are entered into the input field. An example of this can be found in the Address Book application. The KeywordFilterField itself is a ListField and can be added to any container for layout purposes. The contents within this list represent the keyword filter results. The keyword input field can be access via getKeywordField or overridden with a custom TextField via setKeywordField. This field currently only supports prefix keyword filtering.

Since:
BlackBerry API 4.5.0

Field Summary
 
Fields inherited from class net.rim.device.api.ui.component.ListField
MULTI_SELECT, NON_CONTIGUOUS_SELECT, NO_ALTED_PAGE_UP_DOWN, ROW_HEIGHT_FONT
 
Fields inherited from class net.rim.device.api.ui.Field
ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL
 
Fields inherited from interface net.rim.device.api.ui.FieldChangeListener
PROGRAMMATIC
 
Constructor Summary
KeywordFilterField()
          Creates a new KeywordFilterField.
 
Method Summary
 Object getElementAt(int index)
          Retrieves the element at the specified index in the list.
 String getKeyword()
          Retrieves the entered keyword.
 TextField getKeywordField()
          Retrieves the keyword input field.
 String getLabel()
          Retrieves the label preceding the keyword input area.
 ReadableList getResultList()
          Retrieves the list of elements that are currently not filtered out, i.e. search results.
 int getResultListSize()
          Retrieves the size of the list of elements that are currently not filtered out.
 Object getSelectedElement()
          Retrieves the selected element in the results list.
 ReadableList getSourceList()
          Retrieves the source collection list.
 void setKeyword(String keyword)
          Sets a keyword in the keyword input field programmatically.
 void setKeywordField(TextField keywordField)
          Sets a custom keyword input field, which overrides the default field.
 void setLabel(String label)
          Sets the keyword input field's label.
 void setSourceList(ReadableList list, KeywordProvider helper)
          Sets read-only source elements in the collection list from which to search.
 void updateList()
          To be invoked if the contents of the source collection list change.
 
Methods inherited from class net.rim.device.api.ui.component.ListField
delete, drawFocus, getAccessibleContext, getCallback, getEmptyString, getEmptyStringStyle, getFocusRect, getPreferredWidth, getRowHeight, getSelectedIndex, getSelection, getSize, indexOfList, insert, invalidate, invalidate, invalidateRange, isEmpty, keyChar, keyControl, layout, moveFocus, moveFocus, onFocus, paint, setCallback, setEmptyString, setEmptyString, setRowHeight, setSearchable, setSelectedIndex, setSize, setSize, trackwheelClick, trackwheelUnclick
 
Methods inherited from class net.rim.device.api.ui.Field
cursorClick, cursorUnclick, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getPreferredHeight, getScreen, getStyle, getTextFillColor, getTextStrokeColor, getTop, getVisualState, getWidth, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isLeftToRight, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyDown, keyRepeat, keyStatus, keyUp, makeContextMenu, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setExtent, setFocus, setFocusListener, setFont, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, touchEvent, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface net.rim.device.api.ui.FieldChangeListener
fieldChanged
 



Constructor Detail

KeywordFilterField

public KeywordFilterField()
Creates a new KeywordFilterField. Use setSourceList, setLabel (optional), setCallback (optional), setKeywordField (optional) to initialize field.

Since:
BlackBerry API 4.5.0


Method Detail

setLabel

public void setLabel(String label)
Sets the keyword input field's label. Defaults to "Find: " if not set.

Parameters:
label - New label for the input field. Ignored if null.
Since:
BlackBerry API 4.5.0

setKeywordField

public void setKeywordField(TextField keywordField)
Sets a custom keyword input field, which overrides the default field. Important: This method will automatically set a FieldChangeListener for the custom keyword input field via Field#setChangeListener in order for searches to occur.

Parameters:
keywordField - Custom keyword input field. Resets to default text input field if null.
Since:
BlackBerry API 4.5.0

setSourceList

public void setSourceList(ReadableList list,
                          KeywordProvider helper)
Sets read-only source elements in the collection list from which to search. The ReadableList can contain any object.

Parameters:
list - New source collection list for the field.
helper - New keyword provider helper.
Throws:
NullPointerException - if the ReadableList passed in has null values in it.
IllegalArgumentException - In case parameters are set to null.
Exception - The same exception that KeywordProvider.getKeyword(Object) throws.
Since:
BlackBerry API 4.5.0

updateList

public void updateList()
To be invoked if the contents of the source collection list change. This will repaint the list field and reparse the source collection for keywords. Note: This method will lock the source collection list while the update is in progress.

Since:
BlackBerry API 4.5.0

setKeyword

public void setKeyword(String keyword)
Sets a keyword in the keyword input field programmatically. This should be called after setSourceList(). Important: A search thread is started for each keyword set. If initiating a new keyword search before an older one has completed, the older one will be discarded. The results retrieved will reflect that of the new keyword. In order to determine when this KeywordFilterField list is updated with the search results, a FieldChangeListener should be set via setChangeListener. A null keyword is equivalent to an empty string and will reset the search. Note: This method will lock the source collection list while the search is in progress.

Parameters:
keyword - New keyword to search.
Since:
BlackBerry API 4.5.0

getResultList

public ReadableList getResultList()
Retrieves the list of elements that are currently not filtered out, i.e. search results. Returns an empty list if all elements are filtered out, i.e. no elements shown. Returns null if source list is not set.

Returns:
A ReadableList containing the keyword filtered elements shown in the list; if this KeywordFilterField is not set using setSourceList, returns null. Note: If this method is invoked while the current search is still in progress then the result of prior search will be returned. The result list is updated once the search is complete.
Since:
BlackBerry API 4.5.0

getResultListSize

public int getResultListSize()
Retrieves the size of the list of elements that are currently not filtered out. Note: This method will lock the source collection list until the appropriate value is returned.

Returns:
Number of elements in the filtered list; if the list is not set using setSourceList, returns 0.
Since:
BlackBerry API 4.5.0

getSelectedElement

public Object getSelectedElement()
Retrieves the selected element in the results list. Returns null if nothing selected. If the search reveals more than one element in the result list, then, by default, the first element in the result list is returned. If there are no results, then no element (null) is returned. Note: This method will lock the source collection list until the appropriate object is returned.

Returns:
The selected element in the results list or null if nothing selected.
Since:
BlackBerry API 4.5.0

getElementAt

public Object getElementAt(int index)
Retrieves the element at the specified index in the list. Returns null if index is out of bounds. The first element in the list is at index 0. Note: This method will lock the source collection list until the appropriate object is returned.

Parameters:
index - Location of within the list.
Returns:
The element at the specified index in the results list or null if nothing at the index.
Since:
BlackBerry API 4.5.0

getKeyword

public String getKeyword()
Retrieves the entered keyword. Returns an empty string if nothing entered.

Returns:
A String containing the entered keyword. An empty string if no keyword is entered.
Since:
BlackBerry API 4.5.0

getLabel

public String getLabel()
Retrieves the label preceding the keyword input area. Defaults to "Find: ". Use setLabel to change default label.

Returns:
The keyword input field label.
Since:
BlackBerry API 4.5.0

getSourceList

public ReadableList getSourceList()
Retrieves the source collection list. Use setSourceList to set a list of elements in the field.

Returns:
Source collection list for this field; if no list has been set, returns null.
Since:
BlackBerry API 4.5.0

getKeywordField

public TextField getKeywordField()
Retrieves the keyword input field. May be a custom field if explicitly set using setKeywordField.

Returns:
TextField representing the keyword input field.
Since:
BlackBerry API 4.5.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