HListGroup

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.havi.ui
Class HListGroup

    java.lang.Object
      java.awt.Component
          org.havi.ui.HComponent
              org.havi.ui.HVisible
                  org.havi.ui.HListGroup

All Implemented Interfaces:
  ImageObserver, Serializable, TestOpacity, HItemValue, HMatteLayer, HNavigable, HNavigationInputPreferred, HOrientable, HSelectionInputPreferred, HState

    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:

- When the component has focus, sending an `ITEM_START_CHANGE` event to the component causes it to enter selection mode.
- When the component has focus, sending an `ITEM_END_CHANGE` event to the component causes it to leave selection mode.
- When the component has focus and is in selection mode, the current item can be set by sending `ITEM_SET_CURRENT`, `ITEM_SET_PREVIOUS` and `ITEM_SET_NEXT` events to the component.
- When the component has focus and is in selection mode, sending an `ITEM_TOGGLE_SELECTED` event causes the current item to be toggled between a selected and unselected state.
- Irrespective of focus and selection mode, sending an `ITEM_SELECTION_CLEARED` event to the component causes the current selection set to be cleared.
- HListGroup will respond to `HItemEvent` with id SCROLL_PAGE_MORE or SCROLL_PAGE_LESS by adjusting the scrollposition with the value returned by HListGroupLook.getNumVisible(HVisible visible), or an implementation- specific value if no look has been set on this widget.

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

- uses the `HTextLayoutManager` to render text from the elements. `HListGroup` is not required to respect the default horizontal and vertical content alignments specified by `HVisible`. For `HListGroup` these defaults are implementation specific. Application programmers who require a specific alignment policy must therefore make explicit calls to `setHorizontalAlignment` and `setVerticalAlignment` to enforce the alignments required.
- the resize mode as defined by `HVisible` determines how the icons are scaled.
- focus traversal applies to the entire list component. The elements in the list are not components in their own right and never receive focus. The concept of the current element is handled through `HItemEvent` events.
- for the purpose of layout management of the `HListGroup` component, the following constraints are applied:

  1. the minimum size is the size to present one element or an implementation specific minimum (32 x 32 for example) if label and icon size are not set (see `HListGroupLook.getMinimumSize(org.havi.ui.HVisible)`).
  2. the preferred size is that set by `setDefaultSize` rounded down to the nearest element (minimum of one) or the size required to present 5 elements if a default size is not set.
  3. the maximum size is that required to present all elements.

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

Parameter | Description | Default value | Set method | Get 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

Description | Default value | Set 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.
`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.
`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.
`void` | `setIconSize(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(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.
`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, setLookData, setResizeMode, setTextContent, setTextLayoutManager, setVerticalAlignment, update`

Methods inherited from class org.havi.ui.HComponent
`getMatte, isDoubleBuffered, isEnabled, setMatte`

Methods inherited from class java.awt.Component
`addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addNotify, addPropertyChangeListener, areFocusTraversalKeysSet, checkImage, checkImage, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, dispatchEvent, doLayout, enableInputMethods, 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, prepareImage, prepareImage, print, printAll, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, 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
`equals, 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 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(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 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(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 `ITEM_START_CHANGE` and `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 `HItemEvent`a, while the component is disabled.

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD