8311895: CSS Transitions

modules/javafx.graphics/src/main/docs/javafx/scene/doc-files/cssref.html

@@ -253,6 +253,7 @@ <h2>Contents</h2>
           <li><a href="#intronaming">Naming Conventions</a></li>
           <li><a href="#intropublicapi">CSS Public API</a></li>
           <li><a href="#introinheritance">Inheritance</a></li>
+          <li><a href="#introtransitions">Transitions</a>
           <li><a href="#introatrules">&#64; Rules</a></li>
           <li><a href="#introexamples">Examples</a></li>
           <li><a href="#introparserwarnings">Understanding Parser Warnings</a></li>
@@ -277,6 +278,7 @@ <h2>Contents</h2>
           <li><a href="#typefont">&lt;font&gt;</a></li>
           <li><a href="#typepaint">&lt;paint&gt;</a></li>
           <li><a href="#typecolor">&lt;color&gt;</a></li>
+          <li><a href="#typeeasingfunction">&lt;easing-function&gt;</a></li>
           <li><a href="#typetextbounds">&lt;text-bounds&gt;</a></li>
         </ul>
       </li>
@@ -680,6 +682,80 @@ <h3><a id="introinheritance">Inheritance</a></h3>
         inherited provided there is not an author or an inline-style that applies specifically to that node.
         In this case, the inherited font is created from the user-set font and any parts of the applicable
         author or in-line style.
+
+    <h3><a id="introtransitions">Transitions</a></h3>
+    <p>JavaFX supports <em>implicit transitions</em> for properties that are styled by CSS. When a property value is
+        changed, it smoothly transitions to the new value over a period of time. Implicit transitions are supported
+        for all primitive types, as well as for types that implement <code>javafx.animation.Interpolatable</code>.</p>
+    <p>Transitions can be defined for any node in the JavaFX scene graph with the following properties:</p>
+    <table class="csspropertytable">
+    <caption>Transition Properties</caption>
+      <thead>
+        <tr>
+        <th class="propertyname" scope="col">CSS Property</th>
+        <th class="value" scope="col">Values</th>
+        <th scope="col">Default</th>
+        <th scope="col">Comments</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+        <th class="propertyname" scope="row">transition&#8209;property</th>
+          <td class="value">[ none | all | &lt;custom&#8209;ident&gt;# ]</td>
+          <td class="default">all</td>
+          <td>The name of the CSS property to which the transition is applied.</td>
+        </tr>
+        <tr>
+        <th class="propertyname" scope="row">transition&#8209;duration</th>
+          <td class="value"><a href="#typeduration" class="typelink">&lt;duration&gt;#</a></td>
+          <td class="default">0s</td>
+          <td>The duration of the transition, not including an optional delay before the transition starts.</td>
+        </tr>
+        <tr>
+        <th class="propertyname" scope="row">transition&#8209;timing&#8209;function</th>
+          <td class="value"><a href="#typeeasingfunction" class="typelink">&lt;easing&#8209;function&gt;#</a></td>
+          <td class="default">ease</td>
+          <td>The easing function that is used to calculate the intermediate values.</td>
+        </tr>
+        <tr>
+        <th class="propertyname" scope="row">transition&#8209;delay</th>
+          <td class="value"><a href="#typeduration" class="typelink">&lt;duration&gt;#</a></td>
+          <td class="default">0s</td>
+          <td>The delay after which the transition starts. If a negative delay is specified, the transition starts
+              as if it had already been running for the specified time.</td>
+        </tr>
+        <tr>
+        <th class="propertyname" scope="row">transition</th>
+        <td class="value">
+            &lt;single-transition&gt;#
+            <br/><br/>
+            <strong>where</strong> &lt;single&#8209;transition&gt; = [ none | all | &lt;custom&#8209;ident&gt; ] ||
+            <a href="#typeduration" class="typelink">&lt;duration&gt;</a> ||
+            <a href="#typeeasingfunction" class="typelink">&lt;easing&#8209;function&gt;</a> ||
+            <a href="#typeduration" class="typelink">&lt;duration&gt;</a>
+        </td>
+        <td class="default"></td>
+        <td>Short-hand notation for the individual properties. Note that while the order of the values generally
+            doesn't matter, the first duration is always assigned to the <strong>transition-duration</strong>
+            property, while the second duration is always assigned to the <strong>transition-delay</strong>
+            property.</td>
+        </tr>
+      </tbody>
+    </table>
+    <h4>Example</h4>
+    <p>A button that smoothly changes its opacity on mouse-hover can be defined in a stylesheet like this:</p>
+    <p class="example">
+        .button {</br>
+        &nbsp;&nbsp;&nbsp; -fx-opacity: 0.8;</br>
+        &nbsp;&nbsp;&nbsp; transition-property: -fx-opacity;</br>
+        &nbsp;&nbsp;&nbsp; transition-duration: 0.5s;</br>
+        }</br>
+        </br>
+        .button:hover {</br>
+        &nbsp;&nbsp;&nbsp; -fx-opacity: 1;</br>
+        }
+    </p>
+
     <h3><a id="introatrules">&#64; Rules</a></h3>
     <p>
         Beginning with JavaFX 8u20, the CSS
@@ -1579,6 +1655,128 @@ <h4>Color Functions <span class="grammar" style="font-size: smaller;">&lt;color-
           href="#typecolor"
           class="typelink">&lt;color&gt;</a>
         ) ]+ </span></p>
