Lock Screen Widgets

Lock Screen Widgets

Samsung lock-screen widgets use a separate contract from colorful home-screen blur widgets. Treat them as compact RemoteViews providers with monotone metadata and static layouts the lock-screen picker can inflate.

Blur Widget Demo includes:

• Blur Message 1x1, backed by LockScreenMessageSmallWidget.
• Blur Message 2x1, backed by LockScreenMessageWideWidget.
• LockScreenMessageServiceBoxReceiver, which answers Samsung SystemUI REQUEST_SERVICEBOX_REMOTEVIEWS broadcasts with the same RemoteViews.

For the working source, see:

• LockScreenMessageWidgets.kt
• lockscreen_message_1x1.xml
• lockscreen_message_2x1.xml
• lockscreen_message_1x1_widget_info.xml
• lockscreen_message_2x1_widget_info.xml
• AndroidManifest.xml

Device Setup

After installing the app on a Samsung device:

1. Open the lock-screen editor.
2. Choose Widgets.
3. Add Blur Message 1x1 or Blur Message 2x1.
4. Wake the lock screen or wait for the widget update interval to see a short randomized message such as Glass, Calm, or Breathe.

1. Define Samsung Lock-Screen Attributes

Add the lock-screen host, tiny size, per-size layout, and monotone preview attributes alongside the home-screen widgetStyle and widgetSize definitions.

<!-- res/values/attrs.xml -->
<resources>
    <attr name="allowMultipleSizes" format="boolean" />

    <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>

    <attr name="initialLayoutTiny" format="reference" />
    <attr name="initialLayoutSmall" format="reference" />
    <attr name="initialLayoutMedium" format="reference" />
    <attr name="monotonePreviewLayoutTiny" format="reference" />
    <attr name="monotonePreviewLayoutSmall" format="reference" />
    <attr name="monotonePreviewLayoutMedium" format="reference" />
    <attr name="previewLayoutTiny" format="reference" />
    <attr name="previewLayoutSmall" format="reference" />
    <attr name="previewLayoutMedium" format="reference" />

    <attr name="targetHost" format="integer">
        <flag name="home" value="0x1" />
        <flag name="lock_and_aod" value="0x2" />
        <flag name="cover" value="0x4" />
        <flag name="edge" value="0x8" />
        <flag name="dex_home" value="0x10" />
        <flag name="smart_page" value="0x20" />
    </attr>
</resources>

2. Create Compact RemoteViews Layouts

Keep lock-screen layouts simple: transparent root, centered white text, and launcher-safe views. Avoid collection widgets or runtime-only services in the preview path.

<!-- res/layout/lockscreen_message_1x1.xml -->
<FrameLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:padding="6dp">

    <TextView
        android:id="@+id/lockscreen_message"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:ellipsize="end"
        android:fontFamily="sec"
        android:gravity="center"
        android:includeFontPadding="false"
        android:maxLines="2"
        android:text="@string/lockscreen_message_preview"
        android:textColor="@android:color/white"
        android:textSize="13sp" />
</FrameLayout>

For 2x1, use the same pattern with wider horizontal padding and maxLines="1".

3. Add Provider XML For Each Size

Use one appwidget provider XML per lock-screen size.

1x1 Provider

The 1x1 widget maps to Samsung's tiny size.

<!-- res/xml/lockscreen_message_1x1_widget_info.xml -->
<appwidget-provider
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:initialLayout="@layout/lockscreen_message_1x1"
    android:minWidth="56dp"
    android:minHeight="56dp"
    android:minResizeWidth="56dp"
    android:minResizeHeight="56dp"
    android:previewLayout="@layout/lockscreen_message_1x1"
    android:targetCellWidth="1"
    android:targetCellHeight="1"
    android:updatePeriodMillis="1800000"
    android:widgetCategory="0x2000"
    app:initialLayoutTiny="@layout/lockscreen_message_1x1"
    app:previewLayoutTiny="@layout/lockscreen_message_1x1"
    app:targetHost="lock_and_aod|cover"
    app:widgetSize="tiny"
    app:widgetStyle="monotone" />

2x1 Provider

The 2x1 widget maps to Samsung's small and medium lock-screen sizes.

