com.sun.lwuit
Class List

java.lang.Object
  com.sun.lwuit.Component
      com.sun.dtv.ui.MatteEnabledComponent
          com.sun.dtv.ui.ViewOnlyComponent
              com.sun.lwuit.List

All Implemented Interfaces:

Animated, MatteEnabled, StyleListener

Direct Known Subclasses:

ComboBox

public class List

extends ViewOnlyComponent

A set of elements that is rendered using a ListCellRenderer and are extracted via the ListModel.

A list can represent many UI concepts ranging from a carousel to a "todo" checklist, this is made possible thanks to extensive use of Swing's style of MVC. Specifically a list component is relatively simple, it invokes the model in order to extract the displayed/selected information and shows it to the user by invoking the cell renderer.

The list class itself is completely decoupled from everything, thus it allows us to extract its content from any source (e.g. network, storage etc.) and display the information in any form (e.g. checkboxed elements, icons etc.).

See Also:

ListModel

Field Summary

static int	FIXED_CENTER Indicates the list selection is fixed into place at the center of the list.
static int	FIXED_LEAD Indicates the list selection is fixed into place at the top of the list or at the left of the list.
static int	FIXED_NONE Indicates the list isn't fixed and that selection is movable.
static int	FIXED_NONE_CYCLIC Indicates that the list is not fixed in place but cycles its elements.
static int	FIXED_NONE_ONE_ELEMENT_MARGIN_FROM_EDGE Indicates the list selection will only reach the edge when there are no more elements in the list.
static int	FIXED_TRAIL Indicates the list selection is fixed into place at the bottom of the list or at the right of the list.
static int	HORIZONTAL Indicates the list orientation is HORIZONTAL.
static int	VERTICAL Indicates the list orientation is VERTICAL.

Fields inherited from class com.sun.dtv.ui.ViewOnlyComponent

HORIZONTAL_ALIGN_CENTER, HORIZONTAL_ALIGN_JUSTIFIED, HORIZONTAL_ALIGN_LEFT, HORIZONTAL_ALIGN_RIGHT, SCALE_ASPECT_PROOF, SCALE_NO, SCALE_NO_ASPECT_PROOF, VERTICAL_ALIGN_BOTTOM, VERTICAL_ALIGN_CENTER, VERTICAL_ALIGN_JUSTIFIED, VERTICAL_ALIGN_TOP

Fields inherited from class com.sun.lwuit.Component

BOTTOM, BRB_CENTER_OFFSET, BRB_CONSTANT_ASCENT, BRB_CONSTANT_DESCENT, BRB_OTHER, CENTER, LEFT, RIGHT, TOP

Fields inherited from interface com.sun.dtv.ui.Animated

ALTERNATING, LOOP, REPEATING

Constructor Summary

List()
Creates a new instance of List with an empty default model.

List(ListModel model)
Creates a new instance of List with the given model.

List(Object[] items)
Creates a new instance of List.

List(Vector items)
Creates a new instance of List.

Method Summary

