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

Navigation in text areas

This section describes how to interact with text areas built on top of the NavigationArea component in the LUWRAIN platform. This component is designed specifically for non-visual and low-vision access, providing efficient ways to read, navigate, and select text using a keyboard.

When you are focused on a text area, you can use standard keyboard shortcuts to move the cursor (called the "hot point" in LUWRAIN) and read the content:

  • Up Arrow / Down Arrow: Moves the cursor to the previous or next line. The system will announce the new line. If you reach the top or bottom of the text, you will hear a warning message.
  • Left Arrow / Right Arrow: Moves the cursor by a single character. The system will announce the character you just passed. If you reach the end of a line, moving right will automatically wrap to the beginning of the next line.
  • Ctrl + Left Arrow / Ctrl + Right Arrow: Moves the cursor by whole words. The system will announce the word you just jumped over. This is useful for skimming through a line quickly.

Jumping Through Text

For faster navigation across larger documents, you can use the following shortcuts:

  • Home: Jumps directly to the beginning of the current line and announces the first character.
  • End: Jumps directly to the end of the current line.
  • Alt + Home: Jumps directly to the very beginning of the entire text.
  • Alt + End: Jumps directly to the very end of the entire document.
  • Page Up / Page Down: Jumps to the previous or next block of text (usually a paragraph). The system defines a block as text separated by an empty line. Upon jumping, the first line of the new block is announced.

The component fully supports copying text to the system clipboard. You can select regions of text using standard selection commands provided by the LUWRAIN environment, and copy them for use in other applications.

Developer notes

The NavigationArea class is an abstract base class implementing the Area interface. It provides a ready-to-use implementation of standard keyboard navigation, cursor (hot point) management, and clipboard operations for static text.

In the LUWRAIN architecture, an Area is a fundamental visual and interactive entity. The NavigationArea simplifies the creation of text-based areas by handling the boilerplate logic for the "hot point" (represented by hotPointX and hotPointY).

Because NavigationArea does not store data itself, any class extending it must provide the actual text data by implementing the following methods from the Lines interface:

  • getLine(int index): Returns the string representation of a specific line.
  • getLineCount(): Returns the total number of lines. Note that an Area must never return 0; an empty area should return 1 and yield an empty string.

Event Handling

The class overrides onInputEvent(InputEvent event) to catch standard navigation keys. It maps special keys to protected methods, allowing developers to override specific behaviors if needed:

  • onMoveUp(), onMoveDown(), onMoveLeft(), onMoveRight()
  • onAltLeft(), onAltRight() (Word iteration using WordIterator)
  • onHome(), onEnd(), onAltHome(), onAltEnd()
  • onPageUp(), onPageDown() (Paragraph navigation based on isBlockBoundLine())

It also handles system events via onSystemEvent(SystemEvent event), specifically processing MoveHotPointEvent to programmatically move the cursor, as well as delegating clipboard and text query events to ClipboardTranslator and RegionTextQueryTranslator.

Speech Announcements

LUWRAIN relies on the concept of EventResponse to produce speech. The NavigationArea automatically generates appropriate responses during navigation. For example, moving down a line triggers announceLine(), which defaults to defaultLineAnnouncement(). This method handles edge cases, such as announcing Hint.EMPTY_LINE for blank lines or Hint.SPACES for lines containing only whitespace.

Developers can override announceLine(int index, String line) to customize how a line is read to the user.

Hot Point Transactions

When performing complex operations that might move the cursor multiple times internally, developers should wrap the logic in a transaction to prevent excessive screen updates or speech spam:

  1. Call beginHotPointTrans().
  2. Update hotPointX and hotPointY.
  3. Call endHotPointTrans(). This will notify the ControlContext via onAreaNewHotPoint() only once the transaction counter reaches zero.

Clipboard and Text Queries

The class implements ClipboardTranslator.Provider and RegionTextQueryTranslator.Provider. It initializes internal helpers (LinesClipboardProvider and LinesRegionTextQueryProvider) to automatically support copying text regions, copying all text, and querying text for external clipboard tools. The selection state is maintained by the internal regionPoint object.