org.havi.ui
Class HListGroup

java.lang.Object
  extended byjava.awt.Component
      extended byorg.havi.ui.HComponent
          extended byorg.havi.ui.HVisible
              extended byorg.havi.ui.HListGroup
All Implemented Interfaces:
HItemValue, HMatteLayer, HNavigable, HNavigationInputPreferred, HOrientable, HSelectionInputPreferred, HState, java.awt.image.ImageObserver, java.io.Serializable, TestOpacity

public class HListGroup
extends HVisible
implements HItemValue

The HListGroup is a user interface component representing a list of selectable items (HListElements) which contain graphical and / or textual content.

This component can be navigated to, i.e. it can have the input focus. It also responds to HItemEvent events as follows:

HListGroup has the following properties which make it slightly different from the other platform components.

Interoperable HAVi applications shall not add HListElements more than once. If an application requires items with identical contents (label and/or icon), then additional items shall be created. The behavior of the HListGroup if duplicates are added is implementation specific. The methods setIcon() and setLabel() of HListElement shall not be used for elements, which are part of HListGroup. If an application requires to alter the content, it shall either replace the entire element, or remove it temporarily and re-add it after the content was changed.

By default this component uses the HListGroupLook class to render itself.


The parameters to the constructors are as follows, in cases where parameters are not used, then the constructor should use the default values.

Default parameter values exposed in the constructors

