Copying text to the clipboard

Why copying a text to the clipboard is not a single call in Compose Multiplatform, what the library gives for it, what a copy button should say and when, and how this is tested. The problem is not Pantrix's own: it is seen the same way in every Compose Multiplatform project that has a "copy" button in its common code.

Everything said here about Compose was read in the sources of Compose Multiplatform 1.12.1 or seen in a test that runs in this repository; which was seen where is written in sections 7 and 8. What could not be verified is counted apart in section 8.

1. The problem

Symptom

• In common code it used to be one line: LocalClipboardManager.current.setText(AnnotatedString(text)). This interface was deprecated; the compiler says "Use LocalClipboard instead which supports suspend functions".

• LocalClipboard, which came in its place, has no call for "copy this text". The one write call is setClipEntry(clipEntry: ClipEntry?), and a ClipEntry cannot be built in common code.

• The call suspends (suspend): it cannot be called straight from a button's onClick; it needs a coroutine.

• How a copy ends changes from platform to platform. The browser can refuse the write; on a page not in a secure context nothing is copied, and no one says so; on Android 13 and above the system shows what was copied itself. A button that says "copied" the moment it is pressed says something wrong in all three.

Cause

ClipEntry is only a name in common code: expect class ClipEntry { val clipMetadata: ClipMetadata } (ClipboardManager.kt). Its constructor and everything in it are in the platform's own declaration (Compose Multiplatform 1.12.1; on Android, androidx.compose.ui 1.12.1):

Source files: AndroidClipboardManager.android.kt, PlatformClipboard.desktop.kt, PlatformClipboard.ios.kt, PlatformClipboard.js.kt, PlatformClipboard.wasm.kt.

Three details make the work bigger:

1. The two web targets are two separate declarations. ClipEntry is declared separately for js and for wasmJs; the source set the two share (webMain) sees only the empty declaration in common code. The counterpart of an expect function is therefore written five times: Android, iOS, desktop, JS, Wasm.

2. Experimental marks. The desktop's constructor and iOS's withPlainText carry @ExperimentalComposeUiApi; every place that uses them needs @OptIn.

3. Writing suspends, because it does in the browser. The browser's clipboard returns a Promise; Compose waits for it, and if it is rejected the error is thrown from that call. The old interface started the write in the browser and did not wait for its result (JsPlatformClipboardManager.setText); its read, too, always returned empty there (getText(): AnnotatedString? = null). It was an interface that could not tell the result.

How the platforms finish the write

In the two places where it says "silently skipped", setClipEntry returns without throwing: the code that wraps it thinks the text was copied.

2. The solution: three pieces

Without the third piece the first two go wrong in two places. On a page with no clipboard no error is thrown, and the answer is "copied"; on Android 13 the answer is right, but the app says once more what the system has just shown.

3. With Pantrix

The library gives all three pieces (com.pantrixui.foundation.platform):

3.1. The copy button

// commonMain
@Composable
fun CopyLinkButton(link: String) {
    val clipboard = rememberPantrixClipboard()
    val snackbars = LocalPantrixSnackbars.current
    val scope = rememberCoroutineScope()
    PantrixButton(
        text = "Copy the link",
        onClick = {
            scope.launch {
                // Suspends: in the browser it returns when the write is done.
                // The answer says what happened, not that it was pressed.
                val copied = clipboard.copyText(link, label = "Link")
                val message = when {
                    !copied -> "The link could not be copied"
                    // Android 13 and above: the system shows what was copied itself.
                    clipboard.traits.announcedBySystem -> null
                    else -> "Link copied"
                }
                message?.let { snackbars?.show(message = it) }
            }
        }
    )
}

Not one line looks at the platform: the same button compiles on all five targets. rememberCoroutineScope() is the button's own scope; if the screen is left, a copy left halfway is cancelled too, and no answer comes.

3.2. What the button says, and when it keeps quiet

