8314482: TextFlow: TabStopPolicy

[andy-goryachev-oracle]

Tab Stop Policy

Andy Goryachev

[email protected]

Summary

Introduce a tabStopPolicy property in the TextFlow class which, when set, overrides the existing tabSize value and provides consistent way of setting tab stops at the paragraph level, regardless of the individual text segments font [0].

Goals

The goal of this proposal is to provide a better way for controlling tab stops in the TextFlow containing rich text.

Non-Goals

The following are not the goals of this proposal:

• support for tab stop types (BAR, or DECIMAL), or attributes like alignment
• support the leader property (symbols to fill the empty space before the tab stop)
• support for firstLineIndent property
• deprecate the TextFlow::tabsize property

Motivation

The existing tabSize property in the TextFlow is inadequate for representing tab stops when the content contains text with different font sizes.

In addition to that, a rich text editor might require support for user-customizable tab stops, similar to that provided in RTF or MS Word documents.

Description

TextFlow

    /**
     * {@code TabAdvancePolicy} determines the tab stop positions within this {@code TextFlow}.
     * <p>
     * A non-null {@code TabAdvancePolicy} overrides values set by {@link #setTabSize(int)},
     * as well as any values set by {@link Text#setTabSize(int)} in individual {@code Text} instances within
     * this {@code TextFlow}.
     *
     * @defaultValue null
     *
     * @since 999 TODO
     */
    public final ObjectProperty<TabStopPolicy> tabStopPolicyProperty() {

    public final TabStopPolicy getTabStopPolicy() {

    public final void setTabStopPolicy(TabStopPolicy policy) {

    /**
     * The size of a tab stop in spaces.
     * Values less than 1 are treated as 1. This value overrides the
     * {@code tabSize} of contained {@link Text} nodes.
     * <p>
+     * Note that this method should not be used to control the tab placement when multiple {@code Text} nodes
+     * with different fonts are contained within this {@code TextFlow}.
+     * In this case, the {@link #setTabStopPolicy(TabStopPolicy)} should be used instead.
     *
     * @defaultValue 8
     *
     * @since 14
     */
    public final IntegerProperty tabSizeProperty() {

TabStopPolicy

/**
 * The TabStopPolicy determines the tab stop positions within the text layout.
 *
 * @since 999 TODO
 */
public class TabStopPolicy {
    /**
     * Constructs a new {@code TabStopPolicy} instance.
     */
    public TabStopPolicy() {

    /**
     * Specifies the unmodifiable list of tab stops, sorted by position from smallest to largest.
     * The list can be changed using
     *
     * @return the non-null, unmodifiable list of tab stops, sorted by position
     */
    public final ObservableList<TabStop> tabStops() {

    /**
     * Provides default tab stops (beyond the last tab stop specified by {@code #tabStops()},
     * as a fixed repeating distance in pixels from the last tab stop position.
     * The position of default tab stops is computed at regular intervals relative to
     * the leading edge of the {@code TextFlow} this policy is registered with.
     * <p>
     * The value of less than or equal 0 disables the default stops.
     *
     * @return the default tab stops property
     * @defaultValue 0
     */
    public final DoubleProperty defaultStopsProperty() {

    public final double getDefaultStops() {

    public final void setDefaultStops(double value) {

TabStop

/**
 * This class encapsulates an immutable single tab stop within the {@link TabStopPolicy}.
 * <p>
 * A tab stop is at a specified distance from the
 * left margin, aligns text in a specified way, and has a specified leader.
 *
 * @since 999 TODO
 */
public class TabStop {
    /**
     * Constructs a new tab stop with the specified position.
     *
     * @param position the position in pixels
     */
    public TabStop(double position) {

    /**
     * Returns the position, in pixels, of the tab.
     * @return the position of the tab
     */
    public final double getPosition() {

Alternatives

None known.

Risks and Assumptions

Possible incompatibility with custom controls which extend TextFlow and declare a property with the same name.

Dependencies

None.

References

0. JDK-8314482
1. https://github.com/andy-goryachev-oracle/Test/blob/main/doc/TabStopPolicy/TabStopPolicy.md

---

Progress

• [ ] Change requires a CSR request matching fixVersion jfx25 to be approved (needs to be created)
• [x] Change must not contain extraneous whitespace
• [x] Commit message must refer to an issue
• [ ] Change must be properly reviewed (2 reviews required, with at least 1 Reviewer, 1 Author)

Issue

• JDK-8314482: TextFlow: TabStopPolicy (Enhancement - P3)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jfx.git pull/1744/head:pull/1744
$ git checkout pull/1744

Update a local copy of the PR:
$ git checkout pull/1744
$ git pull https://git.openjdk.org/jfx.git pull/1744/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 1744

View PR using the GUI difftool:
$ git pr show -t 1744

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jfx/pull/1744.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper[bot]]

:wave: Welcome back angorya! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk[bot]]

@andy-goryachev-oracle This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8314482: TextFlow: TabStopPolicy

Reviewed-by: kcr, arapte

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 2 new commits pushed to the master branch:

• 2dd90265637dc1c17fa4f5ab36500564b19ce082: 8361379: [macos] Refactor accessibility code to retrieve attribute by name
• 99866ae1f197ae5593b728bedceb00121fe4baca: 8141391: Manual JFXPanel DnD test doesn't work

Please see this link for an up-to-date comparison between the source branch of this pull request and the master branch. As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[andy-goryachev-oracle]

/csr /reviewers 2

[openjdk[bot]]

@andy-goryachev-oracle has indicated that a compatibility and specification (CSR) request is needed for this pull request.

@andy-goryachev-oracle please create a CSR request for issue JDK-8314482 with the correct fix version. This pull request cannot be integrated until the CSR request is approved.

[openjdk[bot]]

@andy-goryachev-oracle The total number of required reviews for this PR (including the jcheck configuration and the last /reviewers command) is now set to 2 (with at least 1 Reviewer, 1 Author).

[mlbridge[bot]]

Webrevs

• 09: Full (5252633b)
• 08: Full (7bdb6ac7)
• 07: Full - Incremental (2a1e479b)
• 06: Full - Incremental (9851c92d)
• 05: Full (00bcf4b0)
• 04: Full (c3842c03)
• 03: Full - Incremental (f873a5b9)
• 02: Full - Incremental (ef38166a)
• 01: Full (7acc55db)
• 00: Full (d624df53)

[bridgekeeper[bot]]

@andy-goryachev-oracle This pull request has been inactive for more than 4 weeks and will be automatically closed if another 4 weeks passes without any activity. To avoid this, simply issue a /touch or /keepalive command to the pull request. Feel free to ask for assistance if you need help with progressing this pull request towards integration!

[andy-goryachev-oracle]

/touch

[openjdk[bot]]

@andy-goryachev-oracle The pull request is being re-evaluated and the inactivity timeout has been reset.

[andy-goryachev-oracle]

question: what about setting the tab stop policy via CSS?

A very good question!

It might be entirely possible (in a separate PR), though judging by experience from adding tab stops to the rich editor demo https://github.com/openjdk/jfx/pull/1800 it's probably unnecessary, since TextFlow is somewhat of a low-level control.

Another complication is that the policy is a complex entity, with a list of (possibly complex) TabStops, and other fields, so I am not sure how easy it would be to add CSS support. How would it look in CSS?

[andy-goryachev-oracle]

Also, decided to make the TabStop class final. We can always remove the final keyword if the use case arises.

[andy-goryachev-oracle]

created the CSR.

[andy-goryachev-oracle]

Good point!

Added comprehensive test, thanks to the latest changes that made the StubTextLayout work essentially like the real one, and the new LayoutInfo API.

[andy-goryachev-oracle]

@arapte could you please take a look at this PR?

[andy-goryachev-oracle]

thank you all

/integrate

[openjdk[bot]]

Going to push as commit 22e43c58af8ca293052b54d86c78818fc32f09d9. Since your change was applied there have been 2 commits pushed to the master branch:

• 2dd90265637dc1c17fa4f5ab36500564b19ce082: 8361379: [macos] Refactor accessibility code to retrieve attribute by name
• 99866ae1f197ae5593b728bedceb00121fe4baca: 8141391: Manual JFXPanel DnD test doesn't work

Your commit was automatically rebased without conflicts.

[openjdk[bot]]

@andy-goryachev-oracle Pushed as commit 22e43c58af8ca293052b54d86c78818fc32f09d9.

:bulb: You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.