PopupProperties

Class
Common
expect class PopupProperties

Properties used to customize the behavior of a Popup.

Secondary Constructors

constructor(
    focusable: Boolean = false,
    dismissOnBackPress: Boolean = true,
    dismissOnClickOutside: Boolean = true,
    clippingEnabled: Boolean = true,
    usePlatformDefaultWidth: Boolean = false,
)
constructor(
    focusable: Boolean = false,
    dismissOnBackPress: Boolean = true,
    dismissOnClickOutside: Boolean = true,
    clippingEnabled: Boolean = true,
)

Properties

Common
val focusable: Boolean
Common
val dismissOnBackPress: Boolean
Common
val dismissOnClickOutside: Boolean
Common
val clippingEnabled: Boolean
Common
val usePlatformDefaultWidth: Boolean
Android
actual class PopupProperties
constructor(
    internal val flags: Int,
    internal val inheritSecurePolicy: Boolean = true,
    actual val dismissOnBackPress: Boolean = true,
    actual val dismissOnClickOutside: Boolean = true,
    val excludeFromSystemGesture: Boolean = true,
    actual val usePlatformDefaultWidth: Boolean = false,
    val windowType: Int = WindowManager.LayoutParams.TYPE_APPLICATION_SUB_PANEL,
    val windowToken: IBinder? = null,
)

Properties used to customize the behavior of a Popup.

Secondary Constructors

actual constructor(
    focusable: Boolean,
    dismissOnBackPress: Boolean,
    dismissOnClickOutside: Boolean,
    clippingEnabled: Boolean,
    usePlatformDefaultWidth: Boolean,
) : this(
    focusable = focusable,
    dismissOnBackPress = dismissOnBackPress,
    dismissOnClickOutside = dismissOnClickOutside,
    securePolicy = SecureFlagPolicy.Inherit,
    excludeFromSystemGesture = true,
    clippingEnabled = clippingEnabled,
    usePlatformDefaultWidth = usePlatformDefaultWidth,
    windowType = WindowManager.LayoutParams.TYPE_APPLICATION_SUB_PANEL,
    windowToken = null,
)
constructor(
    focusable: Boolean = false,
    dismissOnBackPress: Boolean = true,
    dismissOnClickOutside: Boolean = true,
    securePolicy: SecureFlagPolicy = SecureFlagPolicy.Inherit,
    excludeFromSystemGesture: Boolean = true,
    clippingEnabled: Boolean = true,
    usePlatformDefaultWidth: Boolean = false,
) : this(
    focusable = focusable,
    dismissOnBackPress = dismissOnBackPress,
    dismissOnClickOutside = dismissOnClickOutside,
    securePolicy = securePolicy,
    excludeFromSystemGesture = excludeFromSystemGesture,
    clippingEnabled = clippingEnabled,
    usePlatformDefaultWidth = usePlatformDefaultWidth,
    windowType = WindowManager.LayoutParams.TYPE_APPLICATION_SUB_PANEL,
    windowToken = null,
)
constructor(
    flags: Int,
    inheritSecurePolicy: Boolean = true,
    dismissOnBackPress: Boolean = true,
    dismissOnClickOutside: Boolean = true,
    excludeFromSystemGesture: Boolean = true,
    usePlatformDefaultWidth: Boolean = false,
) : this(
    flags = flags,
    inheritSecurePolicy = inheritSecurePolicy,
    dismissOnBackPress = dismissOnBackPress,
    dismissOnClickOutside = dismissOnClickOutside,
    excludeFromSystemGesture = excludeFromSystemGesture,
    usePlatformDefaultWidth = usePlatformDefaultWidth,
    windowType = WindowManager.LayoutParams.TYPE_APPLICATION_SUB_PANEL,
    windowToken = null,
)
actual constructor(
    focusable: Boolean,
    dismissOnBackPress: Boolean,
    dismissOnClickOutside: Boolean,
    clippingEnabled: Boolean,
) : this(
    focusable = focusable,
    dismissOnBackPress = dismissOnBackPress,
    dismissOnClickOutside = dismissOnClickOutside,
    securePolicy = SecureFlagPolicy.Inherit,
    excludeFromSystemGesture = true,
    clippingEnabled = clippingEnabled,
)
constructor(
    focusable: Boolean = false,
    dismissOnBackPress: Boolean = true,
    dismissOnClickOutside: Boolean = true,
    securePolicy: SecureFlagPolicy = SecureFlagPolicy.Inherit,
    excludeFromSystemGesture: Boolean = true,
    clippingEnabled: Boolean = true,
) : this(
    focusable = focusable,
    dismissOnBackPress = dismissOnBackPress,
    dismissOnClickOutside = dismissOnClickOutside,
    securePolicy = securePolicy,
    excludeFromSystemGesture = excludeFromSystemGesture,
    clippingEnabled = clippingEnabled,
    usePlatformDefaultWidth = false,
)
constructor(
    focusable: Boolean = false,
    dismissOnBackPress: Boolean = true,
    dismissOnClickOutside: Boolean = true,
    securePolicy: SecureFlagPolicy = SecureFlagPolicy.Inherit,
    excludeFromSystemGesture: Boolean = true,
    clippingEnabled: Boolean = true,
    usePlatformDefaultWidth: Boolean = false,
    windowType: Int = WindowManager.LayoutParams.TYPE_APPLICATION_SUB_PANEL,
    windowToken: IBinder? = null,
) : this(
    flags = createFlags(focusable, securePolicy, clippingEnabled),
    inheritSecurePolicy = securePolicy == SecureFlagPolicy.Inherit,
    dismissOnBackPress = dismissOnBackPress,
    dismissOnClickOutside = dismissOnClickOutside,
    excludeFromSystemGesture = excludeFromSystemGesture,
    usePlatformDefaultWidth = usePlatformDefaultWidth,
    windowType = windowType,
    windowToken = windowToken,
)

