1 /*
2 * Copyright 2024 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package androidx.compose.foundation.content
18
19 import androidx.compose.foundation.ExperimentalFoundationApi
20 import androidx.compose.ui.platform.ClipEntry
21 import androidx.compose.ui.platform.ClipMetadata
22 import kotlin.jvm.JvmInline
23
24 /**
25 * Represents content that can be transferred between applications or processes.
26 *
27 * Note; Consult platform-specific guidelines for best practices in content transfer operations.
28 *
29 * @property clipEntry The main content data, typically representing a text, image, file, or other
30 * transferable item.
31 * @property source The source from which the content originated like Keyboard, DragAndDrop, or
32 * Clipboard.
33 * @property clipMetadata Metadata associated with the content, providing additional information or
34 * context.
35 * @property platformTransferableContent Optional platform-specific representation of the content,
36 * or additional platform-specific information, that can be used to access platform level APIs.
37 */
38 @ExperimentalFoundationApi
39 class TransferableContent
40 internal constructor(
41 val clipEntry: ClipEntry,
42 val clipMetadata: ClipMetadata,
43 val source: Source,
44 val platformTransferableContent: PlatformTransferableContent? = null
45 ) {
46
47 /** Defines the type of operation that a [TransferableContent] originates from. */
48 @ExperimentalFoundationApi
49 @JvmInline
50 value class Source internal constructor(private val value: Int) {
51
52 companion object {
53
54 /**
55 * Indicates that the [TransferableContent] originates from the soft keyboard (also
56 * known as input method editor or IME)
57 */
58 val Keyboard = Source(0)
59
60 /**
61 * Indicates that the [TransferableContent] was passed on by the system drag and drop.
62 */
63 val DragAndDrop = Source(1)
64
65 /**
66 * Indicates that the [TransferableContent] comes from the clipboard via paste. (e.g.
67 * "Paste" action in the floating action menu or "Ctrl+V" key combination)
68 */
69 val Clipboard = Source(2)
70 }
71
toStringnull72 override fun toString(): String =
73 when (this) {
74 Keyboard -> "Source.Keyboard"
75 DragAndDrop -> "Source.DragAndDrop"
76 Clipboard -> "Source.Clipboard"
77 else -> "Invalid ($value)"
78 }
79 }
80 }
81
82 /**
83 * All the platform-specific information regarding a [TransferableContent] that cannot be abstracted
84 * away in a platform agnostic way.
85 */
86 @ExperimentalFoundationApi expect class PlatformTransferableContent
87
88 /** Returns whether this [TransferableContent] can provide an item with the [mediaType]. */
89 @ExperimentalFoundationApi
hasMediaTypenull90 expect fun TransferableContent.hasMediaType(mediaType: MediaType): Boolean
91
92 /**
93 * Reads the text part of this [ClipEntry]. The returned result may not include the full text
94 * representation of content e.g., if there is a URL pointing at another source. This function only
95 * reads the explicit text that was transferred directly inside the [ClipEntry].
96 */
97 internal expect fun ClipEntry.readPlainText(): String?
98