RFR: 8301121: RichTextArea Control (Incubator) [v10]

[Kevin Rushforth]

On Fri, 13 Sep 2024 21:35:43 GMT, Andy Goryachev <angorya at openjdk.org> wrote:

>> Incubating a new feature - rich text control, **RichTextArea**, intended to bridge the functional gap with Swing and its StyledEditorKit/JEditorPane. The main design goal is to provide a control that is complete enough to be useful out-of-the box, as well as open to extension by the application developers.
>> 
>> This is a complex feature with a large API surface that would be nearly impossible to get right the first time, even after an extensive review. We are, therefore, introducing this in an incubating module, **jfx.incubator.richtext**. This will allow us to evolve the API in future releases without the strict compatibility constraints that other JavaFX modules have.
>> 
>> Please check out two manual test applications - one for RichTextArea (**RichTextAreaDemoApp**) and one for the CodeArea (**CodeAreaDemoApp**). Also, a small example provides a standalone rich text editor, see **RichEditorDemoApp**.
>> 
>> Because it's an incubating module, please focus on the public APIs rather than implementation.  There **will be** changes to the implementation once/if the module is promoted to the core by popular demand.  The goal of the incubator is to let the app developers try the new feature out. 
>> 
>> **References**
>> 
>> - Proposal: https://github.com/andy-goryachev-oracle/Test/blob/main/doc/RichTextArea/RichTextArea.md
>> - Discussion points: https://github.com/andy-goryachev-oracle/Test/blob/main/doc/RichTextArea/RichTextAreaDiscussion.md
>> - API specification (javadoc): https://cr.openjdk.org/~angorya/RichTextArea/javadoc
>> - RichTextArea RFE: https://bugs.openjdk.org/browse/JDK-8301121
>> - Behavior doc: https://github.com/andy-goryachev-oracle/jfx/blob/8301121.RichTextArea/doc-files/behavior/RichTextAreaBehavior.md
>> - CSS Reference: https://cr.openjdk.org/~angorya/RichTextArea/javadoc/javafx.graphics/javafx/scene/doc-files/cssref.html
>> - InputMap (v3): https://github.com/andy-goryachev-oracle/Test/blob/main/doc/InputMap/InputMapV3.md
>> - Previous Draft PR: https://github.com/openjdk/jfx/pull/1374
>
> Andy Goryachev has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 17 additional commits since the last revision:
> 
>  - hide impl. detail
>  - Merge remote-tracking branch 'origin/master' into 8301121.RichTextArea
>  - removed duplicate files
>  - moved to apps, review comments
>  - bsd license for sample code
>  - fixes and review comments
>  - Merge remote-tracking branch 'origin/master' into 8301121.RichTextArea
>  - improved vertical scrolling
>  - Merge remote-tracking branch 'origin/master' into 8301121.RichTextArea
>  - cleanup
>  - ... and 7 more: https://git.openjdk.org/jfx/compare/f7fe32a1...1aafab27

A few more comments on the `RichTextArea` class.

The following directories should be refactored / renamed from `rich` to `richtext` (the one in `doc-files` is causing the images to not show up in the generated docs)


modules/jfx.incubator.richtext/
  build/classes/java/test/test/com/sun/jfx/incubator/scene/control/rich/
  src/main/docs/jfx/incubator/scene/control/rich/
  src/test/java/test/com/sun/jfx/incubator/scene/control/rich/

modules/jfx.incubator.richtext/src/main/java/jfx/incubator/scene/control/richtext/RichTextArea.java line 154:

> 152:  * </ul>
> 153:  *
> 154:  * @author Andy Goryachev

I recommend adding `@see StyledTextModel`.

Btw, we don't typically use the `@author` tag.

modules/jfx.incubator.richtext/src/main/java/jfx/incubator/scene/control/richtext/RichTextArea.java line 314:

> 312:     /**
> 313:      * Creates the instance with the in-memory model {@link RichTextModel}.
> 314:      */

I recommend adding  `@defaultValue`

modules/jfx.incubator.richtext/src/main/java/jfx/incubator/scene/control/richtext/RichTextArea.java line 367:

> 365:      * <p>
> 366:      * Note:
> 367:      * {@code StyledTextModel.selectionProperty()}, {@link #anchorPositionProperty()}, and {@link #caretPositionProperty()}

Typo: `StyledTextModel.selectionProperty` --> `selectionProperty` (it is a property of _this_ class, not the model)

modules/jfx.incubator.richtext/src/main/java/jfx/incubator/scene/control/richtext/RichTextArea.java line 437:

> 435:      * <p>
> 436:      * Note:
> 437:      * {@code StyledTextModel.selectionProperty()}, {@link #anchorPositionProperty()}, and {@link #caretPositionProperty()}

`StyledTextModel.selectionProperty` --> `selectionProperty`

modules/jfx.incubator.richtext/src/main/java/jfx/incubator/scene/control/richtext/RichTextArea.java line 735:

> 733:      * <p>
> 734:      * Note:
> 735:      * {@code StyledTextModel.selectionProperty()}, {@link #anchorPositionProperty()}, and {@link #caretPositionProperty()}

`StyledTextModel.selectionProperty` --> `selectionProperty`

-------------

PR Review: https://git.openjdk.org/jfx/pull/1524#pullrequestreview-2304200371
PR Comment: https://git.openjdk.org/jfx/pull/1524#issuecomment-2350512541
PR Review Comment: https://git.openjdk.org/jfx/pull/1524#discussion_r1759550704
PR Review Comment: https://git.openjdk.org/jfx/pull/1524#discussion_r1759561651
PR Review Comment: https://git.openjdk.org/jfx/pull/1524#discussion_r1759547329
PR Review Comment: https://git.openjdk.org/jfx/pull/1524#discussion_r1759547688
PR Review Comment: https://git.openjdk.org/jfx/pull/1524#discussion_r1759547868