1 /* 2 * Copyright (C) 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 * @addtogroup NativeActivity Native Activity 18 * @{ 19 */ 20 /** 21 * @file surface_control_input_receiver.h 22 */ 23 24 #pragma once 25 26 #include <stdint.h> 27 #include <android/input.h> 28 #include <android/surface_control.h> 29 #include <android/input_transfer_token_jni.h> 30 31 __BEGIN_DECLS 32 33 /** 34 * The AInputReceiver_onMotionEvent callback is invoked when the registered input channel receives 35 * a motion event. 36 * 37 * \param context Optional context provided by the client that is passed when creating the 38 * AInputReceiverCallbacks. 39 * 40 * \param motionEvent The motion event. This must be released with AInputEvent_release. 41 * 42 * Available since API level 35. 43 */ 44 typedef bool (*AInputReceiver_onMotionEvent)(void *_Null_unspecified context, 45 AInputEvent *_Nonnull motionEvent) 46 __INTRODUCED_IN(__ANDROID_API_V__); 47 /** 48 * The AInputReceiver_onKeyEvent callback is invoked when the registered input channel receives 49 * a key event. 50 * 51 * \param context Optional context provided by the client that is passed when creating the 52 * AInputReceiverCallbacks. 53 * 54 * \param keyEvent The key event. This must be released with AInputEvent_release. 55 * 56 * Available since API level 35. 57 */ 58 typedef bool (*AInputReceiver_onKeyEvent)(void *_Null_unspecified context, 59 AInputEvent *_Nonnull keyEvent) 60 __INTRODUCED_IN(__ANDROID_API_V__); 61 62 typedef struct AInputReceiverCallbacks AInputReceiverCallbacks; 63 64 /** 65 * The InputReceiver that holds the reference to the registered input channel. This must be released 66 * using AInputReceiver_release 67 */ 68 typedef struct AInputReceiver AInputReceiver; 69 70 /** 71 * Registers an input receiver for an ASurfaceControl that will receive batched input event. For 72 * those events that are batched, the invocation will happen once per AChoreographer frame, and 73 * other input events will be delivered immediately. 74 * 75 * This is different from AInputReceiver_createUnbatchedInputReceiver in that the input events are 76 * received batched. The caller must invoke AInputReceiver_release to clean up the resources when 77 * no longer needing to use the input receiver. 78 * 79 * \param aChoreographer The AChoreographer used for batching. This should match the 80 * rendering AChoreographer. 81 * \param hostInputTransferToken The host token to link the embedded. This is used to handle 82 * transferring touch gesture from host to embedded and for ANRs 83 * to ensure the host receives the ANR if any issues with 84 * touch on the embedded. This can be retrieved for the host window 85 * by calling AttachedSurfaceControl#getInputTransferToken() 86 * \param aSurfaceControl The ASurfaceControl to register the InputChannel for 87 * \param aInputReceiverCallbacks The SurfaceControlInputReceiver that will receive the input events 88 * 89 * Returns the reference to AInputReceiver to clean up resources when done. 90 * 91 * Available since API level 35. 92 */ 93 AInputReceiver* _Nonnull 94 AInputReceiver_createBatchedInputReceiver(AChoreographer* _Nonnull aChoreographer, 95 const AInputTransferToken* _Nonnull hostInputTransferToken, 96 const ASurfaceControl* _Nonnull aSurfaceControl, 97 AInputReceiverCallbacks* _Nonnull aInputReceiverCallbacks) 98 __INTRODUCED_IN(__ANDROID_API_V__); 99 100 /** 101 * Registers an input receiver for an ASurfaceControl that will receive every input event. 102 * This is different from AInputReceiver_createBatchedInputReceiver in that the input events are 103 * received unbatched. The caller must invoke AInputReceiver_release to clean up the resources when 104 * no longer needing to use the input receiver. 105 * 106 * \param aLooper The looper to use when invoking callbacks. 107 * \param hostInputTransferToken The host token to link the embedded. This is used to handle 108 * transferring touch gesture from host to embedded and for ANRs 109 * to ensure the host receives the ANR if any issues with 110 * touch on the embedded. This can be retrieved for the host window 111 * by calling AttachedSurfaceControl#getInputTransferToken() 112 * \param aSurfaceControl The ASurfaceControl to register the InputChannel for 113 * \param aInputReceiverCallbacks The SurfaceControlInputReceiver that will receive the input events 114 * 115 * Returns the reference to AInputReceiver to clean up resources when done. 116 * 117 * Available since API level 35. 118 */ 119 AInputReceiver* _Nonnull 120 AInputReceiver_createUnbatchedInputReceiver(ALooper* _Nonnull aLooper, 121 const AInputTransferToken* _Nonnull hostInputTransferToken, 122 const ASurfaceControl* _Nonnull aSurfaceControl, 123 AInputReceiverCallbacks* _Nonnull aInputReceiverCallbacks) 124 __INTRODUCED_IN(__ANDROID_API_V__); 125 126 /** 127 * Returns the AInputTransferToken that can be used to transfer touch gesture to or from other 128 * windows. This InputTransferToken is associated with the SurfaceControl that registered an input 129 * receiver and can be used with the host token for things like transfer touch gesture via 130 * WindowManager#transferTouchGesture(). 131 * 132 * This must be released with AInputTransferToken_release. 133 * 134 * \param aInputReceiver The inputReceiver object to retrieve the AInputTransferToken for. 135 * 136 * Available since API level 35. 137 */ 138 const AInputTransferToken *_Nonnull 139 AInputReceiver_getInputTransferToken(AInputReceiver *_Nonnull aInputReceiver) 140 __INTRODUCED_IN(__ANDROID_API_V__); 141 142 /** 143 * Unregisters the input channel and deletes the AInputReceiver. This must be called on the same 144 * looper thread it was created with. 145 * 146 * \param aInputReceiver The inputReceiver object to release. 147 * 148 * Available since API level 35. 149 */ 150 void 151 AInputReceiver_release(AInputReceiver *_Nullable aInputReceiver) __INTRODUCED_IN(__ANDROID_API_V__); 152 153 /** 154 * Creates a AInputReceiverCallbacks object that is used when registering for an AInputReceiver. 155 * This must be released using AInputReceiverCallbacks_release 156 * 157 * \param context Optional context provided by the client that will be passed into the callbacks. 158 * 159 * Available since API level 35. 160 */ 161 AInputReceiverCallbacks* _Nonnull AInputReceiverCallbacks_create(void* _Nullable context) 162 __INTRODUCED_IN(__ANDROID_API_V__); 163 164 /** 165 * Releases the AInputReceiverCallbacks. This must be called on the same 166 * looper thread the AInputReceiver was created with. The receiver will not invoke any callbacks 167 * once it's been released. 168 * 169 * Available since API level 35 170 */ 171 void AInputReceiverCallbacks_release(AInputReceiverCallbacks* _Nullable callbacks) 172 __INTRODUCED_IN(__ANDROID_API_V__); 173 174 /** 175 * Sets a AInputReceiver_onMotionEvent callback for an AInputReceiverCallbacks 176 * 177 * \param callbacks The callback object to set the motion event on. 178 * \param onMotionEvent The motion event that will be invoked 179 * 180 * Available since API level 35. 181 */ 182 void AInputReceiverCallbacks_setMotionEventCallback(AInputReceiverCallbacks* _Nonnull callbacks, 183 AInputReceiver_onMotionEvent _Nonnull onMotionEvent) 184 __INTRODUCED_IN(__ANDROID_API_V__); 185 186 /** 187 * Sets a AInputReceiver_onKeyEvent callback for an AInputReceiverCallbacks 188 * 189 * \param callbacks The callback object to set the motion event on. 190 * \param onMotionEvent The key event that will be invoked 191 * 192 * Available since API level 35. 193 */ 194 void AInputReceiverCallbacks_setKeyEventCallback(AInputReceiverCallbacks* _Nonnull callbacks, 195 AInputReceiver_onKeyEvent _Nonnull onKeyEvent) 196 __INTRODUCED_IN(__ANDROID_API_V__); 197 198 __END_DECLS 199