Package org.luwrain.controls

Class ListArea<E>

java.lang.Object
org.luwrain.controls.ListArea<E>
Type Parameters:
E - the type of items in the list
All Implemented Interfaces:
ClipboardTranslator.Provider, RegionTextQueryTranslator.Provider, Area, HotPoint, Lines
Direct Known Subclasses:
CommanderArea, EditableListArea, ListPopup2, ListPopupBase, MarkableListArea, TreeListArea
public class ListArea<E> extends Object implements Area, ClipboardTranslator.Provider, RegionTextQueryTranslator.Provider
A generic list area that displays a model of items and allows navigation, selection, clipboard operations, and custom appearance. The list area integrates with the LUWRAIN area management, handling input events, system events, and area queries.

The class is parameterized by the type of item <E>. It uses a ListArea.Model to provide the data, an ListArea.Appearance to control how items are displayed and announced, a ListArea.Transition to define movement behaviour, and a ListArea.ClipboardSaver for clipboard operations.

The list can optionally have an empty line at the top and/or bottom, and can announce the selected item when the area is introduced.

  • Field Details

  • Constructor Details

    • ListArea

      public ListArea(ListArea.Params<E> params)
      Constructs a new list area with the given parameters.
      Parameters:
      params - the configuration parameters (must not be null)
      Throws:
      NullPointerException - if params or any required field is null

  • Method Details

    • setListClickHandler

      public void setListClickHandler(ListArea.ClickHandler<E> clickHandler)
      Sets the click handler for item activation.
      Parameters:
      clickHandler - the handler to set (may be null)

    • getListModel

      public ListArea.Model<E> getListModel()
      Returns the data model used by this list.
      Returns:
      the model

    • getListAppearance

      public ListArea.Appearance<E> getListAppearance()
      Returns the appearance controller used by this list.
      Returns:
      the appearance

    • selected

      public final E selected()
      Returns the object in the model corresponding to current hot point position. If the model is empty or hot point is on an empty line, this method always returns null.
      Returns:
      The object in the model associated with the currently selected line or null if there is no any

    • selectedIndex

      public final int selectedIndex()
      The index of the item in the model which is under the hot point in this list. This method returns the index in the model, not on the screen. It means that the value returned by this method may be different than the value returned by getHotPointY() (but may be equal as well). If the list is empty or an empty line is selected, this method returns -1.
      Returns:
      The index of the selected line in the model or -1 if there is no any

    • select

      public boolean select(E obj, boolean announce)
      Searches for the item in the model and sets hot point on it. Given an arbitrary object, this method looks through all items in the model and does a couple of checks: literal pointers equality and a check with equals() method. If at least one of these checks succeeds, the item is considered equal to the given one, and hot points is set on it.
      Parameters:
      obj - The object to search for
      announce - Must be true if it is necessary to introduce the object, once it's found
      Returns:
      True if the request object is found, false otherwise

    • select

      public boolean select(int index, boolean announce)
      Selects the item by its index. Given the non-negative integer value as an index, this method sets the hot point on the item addressed with this index, checking only that index is in appropriate bounds. Index must address the object as a number in the model, ignoring any empty lines.
      Parameters:
      index - The item index to select
      announce - Must be true, if it is necessary to announce the item , once it has been selected
      Returns:
      True if the index is valid and the item gets hot point on it

    • selectEmptyLineBottom

      public boolean selectEmptyLineBottom(boolean announce)
      Moves the hot point to the bottom empty line, if the list has one.
      Parameters:
      announce - if true, the empty line is announced
      Returns:
      true if the operation succeeded, false if there is no bottom empty line

    • getExistingItemIndexOnLine

      public int getExistingItemIndexOnLine(int lineIndex)
      Given a line index (screen coordinate), returns the corresponding item index in the model, or -1 if the line does not contain a valid item.
      Parameters:
      lineIndex - the screen line index (non-negative)
      Returns:
      the model index, or -1 if not on an item
      Throws:
      IllegalArgumentException - if lineIndex is negative

    • getItemIndexOnLine

      public int getItemIndexOnLine(int index)
      Converts a screen line index to a model index, without checking whether the resulting index is within the model bounds. This is used internally for calculations.
      Parameters:
      index - the screen line index
      Returns:
      the model index (may be out of bounds)

    • getLineIndexByItemIndex

      public int getLineIndexByItemIndex(int index)
      Converts a model item index to the corresponding screen line index.
      Parameters:
      index - the model index
      Returns:
      the screen line index, or -1 if the index is invalid

    • getItemOnLine

      public E getItemOnLine(int lineIndex)
      Returns the item displayed on the given screen line.
      Parameters:
      lineIndex - the screen line index (non-negative)
      Returns:
      the item, or null if the line is empty or out of range
      Throws:
      IllegalArgumentException - if lineIndex is negative

    • getListItemCount

      public int getListItemCount()
      Returns the total number of items in the model.
      Returns:
      the item count

    • reset

      public void reset(boolean announce)
      Resets the region point and the hot point to the beginning of the list.
      Parameters:
      announce - if true, the newly selected item is announced

    • resetHotPoint

      public void resetHotPoint()
      Resets the hot point to the first item (or the top empty line if the list is empty) without any announcement.

    • resetHotPoint

      public void resetHotPoint(boolean introduce)
      Resets the hot point to the first item (or the top empty line if the list is empty).
      Parameters:
      introduce - if true, the newly selected item is announced

    • announceSelected

      public void announceSelected()
      Announces the currently selected item using the appearance.

    • refresh

      public void refresh()
      Refreshes the content of the list. This method calls refresh() method of the model and displays new items. It does not produce any speech announcement of the change. HotPointY is preserved if it is possible (meaning, the new number of lines not less than old value of hotPointY), but hotPointX is moved to the beginning of the line.

    • redraw

      public void redraw()
      Redraws the area content and adjusts the hot point similarly to refresh(), but without calling Model.refresh().

    • isEmpty

      public boolean isEmpty()
      Checks whether the list model contains any items.
      Returns:
      true if the model is empty, false otherwise

    • onInputEvent

      public boolean onInputEvent(InputEvent event)
      Specified by:
      onInputEvent in interface Area

    • onSystemEvent

      public boolean onSystemEvent(SystemEvent event)
      Specified by:
      onSystemEvent in interface Area

    • onAreaQuery

      public boolean onAreaQuery(AreaQuery query)
      Specified by:
      onAreaQuery in interface Area

    • getAreaActions

      public Action[] getAreaActions()
      Specified by:
      getAreaActions in interface Area

    • getLineCount

      public int getLineCount()
      Specified by:
      getLineCount in interface Lines

    • getLine

      public String getLine(int index)
      Specified by:
      getLine in interface Lines

    • getHotPointX

      public int getHotPointX()
      Specified by:
      getHotPointX in interface Area
      Specified by:
      getHotPointX in interface HotPoint

    • getHotPointY

      public int getHotPointY()
      Specified by:
      getHotPointY in interface Area
      Specified by:
      getHotPointY in interface HotPoint

    • getAreaName

      public String getAreaName()
      Specified by:
      getAreaName in interface Area

    • setAreaName

      public void setAreaName(String areaName)
      Sets the area name and notifies the context of the change.
      Parameters:
      areaName - the new area name (must not be null)
      Throws:
      NullPointerException - if areaName is null

    • onAnnounce

      protected boolean onAnnounce()
      Announces the list area. If the area is created with AREA_ANNOUNCE_SELECTED flag, this method speaks the screen text of the currently selected item or the area name otherwise (without the flag or if there is no selected item).

    • onAnnounceLine

      protected boolean onAnnounceLine()
      Announces the current line (the item under the hot point).
      Returns:
      true if the announcement was handled

    • onMoveHotPoint

      protected boolean onMoveHotPoint(MoveHotPointEvent event)
      Handles a MoveHotPointEvent to reposition the hot point.
      Parameters:
      event - the event (must not be null)
      Returns:
      true if the hot point was moved

    • onBeginListeningQuery

      protected boolean onBeginListeningQuery(BeginListeningQuery query)
      Handles a BeginListeningQuery to start continuous reading from the current hot point position.
      Parameters:
      query - the query (must not be null)
      Returns:
      true if the query was answered

    • onListeningFinishedEvent

      protected boolean onListeningFinishedEvent(ListeningFinishedEvent event)
      Handles the completion of a listening session, moving the hot point to the position where listening stopped.
      Parameters:
      event - the event (must not be null)
      Returns:
      true if the hot point was updated

    • onChar

      protected boolean onChar(InputEvent event)
      Handles character input for incremental search. Moves the hot point to the first item whose observable text starts with the accumulated prefix.
      Parameters:
      event - the input event
      Returns:
      true if the character was processed

    • onMoveDown

      protected boolean onMoveDown(InputEvent event, boolean briefAnnouncement)
      Handles the "move down" command.
      Parameters:
      event - the input event
      briefAnnouncement - if true, use brief announcement
      Returns:
      true if handled

    • onMoveUp

      protected boolean onMoveUp(InputEvent event, boolean briefAnnouncement)
      Handles the "move up" command.
      Parameters:
      event - the input event
      briefAnnouncement - if true, use brief announcement
      Returns:
      true if handled

    • onPageDown

      protected boolean onPageDown(InputEvent event, boolean briefAnnouncement)
      Handles the "page down" command.
      Parameters:
      event - the input event
      briefAnnouncement - if true, use brief announcement
      Returns:
      true if handled

    • onPageUp

      protected boolean onPageUp(InputEvent event, boolean briefAnnouncement)
      Handles the "page up" command.
      Parameters:
      event - the input event
      briefAnnouncement - if true, use brief announcement
      Returns:
      true if handled

    • onEnd

      protected boolean onEnd(InputEvent event)
      Handles the "end" command (jump to last item).
      Parameters:
      event - the input event
      Returns:
      true if handled

    • onHome

      protected boolean onHome(InputEvent event)
      Handles the "home" command (jump to first item).
      Parameters:
      event - the input event
      Returns:
      true if handled

    • onTransition

      protected boolean onTransition(ListArea.Transition.Type type, Hint hint, boolean briefAnnouncement)
      Performs a transition based on the given type, using the current state and the list's transition logic.
      Parameters:
      type - the type of transition
      hint - the hint to provide if no transition is possible
      briefAnnouncement - if true, use brief announcement
      Returns:
      true if the transition was processed

    • onMoveRight

      protected boolean onMoveRight(InputEvent event)
      Handles the "move right" command (character by character).
      Parameters:
      event - the input event
      Returns:
      true if handled

    • onMoveLeft

      protected boolean onMoveLeft(InputEvent event)
      Handles the "move left" command (character by character).
      Parameters:
      event - the input event
      Returns:
      true if handled

    • onAltRight

      protected boolean onAltRight(InputEvent event)
      Handles the alternative right command (move by word forward).
      Parameters:
      event - the input event
      Returns:
      true if handled

    • onAltLeft

      protected boolean onAltLeft(InputEvent event)
      Handles the alternative left command (move by word backward).
      Parameters:
      event - the input event
      Returns:
      true if handled

    • onAltEnd

      protected boolean onAltEnd(InputEvent event)
      Handles the alternative end command (jump to the end of the line).
      Parameters:
      event - the input event
      Returns:
      true if handled

    • onAltHome

      protected boolean onAltHome(InputEvent event)
      Handles the alternative home command (jump to the beginning of the line).
      Parameters:
      event - the input event
      Returns:
      true if handled

    • onEnter

      protected boolean onEnter(InputEvent event)
      Handles the Enter key activation.
      Parameters:
      event - the input event
      Returns:
      true if the click was handled

    • onOk

      protected boolean onOk(SystemEvent event)
      Handles the OK system event (alternative activation).
      Parameters:
      event - the system event
      Returns:
      true if the click was handled

    • onRegionTextQuery

      public String onRegionTextQuery(int fromX, int fromY, int toX, int toY)
      Specified by:
      onRegionTextQuery in interface RegionTextQueryTranslator.Provider

    • onClipboardCopyAll

      public boolean onClipboardCopyAll()
      Specified by:
      onClipboardCopyAll in interface ClipboardTranslator.Provider

    • onClipboardCopy

      public boolean onClipboardCopy(int fromX, int fromY, int toX, int toY, boolean withDeleting)
      Specified by:
      onClipboardCopy in interface ClipboardTranslator.Provider

    • onDeleteRegion

      public boolean onDeleteRegion(int fromX, int fromY, int toX, int toY)
      Specified by:
      onDeleteRegion in interface ClipboardTranslator.Provider

    • onNewHotPointY

      protected void onNewHotPointY(boolean briefAnnouncement)
      Called after the hot point Y coordinate changes. Updates the hot point X to the left bound of the new item and announces it.
      Parameters:
      briefAnnouncement - if true, use brief announcement

    • getObservableSubstr

      protected String getObservableSubstr(E item)
      Returns the observable substring of an item's screen representation, i.e., the part between its left and right bounds.
      Parameters:
      item - the item (must not be null)
      Returns:
      the observable substring, or an empty string if not applicable

    • noContentStr

      protected String noContentStr()
      Returns the string to display when the list has no content.
      Returns:
      the "no content" string

    • announceChar

      protected void announceChar(String line, int pos, int rightBound)
      Announces a character at the given position, or a line bound hint if at the end.
      Parameters:
      line - the full line text
      pos - the current hot point column
      rightBound - the right observable bound

    • noContent

      protected boolean noContent()
      Checks whether the list has no content and, if so, sets an appropriate hint response.
      Returns:
      true if the list is empty, false otherwise