Constructs a PopupProperties with the given behaviors. This constructor is to support multiplatform and maintain backwards compatibility. Consider the overload that takes a flags parameter if more precise control over the popup flags is desired.

Parameters
focusable Whether the popup is focusable. When true, the popup will receive IME events and key presses, such as when the back button is pressed.
dismissOnBackPress Whether the popup can be dismissed by pressing the back or escape buttons. If true, pressing the back or escape buttons will call onDismissRequest. Note that focusable must be set to true in order to receive key events such as the back button. If the popup is not focusable, then this property does nothing.
dismissOnClickOutside Whether the popup can be dismissed by clicking outside the popup's bounds. If true, clicking outside the popup will call onDismissRequest.
securePolicy Policy for setting WindowManager.LayoutParams.FLAG_SECURE on the popup's window.
excludeFromSystemGesture A flag to check whether to set the systemGestureExclusionRects. The default is true.
clippingEnabled Whether to allow the popup window to extend beyond the bounds of the screen. By default the window is clipped to the screen boundaries. Setting this to false will allow windows to be accurately positioned. The default value is true.
usePlatformDefaultWidth Whether the width of the popup's content should be limited to the platform default, which is smaller than the screen width.
windowType An optional WindowManager.LayoutParams.type for the popup window. Defaults to WindowManager.LayoutParams.TYPE_APPLICATION_SUB_PANEL. Overriding this allows you to change the layer or behavior of the popup. For example, setting it to WindowManager.LayoutParams.TYPE_APPLICATION_OVERLAY can be used to display a popup on top of all other applications (which requires the android.Manifest.permission.SYSTEM_ALERT_WINDOW permission). Note: If you are displaying a popup from a non-Activity context (such as an android.app.Service) but still want it to be anchored to an existing application window, you should leave this as the default sub-panel type and instead provide the windowToken of the target application window.
windowToken An optional android.os.IBinder to be used as the window token for the popup window. In most cases, this can be left null, and the popup will use the token from the hosting Compose view (android.view.View.getApplicationWindowToken). However, this parameter is essential for cross-process scenarios. For instance, if a Service running in a different process needs to display a popup anchored to a window in the main application process, the main application's window token must be provided here. The provided token must be a validandroid.os.IBinder from an existing window and must have the necessary permissions to add sub-windows of the specifiedwindowType. Providing an invalid, stale, or permission-denied token will typically result in an android.view.WindowManager.BadTokenException when the popup attempts to show.

Properties

Android
actual val focusable: Boolean

Whether the popup is focusable. When true, the popup will receive IME events and key presses, such as when the back button is pressed.

Android
val securePolicy: SecureFlagPolicy

Policy for how WindowManager.LayoutParams.FLAG_SECURE is set on the popup's window.

Android
actual val clippingEnabled: Boolean

Whether the popup window is clipped to the screen boundaries, or allowed to extend beyond the bounds of the screen.

Code Examples

PopupFromServiceSample

@Composable
fun PopupFromServiceSample() {
    // In a real Service scenario, appWindowToken would be received via IPC
    // from the main application process. This sample simulates having the token.
    val appWindowToken: IBinder? = null // Provided via IPC
    var showPopup by remember { mutableStateOf(false) }
    Button(onClick = { showPopup = true }) { Text("Show Popup From Service") }
    if (showPopup) {
        Popup(
            onDismissRequest = { showPopup = false },
            properties =
                PopupProperties(
                    // Pass the application's window token
                    windowToken = appWindowToken
                ),
        ) {
            Box(Modifier.size(200.dp, 100.dp).background(Color.Blue.copy(alpha = 0.8f))) {
                Text("Popup Content (Service)", color = Color.White)
            }
        }
    }
}