[External] : Re: Enhanced Text/TextFlow APIs

[Andy Goryachev]

I generally agree.  In this particular case, the distinction is clear and explained in the docs (perhaps it could be explained better, your suggestions are always welcomed).

The new names, I think, fit better: getCaretShape() are far better than getCaretShapeWithInsets (what insets?  why?  what makes insets so special?).

The proposed solution provides the new API without breaking the existing apps.  The apps can take their time to migrate to the new API in due course.  I believe we've done this in the past where things got deprecated but not for removal.

So I think this is a good compromise - things get fixed without immediately breaking the existing apps, a win-win.

Cheers,
-andy





From: Michael Strauß <michaelstrau2 at gmail.com>
Date: Monday, July 7, 2025 at 19:41
To: Andy Goryachev <andy.goryachev at oracle.com>
Cc: openjfx-dev <openjfx-dev at openjdk.org>
Subject: [External] : Re: Enhanced Text/TextFlow APIs
In most cases, I would advise against having similarly-named methods
that exhibit different semantics. If the behavior of the existing
methods is indeed a bug (and not just different, but legitimate
semantics), then fixing that would be best. We've done breaking
changes in the past where appropriate, and expect applications to make
necessary changes in their API use when switching to a new version of
JavaFX. Always keeping old behavior around runs the risk of
fossilizing the API in the long run.

In rare cases, and especially when necessary changes would be more
involved, there's the option to hide the previous behavior behind a
system property. Setting a system property in lieu of changing code is
a low-effort option for applications that are not prepared to fix
their code just yet.

If we want to keep the old methods around indefinitely, another option
would be to make the new methods clearly different to indicate their
changed semantics.

For example, for the existing method `rangeShape(int, int)`, we could
add another method `rangeShapeWithLineSpacing(int, int)`. This makes
the semantics of the method abundantly clear to users, and keeps the
old method around. It also avoids the proposed boolean argument
`includeLineSpacing`, which is usually better API design.

As another example, the existing method `caretShape(int, boolean)`
could be paired with `caretShapeWithInsets(int, boolean)`.

My main criticism is that method pairings like `rangeShape` and
`getRangeShape` muddy the API waters. We'd never have done that, had
we thought about the correct semantics earlier. Evolving an API is
always hard, but the goal should be to have the new API fit well with
the existing API, as if it had been thought of from the beginning.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/openjfx-dev/attachments/20250708/0feff1af/attachment-0001.htm>