Update documentation for theming constants and animation APIs

docs/developer-guide/Advanced-Theming.asciidoc

@@ -186,6 +186,15 @@ SoftKey, Touch, Bar, Title, Right, Native
 |defaultEmblemImage
 |The emblem painted on the side of the multibutton, by default this is an arrow on some platforms
 
+|emblemUiid
+|Overrides the UIID applied to emblem labels rendered by composite buttons such as `MultiButton` and `SpanMultiButton`.
+
+|iconUiid
+|Allows theming the icon component used by `SpanLabel`, `SpanButton`, `MultiButton`, and `SpanMultiButton` when they fetch icon styling via theme constants.
+
+|textUiid
+|Overrides the text component UIID for `SpanLabel`, `SpanButton`, `MultiButton`, and `SpanMultiButton` instances when provided as a theme constant.
+
 |dialogTransitionOutImage
 |Default transition https://www.codenameone.com/javadoc/com/codename1/ui/Image.html[Image] for dialog, causes a https://www.codenameone.com/javadoc/com/codename1/ui/animations/Timeline.html[Timeline] transition effect
 
@@ -279,6 +288,9 @@ SoftKey, Touch, Bar, Title, Right, Native
 |infiniteDefaultColor
 |Hex RGB color used for the auto-generated material spinner when `infiniteImage` isn't supplied. Defaults to `777777`
 
+|interactionDialogSpeedInt
+|Controls the duration in milliseconds that `InteractionDialog` uses when animating into and out of the layered pane (including the directional dispose helpers). Defaults to `400` if the constant is not defined.
+
 |includeNativeBool
 |True to derive from the platform native theme, false to create a blank theme that only uses the basic defaults
 
@@ -504,6 +516,15 @@ SoftKey, Touch, Bar, Title, Right, Native
 |sideSwipeSensitiveInt
 |Indicates the region of the screen that is sensitive to side swipe in the side menu bar, defaults to 10 (percent)
 
+|sigButtonOKUIID
+|Defines the UIID applied to the confirmation button in the signature capture dialog (defaults to `Button`).
+
+|sigButtonResetUIID
+|Defines the UIID applied to the reset/clear button in the signature capture dialog (defaults to `Button`).
+
+|sigButtonCancelUIID
+|Defines the UIID applied to the cancel button in the signature capture dialog (defaults to `Button`).
+
 |slideDirection
 |Default slide transition settings
 

docs/developer-guide/Animations.asciidoc

@@ -29,7 +29,7 @@ This won't work since these methods are meant for the layout manager, which is i
 
 If you add components to a form that is currently showing, it is your responsibility to invoke `revalidate`/`layoutContainer` to arrange the newly added components (see <<layout-reflows,Layout Reflows>>).
 
-`animateLayout()` method is a fancy form of revalidate that animates the components into their laid out position. After changing the layout & invoking this method the components move to their new sizes/positions seamlessly.
+`animateLayout()` method is a fancy form of revalidate that animates the components into their laid out position. After changing the layout & invoking this method the components move to their new sizes/positions seamlessly. `Form` exposes convenience wrappers such as `animateLayout*()` that simply forward to the underlying content pane, so you can usually call the methods directly on the form unless you specifically need to animate a nested container.
 
 This sort of behavior creates a special case where setting the size/position makes sense. When we set the size/position in the demo code here we are positioning the components at the animation start position above the frame.
 
@@ -45,15 +45,15 @@ fall.addActionListener((e) -> {
         b.setY(-fall.getHeight());
         hi.add(b);
     }
-    hi.getContentPane().animateLayout(20000); // <2>
+    hi.animateLayout(20000); // <2>
 });
 hi.add(fall);
 ----
 
 There are a couple of things that you should notice about this example:
 
 <1> We used a button to do the animation rather than doing it on show. Since `show()` implicitly lays out the components it wouldn't have worked correctly.
-<2> We used `hi.getContentPane().animateLayout(20000);` & not `hi.animateLayout(20000);`. You need to animate the "actual" container and `Form` is a special case.
+<2> We used `hi.animateLayout(20000);`, which delegates to the `Form` content pane. If you need to animate a specific container (e.g. a nested layout), call `animateLayout()` on that container instead.
 
 
 This results in:
@@ -71,7 +71,7 @@ image:img/developer-guide/layout-animation-7.png[Frame 7]
 
 While layout animations are really powerful effects for adding elements into the UI and drawing attention to them. The inverse of removing an element from the UI is often more important. E.g. when we delete or remove an element we want to animate it out.
 