void	addActionListener(ActionListener l) Allows binding a listener to user selection actions.
void	addItem(Object item) Allows adding an element to a list if the underlying model supports this, notice that it is an optional operation and if the model does not support it (default list model does) then this operation may failed.
void	addSelectionListener(SelectionListener l) Invoked to indicate interest in future selection events.
boolean	animate() Allows the animation to reduce "repaint" calls when it returns false.
protected Dimension	calcPreferredSize() Calculates the preferred size based on component content.
protected void	fireActionEvent() This method allows us to detect an action event internally without implementing the action listener interface.
protected void	fireClicked() When working in 3 softbutton mode "fire" key (center softbutton) is sent to this method in order to allow 3 button devices to work properly.
int	getBorderGap() Getting the surrounding border gap.
int	getFixedSelection() Indicates whether selection is fixable to place in which case all the elements in the list move and selection stays in place.
int	getItemGap() Returns the gap between items.
ListModel	getModel() Returns the model underlying the list.
int	getOrientation() Returns the list orientation.
ListCellRenderer	getRenderer() Returns the renderer which is used to draw list elements.
Object	getRenderingPrototype() See set rendering prototype.
int	getSelectedIndex() Returns the current selected offset in the list.
Object	getSelectedItem() Returns the current selected item in the list or null for no selection.
protected String	getUIID() Unique identifier for a component, must be overriden for a component so a style can be applied to the component.
protected void	initComponent() Allows subclasses to bind functionality that relies on fully initialized and "ready for action" component state.
boolean	isNumericKeyActions() Indicate whether pressing the number keys should trigger an action.
boolean	isScrollableX() Indicates whether the component should/could scroll on the X axis.
boolean	isScrollableY() Indicates whether the component should/could scroll on the Y axis.
protected boolean	isSelectableInteraction() This method allows a component to indicate that it is interested in an "implicit" select command to appear in the "fire" button when 3 softbuttons are defined in a device.
void	keyPressed(int keyCode) If this Component is focused, the key pressed event will call this method.
void	keyReleased(int keyCode) If this Component is focused, the key released event will call this method.
protected void	modelChanged(int status, int index) Callback to allow subclasses to react to a change in the model.
void	paint(Graphics g) Method to paint the component.
protected String	paramString() Returns a string representing the state of this component.
void	pointerDragged(int x, int y) If this Component is focused, the pointer dragged event will call this method.
void	pointerReleased(int x, int y) If this Component is focused, the pointer released event will call this method.
void	refreshTheme() Makes sure the component is up to date with the current style object.
void	removeActionListener(ActionListener l) Allows binding a listener to user selection actions.
void	removeSelectionListener(SelectionListener l) Invoked to indicate no further interest in future selection events.
void	scrollRectToVisible(Rectangle rect) Makes sure the selected index is visible if it is not in the current view rect the list will scroll so it fits within.
void	setBorderGap(int borderGap) Setting the surrounding border gap.
void	setFixedSelection(int fixedSelection) Indicates whether selection is fixable to place in which case all the elements in the list move and selection stays in place.
void	setHandlesInput(boolean b) Prevents key events from being grabbed for focus traversal.
void	setInputOnFocus(boolean inputOnFocus) A list can start handling input implicitly upon gaining focus, this can make for a more intuitive UI when no other focus elements exist or when their use case is infrequent.
void	setItemGap(int itemGap) Set the gap between items.
void	setListCellRenderer(ListCellRenderer renderer) Sets the renderer which is used to draw list elements.
void	setModel(ListModel model) Replaces/sets the model underlying the list.
void	setNumericKeyActions(boolean numericKeyActions) Indicate whether pressing the number keys should trigger an action.
void	setOrientation(int orientation) Sets the list orientation HORIZONTAL or VERTICAL.
void	setPaintFocusBehindList(boolean paintFocusBehindList) This method determines if the animated focus is drawn on top of the List or behind the List when moving.
void	setRenderingPrototype(Object renderingPrototype) The rendering prototype is optionally used in calculating the size of the List and is recommended for performance reasons.
void	setSelectedIndex(int index) Sets the current selected offset in the list, by default this implementation will scroll the list to the selection if the selection is outside of the screen.
void	setSelectedIndex(int index, boolean scrollToSelection) Sets the current selected offset in the list.
void	setSelectedItem(Object item) Sets the current selected item in the list.
int	size() Returns the number of elements in the list, shorthand for getModel().getSize().

Methods inherited from class com.sun.dtv.ui.ViewOnlyComponent

getAnimateContent, getGraphicContent, getHorizontalAlignment, getInteractionState, getScalingMode, getTextContent, getTextLayoutManager, getVerticalAlignment, isOpaque, setAnimateContent, setGraphicContent, setHorizontalAlignment, setInteractionState, setScalingMode, setTextContent, setTextLayoutManager, setVerticalAlignment

Methods inherited from class com.sun.dtv.ui.MatteEnabledComponent

getMatte, isDoubleBuffered, processEvent, setMatte

Methods inherited from class com.sun.lwuit.Component

addFocusListener, contains, deinitialize, getAbsoluteX, getAbsoluteY, getAnimationMode, getBaseline, getBaselineResizeBehavior, getBorder, getBottomGap, getBounds, getClientProperty, getComponentForm, getDelay, getHeight, getNextFocusDown, getNextFocusLeft, getNextFocusRight, getNextFocusUp, getParent, getPosition, getPreferredSize, getRepetitionMode, getScrollAnimationSpeed, getScrollX, getScrollY, getSideGap, getStyle, getWidth, getX, getY, handlesInput, hasFocus, isEnabled, isFocusable, isFocusPainted, isInitialized, isRunning, isScrollable, isScrollVisible, isSmoothScrolling, isVisible, jumpTo, keyRepeated, longKeyPress, paintBackground, paintBackgrounds, paintBorder, paintComponent, paintComponent, paintScrollbars, paintScrollbarX, paintScrollbarY, pointerPressed, putClientProperty, refreshTheme, removeFocusListener, repaint, repaint, requestFocus, scrollRectToVisible, setAnimationMode, setCellRenderer, setDelay, setEnabled, setFocus, setFocusable, setFocusPainted, setHeight, setInitialized, setIsScrollVisible, setNextFocusDown, setNextFocusLeft, setNextFocusRight, setNextFocusUp, setPreferredSize, setRepetitionMode, setScrollAnimationSpeed, setScrollX, setScrollY, setShouldCalcPreferredSize, setSize, setSmoothScrolling, setStyle, setVisible, setWidth, setX, setY, start, stop, styleChanged, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

