HorizontalCaretMovementRun class

The consecutive sequence of TextPositions that the caret should move to when the user navigates the paragraph using the left arrow key or the right arrow key.

When the user presses the left arrow key or the right arrow key, on many platforms (macOS for instance), the caret will move to the previous line or the next line, while maintaining its original horizontal location. When it encounters a shorter line, the caret moves to the closest horizontal location within that line, and restores the original horizontal location when a long enough line is encountered.

Additionally, the caret will move to the beginning of the document if the left arrow key is pressed and the caret is already on the first line. If the right arrow key is pressed next, the caret will restore its original horizontal location and move to the second line. Similarly the caret moves to the end of the document if the right arrow key is pressed when it's already on the last line.

Consider a top-aligned paragraph: a a a a a —— a where the caret was initially placed at the end of the first line. Pressing the right arrow key once will move the caret to the end of the second line, and twice the arrow key moves to the third line after the second "a" on that line. Pressing the right arrow key again, the caret will move to the end of the third line (the end of the document). Pressing the left arrow key in this state will result in the caret moving to the end of the second line.

Horizontal caret runs are typically interrupted when the layout of the text changes (including when the text itself changes), or when the selection is changed by other input events or programmatically (for example, when the user pressed the up arrow key).

The movePrevious method moves the caret location (which is HorizontalCaretMovementRun.current) to the previous line, and in case the caret is already on the first line, the method does nothing and returns false. Similarly the moveNext method moves the caret to the next line, and returns false if the caret is already on the last line.

If the underlying paragraph's layout changes, isValid becomes false and the HorizontalCaretMovementRun must not be used. The isValid property must be checked before calling movePrevious and moveNext, or accessing current.