[External] : Re: Enhanced Text/TextFlow APIs

[Kevin Rushforth]

I agree with Andy on this, provided that we explain it well. The 
proposed names are what I would have chosen in the first place, and by 
leaving the existing methods in place -- deprecated, but not for removal 
-- we avoid the very real possibility of introducing a regression. It 
isn't an ideal choice, but I think it's the best on in this case.

-- Kevin

On 7/8/2025 8:16 AM, Andy Goryachev wrote:
>
> 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/5988b371/attachment.htm>