Customizing the screens on Android

The call screen (cloud.wordplus:realtime-ui) is the Better Messages native one. Your app can change it as far as it needs to, in three steps, each going further than the last, with your AI coding agent or by hand. Or draw a screen of its own on the calls alone.

1. The look

CallScreen.configure(CallScreen.Appearance(
    strings = mapOf("end_call" to "Hang up", "calling" to "Ringing…"),
    tokens = mapOf("--bm-color-accent" to "37, 99, 235"),       // red, green, blue, or a hex value
    tokensDark = mapOf("--bm-color-accent" to "96, 165, 250"),
))

Token	What it colours
`--bm-color-accent`, `--bm-color-text-on-accent`	a control that is on, and what is drawn on it
`--bm-color-success`, `--bm-color-recording`, `--bm-color-warning`, `--bm-color-online`	answering, hanging up and a microphone off, a warning, the online dot
`--bm-call-canvas`	the stage, near-black unless you set it: a camera picture is seen against it
`--bm-call-tile`	the tiles of a group call
`--bm-call-btn`	each control in the dock
`--bm-call-dock`	the glass behind the dock

The same names as the web call screen, so one palette serves both.

2. A piece of your own

Replace one piece and keep the rest of the screen:

CallScreen.pieces = CallScreen.Pieces(
    // The buttons of the dock: ours by id, in their order, and your own. Hanging up stays last.
    controls = { context, ours, moment ->
        ours.filter { it.id != "pip" } +
            CallScreen.CallControl.own(context, "order", "Show the order", CallScreen.CallControl.icons.getValue("alert")) { showOrder() }
    },
    // The line under the name, null keeps ours.
    status = { moment -> if (moment.phase == "ringing_out") "Ringing Ann…" else null },
    // Your own view while a call rings in, full screen: answer() shows the call on our screen.
    ringing = { context, ring -> RingView(context, ring.name, ring.answer, ring.decline) },
    // A view over the tile of each person in a group call, such as a badge: the same view again stays.
    tile = { context, person -> if (person.handRaised) HandBadge(context) else null },
    // A view over a call between two, under the dock.
    stage = { _, _ -> null },
)

Piece	What it is
`controls`	the dock buttons: ours are `answer`, `settings`, `flip`, `camera`, `mute`, `speaker`, `pip`, `share`, `hand`, `people` and `end`. `CallControl.own(context, id, label, icon, latched) { … }` adds yours, drawn as ours are (`icon` a path in a 24 grid, as the Lucide icons are)
`status`	the line under the name: `moment.phase` is `ringing_out`, `ringing_in`, `connecting`, `in_progress` or `reconnecting`, `moment.seconds` how long the call has been on
`ringing`	your own view for a call ringing in, over the lock screen as ours is
`tile`	a view over the tile of someone in a group call
`stage`	a view over a call between two

3. The code itself

Copy the screen into your app module and change anything in it. Only the screen is copied: the calls under it stay in cloud.wordplus:realtime-calls, and keep getting their fixes.

// app/build.gradle.kts
plugins {
    id("cloud.wordplus.realtime-ui") version "1.0.0"
}

./gradlew :app:wordplusUiAdd

Where it goes: src/main/kotlin, in the packages of the screen: com/wordplus/messenger/calls/BmCallsStage.kt (the call), BmCallsGrid.kt (the grid of a group call), BmCallsActivity.kt and the rest, cloud/wordplus/realtime/ui/CallScreen.kt, which drives them from the calls, and CallScreenPreviewActivity.kt (checking a change) (--dir for another folder).
Its tests go into src/androidTest/kotlin.
Then, in the module: take cloud.wordplus:realtime-ui out of its dependencies, since your copy is the screen now. Keep cloud.wordplus:realtime-calls, add io.livekit:livekit-android and androidx.core:core-ktx, and declare the screen activities in your manifest, as the task prints them. CallScreen.attach(context, calls) works as before.
Your own screen, from scratch: GroupVideoView draws the camera or shared screen of someone in a group call (show(person.identity, call)), or your own camera (showOwn(call)). CallVideoView does the same in a call between two.

When ours changes

Nothing changes your copy by itself.

./gradlew :app:wordplusUiDiff shows what changed in ours since you copied it, file by file, and whether you changed that file too.
./gradlew :app:wordplusUiUpdate takes ours into every file you never changed.
Merge the rest by hand, then build and try a call.
./gradlew :app:wordplusUiAccept records that yours has ours.

wordplus-ui.json and .wordplus-ui/ in the module record what you copied. Commit both.

Checking a change

Every state, with no call: CallScreen.preview(context) lists the states: calling, ringing in, connecting, in a call by voice and by video, with the microphone and camera off, with the other side lost, reconnecting, and in a group call by video and by voice. Its Dark and RTL buttons switch the look. CallScreen.preview(context, CallScreenPreviewActivity.Shown.VIDEO) opens one state. It draws your pieces and your look, and your copy once you have one.

From a command line (a script, or an AI agent): the preview is not exported, so let debug builds open it from adb. In app/src/debug/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools">
    <application>
        <activity android:name="cloud.wordplus.realtime.ui.CallScreenPreviewActivity" android:exported="true" tools:replace="android:exported" />
    </application>
</manifest>

Then open a state and take a screenshot:

adb shell am start -n <applicationId>/cloud.wordplus.realtime.ui.CallScreenPreviewActivity --es cloud.wordplus.realtime.ui.preview.shown VIDEO
adb exec-out screencap -p > video.png

Opened this way, it draws the pieces the app has set by then. Set them in onCreate of your Application to see them here.

The tests: with a copy, run ./gradlew connectedDebugAndroidTest on a device or an emulator after each change. The tests check each state of the preview, the dock buttons and their labels, and your pieces. The module needs testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" and androidx.test.ext:junit, androidx.test:runner and androidx.test:core as androidTestImplementation.
Then a real call, both ways, and a group call.

What must keep working

Every call state: calling out, ringing in, connecting, in a call, reconnecting, ended, and a group call.
A camera or a microphone refused: the call goes on, and says why.
TalkBack: every button keeps its label.
Picture in picture, the lock screen, and the screen put away and brought back.
Right to left, and a small phone and a tablet.

1. The look​

2. A piece of your own​

3. The code itself​

When ours changes​

Checking a change​

What must keep working​