public class InteractionDialog

The top level this dialog appears on when it is shown.

A dialog is not attached to anything at the moment #show(int, int, int, int) runs, so it cannot resolve its own host the way an attached component can. Left unset it uses the current Form, which is the historical behaviour and the right answer for an application with one window. Set it to put the dialog on a Window instead: without it the dialog is added to the main form’s layered pane, so it appears on the main window while the window that asked for it is merely dimmed – and in an application with no form at all there is nothing to resolve and showing it fails.

Sets whether this dialog is backed by a real operating system window.

Takes effect the next time the dialog is shown.

Repositions a dialog that is laid out inside a host surface.

The four arguments are margins against that host, so they describe nothing a platform window has: in native window mode the dialog is the content of a window the operating system places, sizes and lets the user drag. This is inert there rather than approximated, which is the same rule the margin arguments to show() follow – and the body below would otherwise rewrite the geometry of the window’s own content pane and animate a layer built on the owner surface, neither of which has anything to do with the dialog the caller is trying to resize.

This method shows the form as a modal alert allowing us to produce a behavior of an alert/dialog box. This method will block the calling thread even if the calling thread is the EDT. Notice that this method will not release the block until dispose is called even if show() from another form is called!

Modal dialogs Allow the forms “content” to “hang in mid air” this is especially useful for dialogs where you would want the underlying form to “peek” from behind the form.

Callback invoked just before the show animation runs to position the dialog parent at the animation start state. When set, this replaces the default #setRepositionAnimation(boolean) behavior (grow from a 1x1 point at the center, or stay at full size). Inside the callback, manipulate getParent() bounds (setX/setY/setWidth/setHeight) to define where the dialog should animate from. The animation will then interpolate the layered pane layout to the dialog’s final bounds. Pass null (the default) to use the built-in show animation.

This callback only fires when #isAnimateShow() is true.

This hook is the recommended workaround when using popup dialogs that render a pointing-arrow border (#showPopupDialog(com.codename1.ui.Component)). With the built-in “grow from 1x1” animation the dialog is too small for the arrow image to render until the animation completes; providing a translate-from-edge setup keeps the dialog at full size for the entire animation so the arrow is visible throughout. For example, to slide in from off-screen below:

dlg.setShowAnimationSetup(() -> {
    Container parent = dlg.getParent();
    parent.setY(Display.getInstance().getDisplayHeight());
});

Callback invoked just before the dispose animation runs to position the dialog at the animation end state. When set, this replaces the default #setRepositionAnimation(boolean) behavior (shrink to a 1x1 point at the dialog center). Inside the callback, manipulate the dialog bounds (setX/setY/setWidth/setHeight) to define where the dialog should animate to. Pass null (the default) to use the built-in dispose animation.

This callback only fires when #isAnimateShow() is true.

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.

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.

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.

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.

Opt-in robustness mode for applications that show several InteractionDialogs at the same time (for example a step-by-step walkthrough that highlights different components).

All InteractionDialog instances share a single layered pane keyed by the class. In the default (historical) behavior, disposing one dialog clears that whole layer (removeAll() / layer removal), which also wipes any sibling dialog still showing in it – so when dialogs overlap one of them can silently fail to appear (#5193). When stackable mode is enabled dispose removes only the disposed dialog’s own component; remaining dialogs stay visible, layered by the order in which #show(int, int, int, int) was called (later shows render on top). The shared layer container is removed only once it becomes empty, so layers do not accumulate as dialogs come and go.

This is a global, app-wide setting (it must be on for every dialog that participates) and defaults to false to preserve backwards compatibility.