RFR: 6955128: Spec for javax.swing.plaf.basic.BasicTextUI.getVisibleEditorRect contains inappropriate wording

[Alexey Ivanov]

On Thu, 19 Jun 2025 04:01:49 GMT, Prasanta Sadhukhan <psadhukhan at openjdk.org> wrote:

>> src/java.desktop/share/classes/javax/swing/plaf/basic/BasicTextUI.java line 1033:
>> 
>>> 1031:     /**
>>> 1032:      * Gets the allocation to give the root View.
>>> 1033:      * The Rectangle returned has nothing to do with visibility but
>> 
>> "nothing to do with" ->  "unrelated to"
>> 
>> 
>> But what I'd really like to see is an explanation of what the return from this method ACTUALLY means / is used for.
>> What does "the allocation" mean ? Too woolly for me.
>
> getVisibleEditorRect() return the bounds of the text editor and the return value is used to to set-size/paint the 
> `javax.swing.text.View` of this text editor component.
> "the allocation" refers to what allocated area the view needs to paint, it seems to be a common phrase used in context of View class which says 
> 
>> "The view gets its allocation from the parent at paint time, so it must be prepared to redo layout if the allocated area is different from what it is prepared to deal with. "
> 
> In that regard, probably getAllocatedViewRect() would have been better choice of the method name

@prsadhuk @prrace Does this description work?


    /**
     * Gets the allocation for the root view.
     * The returned rectangle is unrelated to visibility,
     * it is passed as the {@code allocation} parameter to
     * the {@link View#paint(Graphics, Shape) View.paint} method.
     * The component must have a non-zero positive size for
     * this translation to be computed.
     *
     * @return the bounding box for the root view
     */
    protected Rectangle getVisibleEditorRect() {


This renders like this:

> Gets the allocation for the root view. The returned rectangle is unrelated to visibility, it is passed as the allocation parameter to the [`View.paint`](https://docs.oracle.com/en/java/javase/24/docs/api/java.desktop/javax/swing/text/View.html#paint(java.awt.Graphics,java.awt.Shape)) method. The component must have a non-zero positive size for this translation to be computed.

We can also add @TejeshR13's [suggestion](https://github.com/openjdk/jdk/pull/25850/files#r2153658561): “The method name is preserved for backward compatibility.”

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25850#discussion_r2157389675