Downloads Sources Documentation
Basic principals Support of user scripts Your own app Javadoc Who we are?

List area

Below you will find a detailed User Manual and a Developer Guide for the list area control in the LUWRAIN platform. This control is implemented by org.luwrain.controls.ListArea class. it is a core user interface element in the LUWRAIN platform designed to present a list of items. Using list area, users get efficient ways to navigate, read, search, and copy information.

To navigate through the items in a list area you can use standard keyboard commands:

  • Up Arrow / Down Arrow: Move to the previous or next item in the list. LUWRAIN will announce the newly selected item.
  • Page Up / Page Down: Jump multiple items up or down to scroll through large lists quickly.
  • Home / End: Instantly jump to the very first or the very last item of the list.

If you want to explore the text of a currently selected item in detail, you can move the reading cursor (the hot point) horizontally:

  • Left Arrow / Right Arrow: Read the current item character by character.
  • Alt + Left Arrow / Alt + Right Arrow: Read the current item word by word.
  • Alt + Home / Alt + End: Move the cursor directly to the beginning or to the end of the current line.

When you find an item you want to interact with , press the Enter key. Depending on the specific application, this will trigger an action, such as opening a file, following a link, or confirming a selection.

If you know the name of the item you are looking for , you can quickly find it by typing its name on the keyboard. As you type letters, the list area will automatically move the selection to the first item that begins with the characters you entered.

The list area controls supports system clipboard commands:

  • You can copy the currently selected item to the clipboard.
  • You can select a region of text and copy only a specific part of an item.
  • You can use the "Copy All" command to save the entire list of items to the clipboard.

Depending on how the application is configured, a list area control might contain an empty line at the top or at the bottom. These empty lines are often used to drop the selection or to indicate the boundaries of the list. LUWRAIN will explicitly announce "Empty line" when you navigate to them.

Developer Guide

The org.luwrain.controls.ListArea is a generic class parameterized by the type <E>, which represents the data entity of a single list item. It relies on a modular architecture, separating data (Model), presentation (Appearance), and behavior (Transition, ClickHandler).

To use a ListArea class, you must implement several core interfaces:

The Model<E> Interface

This interface provides the underlying data for the list.

  • getItemCount(): Returns the total number of items.
  • getItem(int index): Returns the object of type <E> at the specified index.
  • refresh(): Called when the data source changes and needs to be reloaded.

The Appearance<E> Interface

This interface dictates how an item is presented on the screen and how it is spoken.

  • announceItem(E item, Set<Flags> flags): Sends the speech representation of the item to the screen reader.
  • getScreenAppearance(E item, Set<Flags> flags): Returns the visual string representation of the item.
  • getObservableLeftBound(E item) and getObservableRightBound(E item): Define the interactive text boundaries for horizontal character-by-character navigation.

The ClickHandler<E> Interface (Optional)

Implement this interface to handle user activation (e.g., when the user presses Enter).

  • onListClick(ListArea<E> area, int index, E item): Define the logic to execute when an item is activated. Return true if the event was handled.

Configuration and Initialization

To instantiate a ListArea, you must build a ListArea.Params object. This parameters object ensures that all required dependencies are injected before the area is created.

ListArea.Params<MyItem> params = new ListArea.Params<>();
params.context = getControlContext(); // Provided by the LUWRAIN environment
params.model = new MyListModel();
params.appearance = new MyListAppearance();
params.name = "My custom list";

Using ListArea.Flags

You can customize the behavior of the list using the ListArea.Flags enumeration inside your ListArea.Params:

  • EMPTY_LINE_TOP: Adds an empty, selectable line at the beginning of the list.
  • EMPTY_LINE_BOTTOM: Adds an empty, selectable line at the end of the list (enabled by default).
  • AREA_ANNOUNCE_SELECTED: When the area gains focus, it will announce the currently selected item instead of the area name.

Example of setting flags:

params.flags = EnumSet.of(ListArea.Flags.EMPTY_LINE_BOTTOM, ListArea.Flags.AREA_ANNOUNCE_SELECTED);

Advanced Customization

  • Custom Navigation: By default, the list uses ListUtils.DefaultTransition. If you need complex navigation logic (e.g., skipping certain disabled items), you can implement the ListArea.Transition interface and assign it to params.transition.
  • Custom Clipboard Formatting: If you want to change how items are formatted when a user copies them to the clipboard, implement the ListArea.ClipboardSaver interface and assign it to params.clipboardSaver.

Programmatic Control

Once the ListArea is created, you can control it programmatically:

  • select(int index, boolean announce): Moves the hot point to a specific index.
  • select(E obj, boolean announce): Searches for a specific object in the model and selects it.
  • refresh(): Forces the list to reload data from the Model and updates the screen.
  • redraw(): Updates the screen without calling the refresh method on the underlying Model.
  • selected(): Returns the currently selected object of type <E>.
  • selectedIndex(): Returns the index of the currently selected item.