ParameterDescriptionDefault value Set methodGet method
x x-coordinate of top left hand corner of this component in pixels, relative to its parent container (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds
y y-coordinate of top left hand corner of this component in pixels, relative to its parent container (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds
width width of this component in pixels (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds
height height of this component in pixels (subject to layout management). --- java.awt.Component#setBounds java.awt.Component#getBounds
items The initial list of elements for this HListGroup or null for an empty list. null setListContent(org.havi.ui.HListElement[]) getListContent()

Default parameter values not exposed in the constructors

DescriptionDefault valueSet method Get method
Associated matte (HMatte). none (i.e. getMatte() returns null) setMatte getMatte
The text layout manager responsible for text formatting. An HDefaultTextLayoutManager object. HVisible.setTextLayoutManager(org.havi.ui.HTextLayoutManager) HVisible.getTextLayoutManager()
The background painting mode HVisible.NO_BACKGROUND_FILL HVisible.setBackgroundMode(int) HVisible.getBackgroundMode()
The default preferred size not set (i.e. NO_DEFAULT_SIZE) unless specified by width and height parameters HVisible.setDefaultSize(java.awt.Dimension) HVisible.getDefaultSize()
The horizontal content alignment HVisible.HALIGN_CENTER HVisible.setHorizontalAlignment(int) HVisible.getHorizontalAlignment()
The vertical content alignment HVisible.VALIGN_CENTER HVisible.setVerticalAlignment(int) HVisible.getVerticalAlignment()
The content scaling mode HVisible.RESIZE_NONE HVisible.setResizeMode(int) HVisible.getResizeMode()
The border mode true HVisible.setBordersEnabled(boolean) HVisible.getBordersEnabled()
Orientation ORIENT_TOP_TO_BOTTOM setOrientation getOrientation
Multi selection false setMultiSelection getMultiSelection
Selection mode false setSelectionMode getSelectionMode
Current item 0 if list content was set (i.e. at least one HListElement), ITEM_NOT_FOUND else setCurrentItem getCurrentIndex
Scrollposition 0 if list content was set (i.e. at least one HListElement), ITEM_NOT_FOUND else setScrollPosition getScrollPosition
Selection null getSelection ---
Label size not set (i.e. null) setLabelSize getLabelSize
Icon size not set (i.e. null) setIconSize getIconSize
The default "look" for this class. A platform specific HListGroupLook HListGroup.setDefaultLook HListGroup.getDefaultLook
The "look" for this object. The HListGroupLook returned from HListGroup.getDefaultLook when this object was created. HListGroup.setLook HListGroup.getLook
The gain focus sound. null setGainFocusSound getGainFocusSound
The lose focus sound. null setLoseFocusSound getLoseFocusSound
The selection sound. null setSelectionSound getSelectionSound

See Also:
HListElement, HListGroupLook, HNavigable, HItemValue, Serialized Form

Field Summary
static int ADD_INDEX_END
          A constant for use with addItem and addItems which specifies that the new items shall be appended to the end of the list.
static int DEFAULT_ICON_HEIGHT
          A constant for use with setIconSize and getIconSize.
static int DEFAULT_ICON_WIDTH
          A constant for use with setIconSize and getIconSize.
static int DEFAULT_LABEL_HEIGHT
          A constant for use with setLabelSize and getLabelSize.
static int DEFAULT_LABEL_WIDTH
          A constant for use with setLabelSize and getLabelSize.
static int ITEM_NOT_FOUND
          A constant which shall be returned from getIndex if the requested element is not found in the content.
 
Fields inherited from class org.havi.ui.HVisible
ADJUSTMENT_VALUE_CHANGE, ANIMATE_CONTENT_CHANGE, ANIMATION_POSITION_CHANGE, BACKGROUND_FILL, BORDER_CHANGE, CARET_POSITION_CHANGE, CONTENT_CHANGE, ECHO_CHAR_CHANGE, EDIT_MODE_CHANGE, FIRST_CHANGE, GRAPHIC_CONTENT_CHANGE, HALIGN_CENTER, HALIGN_JUSTIFY, HALIGN_LEFT, HALIGN_RIGHT, ITEM_VALUE_CHANGE, LAST_CHANGE, LIST_CONTENT_CHANGE, LIST_ICONSIZE_CHANGE, LIST_LABELSIZE_CHANGE, LIST_MULTISELECTION_CHANGE, LIST_SCROLLPOSITION_CHANGE, LIST_SELECTION_CHANGE, MIN_MAX_CHANGE, NO_BACKGROUND_FILL, NO_DEFAULT_HEIGHT, NO_DEFAULT_SIZE, NO_DEFAULT_WIDTH, ORIENTATION_CHANGE, REPEAT_COUNT_CHANGE, RESIZE_ARBITRARY, RESIZE_NONE, RESIZE_PRESERVE_ASPECT, SIZE_CHANGE, STATE_CHANGE, TEXT_CONTENT_CHANGE, TEXT_VALUE_CHANGE, THUMB_OFFSETS_CHANGE, UNKNOWN_CHANGE, VALIGN_BOTTOM, VALIGN_CENTER, VALIGN_JUSTIFY, VALIGN_TOP
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface org.havi.ui.HOrientable
ORIENT_BOTTOM_TO_TOP, ORIENT_LEFT_TO_RIGHT, ORIENT_RIGHT_TO_LEFT, ORIENT_TOP_TO_BOTTOM
 
Fields inherited from interface org.havi.ui.HState
ACTIONED_FOCUSED_STATE, ACTIONED_STATE, ACTIONED_STATE_BIT, ALL_STATES, DISABLED_ACTIONED_FOCUSED_STATE, DISABLED_ACTIONED_STATE, DISABLED_FOCUSED_STATE, DISABLED_STATE, DISABLED_STATE_BIT, FIRST_STATE, FOCUSED_STATE, FOCUSED_STATE_BIT, LAST_STATE, NORMAL_STATE
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
HListGroup()
          Creates an HListGroup object.
HListGroup(HListElement[] items)
          Creates an HListGroup object.
HListGroup(HListElement[] items, int x, int y, int width, int height)
          Creates an HListGroup object.
 
Method Summary
 void addHFocusListener(HFocusListener l)
          Adds the specified HFocusListener to receive HFocusEvent events sent from this HNavigable: If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.
 void addItem(HListElement item, int index)
          Add an item to this HListGroup.
 void addItemListener(HItemListener l)
          Adds the specified HItemListener to receive HItemEvents sent from this object.
 void addItems(HListElement[] items, int index)
          Add an array of items to this HListGroup.
 void clearSelection()
          Destroy the selection.
 int getCurrentIndex()
          Retrieve the current active item index, if one is currently chosen.
 HListElement getCurrentItem()
          Retrieve the current active item, if one has been chosen.
static HListGroupLook getDefaultLook()
          Returns the currently set default HLook for HListGroup components.
 HSound getGainFocusSound()
          Get the sound associated with the gain focus event.
 java.awt.Dimension getIconSize()
          Retrieve the icon size for this HListGroup.
 int getIndex(HListElement item)
          Retrieve the index position of an item in the content list.
 HListElement getItem(int index)
          Retrieve an item from the content list by index.
 java.awt.Dimension getLabelSize()
          Retrieve the label size for this HListGroup.
 HListElement[] getListContent()
          Retrieve the list content for this HListGroup.
 HSound getLoseFocusSound()
          Get the sound associated with the lost focus event.
 HNavigable getMove(int keyCode)
          Provides the HNavigable object that is navigated to when a particular key is pressed.
 boolean getMultiSelection()
          Return the multiple selection mode currently active for this HListGroup.
 int[] getNavigationKeys()
          Retrieve the set of key codes which this component maps to navigation targets.
 int getNumItems()
          Retrieve the number of items in the content list.
 int getNumSelected()
          Return the number of items which would be in the selection, if the HListGroup#getSelection method were called at this time.
 int getOrientation()
          Retrieve the orientation of the HListGroup.
 int getScrollPosition()
          Retrieve the scroll position of the HListGroup.
 HListElement[] getSelection()
          Get the selection from this HListGroup.
 int[] getSelectionIndices()
          Get the list of selection indices from this HListGroup.
 boolean getSelectionMode()
          Get the selection mode for this HListGroup.
 HSound getSelectionSound()
          Get the sound to be played when the selection changes.
 boolean isItemSelected(int index)
          Retrieve the selection state of a particular HListElement.
 boolean isSelected()
          Indicates if this component has focus.
 void processHFocusEvent(HFocusEvent evt)
          Process an HFocusEvent sent to this HListGroup.
 void processHItemEvent(HItemEvent evt)
          Process an HItemEvent sent to this HListGroup.
 void removeAllItems()
          Remove all the content.
 void removeHFocusListener(HFocusListener l)
          Removes the specified HFocusListener so that it no longer receives HFocusEvent events from this HNavigable.
 HListElement removeItem(int index)
          Remove the HListElement at the specified index.
 void removeItemListener(HItemListener l)
          Removes the specified HItemListener so that it no longer receives HItemEvents from this object.
 boolean setCurrentItem(int index)
          Set the current active item.
static void setDefaultLook(HListGroupLook look)
          Sets the default HLook for further HListGroup Components.
 void setFocusTraversal(HNavigable up, HNavigable down, HNavigable left, HNavigable right)
          Set the focus control for an HNavigable component.
 void setGainFocusSound(HSound sound)
          Associate a sound with gaining focus, i.e. when the HNavigable receives a HFocusEvent event of type FOCUS_GAINED.
 void setIconSize(java.awt.Dimension size)
          Set the icon size for this HListGroup.
 void setItemSelected(int index, boolean sel)
          Set the selection state of a particular HListElement.
 void setLabelSize(java.awt.Dimension size)
          Set the label size for this HListGroup.
 void setListContent(HListElement[] elements)
          Set the list content for this HListGroup.
 void setLook(HLook hlook)
          Sets the HLook for this component.
 void setLoseFocusSound(HSound sound)
          Associate a sound with losing focus, i.e. when the HNavigable receives a HFocusEvent event of type FOCUS_LOST.
 void setMove(int keyCode, HNavigable target)
          Defines the navigation path from the current HNavigable to another HNavigable when a particular key is pressed.
 void setMultiSelection(boolean multi)
          Set the multiple selection mode for this HListGroup.
 void setOrientation(int orient)
          Set the orientation of the HListGroup.
 void setScrollPosition(int scroll)
          Set the scroll position of the HListGroup.
 void setSelectionMode(boolean edit)
          Set the selection mode for this HListGroup.
 void setSelectionSound(HSound sound)
          Associate a sound to be played when the selection is modified.
 
Methods inherited from class org.havi.ui.HVisible
getAnimateContent, getBackgroundMode, getBordersEnabled, getContent, getDefaultSize, getGraphicContent, getHorizontalAlignment, getInteractionState, getLook, getLookData, getMaximumSize, getMinimumSize, getPreferredSize, getResizeMode, getTextContent, getTextLayoutManager, getVerticalAlignment, isFocusTraversable, isOpaque, paint, setAnimateContent, setBackgroundMode, setBordersEnabled, setContent, setDefaultSize, setEnabled, setGraphicContent, setHorizontalAlignment, setInteractionState, setLookData, setResizeMode, setTextContent, setTextLayoutManager, setVerticalAlignment, update
 
Methods inherited from class org.havi.ui.HComponent
getMatte, isDoubleBuffered, isEnabled, processEvent, setMatte
 
Methods inherited from class java.awt.Component
addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addNotify, addPropertyChangeListener, areFocusTraversalKeysSet, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, doLayout, enableEvents, enableInputMethods, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getCursor, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, hasFocus, imageUpdate, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isFocusable, isFocusCycleRoot, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, isVisible, list, list, list, list, list, paintAll, paramString, prepareImage, prepareImage, print, printAll, processComponentEvent, processFocusEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, setBackground, setBounds, setBounds, setCursor, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ITEM_NOT_FOUND

public static final int ITEM_NOT_FOUND
A constant which shall be returned from getIndex if the requested element is not found in the content.

See Also:
Constant Field Values

ADD_INDEX_END

public static final int ADD_INDEX_END
A constant for use with addItem and addItems which specifies that the new items shall be appended to the end of the list.

See Also:
Constant Field Values

DEFAULT_LABEL_WIDTH

public static final int DEFAULT_LABEL_WIDTH
A constant for use with setLabelSize and getLabelSize. When no call to setLabelSize has been made then getLabelSize will return this value for its default width. The default label width for all orientations is implementation specific.

See Also:
Constant Field Values

DEFAULT_LABEL_HEIGHT

public static final int DEFAULT_LABEL_HEIGHT
A constant for use with setLabelSize and getLabelSize. When no call to setLabelSize has been made then getLabelSize will return this value for its default height. The default label height for all orientations is the current font height.

See Also:
Constant Field Values

DEFAULT_ICON_WIDTH

public static final int DEFAULT_ICON_WIDTH
A constant for use with setIconSize and getIconSize. When no call to setIconSize has been made then getIconSize will return this value for its default width. The default icon width for all orientations is implementation specific.

See Also:
Constant Field Values

DEFAULT_ICON_HEIGHT

public static final int DEFAULT_ICON_HEIGHT
A constant for use with setIconSize and getIconSize. When no call to setIconSize has been made then getIconSize will return this value for its default height. The default icon height for all orientations is implementation specific.

See Also:
Constant Field Values
Constructor Detail

HListGroup

public HListGroup()
Creates an HListGroup object. See the class description for details of constructor parameters and default values.


HListGroup

public HListGroup(HListElement[] items)
Creates an HListGroup object. See the class description for details of constructor parameters and default values.


HListGroup

public HListGroup(HListElement[] items,
                  int x,
                  int y,
                  int width,
                  int height)
Creates an HListGroup object. See the class description for details of constructor parameters and default values.

Method Detail

setLook

public void setLook(HLook hlook)
             throws HInvalidLookException
Sets the HLook for this component.

Overrides:
setLook in class HVisible
Parameters:
hlook - The HLook that is to be used for this component. Note that this parameter may be null, in which case the component will not draw itself until a look is set.
Throws:
HInvalidLookException - If the Look is not an HListGroupLook.

setDefaultLook

public static void setDefaultLook(HListGroupLook look)
Sets the default HLook for further HListGroup Components.

Parameters:
look - The HLook that will be used by default when creating a new HListGroup component. Note that this parameter may be null, in which case newly created components shall not draw themselves until a non-null look is set using the setLook method.

getDefaultLook

public static HListGroupLook getDefaultLook()
Returns the currently set default HLook for HListGroup components.

Returns:
The HLook that is used by default when creating a new HListGroup component.

getListContent

public HListElement[] getListContent()
Retrieve the list content for this HListGroup.

Returns:
the list content or null if no content has been set.

setListContent

public void setListContent(HListElement[] elements)
Set the list content for this HListGroup. If any items are selected, then the selection shall be discarded and an HItemEvent with an ID of ITEM_SELECTION_CLEARED shall be generated and sent to all registered listeners.

If elements is null then the current active item index shall be set to ITEM_NOT_FOUND. If elements is not null then the current active item index shall be set to zero. An HItemEvent with an ID of ITEM_SET_CURRENT shall be sent to all registered listeners.

Parameters:
elements - the list content. If this parameter is null any existing content is removed.

addItem

public void addItem(HListElement item,
                    int index)
Add an item to this HListGroup. The item is inserted at the specified zero-based index in the content list. All following elements are shifted. If no content exists a new content list is created to contain the new item and the value of the index parameter is ignored.

If the act of adding a new item causes the current active item index to change, an HItemEvent shall be sent.

Note that items are stored in the content list by reference, they are not copied.

Parameters:
item - the item to add.
index - the index of the currently existing item which the new item should be placed at, or ADD_INDEX_END to append the new item to the end of the list. If this value is not a valid item index for this list a java.lang.IndexOutOfBoundsException shall be thrown.

addItems

public void addItems(HListElement[] items,
                     int index)
Add an array of items to this HListGroup. The items are inserted in the same order as they are in the array at the specified zero-based index. All following items are shifted. If no content exists a new content list is created to contain the new items and the value of the index parameter is ignored.

If the act of adding a new item causes the current active item index to change, an HItemEvent shall be sent.

Note that items are stored in the content list by reference, they are not copied.

Parameters:
items - the items to add.
index - the index of the currently existing item which the new items should be placed at, or ADD_INDEX_END to append the new items to the end of the list. If this value is not a valid item index for this list a java.lang.IndexOutOfBoundsException shall be thrown.

getItem

public HListElement getItem(int index)
Retrieve an item from the content list by index.

Parameters:
index - the index of the item to retrieve. If this parameter is negative a java.lang.IllegalArgumentException shall be thrown.
Returns:
the HListElement at the given index, or null if no such element exists.

getIndex

public int getIndex(HListElement item)
Retrieve the index position of an item in the content list.

Parameters:
item - the item to retrieve the index for.
Returns:
the index of the given HListElement, or ITEM_NOT_FOUND if no such element exists.

getNumItems

public int getNumItems()
Retrieve the number of items in the content list.

Returns:
the number of items in the content list, or 0 if no content has been set.

removeItem

public HListElement removeItem(int index)
Remove the HListElement at the specified index. All following items are shifted.

If the item is the only HListElement in this HListGroup then the current active item index shall be set to ITEM_NOT_FOUND. If the removal of the item causes a change of the current active item index, then an HItemEvent with an ID of ITEM_SET_CURRENT shall be generated and sent to all registered listeners.

If the item is selected then it shall be removed from the selection and an HItemEvent with an ID of ITEM_CLEARED shall be generated and sent to all registered listeners.

Parameters:
index - the index of the item to remove.
Returns:
the HListElement that has been removed or null if the index is not valid. No exception is thrown if index is not valid.
See Also:
getSelection()

removeAllItems

public void removeAllItems()
Remove all the content. If any items are selected, then the selection shall be discarded and an HItemEvent with an ID of ITEM_SELECTION_CLEARED shall be generated and sent to all registered listeners.

The current active item index shall be set to ITEM_NOT_FOUND and an HItemEvent with an ID of ITEM_SET_CURRENT shall be generated and sent to all registered listeners.

See Also:
getSelection()

getCurrentIndex

public int getCurrentIndex()
Retrieve the current active item index, if one is currently chosen. The current index is the index of the HListElement which would be selected or deselected should the user toggle the HListGroup. If there is no current element or there is no content set this method shall return ITEM_NOT_FOUND.

Returns:
the current item index, or ITEM_NOT_FOUND if no such item exists.

getCurrentItem

public HListElement getCurrentItem()
Retrieve the current active item, if one has been chosen. The current item is the HListElement which would be selected or deselected should the user toggle the HListGroup. If there is no current item or there is no content set this method shall return null.

Returns:
the current item, or null if no such item exists.

setCurrentItem

public boolean setCurrentItem(int index)
Set the current active item. The current item is the HListElement which would be selected or deselected should the user toggle the HListGroup.

If index is valid for this HListGroup then the current active item index shall be set to index. If this causes a change in the current active item index then an HItemEvent with an ID of ITEM_SET_CURRENT shall be generated and sent to all registered listeners.

Parameters:
index - the index of the new current item.
Returns:
true if the current item was changed, false if index was not a valid index for this HListGroup or the current item was not changed because it was already the current item. No exception is thrown if index is not valid.

getSelectionIndices

public int[] getSelectionIndices()
Get the list of selection indices from this HListGroup. The selection is defined as that set of HListElement indices which the user has caused to be selected by toggling the HListGroup.

Returns:
the index selection, or null if no items are selected. Only items which are currently part of the content for this HListGroup may be selected.

getSelection

public HListElement[] getSelection()
Get the selection from this HListGroup. The selection is defined as that set of HListElements which the user has caused to be selected by toggling the HListGroup.

Returns:
the selection, or null if no items are selected. Only items which are currently part of the content for this HListGroup may be selected.

clearSelection

public void clearSelection()
Destroy the selection. This method deselects any selected HListElement, but does not remove them from the HListGroup. After calling this method calls to getSelection shall return null until a new selection is made.

If the selection was not already empty, an HItemEvent shall be sent to any registered listeners.

See Also:
getSelection()

getNumSelected

public int getNumSelected()
Return the number of items which would be in the selection, if the HListGroup#getSelection method were called at this time.

Returns:
the number of selected items.

getMultiSelection

public boolean getMultiSelection()
Return the multiple selection mode currently active for this HListGroup. Multiple selection mode means that there may be more than one HListElement selected at a time.

Returns:
true if multiple selections are permitted, false otherwise.

setMultiSelection

public void setMultiSelection(boolean multi)
Set the multiple selection mode for this HListGroup. Multiple selection mode means that there may be more than one HListElement selected at a time.

Note that if the HListGroup is switched out of multiple selection mode and more than one item is selected, the selection shall change so that the first of the items is selected and the others are deselected. An HItemEvent with an ID of ITEM_CLEARED shall be sent to all registered listeners for each deselected item.

Parameters:
multi - true if multiple selections are to be permitted, false otherwise.

setItemSelected

public void setItemSelected(int index,
                            boolean sel)
Set the selection state of a particular HListElement.

If a call to this method causes an item to become deselected an HItemEvent with an ID of ITEM_CLEARED shall be sent to all registered listeners. This can happen because either sel is false or this HListGroup is not in multi selection mode.

If a call to this method causes a non selected item to become a selected item then an HItemEvent with an ID of ITEM_SELECTED shall be sent to all registered listeners.

Parameters:
index - the index of the HListElement to alter. A java.lang.IllegalArgumentException shall be thrown if this index is not valid for the HListGroup.
sel - true to select the given HListElement, false otherwise.

isItemSelected

public boolean isItemSelected(int index)
Retrieve the selection state of a particular HListElement.

Note that if multiple selections are not permitted only one HListElement may be selected at a time.

Parameters:
index - the index of the HListElement to query. A java.lang.IllegalArgumentException shall be thrown if this index is not valid for the HListGroup.
Returns:
true if the given HListElement is selected, false otherwise.

getScrollPosition

public int getScrollPosition()
Retrieve the scroll position of the HListGroup. The scroll position determines the first HListElement to be drawn when the HListGroupLook lays out the list.

Returns:
the current scroll position, or ITEM_NOT_FOUND if no content is set.

setScrollPosition

public void setScrollPosition(int scroll)
Set the scroll position of the HListGroup. The scroll position determines the first HListElement to be drawn when the HListGroupLook lays out the list. An IllegalArgumentException shall be thrown if scroll is not a valid scroll position.

It is an implementation option for HListGroupLook to draw elements before this first one, in order to fill the available space.

Valid scrollpositions conform to 0<= scrollposition< size. If no content is set there are no valid scrollpositions.

Parameters:
scroll - the scroll position

getIconSize

public java.awt.Dimension getIconSize()
Retrieve the icon size for this HListGroup. This size is the desired size of the area into which the HListGroupLook should render any image content of the HListElements. If label and icon size do not match the size per element, the associated HListGroupLook is allowed to use other sizes during the rendering process. This size shall be used by HListGroupLook to calculate the size per element.

Returns:
the icon size. If no size has been set then this method shall return new Dimension(DEFAULT_ICON_WIDTH, DEFAULT_ICON_HEIGHT).

setIconSize

public void setIconSize(java.awt.Dimension size)
Set the icon size for this HListGroup. This size is the desired size of the area into which the HListGroupLook should render any image content of the HListElements. If label and icon size do not match the size per element, the associated HListGroupLook is allowed to use other sizes during the rendering process. This size shall be used by HListGroupLook to calculate the size per element.

Parameters:
size - the icon size. If this parameter is new Dimension(DEFAULT_ICON_WIDTH, DEFAULT_ICON_HEIGHT) or null the HListGroup shall revert to using an implementation-specific icon size.

getLabelSize

public java.awt.Dimension getLabelSize()
Retrieve the label size for this HListGroup. This size is the desired size of the area into which the HListGroupLook should render any textual content of the HListElements. If label and icon size do not match the size per element, the associated HListGroupLook is allowed to use other sizes during the rendering process. This size shall be used by HListGroupLook to calculate the size per element.

Returns:
the label size. If no size has been set then this method shall return new Dimension(DEFAULT_LABEL_WIDTH, DEFAULT_LABEL_HEIGHT).

setLabelSize

public void setLabelSize(java.awt.Dimension size)
Set the label size for this HListGroup. This size is the desired size of the area into which the HListGroupLook should render any textual content of the HListElements. If label and icon size do not match the size per element, the associated HListGroupLook is allowed to use other sizes during the rendering process. This size shall be used by HListGroupLook to calculate the size per element.

Parameters:
size - the label size. If this parameter is new Dimension(DEFAULT_LABEL_WIDTH, DEFAULT_LABEL_HEIGHT) or null the HListGroup shall revert to using an implementation-specific label size.

setMove

public void setMove(int keyCode,
                    HNavigable target)
Defines the navigation path from the current HNavigable to another HNavigable when a particular key is pressed.

Note that setFocusTraversal is equivalent to multiple calls to setMove, where the key codes VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT are used.

Specified by:
setMove in interface HNavigable
Parameters:
keyCode - The key code of the pressed key. Any numerical keycode is allowed, but the platform may not be able to generate all keycodes. Application authors should only use keys for which HRcCapabilities.isSupported() or HKeyCapabilities.isSupported() returns true.
target - The target HNavigable object that should be navigated to. If a target is to be removed from a particular navigation path, then null shall be specified.

getMove

public HNavigable getMove(int keyCode)
Provides the HNavigable object that is navigated to when a particular key is pressed.

Specified by:
getMove in interface HNavigable
Parameters:
keyCode - The key code of the pressed key.
Returns:
Returns the HNavigable object or null if no HNavigable is associated with the keyCode.

setFocusTraversal

public void setFocusTraversal(HNavigable up,
                              HNavigable down,
                              HNavigable left,
                              HNavigable right)
Set the focus control for an HNavigable component. Note setFocusTraversal is a convenience function for application programmers where a standard up, down, left and right focus traversal between components is required.

Note setFocusTraversal is equivalent to multiple calls to setMove, where the key codes VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT are used.

Note that this API does not prevent the creation of "isolated" HNavigable components --- authors should endeavor to avoid confusing the user.

Specified by:
setFocusTraversal in interface HNavigable
Parameters:
up - The HNavigable component to move to, when the user generates a VK_UP KeyEvent. If there is no HNavigable component to move "up" to, then null shall be specified.
down - The HNavigable component to move to, when the user generates a VK_DOWN KeyEvent. If there is no HNavigable component to move "down" to, then null shall be specified.
left - The HNavigable component to move to, when the user generates a VK_LEFT KeyEvent. If there is no HNavigable component to move "left" to, then null shall be specified.
right - The HNavigable component to move to, when the user generates a VK_RIGHT KeyEvent. If there is no HNavigable component to move "right" to, then null shall be specified.

isSelected

public boolean isSelected()
Indicates if this component has focus.

Specified by:
isSelected in interface HNavigable
Returns:
true if the component has focus, otherwise returns false.

setGainFocusSound

public void setGainFocusSound(HSound sound)
Associate a sound with gaining focus, i.e. when the HNavigable receives a HFocusEvent event of type FOCUS_GAINED. This sound will start to be played when an object implementing this interface gains focus. It is not guaranteed to be played to completion. If the object implementing this interface loses focus before the audio completes playing, the audio will be truncated. Applications wishing to ensure the audio is always played to completion must implement special logic to slow down the focus transitions.

By default, an HNavigable object does not have any gain focus sound associated with it.

Note that the ordering of playing sounds is dependent on the order of the focus lost, gained events.

Specified by:
setGainFocusSound in interface HNavigable
Parameters:
sound - the sound to be played, when the component gains focus. If sound content is already set, the original content is replaced. To remove the sound specify a null HSound.

setLoseFocusSound

public void setLoseFocusSound(HSound sound)
Associate a sound with losing focus, i.e. when the HNavigable receives a HFocusEvent event of type FOCUS_LOST. This sound will start to be played when an object implementing this interface loses focus. It is not guaranteed to be played to completion. It is implementation dependent whether and when this sound will be truncated by any gain focus sound played by the next object to gain focus.

By default, an HNavigable object does not have any lose focus sound associated with it.

Note that the ordering of playing sounds is dependent on the order of the focus lost, gained events.

Specified by:
setLoseFocusSound in interface HNavigable
Parameters:
sound - the sound to be played, when the component loses focus. If sound content is already set, the original content is replaced. To remove the sound specify a null HSound.

getGainFocusSound

public HSound getGainFocusSound()
Get the sound associated with the gain focus event.

Specified by:
getGainFocusSound in interface HNavigable
Returns:
The sound played when the component gains focus. If no sound is associated with gaining focus, then null shall be returned.

getLoseFocusSound

public HSound getLoseFocusSound()
Get the sound associated with the lost focus event.

Specified by:
getLoseFocusSound in interface HNavigable
Returns:
The sound played when the component loses focus. If no sound is associated with losing focus, then null shall be returned.

addHFocusListener

public void addHFocusListener(HFocusListener l)
Adds the specified HFocusListener to receive HFocusEvent events sent from this HNavigable: If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.

Specified by:
addHFocusListener in interface HNavigable
Parameters:
l - the HFocusListener to add

removeHFocusListener

public void removeHFocusListener(HFocusListener l)
Removes the specified HFocusListener so that it no longer receives HFocusEvent events from this HNavigable. If the specified listener is not registered, the method has no effect. If multiple references to a single listener have been registered it should be noted that this method will only remove one reference per call.

Specified by:
removeHFocusListener in interface HNavigable
Parameters:
l - the HFocusListener to remove

getNavigationKeys

public int[] getNavigationKeys()
Retrieve the set of key codes which this component maps to navigation targets.

Specified by:
getNavigationKeys in interface HNavigationInputPreferred
Returns:
an array of key codes, or null if no navigation targets are set on this component.

processHFocusEvent

public void processHFocusEvent(HFocusEvent evt)
Process an HFocusEvent sent to this HListGroup.

Specified by:
processHFocusEvent in interface HNavigationInputPreferred
Parameters:
evt - the HFocusEvent to process.

getOrientation

public int getOrientation()
Retrieve the orientation of the HListGroup. The orientation controls how an associated HLook lays out the component and affects the visual behavior of HItemEvent events.

Specified by:
getOrientation in interface HOrientable
Returns:
one of ORIENT_LEFT_TO_RIGHT, ORIENT_RIGHT_TO_LEFT, ORIENT_TOP_TO_BOTTOM, or ORIENT_BOTTOM_TO_TOP.

setOrientation

public void setOrientation(int orient)
Set the orientation of the HListGroup. The orientation controls the layout of the component.

Specified by:
setOrientation in interface HOrientable
Parameters:
orient - one of ORIENT_LEFT_TO_RIGHT, ORIENT_RIGHT_TO_LEFT, ORIENT_TOP_TO_BOTTOM, or ORIENT_BOTTOM_TO_TOP.

addItemListener

public void addItemListener(HItemListener l)
Adds the specified HItemListener to receive HItemEvents sent from this object. If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.

Specified by:
addItemListener in interface HItemValue
Parameters:
l - the HItemListener to be notified.

removeItemListener

public void removeItemListener(HItemListener l)
Removes the specified HItemListener so that it no longer receives HItemEvents from this object. If the specified listener is not registered, the method has no effect. If multiple references to a single listener have been registered it should be noted that this method will only remove one reference per call.

Specified by:
removeItemListener in interface HItemValue
Parameters:
l - the HItemListener to be removed from notification.

setSelectionSound

public void setSelectionSound(HSound sound)
Associate a sound to be played when the selection is modified. The sound is played irrespective of whether an HItemEvent is sent to one or more listeners.

Specified by:
setSelectionSound in interface HItemValue
Parameters:
sound - the sound to be played, when the selection is modified. If sound content is already set, the original content is replaced. To remove the sound specify a null HSound.

getSelectionSound

public HSound getSelectionSound()
Get the sound to be played when the selection changes.

Specified by:
getSelectionSound in interface HItemValue
Returns:
The sound played when the selection changes

getSelectionMode

public boolean getSelectionMode()
Get the selection mode for this HListGroup. If the returned value is true the component is in selection mode, and the selection may be changed.

The component is switched into and out of selection mode on receiving HItemEvent.ITEM_START_CHANGE and HItemEvent.ITEM_END_CHANGE events. Note that these events are ignored, if the component is disabled.

Specified by:
getSelectionMode in interface HSelectionInputPreferred
Returns:
true if this component is in selection mode, false otherwise.
See Also:
HComponent.setEnabled(boolean)

setSelectionMode

public void setSelectionMode(boolean edit)
Set the selection mode for this HListGroup.

This method is provided for the convenience of component implementors. Interoperable applications shall not call this method. It cannot be made protected because interfaces cannot have protected methods.

Calls to this method shall be ignored, if the component is disabled.

Specified by:
setSelectionMode in interface HSelectionInputPreferred
Parameters:
edit - true to switch this component into selection mode, false otherwise.
See Also:
HComponent.setEnabled(boolean), HSelectionInputPreferred.getSelectionMode()

processHItemEvent

public void processHItemEvent(HItemEvent evt)
Process an HItemEvent sent to this HListGroup.

Widgets implementing this interface shall ignore HItemEvents, while the component is disabled.

Specified by:
processHItemEvent in interface HSelectionInputPreferred
Parameters:
evt - the HItemEvent to process.
See Also:
HComponent.setEnabled(boolean)