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

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.component.ListField
              |
              +--net.rim.device.api.ui.component.KeywordFilterField
All Implemented Interfaces:
FieldChangeListener, IComponent, InputMethodListener, VariableRowHeightProvider

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

Field Summary
 
Fields inherited from class net.rim.device.api.ui.component.ListField
MULTI_SELECT, NO_ALTED_PAGE_UP_DOWN, NON_CONTIGUOUS_SELECT, ROW_HEIGHT_FONT
 
Fields inherited from class net.rim.device.api.ui.Field
ACTION_INVOKE, 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()
          Updates the collection of elements to display in the list field.
 
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, invalidateRange, isEmpty, layout, moveFocus, moveFocus, onFocus, paint, setCallback, setEmptyString, setEmptyString, setRowHeight, setSearchable, setSelectedIndex, setSize, setSize
 
Methods inherited from class net.rim.device.api.ui.Field
drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getPreferredHeight, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isFocus, isFocusable, isMuddy, isPasteable, 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, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, setVisualState, trackwheelClick, trackwheelUnclick, updateLayout
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

KeywordFilterField

public KeywordFilterField()
Creates a new KeywordFilterField. Use setSourceList, setLabel (optional), setCallback (optional), setKeywordField (optional) to initialize field.
Since:
JDE 4.5.0
Method Detail

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

setKeyword

public void setKeyword(String keyword)
Sets a keyword in the keyword input field programmatically. 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:
JDE 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:
JDE 4.5.0

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

updateList

public void updateList()
Updates the collection of elements to display in the list field. To be invoked if the contents of the source collection list change. Note: This method will lock the source collection list while the update is in progress.
Since:
JDE 4.5.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.