FIXED_NONE

public static final int FIXED_NONE

Indicates the list isn't fixed and that selection is movable.

See Also:

Constant Field Values

FIXED_NONE_CYCLIC

public static final int FIXED_NONE_CYCLIC

Indicates that the list is not fixed in place but cycles its elements.

See Also:

Constant Field Values

FIXED_NONE_ONE_ELEMENT_MARGIN_FROM_EDGE

public static final int FIXED_NONE_ONE_ELEMENT_MARGIN_FROM_EDGE

Indicates the list selection will only reach the edge when there are no more elements in the list.

See Also:

Constant Field Values

FIXED_LEAD

public static final int FIXED_LEAD

Indicates the list selection is fixed into place at the top of the list or at the left of the list.

See Also:

Constant Field Values

FIXED_TRAIL

public static final int FIXED_TRAIL

Indicates the list selection is fixed into place at the bottom of the list or at the right of the list.

See Also:

Constant Field Values

FIXED_CENTER

public static final int FIXED_CENTER

Indicates the list selection is fixed into place at the center of the list.

See Also:

Constant Field Values

VERTICAL

public static final int VERTICAL

Indicates the list orientation is VERTICAL.

See Also:

Constant Field Values

HORIZONTAL

public static final int HORIZONTAL

Indicates the list orientation is HORIZONTAL.

See Also:

Constant Field Values

Constructor Detail

List

public List(Vector items)

Creates a new instance of List.

Parameters:

items - set of items placed into the list model

List

public List(Object[] items)

Creates a new instance of List.

Parameters:

items - set of items placed into the list model

List

public List()

Creates a new instance of List with an empty default model.

List

public List(ListModel model)

Creates a new instance of List with the given model.

Parameters:

model - the model instance

Method Detail

initComponent

protected void initComponent()

Description copied from class: Component

Allows subclasses to bind functionality that relies on fully initialized and "ready for action" component state.

Overrides:

initComponent in class Component

modelChanged

protected void modelChanged(int status,
                            int index)

Callback to allow subclasses to react to a change in the model.

Parameters:

status - the type data change; REMOVED, ADDED or CHANGED

index - item index in a list model

isScrollableY

public boolean isScrollableY()

Description copied from class: Component

Indicates whether the component should/could scroll on the Y axis.

Overrides:

isScrollableY in class Component

Returns:

whether the component is scrollable on the X axis

isScrollableX

public boolean isScrollableX()

Description copied from class: Component

Indicates whether the component should/could scroll on the X axis.

Overrides:

isScrollableX in class Component

Returns:

whether the component is scrollable on the X axis

size

public int size()

Returns the number of elements in the list, shorthand for getModel().getSize().

Returns:

the number of elements in the list

getSelectedIndex

public int getSelectedIndex()

Returns the current selected offset in the list.

Returns:

the current selected offset in the list

See Also:

setSelectedIndex(int), setSelectedIndex(int, boolean)

setSelectedIndex

public void setSelectedIndex(int index)

Sets the current selected offset in the list, by default this implementation will scroll the list to the selection if the selection is outside of the screen.

Parameters:

index - the current selected offset in the list

See Also:

getSelectedIndex()

setSelectedIndex

public void setSelectedIndex(int index,
                             boolean scrollToSelection)

Sets the current selected offset in the list.

Parameters:

index - the current selected offset in the list

scrollToSelection - indicates whether scrolling to selection should occur if the selection is outside of view

See Also:

getSelectedIndex()

getSelectedItem

public Object getSelectedItem()

Returns the current selected item in the list or null for no selection.

Returns:

the current selected item in the list

See Also:

setSelectedItem(java.lang.Object)

setSelectedItem

public void setSelectedItem(Object item)

Sets the current selected item in the list.

Parameters:

item - the current selected item in the list

See Also:

getSelectedItem()

getModel

public ListModel getModel()

Returns the model underlying the list.

Returns:

the model underlying the list

See Also:

setModel(com.sun.lwuit.list.ListModel)

setModel

