1 /*
2  * Copyright 2020 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.ui.input.key
18 
19 /** The native platform-specific keyboard key event. */
20 expect class NativeKeyEvent
21 
22 /**
23  * When a user presses a key on a hardware keyboard, a [KeyEvent] is sent to the item that is
24  * currently focused. Any parent composable can intercept this [key event][KeyEvent] on its way to
25  * the focused item by using [Modifier.onPreviewKeyEvent()]][onPreviewKeyEvent]. If the item is not
26  * consumed, it returns back to each parent and can be intercepted by using
27  * [Modifier.onKeyEvent()]][onKeyEvent].
28  *
29  * @sample androidx.compose.ui.samples.KeyEventSample
30  */
31 @kotlin.jvm.JvmInline value class KeyEvent(val nativeKeyEvent: NativeKeyEvent)
32 
33 /**
34  * The key that was pressed.
35  *
36  * @sample androidx.compose.ui.samples.KeyEventIsAltPressedSample
37  */
38 expect val KeyEvent.key: Key
39 
40 /**
41  * The UTF16 value corresponding to the key event that was pressed. The unicode character takes into
42  * account any meta keys that are pressed (eg. Pressing shift results in capital alphabets). The
43  * UTF16 value uses the [U+n notation][http://www.unicode.org/reports/tr27/#notation] of the Unicode
44  * Standard.
45  *
46  * An [Int] is used instead of a [Char] so that we can support supplementary characters. The Unicode
47  * Standard allows for characters whose representation requires more than 16 bits. The range of
48  * legal code points is U+0000 to U+10FFFF, known as Unicode scalar value.
49  *
50  * The set of characters from U+0000 to U+FFFF is sometimes referred to as the Basic Multilingual
51  * Plane (BMP). Characters whose code points are greater than U+FFFF are called supplementary
52  * characters. In this representation, supplementary characters are represented as a pair of char
53  * values, the first from the high-surrogates range, (\uD800-\uDBFF), the second from the
54  * low-surrogates range (\uDC00-\uDFFF).
55  */
56 expect val KeyEvent.utf16CodePoint: Int
57 
58 /**
59  * The [type][KeyEventType] of key event.
60  *
61  * @sample androidx.compose.ui.samples.KeyEventTypeSample
62  */
63 expect val KeyEvent.type: KeyEventType
64 
65 /**
66  * Indicates whether the Alt key is pressed.
67  *
68  * @sample androidx.compose.ui.samples.KeyEventIsAltPressedSample
69  */
70 expect val KeyEvent.isAltPressed: Boolean
71 
72 /**
73  * Indicates whether the Ctrl key is pressed.
74  *
75  * @sample androidx.compose.ui.samples.KeyEventIsCtrlPressedSample
76  */
77 expect val KeyEvent.isCtrlPressed: Boolean
78 
79 /**
80  * Indicates whether the Meta key is pressed.
81  *
82  * @sample androidx.compose.ui.samples.KeyEventIsMetaPressedSample
83  */
84 expect val KeyEvent.isMetaPressed: Boolean
85 
86 /**
87  * Indicates whether the Shift key is pressed.
88  *
89  * @sample androidx.compose.ui.samples.KeyEventIsShiftPressedSample
90  */
91 expect val KeyEvent.isShiftPressed: Boolean
92 
93 /**
94  * The type of Key Event.
95  *
96  * @sample androidx.compose.ui.samples.KeyEventTypeSample
97  */
98 @kotlin.jvm.JvmInline
99 value class KeyEventType internal constructor(@Suppress("unused") private val value: Int) {
100 
toStringnull101     override fun toString(): String {
102         return when (this) {
103             KeyUp -> "KeyUp"
104             KeyDown -> "KeyDown"
105             Unknown -> "Unknown"
106             else -> "Invalid"
107         }
108     }
109 
110     companion object {
111         /**
112          * Unknown key event.
113          *
114          * @sample androidx.compose.ui.samples.KeyEventTypeSample
115          */
116         val Unknown: KeyEventType = KeyEventType(0)
117 
118         /**
119          * Type of KeyEvent sent when the user lifts their finger off a key on the keyboard.
120          *
121          * @sample androidx.compose.ui.samples.KeyEventTypeSample
122          */
123         val KeyUp: KeyEventType = KeyEventType(1)
124 
125         /**
126          * Type of KeyEvent sent when the user presses down their finger on a key on the keyboard.
127          *
128          * @sample androidx.compose.ui.samples.KeyEventTypeSample
129          */
130         val KeyDown: KeyEventType = KeyEventType(2)
131     }
132 }
133