Skip to content

One UI Blur Integration

Jump to bottom
Josh Skinner edited this page Jun 30, 2026 · 2 revisions

One UI Blur Integration

Third-party Android widgets can hook into Samsung One UI Home's native wallpaper blur, the frosted-glass effect used by Samsung's own Weather, Clock, and Calendar widgets. Samsung does not document this, but it works on One UI 7.0+ devices.

The widget itself never renders a blur. It declares the right metadata and paints a semi-transparent background. The launcher detects that, captures the wallpaper region behind the widget, blurs it, and draws it underneath. Your background color then tints the result.

For a working reference, see:

The Three Requirements

1. The root view must have android:id="@android:id/background"

This is the critical piece. One UI Home walks each widget's view hierarchy looking for a view with the framework ID @android:id/background (0x01020000). If it is not found, blur is never applied.

Once found, the launcher reads the alpha channel of that view's background, usually a ColorDrawable or GradientDrawable. The alpha must be between 1 and 254. Fully transparent (0) and fully opaque (255) both disable blur.

<!-- res/layout/widget_layout.xml -->
<FrameLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@android:id/background"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="#80FFFFFF">

    <!-- Your widget content here. -->

</FrameLayout>

2. Set app:widgetStyle="colorful"

One UI Home checks for Samsung's colorful widget-style flag. Without it, the widget is treated as legacy or monotone and blur is skipped.

Define the Samsung attributes once in res/values/attrs.xml:

<resources>
    <attr name="widgetStyle" format="integer">
        <flag name="colorful" value="0x1" />
        <flag name="monotone" value="0x2" />
    </attr>

    <attr name="widgetSize" format="integer">
        <flag name="tiny" value="0x1" />
        <flag name="small" value="0x2" />
        <flag name="wideSmall" value="0x4" />
        <flag name="medium" value="0x8" />
        <flag name="large" value="0x10" />
        <flag name="extraLarge" value="0x20" />
        <flag name="extraLargeLong" value="0x40" />
    </attr>
</resources>

Then reference them from your provider XML using the app: namespace:

<appwidget-provider
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:initialLayout="@layout/widget_layout"
    android:minWidth="110dp"
    android:minHeight="40dp"
    android:targetCellWidth="2"
    android:targetCellHeight="1"
    android:widgetCategory="home_screen"
    app:widgetStyle="colorful"
    app:widgetSize="small|wideSmall|medium|large" />

3. Set a real app:widgetSize

The launcher reads widgetSize to decide sizing behavior. If it resolves to Unknown, which is the default when omitted, the launcher returns false from its background-blur check. Set it to whichever sizes your widget supports.

What One UI Home Does

When all three conditions are met, One UI Home:

  1. Captures the wallpaper region behind the widget.
  2. Applies a blur to that crop.
  3. Draws the blurred wallpaper behind your widget view.
  4. Uses your semi-transparent background color as the tint over that blur.

Controlling Opacity

The background alpha directly controls the blur appearance. Lower alpha means more transparency and more visible wallpaper blur.

Alpha Hex Effect
~38 #26FFFFFF Glass: very transparent, strong blur visible
~102 #66FFFFFF Light: moderate transparency
~178 #B2FFFFFF Medium: mostly opaque with subtle blur
~240 #F0FFFFFF Solid: nearly opaque, minimal visible blur

Set the background color at runtime via RemoteViews:

val alpha = 102 // Must stay in 1..254.
val bgColor = Color.argb(alpha, 255, 255, 255)
views.setInt(android.R.id.background, "setBackgroundColor", bgColor)

Use RGB values of 255, 255, 255 for a light tint, 0, 0, 0 for a dark tint, or HSV values if you want a configurable color picker.

Blur Widget Demo stores per-widget hue, saturation, value, and alpha in SharedPreferences, then rebuilds the color with Color.HSVToColor.

Static Preview Layouts

One UI's widget picker may inflate preview layouts separately from the live RemoteViews path. Provide a static android:previewLayout and Samsung per-size preview layouts so the picker has something safe to show:

<appwidget-provider
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:initialLayout="@layout/widget_blur"
    android:previewLayout="@layout/widget_preview_strip"
    app:previewLayoutSmall="@layout/widget_preview_strip"
    app:previewLayoutWideSmall="@layout/widget_preview_strip"
    app:previewLayoutMedium="@layout/widget_preview_square"
    app:previewLayoutLarge="@layout/widget_preview_large"
    app:previewLayoutExtraLarge="@layout/widget_preview_large"
    app:previewLayoutExtraLargeLong="@layout/widget_preview_large" />

Keep preview layouts simple. Avoid collection widgets, services, or anything that depends on runtime-only RemoteViews behavior.

Featured Widget Labels

One UI Home can show a label below featured widgets. Define featuredWidget and reference it from the provider XML:

<attr name="featuredWidget" format="integer">
    <flag name="tiny" value="0x1" />
    <flag name="small" value="0x2" />
    <flag name="wideSmall" value="0x4" />
    <flag name="medium" value="0x8" />
    <flag name="large" value="0x10" />
    <flag name="extraLarge" value="0x20" />
    <flag name="extraLargeLong" value="0x40" />
</attr>
app:featuredWidget="small|wideSmall|medium|large"

The label text comes from the receiver's android:label in the manifest.

Checklist

  • Root widget view has android:id="@android:id/background".
  • Root background alpha is between 1 and 254.
  • attrs.xml defines widgetStyle and widgetSize.
  • Provider XML sets app:widgetStyle="colorful".
  • Provider XML sets app:widgetSize to at least one supported size.
  • Provider XML includes static preview layouts for picker reliability.

Related

Clone this wiki locally