public void setModel(ListModel model)

Replaces/sets the model underlying the list.

Parameters:

model - the new model underlying the list

See Also:

getModel()

isNumericKeyActions

public boolean isNumericKeyActions()

Indicate whether pressing the number keys should trigger an action.

Returns:

true if pressing the number keys should trigger an action, false otherwise

setNumericKeyActions

public void setNumericKeyActions(boolean numericKeyActions)

Indicate whether pressing the number keys should trigger an action.

Parameters:

numericKeyActions - true to trigger an action on number keys

setListCellRenderer

public void setListCellRenderer(ListCellRenderer renderer)

Sets the renderer which is used to draw list elements.

Parameters:

renderer - cell renderer instance

getRenderer

public ListCellRenderer getRenderer()

Returns the renderer which is used to draw list elements.

Returns:

the renderer which is used to draw list elements

getOrientation

public int getOrientation()

Returns the list orientation.

Returns:

the list orientation HORIZONTAL or VERTICAL

See Also:

setOrientation(int), HORIZONTAL, VERTICAL

refreshTheme

public void refreshTheme()

Description copied from class: Component

Makes sure the component is up to date with the current style object.

Overrides:

refreshTheme in class Component

setOrientation

public void setOrientation(int orientation)

Sets the list orientation HORIZONTAL or VERTICAL.

Parameters:

orientation - the list orientation HORIZONTAL or VERTICAL

See Also:

getOrientation(), HORIZONTAL, VERTICAL

scrollRectToVisible

public void scrollRectToVisible(Rectangle rect)

Makes sure the selected index is visible if it is not in the current view rect the list will scroll so it fits within.

Parameters:

rect - the rectangle area to scroll to

setHandlesInput

public void setHandlesInput(boolean b)

Description copied from class: Component

Prevents key events from being grabbed for focus traversal. E.g. a list component might use the arrow keys for internal navigation so it will switch this flag to true in order to prevent the focus manager from moving to the next component.

Overrides:

setHandlesInput in class Component

Parameters:

b - indicates whether key events can be grabbed for focus traversal

fireClicked

protected void fireClicked()

Description copied from class: Component

When working in 3 softbutton mode "fire" key (center softbutton) is sent to this method in order to allow 3 button devices to work properly. When overriding this method you should also override isSelectableInteraction to indicate that a command is placed appropriately on top of the fire key for 3 soft button phones.

Overrides:

fireClicked in class Component

isSelectableInteraction

protected boolean isSelectableInteraction()

Description copied from class: Component

This method allows a component to indicate that it is interested in an "implicit" select command to appear in the "fire" button when 3 softbuttons are defined in a device.

Overrides:

isSelectableInteraction in class Component

Returns:

true if the component to indicate that it is interested in an "implicit" select command to appear in the "fire" button when 3 softbuttons are defined in a device

keyReleased

public void keyReleased(int keyCode)

Description copied from class: Component

If this Component is focused, the key released event will call this method.

Overrides:

keyReleased in class Component

Parameters:

keyCode - the key code value to indicate a physical key.

keyPressed

public void keyPressed(int keyCode)

Description copied from class: Component

If this Component is focused, the key pressed event will call this method.

Overrides:

keyPressed in class Component

Parameters:

keyCode - the key code value to indicate a physical key.

paint

public void paint(Graphics g)

Description copied from class: ViewOnlyComponent

Method to paint the component.

Specified by:

paint in interface Animated

Overrides:

paint in class ViewOnlyComponent

Parameters:

g - the graphics context to use for painting.

getUIID

protected String getUIID()

Description copied from class: Component

Unique identifier for a component, must be overriden for a component so a style can be applied to the component.

Overrides:

getUIID in class Component

Returns:

unique string identifying this component for the style sheet

addSelectionListener

public void addSelectionListener(SelectionListener l)

Invoked to indicate interest in future selection events.

Parameters:

l - the selection listener to be added

See Also:

removeSelectionListener(com.sun.lwuit.events.SelectionListener)

removeSelectionListener

public void removeSelectionListener(SelectionListener l)

Invoked to indicate no further interest in future selection events.

Parameters:

l - the selection listener to be removed

See Also:

addSelectionListener(com.sun.lwuit.events.SelectionListener)

addActionListener

public void addActionListener(ActionListener l)

Allows binding a listener to user selection actions.

Parameters:

l - the action listener to be added

See Also:

removeActionListener(com.sun.lwuit.events.ActionListener)

removeActionListener

public void removeActionListener(ActionListener l)

Allows binding a listener to user selection actions.

