Add API: get the line index of the caret in a multi-line paragraph/viewport

[JordanMartinez]

Implements feature requested in #386:

It would be convenient if there was a getLineNumber() method that indicated the line number within the current paragraph, such as:

StyleClassedTextArea editor = // ...
Paragraph p = editor.getCurrentParagraph();
int n = p.getLineNumber();

Asking the editor's line number should give the line number from the top of the text area (starting from line 1), not the current paragraph. Also, using natural numbers seems like a good fit, as opposed to whole numbers, for line numbers.

[JordanMartinez]

@DaveJarvis In this PR, the method getCaretLineIndexInParagraph makes sense to me, but what about the second one? Looking at previous comments in other unrelated issues, it seems you wanted the second method so that you can have more accurate scrolling capabilities. However, I don't know how much such a method will help in that case. What is your use case?

[ghost]

I've changed the way scrolling is implemented.

The problem I had was this: Given a plain Markdown, R Markdown, XML, or R XML file to edit, ensure that the HTML preview of the edited content is scrolled such that the cursor position is reflected. The editor is now completely decoupled from the preview pane so that processors can inject a hidden element within the text at the caret offset during processing. In other words, a token is passed along from editor, through various links of a processor chain (chain-of-responsibility pattern), and written as a <span> element in the preview, which is used to synchronize the preview with the editor's caret offset.

Issue #386 now, which allows efficient editing by enabling the use of Home/End keys to perform the expected behaviour, is outstanding. As it stands, the name getCaretLineIndexInParagraph() seems a bit clunky and counter-intuitive. Here's what seems to be a bit more OOP-ish:

// Get a handle to the paragraph that contains the caret.
Paragraph p = editor.getCaretParagraph();

// Throws InvalidCaretParagraphException if the paragraph doesn't contain the caret.
int line = p.getCaretLineNumber();

// Returns the number of lines in the paragraph (unused in this example, but useful).
int tally = p.getLineCount();

// Move the caret to the start of the line; i.e., Home key
editor.moveTo( p, line, 0 );

// Find the number of columns for the caret's line.
int column = p.getColumnCount( line ):

// Move the caret to the end of the line; i.e., the End key
editor.moveTo( p, line, column );

I don't know if this is possible, but the code could be simplified to:

editor.moveTo( CaretPosition.END_OF_LINE );
editor.moveTo( CaretPosition.START_OF_LINE );

Or simpler still:

// End of the caret's current line
editor.moveToEnd();

// Start of the caret's current line
editor.moveToStart();

Or a bit more generically, re-using the aforementioned column variable:

// Jump to the end of the current line of the caret's paragraph.
editor.moveTo( line, column );

// Jump to the beginning of the current line of the caret's paragraph.
editor.moveTo( line, 0 );

That said, a pie-in-the-sky OOP implementation might resemble:

// Caret scope is the current paragraph.
Caret caret = editor.getCaret();

// Line number within the current paragraph.
int line = caret.getLineNumber();

// Get the number of columns for the current line.
int column = caret.getColumnCount();

// Move the caret to the start of the current line.
caret.moveTo( 0 );

// Move the caret to the end of the current line.
caret.moveTo( column );

// And convenience methods:
caret.moveToStartOfLine();
caret.moveToEndOfLine();

[JordanMartinez]

You mean... lineStart and lineEnd, which is now the default behavior? 😄

[ghost]

That's fantastic! Am greatly anticipating 0.7-M4.

I still think a Caret class could eliminate a decent amount of complexity in client code.

[JordanMartinez]

To be honest, a caret object would bring more OOP to that area in the code.... It might also help implement #222.... Hmm... I'm going to open a new issue so we can discuss that further.