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