8337287: Update image in javax.swing.text.Document.insert

[aivanov-jdk]

This changeset updates the image in the documentation for the Document.insert method. The image in Document.remove was updated by JDK-4622866 in PR #15701.

Now the illustration of inserting looks similar to removing. The new image is in SVG format.

For reference:

• Document.insert in JDK 22;
• Updated docs for JDK 24.

As in the case with remove, I marked up to classes and members with {@code}.

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue

Issue

• JDK-8337287: Update image in javax.swing.text.Document.insert (Enhancement - P4)

Reviewers

• Phil Race (@prrace - Reviewer) Review applies to 697da25b
• Abhishek Kumar (@kumarabhi006 - Reviewer) Review applies to 697da25b
• Sergey Bylokhov (@mrserb - Reviewer)

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 20376

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

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/20376.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back aivanov! 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]

@aivanov-jdk 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:

8337287: Update image in javax.swing.text.Document.insert

Reviewed-by: serb, prr, abhiscxk

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 no new commits pushed to the master branch. If another commit should be pushed before you perform the /integrate command, your PR will be automatically rebased. If you prefer to avoid any potential 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.

[openjdk]

@aivanov-jdk The following label will be automatically applied to this pull request:

• client

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

[mlbridge]

Webrevs

• 02: Full - Incremental (c6cd5076)
• 01: Full - Incremental (8077bde0)
• 00: Full (697da25b)

[aivanov-jdk]

@prrace Does it make sense to add a sentence which describes the image? I added one for remove to explain all the Positions in the removed area are collapsed.

Inserting a string is more straightforward: all the Positions at and after the insertion point are moved by the length of the inserted string.

[prrace]

@prrace Does it make sense to add a sentence which describes the image? I added one for remove to explain all the Positions in the removed area are collapsed.

Inserting a string is more straightforward: all the Positions at and after the insertion point are moved by the length of the inserted string.

I missed this question. Yes, sure.

[mrserb]

Just curious why the chars are not in the middle of the boxes?

[aivanov-jdk]

Just curious why the chars are not in the middle of the boxes?

They're aligned according to CSS rules:

            text-anchor: middle;
            dominant-baseline: middle;

The text is positioned in the middle of the box -0.5 pixels.

However, I agree the text looks visually unbalanced. Indeed, at 200% scale and Arial font, there are 6 pixels on top of ‘T’ and ‘h’, but there are 8 pixels on the bottom of ‘q’. If I use Calibri font, the values are 8 and 9 pixels correspondingly. So it depends on the font used. The situation is similar on macOS.

[aivanov-jdk]

The text is positioned in the middle of the box -0.5 pixels.

Moving the text position by 0.5 seems to help, and the values become equal: 7 on either side.

This needs to be done for the image in remove too, so I'd rather do that separately, at a later time.

At this time, the diagrams for insertString and remove look the same.

[aivanov-jdk]

Just curious why the chars are not in the middle of the boxes?

The text is positioned in the middle of the box -0.5 pixels.

Moving the text position by 0.5 seems to help, and the values become equal: 7 on either side.

This needs to be done for the image in remove too, so I'd rather do that separately, at a later time.

Submitted JDK-8340580: Characters in Document diagrams not in the middle.

[aivanov-jdk]

Does it make sense to add a sentence which describes the image? I added one for remove to explain all the Positions in the removed area are collapsed.

I missed this question. Yes, sure.

@prrace I updated the PR with an example, look for “For example, if the document contains the text…”.

[aivanov-jdk]

@mrserb Do you have any other questions?

I'll update the position of text in Document-insert.svg and Document-remove.svg separately after this PR is integrated.

[aivanov-jdk]

Pinging… Do you, @prrace and @mrserb, have any additional comments?

[aivanov-jdk]

Does it make sense to add a sentence which describes the image? I added one for remove to explain all the Positions in the removed area are collapsed.

I missed this question. Yes, sure.

I updated the PR with an example, look for “For example, if the document contains the text…”.

@prrace Did you have a chance to look at the updated text? The newly added paragraph starts at line 482.

[aivanov-jdk]

/integrate

[openjdk]

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

• 8647c00: 8342602: Remove JButton/PressedButtonRightClickTest test
• fcf185c: 8345325: SM cleanup of GetPropertyAction in java.base
• eac00f6: 8345396: Fix headers after JDK-8345164
• dfa5620: 8345164: Remove residual --enable-preview in FFM tests and benchmarks
• 65b5a2e: 8345158: IGV: local scheduling should not place successors before predecessors
• 8cad043: 8336768: Allow captureCallState and critical linker options to be combined
• 63af2f4: 8344414: ZGC: Another division by zero in rule_major_allocation_rate
• 077b842: 8345074: java.net.InterfaceAddress constructor could be made private
• ec93cc5: 8343932: Error when parsing qualified generic type test pattern in switch
• c330b90: 8343780: Add since checker tests to the Tools area modules and add missing @SInCE to jdk.jfr
• ... and 517 more: https://git.openjdk.org/jdk/compare/c0e6c3b93c0d21debc538e0135805c2957053108...master

Your commit was automatically rebased without conflicts.

[openjdk]

@aivanov-jdk Pushed as commit caf053b.

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