+
+    <h3><a id="typeeasingfunction">&lt;easing-function&gt;</a></h3>
+    <p class="grammar">linear | &lt;cubic-bezier-easing-function&gt; | &lt;step-easing-function&gt; | &lt;fx-easing-function&gt;</p>
+    <p><strong>Linear</strong> <span class="grammar" style="font-size: smaller;">linear</span><br/>
+       The linear easing function is a simple linear mapping from the input progress value to the output progress value.</p>
+    <figure style="display: inline-block">
+        <img src="easing-linear.svg" width="200" alt="Linear easing function">
+    </figure>
+    <p><strong>Cubic Bézier Easing Functions</strong> <span class="grammar" style="font-size: smaller;">&lt;cubic-bezier-easing-function&gt;</span></br></p>
+    <p class="grammar">ease | ease-in | ease-out | ease-in-out | cubic-bezier(<a href="#typenumber" class="typelink">&lt;number&nbsp;[0,1]&gt;</a>, <a href="#typenumber" class="typelink">&lt;number&gt;</a>, <a href="#typenumber" class="typelink">&lt;number&nbsp;[0,1]&gt;</a>, <a href="#typenumber" class="typelink">&lt;number&gt;</a>)</p>
+    <p>The values have the following meaning:</p>
+    <table style="margin-left: 40px;">
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">ease</span></td>
+            <td>equivalent to <span class="grammar">cubic-bezier(0.25, 0.1, 0.25, 1)</span></td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">ease-in</span></td>
+            <td>equivalent to <span class="grammar">cubic-bezier(0.42, 0, 1, 1)</span></td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">ease-out</span></td>
+            <td>equivalent to <span class="grammar">cubic-bezier(0, 0, 0.58, 1)</span></td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">ease-in-out</span></td>
+            <td>equivalent to <span class="grammar">cubic-bezier(0.42, 0, 0.58, 1)</span></td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">cubic-bezier</span></td>
+            <td>defines the control points P1 and P2 using four real numbers: (x<sub>P1</sub>, y<sub>P1</sub>, x<sub>P2</sub>, y<sub>P2</sub>)</td>
+        </tr>
+    </table>
+    <p>A cubic Bézier function is defined by four control points, where P0 is fixed at (0,0) and P3 is fixed at (1,1).
+       P1 and P2 are restricted to the interval [0,1] on the input progress axis:</p>
+    <figure style="display: inline-block">
+        <img src="easing-cubicbezier.svg" width="200" alt="Cubic Bèzier easing function">
+    </figure>
+    <p><strong>Step Easing Functions</strong> <span class="grammar" style="font-size: smaller;">&lt;step-easing-function&gt;</span></p>
+    <p class="grammar">step-start | step-end | steps(<a href="#typenumber" class="typelink">&lt;integer&gt;</a>[,&lt;step-position&gt;]?)</p>
+    <p class="grammar">where &lt;step-position&gt; = jump-start | jump-end | jump-none | jump-both | start | end</p>
+    <p>The values have the following meaning:</p>
+    <table style="margin-left: 40px;">
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">step-start</span></td>
+            <td>equivalent to <span class="grammar">steps(1, start)</span></td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">step-end</span></td>
+            <td>equivalent to <span class="grammar">steps(1, end)</span></td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">steps</span></td>
+            <td>defines a step function with <a href="#typenumber" class="typelink">&lt;integer&gt;</a> intervals
+                and an optional <span class="grammar">&lt;step-position&gt;</span>;<br/>if omitted,
+                <span class="grammar">end</span> is implied</span>
+            </td>
+        </tr>
+        <tr><td><br/></td></tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">jump-start</span></td>
+            <td>the interval starts with a rise point when the input progress value is 0</td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">jump-end</span></td>
+            <td>the interval ends with a rise point when the input progress value is 1</td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">jump-none</span></td>
+            <td>all rise points are within the open interval (0..1)</td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">jump-both</span></td>
+            <td>the interval starts with a rise point when the input progress value is 0,
+                and ends with a rise point when the input progress value is 1</td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">start</span></td>
+            <td>equivalent to <span class="grammar">jump-start</span></td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">end</span></td>
+            <td>equivalent to <span class="grammar">jump-end</span></td>
+        </tr>
+    </table>
+    <p>Examples of step easing functions:</p>
+    <figure style="display: inline-block">
+        <img src="easing-stepstart.svg" width="200" alt="jump-start easing function">
+        <figcaption style="margin-left: 30px" class="grammar">steps(3, jump-start)</figcaption>
+    </figure>
+    <figure style="display: inline-block">
+        <img src="easing-stepend.svg" width="200" alt="jump-end easing function">
+        <figcaption style="margin-left: 30px" class="grammar">steps(3, jump-end)</figcaption>
+    </figure>
+    <figure style="display: inline-block">
+        <img src="easing-stepnone.svg" width="200" alt="jump-none easing function">
+        <figcaption style="margin-left: 30px" class="grammar">steps(3, jump-none)</figcaption>
+    </figure>
+    <figure style="display: inline-block">
+        <img src="easing-stepboth.svg" width="200" alt="jump-both easing function">
+        <figcaption style="margin-left: 30px" class="grammar">steps(3, jump-both)</figcaption>
+    </figure>
+    <p><strong>SMIL 3.0 Easing Functions</strong> <span class="grammar" style="font-size: smaller;">&lt;fx-easing-function&gt;</span></br></p>
+    <p class="grammar">-fx-ease-in | -fx-ease-out | -fx-ease-both</p>
+    <p>The values have the following meaning:</p>
+    <table style="margin-left: 40px;">
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">-fx-ease-in</span></td>
+            <td>SMIL 3.0 ease-in function with an acceleration factor of 0.2</td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">-fx-ease-out</span></td>
+            <td>SMIL 3.0 ease-out function with a deceleration factor of 0.2</td>
+        </tr>
+        <tr>
+            <td style="width: 120px; vertical-align: top"><span class="grammar">-fx-ease-both</span></td>
+            <td>SMIL 3.0 ease-in/out function with an acceleration and decelaration factor of 0.2</td>
+        </tr>
+    </table>
+    <p>These functions are provided for compatibility with <code>javafx.animation.Interpolator</code>
+       implementations of SMIL 3.0 cubic bezier easing functions.</p>
+
     <h3><a id="typetextbounds">&lt;text-bounds&gt;</a></h3>
     <p>The geometry of text can be measured either in terms of the bounds of
        the particular text to be rendered - visual bounds, or as properties