From d0667a3440ab453ce7cd45072a71242ed22ca64e Mon Sep 17 00:00:00 2001 From: Shai Almog <67850168+shai-almog@users.noreply.github.com> Date: Fri, 29 May 2026 18:50:47 +0300 Subject: [PATCH] docs(InteractionDialog): clarify animation, formMode, and no-op transitions (#5071) Expand the documentation on InteractionDialog to address the four areas flagged in #5071: - setAnimateShow / setRepositionAnimation cross-reference each other and explicitly state that repositionAnimation is gated on animateShow. - setRepositionAnimation now describes the "grow from / shrink to a 1x1 point at the center" effect and what false actually means. - setFormMode explains the two layered panes, what each is appropriate for, that showPopupDialog(Component) auto-enables it when the target lives outside the content pane, and gives a default recommendation. - setTransitions is now documented as a no-op, pointing readers at setAnimateShow / setRepositionAnimation for actual animation control. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../components/InteractionDialog.java | 84 +++++++++++++++++-- 1 file changed, 77 insertions(+), 7 deletions(-) diff --git a/CodenameOne/src/com/codename1/components/InteractionDialog.java b/CodenameOne/src/com/codename1/components/InteractionDialog.java index 3c7d3be56e..e1a85034bb 100644 --- a/CodenameOne/src/com/codename1/components/InteractionDialog.java +++ b/CodenameOne/src/com/codename1/components/InteractionDialog.java @@ -587,7 +587,12 @@ public boolean isShowing() { return getParent() != null; } - /// Indicates whether show/dispose should be animated or not + /// Indicates whether show/dispose should be animated or not. When true (the default) + /// the dialog animates into view on `#show(int, int, int, int)` and out on + /// `#dispose()` over `interactionDialogSpeedInt` (default 400ms). When false, both + /// transitions are immediate. This flag also gates `#isRepositionAnimation()`: + /// the grow/shrink behavior of `repositionAnimation` only takes effect when + /// `animateShow` is true. /// /// #### Returns /// @@ -596,7 +601,12 @@ public boolean isAnimateShow() { return animateShow; } - /// Indicates whether show/dispose should be animated or not + /// Indicates whether show/dispose should be animated or not. When true (the default) + /// the dialog animates into view on `#show(int, int, int, int)` and out on + /// `#dispose()` over `interactionDialogSpeedInt` (default 400ms). When false, both + /// transitions are immediate. This flag also gates `#setRepositionAnimation(boolean)`: + /// the grow/shrink behavior of `repositionAnimation` only takes effect when + /// `animateShow` is true. /// /// #### Parameters /// @@ -989,7 +999,17 @@ public Style getDialogStyle() { return getContentPane().getStyle(); } - /// Repositions the component so the animation will "grow/shrink" when showing/disposing + /// Controls the "grow from center / shrink to center" effect used by the + /// show/dispose animation. When true (the default), `#show(int, int, int, int)` + /// collapses the dialog to a 1x1 point at the center of its target bounds and + /// the layered pane's animation interpolates from that point out to the full + /// dialog size. `#dispose()` performs the reverse, shrinking the dialog to a + /// point before removal. When false, the dialog keeps its full size for the + /// duration of the animation (only the layered pane's layout transition runs, + /// which is typically not visible for a dialog whose bounds do not change). + /// + /// This flag has no effect when `#isAnimateShow()` is false, since the + /// show/dispose animation is skipped entirely in that case. /// /// #### Returns /// @@ -998,7 +1018,17 @@ public boolean isRepositionAnimation() { return repositionAnimation; } - /// Repositions the component so the animation will "grow/shrink" when showing/disposing + /// Controls the "grow from center / shrink to center" effect used by the + /// show/dispose animation. When true (the default), `#show(int, int, int, int)` + /// collapses the dialog to a 1x1 point at the center of its target bounds and + /// the layered pane's animation interpolates from that point out to the full + /// dialog size. `#dispose()` performs the reverse, shrinking the dialog to a + /// point before removal. When false, the dialog keeps its full size for the + /// duration of the animation (only the layered pane's layout transition runs, + /// which is typically not visible for a dialog whose bounds do not change). + /// + /// This flag has no effect when `#isAnimateShow()` is false, since the + /// show/dispose animation is skipped entirely in that case. /// /// #### Parameters /// @@ -1007,7 +1037,25 @@ public void setRepositionAnimation(boolean repositionAnimation) { this.repositionAnimation = repositionAnimation; } - /// Whether the interaction dialog uses the form layered pane of the regular layered pane + /// Selects which layered pane hosts the dialog. + /// + /// When false (the default), the dialog is added to `Form#getLayeredPane()`, + /// which sits above the form's content pane but below the title area, side + /// menu, and status bar. This is the right choice for most dialogs that + /// interact with content pane components, and is the historical behavior of + /// `InteractionDialog`. + /// + /// When true, the dialog is added to `Form#getFormLayeredPane(Class, boolean)`, + /// which sits above the entire form including the title area and side menu. + /// Use this when the dialog needs to overlay or point at a component that + /// lives outside the content pane (for example a title bar button or an item + /// in the side menu). `#showPopupDialog(Component)` enables this + /// automatically when it detects that the target component is not inside the + /// form's content pane. + /// + /// In short, leave this at the default unless you observe the dialog being + /// clipped by the title/side menu or you are pointing at a component outside + /// the content pane. /// /// #### Returns /// @@ -1016,7 +1064,25 @@ public boolean isFormMode() { return formMode; } - /// Whether the interaction dialog uses the form layered pane of the regular layered pane + /// Selects which layered pane hosts the dialog. + /// + /// When false (the default), the dialog is added to `Form#getLayeredPane()`, + /// which sits above the form's content pane but below the title area, side + /// menu, and status bar. This is the right choice for most dialogs that + /// interact with content pane components, and is the historical behavior of + /// `InteractionDialog`. + /// + /// When true, the dialog is added to `Form#getFormLayeredPane(Class, boolean)`, + /// which sits above the entire form including the title area and side menu. + /// Use this when the dialog needs to overlay or point at a component that + /// lives outside the content pane (for example a title bar button or an item + /// in the side menu). `#showPopupDialog(Component)` enables this + /// automatically when it detects that the target component is not inside the + /// form's content pane. + /// + /// In short, leave this at the default unless you observe the dialog being + /// clipped by the title/side menu or you are pointing at a component outside + /// the content pane. /// /// #### Parameters /// @@ -1031,7 +1097,11 @@ public void setDialogType(int dialogType) { // no-op for InteractionDialog. Dialog sounds are specific to Dialog/Form internals. } - /// {@inheritDoc} + /// No-op for `InteractionDialog`. Transitions are not supported; the show + /// and dispose animations are governed by `#setAnimateShow(boolean)` and + /// `#setRepositionAnimation(boolean)` and run on the host layered pane + /// rather than as a Form-level transition. The method is provided only to + /// satisfy the `AbstractDialog` contract. @Override public void setTransitions(Transition transition) { }