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

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 1038 new commits pushed to the master branch:

• 8591109: 8340698: JVMTI FRAME_POP event is sometimes missed if NotifyFramePop is called as a method is returning
• 0784011: 8340488: Clarify LocaleServiceProvider deployment on application module path
• 4dcc7f3: 8337536: AArch64: Enable BTI branch protection for runtime part
• 28252bb: 8341444: Unnecessary check for JSRs in CDS
• 8174cbd: 8341978: Improve JButton/bug4490179.java
• 9201e9f: 8342409: [s390x] C1 unwind_handler fails to unlock synchronized methods with LM_MONITOR
• 0963b9e: 8341664: ReferenceClassDescImpl cache internalName
• c51a086: 8339694: ciTypeFlow does not correctly handle unresolved constant dynamic of array type
• 7f4ed50: 8341020: Error handler crashes when Metaspace is not fully initialized
• f50bd0d: 8341513: Remove the unused thread_type field from OSThread
• ... and 1028 more: https://git.openjdk.org/jdk/compare/5ff7c57f9ff5428ef3d2aedd7e860bb1e8ff29ea...master

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.

[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

• 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?