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:
AccessibleContext, 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_LEFT, FIELD_RIGHT, FIELD_TOP, 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
 
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, 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, getChangeListener, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getOriginal, getPreferredHeight, getScreen, getStyle, getTop, 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, setChangeListener, setCookie, setDirty, setEditable, setExtent, setFocus, setFocusListener, setFont, setMuddy, setNonSpellCheckable, setPosition, 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 setList, 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.
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 setKeywordInputField.
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 setList, returns null.
Since:
JDE 4.5.0

getResultListSize

public int getResultListSize()
Retrieves the size of the list of elements that are currently not filtered out.
Returns:
Number of elements in the filtered list; if the list is not set using setList, returns 0.
Since:
JDE 4.5.0

getSelectedElement

public Object getSelectedElement()
Retrieves the selected element in the results list. Returns null if nothing selected.
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 setList 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.
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.
Parameters:
list - New source collection list for the field.
helper - New keyword provider helper.
Throws:
IllegalArgumentException - In case parameters are set to null.
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.
Since:
JDE 4.5.0



Copyright 1999-2008 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.