DEV Community

ReClaim
ReClaim

Posted on AI-assisted

A launcher Home screen over any wallpaper: windowShowWallpaper, a Photo Picker override, and the contrast math we got wrong

We're building ReClaim, a minimalist Android launcher that's on Google Play. Its Home screen is a clock, a few favorites, a short task list, and two corner shortcuts. It has no widgets and no dock. Most of the pixels on the Home screen belong to the user's wallpaper.

That makes the wallpaper a real design problem. A launcher doesn't pick the background. The user does, and it can be anything: a white beach, a black AMOLED gradient, a busy photo of their dog. Every piece of text we draw has to stay readable over all of it. This post covers how ReClaim's Home screen sits on the wallpaper, how a user can override it with their own photo, who wins when the two disagree, and the contrast math that turned out to be wrong when we checked it for this write-up.

Stack: Kotlin, Jetpack Compose, Hilt, DataStore, Coil 2.7, minSdk 26, targetSdk 36. Snippets are trimmed from the real code; // ... marks cuts. The last post covered the app drawer. This one stays on Home.

1. Let the system draw the wallpaper

The first rule: don't draw the wallpaper yourself. The window theme is transparent and asks for the wallpaper behind it:

<style name="Theme.ReClaim" parent="@android:style/Theme.Material.NoActionBar">
    <item name="android:windowBackground">@android:color/transparent</item>
    <item name="android:windowShowWallpaper">true</item>
    <item name="android:windowDrawsSystemBarBackgrounds">true</item>
    <item name="android:statusBarColor">@android:color/transparent</item>
    <item name="android:navigationBarColor">@android:color/transparent</item>
</style>
Enter fullscreen mode Exit fullscreen mode

windowShowWallpaper maps to FLAG_SHOW_WALLPAPER. The reference is precise about what that flag does and doesn't do: "The window surface must be translucent to be able to actually see the wallpaper behind it; this flag just ensures that the wallpaper surface will be there if this window actually has translucent regions." The system composites the real wallpaper, so we never decode or scale it, and a live wallpaper keeps animating behind Home.

The flip side is that every screen in the same window sits on the wallpaper too. With no custom photo set, the Home screen paints nothing behind itself, on purpose. The app drawer and Settings each wrap their content in an opaque Surface(color = MaterialTheme.colorScheme.background), so the wallpaper only shows where we mean it to.

2. A photo override, copied instead of referenced

Users can also pick a photo for ReClaim's Home screen without changing the system wallpaper. Settings uses the Photo Picker through the AndroidX contract:

val pickImage = rememberLauncherForActivityResult(
    contract = ActivityResultContracts.PickVisualMedia(),
) { uri -> uri?.let(viewModel::setHomeBackground) }

// ...
pickImage.launch(PickVisualMediaRequest(ActivityResultContracts.PickVisualMedia.ImageOnly))
Enter fullscreen mode Exit fullscreen mode

The obvious move is to store the returned Uri and load it on Home. That breaks. The photo picker guide says: "By default, the system grants your app access to media files until the device is restarted or until your app stops." A launcher is one of the first things to start after a reboot, so that grant would expire right when we need it. You can call takePersistableUriPermission(), but we didn't want Home to depend on a grant at all. Instead, the store decodes the image once, downscales it, and keeps a private JPEG:

private val file = File(context.filesDir, "home_background.jpg")

suspend fun save(uri: Uri): String? = withContext(Dispatchers.IO) {
    runCatching {
        val bitmap = decodeDownscaled { context.contentResolver.openInputStream(uri) } ?: return@withContext null
        writeJpeg(file, bitmap)
        file.absolutePath
    }.getOrNull()
}

private fun decodeDownscaled(maxDimension: Int = 2160, open: () -> InputStream?): Bitmap? {
    val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
    open()?.use { BitmapFactory.decodeStream(it, null, bounds) }
    if (bounds.outWidth <= 0 || bounds.outHeight <= 0) return null

    var sampleSize = 1
    while (bounds.outWidth / (sampleSize * 2) >= maxDimension || bounds.outHeight / (sampleSize * 2) >= maxDimension) {
        sampleSize *= 2
    }
    val options = BitmapFactory.Options().apply { inSampleSize = sampleSize }
    return open()?.use { BitmapFactory.decodeStream(it, null, options) }
}
Enter fullscreen mode Exit fullscreen mode

Two passes over the stream: one with inJustDecodeBounds to read the size, one real decode. inSampleSize only works in powers of two ("any other value will be rounded down to the nearest power of 2"), so the loop doubles. Our loop differs slightly from the one in Loading large bitmaps efficiently. The guide keeps doubling while both halves stay above the target (&&), so neither side drops below it. Ours keeps doubling while either half is still at least 2160 px (||). So for a large photo, the long side ends up between 2160 and 4319 px and the short side can be smaller. That's fine for a full-screen ContentScale.Crop background, and it caps memory for huge camera files.

