<!DOCTYPE html><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  </head>
  <body>
    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.<br>
    <br>
    -- Kevin<br>
    <br>
    <div class="moz-cite-prefix">On 7/8/2025 8:16 AM, Andy Goryachev
      wrote:<br>
    </div>
    <blockquote type="cite" cite="mid:CY8PR10MB7265E48948A4430A17A5EAD8E54EA@CY8PR10MB7265.namprd10.prod.outlook.com">
      
      <meta name="Generator" content="Microsoft Word 15 (filtered medium)">
      <style>@font-face
        {font-family:"Cambria Math";
        panose-1:2 4 5 3 5 4 6 3 2 4;}@font-face
        {font-family:Aptos;
        panose-1:2 11 0 4 2 2 2 2 2 4;}@font-face
        {font-family:"Iosevka Fixed SS16";
        panose-1:2 0 5 9 3 0 0 0 0 4;}@font-face
        {font-family:"Times New Roman \(Body CS\)";
        panose-1:2 11 6 4 2 2 2 2 2 4;}p.MsoNormal, li.MsoNormal, div.MsoNormal
        {margin:0in;
        font-size:10.0pt;
        font-family:"Aptos",sans-serif;}span.EmailStyle19
        {mso-style-type:personal-reply;
        font-family:"Iosevka Fixed SS16";
        color:windowtext;}.MsoChpDefault
        {mso-style-type:export-only;
        font-size:10.0pt;
        mso-ligatures:none;}div.WordSection1
        {page:WordSection1;}</style>
      <div class="WordSection1">
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">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).<o:p></o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">The
            new names, I think, fit better: getCaretShape() are far
            better than getCaretShapeWithInsets (what insets?  why? 
            what makes insets so special?).<o:p></o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">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.<o:p></o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">So I
            think this is a good compromise - things get fixed without
            immediately breaking the existing apps, a win-win.<o:p></o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">Cheers,<o:p></o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16"">-andy<o:p></o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
        <p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Iosevka Fixed SS16""><o:p> </o:p></span></p>
        <div id="mail-editor-reference-message-container">
          <div>
            <div>
              <div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
                <p class="MsoNormal" style="margin-bottom:12.0pt"><b><span style="font-size:12.0pt;color:black">From:
                    </span></b><span style="font-size:12.0pt;color:black">Michael Strauß
                    <a class="moz-txt-link-rfc2396E" href="mailto:michaelstrau2@gmail.com"><michaelstrau2@gmail.com></a><br>
                    <b>Date: </b>Monday, July 7, 2025 at 19:41<br>
                    <b>To: </b>Andy Goryachev
                    <a class="moz-txt-link-rfc2396E" href="mailto:andy.goryachev@oracle.com"><andy.goryachev@oracle.com></a><br>
                    <b>Cc: </b>openjfx-dev
                    <a class="moz-txt-link-rfc2396E" href="mailto:openjfx-dev@openjdk.org"><openjfx-dev@openjdk.org></a><br>
                    <b>Subject: </b>[External] : Re: Enhanced
                    Text/TextFlow APIs<o:p></o:p></span></p>
              </div>
              <div>
                <p class="MsoNormal"><span style="font-size:11.0pt">In
                    most cases, I would advise against having
                    similarly-named methods<br>
                    that exhibit different semantics. If the behavior of
                    the existing<br>
                    methods is indeed a bug (and not just different, but
                    legitimate<br>
                    semantics), then fixing that would be best. We've
                    done breaking<br>
                    changes in the past where appropriate, and expect
                    applications to make<br>
                    necessary changes in their API use when switching to
                    a new version of<br>
                    JavaFX. Always keeping old behavior around runs the
                    risk of<br>
                    fossilizing the API in the long run.<br>
                    <br>
                    In rare cases, and especially when necessary changes
                    would be more<br>
                    involved, there's the option to hide the previous
                    behavior behind a<br>
                    system property. Setting a system property in lieu
                    of changing code is<br>
                    a low-effort option for applications that are not
                    prepared to fix<br>
                    their code just yet.<br>
                    <br>
                    If we want to keep the old methods around
                    indefinitely, another option<br>
                    would be to make the new methods clearly different
                    to indicate their<br>
                    changed semantics.<br>
                    <br>
                    For example, for the existing method
                    `rangeShape(int, int)`, we could<br>
                    add another method `rangeShapeWithLineSpacing(int,
                    int)`. This makes<br>
                    the semantics of the method abundantly clear to
                    users, and keeps the<br>
                    old method around. It also avoids the proposed
                    boolean argument<br>
                    `includeLineSpacing`, which is usually better API
                    design.<br>
                    <br>
                    As another example, the existing method
                    `caretShape(int, boolean)`<br>
                    could be paired with `caretShapeWithInsets(int,
                    boolean)`.<br>
                    <br>
                    My main criticism is that method pairings like
                    `rangeShape` and<br>
                    `getRangeShape` muddy the API waters. We'd never
                    have done that, had<br>
                    we thought about the correct semantics earlier.
                    Evolving an API is<br>
                    always hard, but the goal should be to have the new
                    API fit well with<br>
                    the existing API, as if it had been thought of from
                    the beginning.<o:p></o:p></span></p>
              </div>
            </div>
          </div>
        </div>
      </div>
    </blockquote>
    <br>
  </body>
</html>