<!-- res/xml/lockscreen_message_2x1_widget_info.xml -->
<appwidget-provider
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:initialLayout="@layout/lockscreen_message_2x1"
    android:minWidth="124dp"
    android:minHeight="56dp"
    android:minResizeWidth="124dp"
    android:minResizeHeight="56dp"
    android:previewLayout="@layout/lockscreen_message_2x1"
    android:targetCellWidth="2"
    android:targetCellHeight="1"
    android:updatePeriodMillis="1800000"
    android:widgetCategory="0x2000"
    app:monotonePreviewLayoutSmall="@layout/lockscreen_message_2x1"
    app:monotonePreviewLayoutMedium="@layout/lockscreen_message_2x1"
    app:targetHost="lock_and_aod|cover"
    app:widgetSize="small|medium"
    app:widgetStyle="monotone" />

4. Add Samsung Monotone Metadata Files

Samsung also reads a companion samsung-appwidget-info XML file.

<!-- res/xml/lockscreen_message_1x1_widget_info_oneui.xml -->
<samsung-appwidget-info
    xmlns:app="http://schemas.android.com/apk/res-auto"
    app:allowMultipleSizes="true"
    app:initialLayoutTiny="@layout/lockscreen_message_1x1"
    app:previewLayoutTiny="@layout/lockscreen_message_1x1"
    app:targetHost="lock_and_aod|cover"
    app:widgetSize="tiny" />

For 2x1, map both small and medium to the wide layout:

<!-- res/xml/lockscreen_message_2x1_widget_info_oneui.xml -->
<samsung-appwidget-info
    xmlns:app="http://schemas.android.com/apk/res-auto"
    app:allowMultipleSizes="true"
    app:initialLayoutMedium="@layout/lockscreen_message_2x1"
    app:initialLayoutSmall="@layout/lockscreen_message_2x1"
    app:previewLayoutMedium="@layout/lockscreen_message_2x1"
    app:previewLayoutSmall="@layout/lockscreen_message_2x1"
    app:targetHost="lock_and_aod|cover"
    app:widgetSize="small|medium" />

5. Register The Receivers

Register one AppWidgetProvider receiver per lock-screen size and attach both metadata resources.

<receiver
    android:name=".LockScreenMessageSmallWidget"
    android:exported="true"
    android:label="@string/lockscreen_message_1x1_label">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data
        android:name="android.appwidget.provider"
        android:resource="@xml/lockscreen_message_1x1_widget_info" />
    <meta-data
        android:name="samsung.appwidget.monotone.info"
        android:resource="@xml/lockscreen_message_1x1_widget_info_oneui" />
</receiver>

Repeat that for the 2x1 provider.

6. Serve RemoteViews From Kotlin

The provider can be small. Build a RemoteViews, fill the text, and call updateAppWidget() for each widget ID.

class LockScreenMessageSmallWidget : AppWidgetProvider() {
    override fun onUpdate(context: Context, manager: AppWidgetManager, ids: IntArray) {
        ids.forEach { id ->
            val views = RemoteViews(context.packageName, R.layout.lockscreen_message_1x1)
            views.setTextViewText(
                R.id.lockscreen_message,
                listOf("Glass", "Calm", "Glow").random()
            )
            manager.updateAppWidget(id, views)
        }
    }
}

For a shared implementation, pass the layout ID into a helper object and reuse the same message-binding code for 1x1 and 2x1.

7. Optional: Support Samsung ServiceBox Requests

Some Samsung lock-screen surfaces request RemoteViews through:

com.samsung.android.intent.action.REQUEST_SERVICEBOX_REMOTEVIEWS

Add a BroadcastReceiver for that action:

<receiver
    android:name=".LockScreenMessageServiceBoxReceiver"
    android:exported="true">
    <intent-filter>
        <action android:name="com.samsung.android.intent.action.REQUEST_SERVICEBOX_REMOTEVIEWS" />
    </intent-filter>
</receiver>

Respond to:

com.samsung.android.intent.action.RESPONSE_SERVICEBOX_REMOTEVIEWS

Include these extras:

Extra	Value
package	Your package name
pageId	The requested page ID
show	true
origin	Normal lock-screen RemoteViews
aod	AOD RemoteViews

The demo's LockScreenMessageServiceBoxReceiver reuses the same 1x1 and 2x1 message layouts for both origin and aod.

Checklist

• Separate receiver/provider XML for every lock-screen size.
• Provider XML sets android:widgetCategory="0x2000".
• Provider XML sets app:widgetStyle="monotone".
• Provider XML sets app:targetHost="lock_and_aod|cover".
• 1x1 maps to widgetSize="tiny" and tiny initial/preview layouts.
• 2x1 maps to widgetSize="small|medium" and small/medium layouts.
• Manifest includes samsung.appwidget.monotone.info.
• Optional ServiceBox receiver returns origin and aod RemoteViews.

Related

• One UI Blur Integration