Parameters:

l - the action listener to be removed

See Also:

addActionListener(com.sun.lwuit.events.ActionListener)

fireActionEvent

protected void fireActionEvent()

This method allows us to detect an action event internally without implementing the action listener interface.

setInputOnFocus

public void setInputOnFocus(boolean inputOnFocus)

A list can start handling input implicitly upon gaining focus, this can make for a more intuitive UI when no other focus elements exist or when their use case is infrequent. However, it might be odd in some cases where the list "steals" focus.

Parameters:

inputOnFocus - true is a list can start handling input implicitly upon gaining focus

setPaintFocusBehindList

public void setPaintFocusBehindList(boolean paintFocusBehindList)

This method determines if the animated focus is drawn on top of the List or behind the List when moving.

Parameters:

paintFocusBehindList - true for behind, false for on top

getItemGap

public int getItemGap()

Returns the gap between items.

Returns:

the gap between items

See Also:

setItemGap(int)

setItemGap

public void setItemGap(int itemGap)

Set the gap between items.

Parameters:

itemGap - the gap between items

See Also:

getItemGap()

setRenderingPrototype

public void setRenderingPrototype(Object renderingPrototype)

The rendering prototype is optionally used in calculating the size of the List and is recommended for performance reasons. You should invoke it with an object representing a theoretical value in the list which will be used to calculate the size required for each element in the list.

This allows list size calculations to work across look and feels and allows developers to predetermine size for list elements.

e.g. For a list of Strings which you would like to always be 5 characters wide you can use a prototype "XXXXX" which would use the preferred size of the XXXXX String to determine the size of the list element. E.g. for a list of dates you can use new Date(30, 12, 00) etc..

Parameters:

renderingPrototype - a value that can be passed to the renderer to indicate the preferred size of a list component.

See Also:

getRenderingPrototype()

getRenderingPrototype

public Object getRenderingPrototype()

See set rendering prototype.

Returns:

the value of the rendering prototype

See Also:

setRenderingPrototype(java.lang.Object)

pointerDragged

public void pointerDragged(int x,
                           int y)

Description copied from class: Component

If this Component is focused, the pointer dragged event will call this method.

Overrides:

pointerDragged in class Component

Parameters:

x - the pointer x coordinate

y - the pointer y coordinate

pointerReleased

public void pointerReleased(int x,
                            int y)

Description copied from class: Component

If this Component is focused, the pointer released event will call this method.

Overrides:

pointerReleased in class Component

Parameters:

x - the pointer x coordinate

y - the pointer y coordinate

calcPreferredSize

protected Dimension calcPreferredSize()

Description copied from class: Component

Calculates the preferred size based on component content. This method is invoked lazily by getPreferred size.

Overrides:

calcPreferredSize in class Component

Returns:

the calculated preferred size based on component content

addItem

public void addItem(Object item)

Allows adding an element to a list if the underlying model supports this, notice that it is an optional operation and if the model does not support it (default list model does) then this operation may failed.

Parameters:

item - the item to be added to a list model

getFixedSelection

public int getFixedSelection()

Indicates whether selection is fixable to place in which case all the elements in the list move and selection stays in place.

Returns:

one of: FIXED_NONE, FIXED_TRAIL, FIXED_LEAD, FIXED_CENTER, FIXED_NONE_CYCLIC

See Also:

setFixedSelection(int)

setFixedSelection

public void setFixedSelection(int fixedSelection)

Indicates whether selection is fixable to place in which case all the elements in the list move and selection stays in place.

Parameters:

fixedSelection - one of: FIXED_NONE, FIXED_TRAIL, FIXED_LEAD, FIXED_CENTER, FIXED_NONE_CYCLIC

See Also:

getFixedSelection()

animate

public boolean animate()

Description copied from interface: Animated

Allows the animation to reduce "repaint" calls when it returns false. It is called once for every frame.

Specified by:

animate in interface Animated

Overrides:

animate in class Component

setBorderGap

public void setBorderGap(int borderGap)

Setting the surrounding border gap.

Parameters:

borderGap - number of pixels for the gap

See Also:

getBorderGap()

getBorderGap

public int getBorderGap()

Getting the surrounding border gap.

Returns:

border gap in pixels

See Also:

setBorderGap(int)

paramString

protected String paramString()

Description copied from class: Component

Returns a string representing the state of this component. This method is intended to be used only for debugging purposes, and the content and format of the returned string may vary between implementations. The returned string may be empty but may not be null.

Overrides:

paramString in class Component

Returns:

a string representation of this component's state