PopupProperties

Added in 1.0.0

Cmn
```
class PopupProperties
```

Properties used to customize the behavior of a Popup.

Summary

Public constructors
`PopupProperties( focusable: Boolean, dismissOnBackPress: Boolean, dismissOnClickOutside: Boolean, clippingEnabled: Boolean, usePlatformDefaultWidth: Boolean )`	Cmn android
`PopupProperties( focusable: Boolean, dismissOnBackPress: Boolean, dismissOnClickOutside: Boolean, securePolicy: SecureFlagPolicy, excludeFromSystemGesture: Boolean, clippingEnabled: Boolean )`	android
`PopupProperties( flags: Int, inheritSecurePolicy: Boolean, dismissOnBackPress: Boolean, dismissOnClickOutside: Boolean, excludeFromSystemGesture: Boolean, usePlatformDefaultWidth: Boolean, windowType: Int, windowToken: IBinder?, blurBehindRadius: Dp, scrimAlpha: Float )`	android
`PopupProperties( focusable: Boolean, dismissOnBackPress: Boolean, dismissOnClickOutside: Boolean, securePolicy: SecureFlagPolicy, excludeFromSystemGesture: Boolean, clippingEnabled: Boolean, usePlatformDefaultWidth: Boolean, windowType: Int, windowToken: IBinder?, blurBehindRadius: Dp, scrimAlpha: Float )` Constructs a `PopupProperties` with the given behaviors.	android

Public functions
`open operator Boolean`	`equals(other: Any?)`	android
`open Int`	`hashCode()`	android

Public properties
`Dp`	`blurBehindRadius` Blurs the screen behind the window.	android
`Boolean`	`clippingEnabled` Whether to allow the popup window to extend beyond the bounds of the screen.	Cmn android
`Boolean`	`dismissOnBackPress` Whether the popup can be dismissed by pressing the back or escape buttons on Android or the escape key on desktop.	Cmn android
`Boolean`	`dismissOnClickOutside` Whether the popup can be dismissed by clicking outside the popup's bounds.	Cmn android
`Boolean`	`excludeFromSystemGesture` A flag to check whether to set the systemGestureExclusionRects.	android
`Boolean`	`focusable` Whether the popup is focusable.	Cmn android
`Float`	`scrimAlpha` The opacity of the scrim (also known as dimming) applied behind the popup window.	android
`SecureFlagPolicy`	`securePolicy` Policy for how `WindowManager.LayoutParams.FLAG_SECURE` is set on the popup's window.	android
`Boolean`	`usePlatformDefaultWidth` Whether the width of the popup's content should be limited to the platform default, which is smaller than the screen width.	Cmn android
`IBinder?`	`windowToken` An optional `android.os.IBinder` to be used as the window token for the popup window.	android
`Int`	`windowType` An optional `WindowManager.LayoutParams.type` for the popup window.	android

Public constructors

PopupProperties

Cmn android

Added in 1.11.0

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

PopupProperties

android

Added in 1.0.0

PopupProperties(
    focusable: Boolean = false,
    dismissOnBackPress: Boolean = true,
    dismissOnClickOutside: Boolean = true,
    securePolicy: SecureFlagPolicy = SecureFlagPolicy.Inherit,
    excludeFromSystemGesture: Boolean = true,
    clippingEnabled: Boolean = true
)

PopupProperties

android

Added in 1.13.0-alpha01

PopupProperties(
    flags: Int,
    inheritSecurePolicy: Boolean = true,
    dismissOnBackPress: Boolean = true,
    dismissOnClickOutside: Boolean = true,
    excludeFromSystemGesture: Boolean = true,
    usePlatformDefaultWidth: Boolean = false,
    windowType: Int = WindowManager.LayoutParams.TYPE_APPLICATION_SUB_PANEL,
    windowToken: IBinder? = null,
    blurBehindRadius: Dp = Dp.Unspecified,
    scrimAlpha: Float = Float.NaN
)

PopupProperties

android

Added in 1.13.0-alpha01

PopupProperties(
    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,
    blurBehindRadius: Dp = Dp.Unspecified,
    scrimAlpha: Float = Float.NaN
)

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.

import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.size
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.Popup
import androidx.compose.ui.window.PopupProperties

// 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)
        }
    }
}