• On every platform a failed copy is said. The system does not show it; on Android 13 too, the app says it.

• writable is known before the press. Drawing the button disabled from the start, or not drawing it at all, is a choice too: enabled = clipboard.traits.writable. The sample app in this repository draws the button, and says "could not be copied" when it is pressed.

• The rule is the app's. The library says what happened; the app decides what to say. In the sample app this decision is one function, and is tested apart (copyMessage, CopyMessageTest).

3.3. The label

label says what was put on the clipboard: "Link", "Code". Only Android carries it; the documentation of ClipData.newPlainText calls it "User-visible label for the clip data", so it is given in the app's language. On the other platforms it is ignored. If it is not given, it is empty.

4. Without Pantrix

The same solution, with Compose Multiplatform's own API only. The code below can be copied into any project; it is a simplified form of its counterparts in the library.

4.1. Common code (commonMain)

/** [text], in the type this platform's clipboard takes. Only Android carries the label. */
expect fun plainTextClipEntry(label: String, text: String): ClipEntry

/** The clipboard's two traits on this platform. */
data class ClipboardTraits(
    val writable: Boolean = true,
    val announcedBySystem: Boolean = false
)

/** This platform's clipboard traits, as they are at the moment asked. */
expect fun currentClipboardTraits(): ClipboardTraits

/** The traits the buttons look at. A test gives another platform's traits from here. */
val LocalClipboardTraits = staticCompositionLocalOf { currentClipboardTraits() }

/** Puts [text] on the clipboard and says whether it was put. */
suspend fun Clipboard.copyText(
    text: String,
    label: String = "",
    traits: ClipboardTraits = currentClipboardTraits()
): Boolean = traits.writable &&
    try {
        setClipEntry(plainTextClipEntry(label, text))
        true
    } catch (cancelled: CancellationException) {
        // Cancellation is not an answer: if it is swallowed, the cancelled coroutine goes on its way.
        throw cancelled
    } catch (_: Throwable) {
        // The browser's refusal is not a Kotlin `Exception`.
        false
    }

CancellationException here is kotlin.coroutines.cancellation.CancellationException.

4.2. Platform counterparts

// androidMain
actual fun plainTextClipEntry(label: String, text: String): ClipEntry =
    ClipEntry(ClipData.newPlainText(label, text))

// From Android 13 (API 33) on, the system shows what was put on the clipboard with its own preview.
actual fun currentClipboardTraits(): ClipboardTraits =
    ClipboardTraits(announcedBySystem = Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU)

// jvmMain
@OptIn(ExperimentalComposeUiApi::class)
actual fun plainTextClipEntry(label: String, text: String): ClipEntry = ClipEntry(StringSelection(text))

// A JVM with no screen (headless) has no system clipboard; Compose skips writing there without throwing.
actual fun currentClipboardTraits(): ClipboardTraits =
    ClipboardTraits(writable = !GraphicsEnvironment.isHeadless())

// iosMain
@OptIn(ExperimentalComposeUiApi::class)
actual fun plainTextClipEntry(label: String, text: String): ClipEntry = ClipEntry.withPlainText(text)

actual fun currentClipboardTraits(): ClipboardTraits = ClipboardTraits()

// jsMain and wasmJsMain: the same line, in two separate files
actual fun plainTextClipEntry(label: String, text: String): ClipEntry = ClipEntry.withPlainText(text)

// webMain
actual fun currentClipboardTraits(): ClipboardTraits = ClipboardTraits(writable = browserClipboardWrites())

// The browser gives the clipboard only in a secure context: https, or the machine itself.
@OptIn(ExperimentalWasmJsInterop::class)
private fun browserClipboardWrites(): Boolean =
    js("window.isSecureContext === true && Boolean(window.navigator.clipboard && window.navigator.clipboard.writeText)")

The question asked of the browser is written once, in webMain; ClipEntry.withPlainText cannot be, and stands apart on the two targets (see section 7, "A counterpart written in webMain"). In a project with only one web target, both are written in that target's source set.

