Project Documentation

ClyoWallpaper

Build #27 Successful
Downloads Code Repository

Architecture & Design - ClyoWallpaper

This document details the background tasks, wallpaper manipulation math, and widget components of ClyoWallpaper.

1. Core Background Lifecycle Components

ClyoWallpaper combines services, receivers, and workers to ensure reliable auto-cycling:

graph TD
    UI[Compose Settings Screen] -->|Start Service| Service[WallpaperCycleService]
    Receiver[WallpaperCycleReceiver] -->|Boot Completed| Service
    Widget[App Widget Provider] -->|Force Refresh| Service
    Service -->|Schedule Timeout| Handler[Handler / Looper]
    Handler -->|Run Rotation| Task[Background Task Thread]
    Task -->|Download & Apply| WP[WallpaperManager]
  • WallpaperCycleService: A persistent foreground service. It runs on start actions (ACTION_START), stops on (ACTION_STOP), and processes manual overrides via (ACTION_FORCE_CYCLE).
  • WakeLock Management: Acquires a PowerManager.PARTIAL_WAKE_LOCK for 60 seconds during wallpaper updates. This prevents the device from falling into deep sleep while downloading and applying new bitmaps over the network.
  • WallpaperCycleReceiver: Listens for system boot events to reschedule cycles if the user enabled auto-cycling.
  • WallpaperCycleWorker: Leverages WorkManager for lightweight scheduled jobs if needed.

2. Crop & Pan Math

In [WallpaperCycleService.kt](file:///home/weexnes/ClyoWallpaper/ClyoWallpaper/app/src/main/java/dev/weexnes/clyowallpaper/WallpaperCycleService.kt), the crop calculations map Compose user edits directly onto full-resolution bitmaps.

Math Formula

  1. Scale Adjustment: The source bitmap dimensions are scaled by the factor saved in the Editor: $$\text{ScaleFactor} = \text{BaseScale} \times \text{UserScale}$$
  2. Pan Coordinates: Pan offset coordinates (relative values between $-1.0$ and $+1.0$) are normalized against scaled surplus widths and heights: $$\text{translateX} = \text{panX} \times \frac{(\text{ScaledWidth} - \text{ScreenWidth})}{2}$$ $$\text{translateY} = \text{panY} \times \frac{(\text{ScaledHeight} - \text{ScreenHeight})}{2}$$
  3. Application: A cropped/transformed bitmap slice is generated and applied to the home or lock screen via: WallpaperManager.getInstance(context).setBitmap(finalBitmap, null, true, destinationFlag)

3. Interactive App Widget

Managed by WallpaperAppWidgetProvider:

  • Actions: Listens for click events on the Refresh button. When clicked, it broadcasts ACTION_FORCE_CYCLE to WallpaperCycleService.
  • Rendering: Updates a RemoteViews layout showing:
    1. The name of the currently active wallpaper.
    2. The next scheduled wallpaper.
    3. Remaining time until the next automatic cycle.