-Layout animations don't really do that since they will try to bring the animated item into place. What we want is the exact opposite of a layout animation and that is the "unlayout animation".
+Layout animations don't really do that since they will try to bring the animated item into place. What we want is the exact opposite of a layout animation and that is the "unlayout animation". `Container.animateUnlayout(int, int, Runnable)` and the `Form.animateUnlayout*()` helpers let you trigger this transition either asynchronously (with a completion callback) or synchronously via the `AndWait` variants.
 
 The "unlayout animation" takes a valid laid out state and shifts the components to an invalid state that we defined in advance. E.g. we can fix the example above to flip the "fall" button into a "rise" button when the buttons come into place and this will allow the buttons to float back up to where they came from in the exact reverse order.
 
@@ -92,14 +92,14 @@ fall.addActionListener((e) -> {
             b.setY(-fall.getHeight());
             hi.add(b);
         }
-        hi.getContentPane().animateLayout(20000);
+        hi.animateLayout(20000);
     } else {
         fall.setText("Fall");
         for(int iter = 1 ; iter < hi.getContentPane().getComponentCount() ; iter++) { // <1>
             Component c = hi.getContentPane().getComponentAt(iter);
             c.setY(-fall.getHeight()); // <2>
         }
-        hi.getContentPane().animateUnlayoutAndWait(20000, 255); // <3>
+        hi.animateUnlayoutAndWait(20000, 255); // <3>
         hi.removeAll(); // <4>
         hi.add(fall);
         hi.revalidate();
@@ -112,7 +112,7 @@ You will notice some similarities with the unlayout animation but the difference
 
 <1> We loop over existing components (not newly created ones)
 <2> We set the desired end position not the desired starting position
-<3> We used the `AndWait` variant of the animate unlayout call. We could have used the async call as well.
+<3> We used the `animateUnlayoutAndWait(...)` variant to block until completion; `animateUnlayout(duration, opacity, callback)` provides the non-blocking alternative when you want to continue immediately and run code from a callback instead.
 <4> After the animation completes we need to actually remove the elements since the UI is now in an invalid position with elements outside of the screen but still physically there!
 
 ==== Hiding & Visibility
@@ -121,9 +121,9 @@ A common trick for animating Components in Codename One is to set their preferre
 
 Instead of using that trick you can use `setHidden`/`isHidden` who effectively encapsulate this functionality and a bit more.
 
-One of the issues `setHidden` tries to solve is the fact that preferred size doesn't include the margin in the total and thus a component might still occupy space despite being hidden. To solve this the margin is set to `0` when hiding and restored to its original value when showing the component again by resetting the UIID (which resets all style modifications).
+One of the issues `setHidden` tries to solve is the fact that preferred size doesn't include the margin in the total and thus a component might still occupy space despite being hidden. When you request the margin adjustment the current margins are cached, the component is given zero margins while hidden, and those cached values are restored when it is shown again—without resetting the UIID or other style state.
 
-This functionality might be undesirable which is why there is a version of the `setHidden` method that accepts a boolean flag indicating whether the margin/UIID should be manipulated. You can effectively `hide`/`show` a component without deprecated code using something like this:
+This functionality might be undesirable which is why there is a version of the `setHidden` method that accepts a boolean flag indicating whether the margin cache should be manipulated. You can effectively `hide`/`show` a component without deprecated code using something like this:
 
 [source,java]
 ----
@@ -145,13 +145,13 @@ TIP: Notice that the code above uses `setVisible()`, which shouldn't be confused
 
 Most animations have two or three variants:
 
-- Standard animation e.g. `animateLayout(int)`
-- And wait variant e.g. `animateLayoutAndWait(int)`
-- Callback variant e.g. `animateUnlayout(int, int, Runnable)`
+- Standard animation e.g. `animateLayout(int)` or the non-blocking `animateUnlayout(int, int, Runnable)`
+- And wait variant e.g. `animateLayoutAndWait(int)` / `animateUnlayoutAndWait(int, int)`
+- Callback variant e.g. `animateLayoutFade(int, int, Runnable)`
 
 The standard animation is invoked when we don't care about the completion of the animation. We can do this for a standard animation.
 
-NOTE: The unlayout animations don't have a standard variant. Since they leave the UI in an invalid state we must always do something once the animation completes so a standard variant makes no sense
+NOTE: Unlayout animations always leave the container in an invalid state, so even the standard helper expects you to tidy up either in the callback or immediately after the animation finishes.
 
 The `AndWait` variant blocks the calling thread until the animation completes. This is really useful for sequencing animations one after the other e.g this code from the kitchen sink demo:
 
@@ -180,7 +180,7 @@ The callback variant is similar to the `invokeAndBlock` variant but uses a more
 
 [source,java]
 ----
-hi.getContentPane().animateUnlayout(20000, 255, () -> {
+hi.animateUnlayout(20000, 255, () -> {
     hi.removeAll();
     hi.add(fall);
     hi.revalidate();