4.3. Use

// commonMain
@Composable
fun CopyLinkButton(link: String, snackbars: SnackbarHostState) {
    val clipboard = LocalClipboard.current
    val traits = LocalClipboardTraits.current
    val scope = rememberCoroutineScope()
    Button(
        onClick = {
            scope.launch {
                val copied = clipboard.copyText(link, label = "Link", traits = traits)
                val message = when {
                    !copied -> "The link could not be copied"
                    // Android 13 and above: the system shows what was copied itself.
                    traits.announcedBySystem -> null
                    else -> "Link copied"
                }
                message?.let { snackbars.showSnackbar(it) }
            }
        }
    ) {
        Text("Copy the link")
    }
}

5. What the helper does not do

The helper does one job: it puts a plain text on the clipboard and says whether it was put. It does not do these:

• It does not read from the clipboard. It has no call for pasting.

• It puts nothing but plain text. It carries no styled text, HTML, address (URI), image or file.

• It does not empty the clipboard. In Compose that is setClipEntry(null).

• It does not mark the content as sensitive. On Android, the mark that asks for content such as a password to be hidden while it is shown is ClipDescription.EXTRA_IS_SENSITIVE (the Android SDK's source); ClipData.newPlainText does not put it.

• It does not tell. The app shows the snackbar; the helper only says what happened.

If a project is to write the first two itself, the way again parts from platform to platform. What Compose's sources show is below; the reading column is taken from Compose Foundation's own reader, which its text fields use when pasting (ClipboardUtils.*.kt, readText()). That reader is internal; an app cannot call it.

6. Testing

6.1. A fake clipboard

Compose gives a test the real clipboard (see section 7, "A clipboard given no fake"). Every test that copies gives its own clipboard with LocalClipboard:

/** A clipboard that keeps everything put on it and does not touch the machine's clipboard. */
class RecordingClipboard(private val refuses: Boolean = false) : Clipboard {
    val entries = mutableListOf<ClipEntry?>()

    override suspend fun getClipEntry(): ClipEntry? = entries.lastOrNull()

    override suspend fun setClipEntry(clipEntry: ClipEntry?) {
        check(!refuses) { "NotAllowedError: Write permission denied." }
        entries += clipEntry
    }
}

Clipboard is in common code: this fake can be written in a common test too. What can be looked at there is how many times it was written to and what copyText says; the text inside the ClipEntry that comes cannot be read in common code.

6.2. Another platform's traits

The behaviour of Android 13, or of a page with no clipboard, is tested in a test that does not run on that platform too: the traits are given with LocalClipboardTraits.

// jvmTest
@OptIn(ExperimentalTestApi::class, ExperimentalComposeUiApi::class)
class CopyLinkButtonTest {
    @Test
    fun a_copy_the_system_shows_itself_is_not_told_twice() = runComposeUiTest {
        val clipboard = RecordingClipboard()
        val snackbars = PantrixSnackbarState()
        setContent {
            PantrixTheme {
                CompositionLocalProvider(
                    LocalClipboard provides clipboard,
                    // Android 13's traits, in a test that runs on the desktop.
                    LocalClipboardTraits provides ClipboardTraits(announcedBySystem = true),
                    LocalPantrixSnackbars provides snackbars
                ) {
                    CopyLinkButton(link = "https://example.com")
                }
            }
        }
        onNodeWithText("Copy the link").performClick()
        waitForIdle()
        // The text is read as the desktop reads it: with the `Transferable`'s text flavour.
        val copied = clipboard.entries.single()?.asAwtTransferable?.getTransferData(DataFlavor.stringFlavor)
        assertEquals("https://example.com", copied)
        assertEquals(null, snackbars.current)
    }
}

With ClipboardTraits(writable = false) the same test tries the page with no clipboard: nothing comes to the fake clipboard, and the button says "could not be copied". RecordingClipboard(refuses = true) is a browser that refuses.

6.3. Reading the text that came

Each platform's test looks at the text itself its own way:

On the web the way is different. webTest, like webMain, is the source set the two targets share, and the inside of ClipEntry cannot be written there in one form: its items are an Array on one target and a JsArray on the other. What the test stands in for is not Compose's clipboard but the browser's: so what Compose really gives the browser is seen, and a refused write goes its real way too (Promise.reject(new DOMException(…, 'NotAllowedError'))). Both functions are stood in for; Compose decides which to call by looking at the browser.

7. Pitfalls

8. Verification

Tests

For 32 on Android no separate runtime was downloaded: Robolectric keeps the version number in a writable field, and the test writes 32 into that field on 33's runtime and puts it back. 30, 33 and 34 run on their own runtimes.

Behaviours broken by hand

Each behaviour was broken once by hand, and which test turned red was looked at; then it was put back.

• Common code: the write never made; false said after writing; writable not looked at; true said to a clipboard that throws; only Exception caught; the cancellation swallowed; remember removed; the clipboard or the traits taken out of its keys; the traits not read from LocalClipboardTraits; the label and the text swapped. In all eleven a test turned red.

• The platforms: on each platform, the label put in place of the text; on Android, the bound moved to 34, to 32 and to 30; on the desktop and iOS, the traits changed; in the browser, the question always saying "there is" and always "there is none". In all of them a test of that platform turned red.

• Seen in one place only: when the default of LocalClipboardTraits is empty traits instead of the platform's, no test turns red on the JVM, because the two are the same there. On Android on_android_14_a_remembered_clipboard_knows_the_system_shows_a_copy_itself turns red.

Not verified

• Android 13's preview. That the system shows what was copied itself, and asks the app not to say it a second time, is from Android's documentation. That it was seen in this repository on an Android 14 emulator is written in docs/OPEN_ITEMS.md; it was not looked at again while this guide was written. Robolectric does not draw the preview: the tests look only at what the trait says on which version.

• A real http page. The insecure context was not tried on a page served over plain http. In the test, navigator.clipboard was hidden from the page; that Compose skips the write in that case was read in the source, not seen in a test.

• The browser's real refusal. Under which conditions a browser refuses the write was not looked at. The refusal in the test is one the test put there itself; no test wrote to a real clipboard.

• A browser without the full clipboard interface. The way where Compose falls back to writeText (by the note in the source, Firefox older than 127) did not run in any browser. The tests ran only in ChromeHeadless 154.

• The real clipboards. On the desktop, iOS and the browser no test wrote to the system's clipboard. That what was copied can be pasted into another app was not looked at for this guide.

• A very large text on Android. That a text too large for the system to carry is refused was not tried. What is seen in the source is that the service's error is thrown as a RuntimeException.

• A clipboard not available on the desktop. IllegalStateException is written in the JDK's documentation; it was not seen.

• A headless JVM itself. AWT decides once for a JVM whether it has a screen, and it cannot be changed later. The test tries the rule (desktopClipboardTraits) and looks at whether the answer of the JVM it runs on comes from that rule; it did not run on a headless JVM.

• The iOS simulator's clipboard. The simulator can share its clipboard with the machine it runs on; the iOS tests therefore run with the fake clipboard. The sharing itself was not tried.

• The quiet systems. That the system does not show a copy itself on the desktop, iOS, the browser and Android 12L and below is the library's assumption (announcedBySystem = false); it was not looked at on real devices.

• A screen reader. How a copy is announced aloud was not looked at.

9. Where it is in this repository

10. What is left open

• The helper does not read from the clipboard and carries nothing but plain text (see section 5).

• On the desktop and iOS, the Compose API it rests on is experimental (@ExperimentalComposeUiApi); it can change in a later version of Compose Multiplatform.

• It was seen only in tests: it was not looked at on real devices, in real browsers or on a page served over plain http.