Parameters
`focusable: Boolean = false`	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: Boolean = true`	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: Boolean = true`	Whether the popup can be dismissed by clicking outside the popup's bounds. If true, clicking outside the popup will call onDismissRequest.
`securePolicy: SecureFlagPolicy = SecureFlagPolicy.Inherit`	Policy for setting `WindowManager.LayoutParams.FLAG_SECURE` on the popup's window.
`excludeFromSystemGesture: Boolean = true`	A flag to check whether to set the systemGestureExclusionRects. The default is true.
`clippingEnabled: Boolean = true`	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: Boolean = false`	Whether the width of the popup's content should be limited to the platform default, which is smaller than the screen width.
`windowType: Int = WindowManager.LayoutParams.TYPE_APPLICATION_SUB_PANEL`	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: IBinder? = null`	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 valid`android.os.IBinder` from an existing window and must have the necessary permissions to add sub-windows of the specified`windowType`. Providing an invalid, stale, or permission-denied token will typically result in an `android.view.WindowManager.BadTokenException` when the popup attempts to show.
`blurBehindRadius: Dp = Dp.Unspecified`	Blurs the screen behind the window. The effect is similar to that of `scrimAlpha`, but instead of having a scrim applied, the content behind the window will be blurred (or combined with the scrim opacity, if such is specified). The density of the blur is set by the blur radius. The radius defines the size of the neighboring area, from which pixels will be averaged to form the final color for each pixel. The operation approximates a Gaussian blur. A radius of `0.dp` means no blur. The higher the radius, the denser the blur. Some devices might not support cross-window blur due to GPU limitations. It can also be disabled by the system at runtime (e.g. during battery saving mode). In such situations, no blur will be computed or drawn. Supported on Android 12 (`Build.VERSION_CODES.S`) and above.
`scrimAlpha: Float = Float.NaN`	The opacity of the scrim (also known as dimming) applied behind the popup window. Ranging from 0.0f (no scrim) to 1.0f (completely opaque). By default, this value is `Float.NaN`, which means the popup retains the standard system popup behavior with no scrim applied behind the window. Example usage:

Public functions

equals

android

open operator fun equals(other: Any?): Boolean

hashCode

android

open fun hashCode(): Int

Public properties

blurBehindRadius

android

val blurBehindRadius: Dp

Blurs the screen behind the window. The effect is similar to that of scrimAlpha, but instead of having a scrim applied, the content behind the window will be blurred (or combined with the scrim opacity, if such is specified). The density of the blur is set by the blur radius. The radius defines the size of the neighboring area, from which pixels will be averaged to form the final color for each pixel. The operation approximates a Gaussian blur. A radius of 0.dp means no blur. The higher the radius, the denser the blur. For blur behind, a radius of 10.dp (~20 px) creates a good depth-of-field effect. Avoid blur radii higher than 50.dp (~150 px), as this will significantly impact performance. Some devices might not support cross-window blur due to GPU limitations. It can also be disabled by the system at runtime (e.g. during battery saving mode). In such situations, no blur will be computed or drawn. Supported on Android 12 (Build.VERSION_CODES.S) and above.

clippingEnabled

Cmn android

Added in 1.0.0

val clippingEnabled: Boolean

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.

dismissOnBackPress

Cmn android

Added in 1.0.0

val dismissOnBackPress: Boolean

Whether the popup can be dismissed by pressing the back or escape buttons on Android or the escape key on desktop. If true, pressing the back button 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

Cmn android

Added in 1.0.0

val dismissOnClickOutside: Boolean

Whether the popup can be dismissed by clicking outside the popup's bounds. If true, clicking outside the popup will call onDismissRequest.

excludeFromSystemGesture

android

Added in 1.0.0

val excludeFromSystemGesture: Boolean

A flag to check whether to set the systemGestureExclusionRects. The default is true.

focusable

Cmn android

Added in 1.0.0

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.

scrimAlpha

android

Added in 1.13.0-alpha01

val scrimAlpha: Float

The opacity of the scrim (also known as dimming) applied behind the popup window. Ranging from 0.0f (no scrim) to 1.0f (completely opaque). By default, this value is Float.NaN, which means the popup retains the standard system popup behavior with no scrim applied behind the window.

Example usage:

securePolicy

android

Added in 1.0.0

val securePolicy: SecureFlagPolicy

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

usePlatformDefaultWidth

Cmn android

Added in 1.0.0

val usePlatformDefaultWidth: Boolean

Whether the width of the popup's content should be limited to the platform default, which is smaller than the screen width.

windowToken

android

Added in 1.11.0

val windowToken: IBinder?

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.

windowType

android

Added in 1.11.0

val windowType: Int

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.