Home then draws the file with Coil, plus a scrim:

if (backgroundPath != null) {
    AsyncImage(
        model = File(backgroundPath),
        contentDescription = null,
        contentScale = ContentScale.Crop,
        modifier = Modifier.fillMaxSize(),
    )
    // Subtle scrim so clock/labels stay legible over an arbitrary photo.
    Box(
        modifier = Modifier
            .fillMaxSize()
            .background(
                Brush.verticalGradient(
                    listOf(Color.Black.copy(alpha = 0.15f), Color.Black.copy(alpha = 0.35f)),
                ),
            ),
    )
}
Enter fullscreen mode Exit fullscreen mode

Hold on to that scrim. It comes back in section 5.

3. Who owns the background? The phone's wallpaper picker

An early version had a quiet bug. Once someone picked a photo inside ReClaim, setting a new wallpaper the normal Android way (long-press Home, or Settings > Wallpaper) did nothing on ReClaim's Home screen. The override never cleared. The fix is a small singleton that drops the override on any real wallpaper change:

@Singleton
class WallpaperChangeListener @Inject constructor(
    @ApplicationContext private val context: Context,
    @ApplicationScope private val appScope: CoroutineScope,
    private val settingsRepository: SettingsRepository,
    private val homeBackgroundStore: HomeBackgroundStore,
) {
    private val receiver = object : BroadcastReceiver() {
        override fun onReceive(c: Context?, intent: Intent?) {
            appScope.launch {
                homeBackgroundStore.clear()
                settingsRepository.setHomeBackgroundPath(null)
            }
        }
    }

    /** Call once, from ReClaimApp.onCreate. */
    fun register() {
        context.registerReceiver(receiver, IntentFilter(Intent.ACTION_WALLPAPER_CHANGED))
    }
}
Enter fullscreen mode Exit fullscreen mode

The rule is simple: setting the phone's wallpaper always sets the launcher's background. The Settings screen says so under the photo preview ("Setting a new wallpaper from your phone's own wallpaper picker replaces this automatically"), so nobody has to guess.

Three details we checked against the docs:

  • The broadcast is deprecated, but for a different use. ACTION_WALLPAPER_CHANGED has been deprecated since API 16 with the note that apps "should use WindowManager.LayoutParams.FLAG_SHOW_WALLPAPER to have the wallpaper shown behind their UI, rather than watching for this broadcast and rendering the wallpaper on their own." We already do that (section 1). We only use the broadcast as a signal to drop our own override, which the reference still allows: "This should only be used to determine when the wallpaper has changed to show the new wallpaper to the user."
  • No export flag, on purpose. Android 14 requires RECEIVER_EXPORTED or RECEIVER_NOT_EXPORTED for context-registered receivers, with an exception: if you register "only for system broadcasts," you "shouldn't specify a flag."
  • It only hears changes while the process is alive. A context-registered receiver lives as long as the process. Launcher processes usually stay around, but not always. That gap is an open item, and the fix is already in our codebase. Our backup code compares WallpaperManager.getWallpaperId() against a cached value, and the reference says that ID "allows the caller to determine whether the wallpaper imagery has changed, regardless of how that change happened." Saving the ID when a photo is picked and checking it on start would catch the changes the receiver missed.

4. Text that stays readable: palette colors and a backdrop

The clock and the Home task list draw straight on the background. Users can keep the theme's text color or choose one of eight colors from a small palette (white, black, red, orange, yellow, green, blue, purple). The enum lives in the data layer, and the colors resolve in the UI layer so DataStore code never imports Compose:

fun textColorFor(option: TextColorOption): Color? = when (option) {
    TextColorOption.THEME -> null
    TextColorOption.WHITE -> Color(0xFFFFFFFF)
    TextColorOption.BLACK -> Color(0xFF000000)
    TextColorOption.RED -> Color(0xFFE53935)
    // ... ORANGE, YELLOW, GREEN, BLUE, PURPLE
}
Enter fullscreen mode Exit fullscreen mode

The task list also gets an optional translucent panel behind it, on by default. Its color comes from the text, not the theme, because a user can pin white text on a light theme:

/**
 * A translucent panel color guaranteed to contrast with [textColor], for text drawn straight over
 * the wallpaper. ...
 */
fun backdropFor(textColor: Color): Color =
    if (textColor.luminance() > 0.5f) Color.Black.copy(alpha = 0.45f) else Color.White.copy(alpha = 0.55f)
Enter fullscreen mode Exit fullscreen mode

The panel is drawn with drawBehind and deliberately extends past the layout bounds, so turning it on doesn't move any text. The task titles stay lined up with the clock above them:

Modifier.drawBehind {
    val padX = 14.dp.toPx()
    val padY = 10.dp.toPx()
    drawRoundRect(
        color = backdropColor,
        topLeft = Offset(-padX, -padY),
        size = Size(size.width + padX * 2, size.height + padY * 2),
        cornerRadius = CornerRadius(18.dp.toPx()),
    )
}
Enter fullscreen mode Exit fullscreen mode

The same helper also handles a small detail. A completed task's check mark is tinted backdropFor(tint).copy(alpha = 1f), so it stands out against the filled circle in any palette color.

5. The contrast math we got wrong

The KDoc says "guaranteed to contrast." While writing this post, we tested that claim.

Compose's Color.luminance() returns relative luminance "based on the formula for relative luminance defined in WCAG 2.0." WCAG defines the contrast ratio as (L1 + 0.05) / (L2 + 0.05) and asks for at least 4.5:1 for normal text (3:1 for large text). So we took each palette color, blended its panel over the two extreme wallpapers (pure white and pure black), and computed the worse of the two ratios. The blend mixes channel values directly, which is a simplification, but it shows the trend clearly:

Text color Panel chosen Worst-case contrast
White black 45% 3.36:1
Black white 55% 6.25:1
Yellow black 45% 2.41:1
Purple white 55% 2.09:1
Orange white 55% 1.42:1
Red white 55% 1.26:1
Blue white 55% 1.09:1
Green white 55% 1.02:1

Only black passes. Two things are wrong.

The 0.5 threshold is in the wrong place. Contrast against black equals contrast against white at a luminance of about 0.18 (solve (L + 0.05) / 0.05 = 1.05 / (L + 0.05)), not 0.5. Our green, blue, red and orange all sit between those values. They read better on dark than on light, but they get a light panel. Over a black wallpaper, a 55% white panel turns mid-grey, and mid-tone text on mid-grey nearly disappears.

A translucent panel can't guarantee much for mid-tones. Even with the right panel color, the panel only works at high opacity. With the same simplified math, green needs a black panel at roughly 85% opacity to reach 4.5:1 over a white wallpaper, and blue needs about 89%. At that point it's a solid card, not a hint of a panel.

The scrim from section 2 has the same blind spot in a different form. It's always black (15% to 35%). That helps white text, but with the default light theme our text is black, so the scrim darkens the photo under dark text. And when the user keeps the system wallpaper, Home draws theme-colored text and labels with no scrim at all.

What we plan to change (none of it has shipped yet):

  1. Choose the panel by comparing contrast, not with a fixed 0.5 cutoff. That just means computing both ratios and taking the higher one.
  2. Raise the panel opacity for mid-tone palette colors, or say in the color picker that those colors need the panel.
  3. Use the platform's hint when the system wallpaper is showing. WallpaperColors has HINT_SUPPORTS_DARK_TEXT (API 31+), documented as "A launcher may set its text color to black if this flag is specified." getWallpaperColors() can return null (for example, while colors are still being processed, or for some live wallpapers) and goes over IPC, so it has to run off the main thread with a fallback.
  4. Pick the scrim color from the text color, the same way the panel does.

6. One more: the same path, the same state

One more possible bug turned up while we traced the photo flow. Picking a second photo overwrites the same home_background.jpg and writes the same path string to DataStore. The repository adds a "saved at" timestamp to make that edit visible to the backup code, but the timestamp isn't part of AppSettings. So the new AppSettings equals the old one. StateFlow is explicit about what happens next: values are "conflated using Any.equals comparison," which suppresses "emission of the values to collectors when new value is equal to the previously emitted one." Home never recomposes with a new model, so the old photo can stay on screen until the activity restarts. (Coil 2's default cache key for a File includes lastModified(), so a fresh load would pick up the new file.) We haven't confirmed this on a device yet. The likely fix is to give each saved photo its own file name, so the path itself changes.

Takeaways

  • Let the system composite the wallpaper with windowShowWallpaper, and give every screen except Home its own opaque background.
  • Copy picked photos into app storage. Photo Picker grants are temporary by default, and a launcher starts at boot.
  • Decide who owns the background and say it in the UI. Ours: the phone's wallpaper picker always wins.
  • Don't trust "guaranteed contrast" until you've done the math. Put your palette through the WCAG formula against both a white and a black background. A 0.5 luminance cutoff is a guess, not a rule.
  • If the value doesn't change, the UI won't either. Overwriting a file in place is invisible to StateFlow.

If you'd like to see the Home screen itself, ReClaim is free on Google Play. For the product thinking behind keeping Home this sparse, see designing a minimal Android home screen.

This post was drafted with AI assistance and reviewed by the ReClaim team.

Top comments (0)