Enhanced Text/TextFlow APIs

[Michael Strauß]

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.