/* * Copyright (C) 2024 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ /** * @addtogroup NativeActivity Native Activity * @{ */ /** * @file surface_control_input_receiver.h */ #pragma once #include #include #include #include __BEGIN_DECLS /** * The AInputReceiver_onMotionEvent callback is invoked when the registered input channel receives * a motion event. * * \param context Optional context provided by the client that is passed when creating the * AInputReceiverCallbacks. * * \param motionEvent The motion event. This must be released with AInputEvent_release. * * Available since API level 35. */ typedef bool (*AInputReceiver_onMotionEvent)(void *_Null_unspecified context, AInputEvent *_Nonnull motionEvent) __INTRODUCED_IN(__ANDROID_API_V__); /** * The AInputReceiver_onKeyEvent callback is invoked when the registered input channel receives * a key event. * * \param context Optional context provided by the client that is passed when creating the * AInputReceiverCallbacks. * * \param keyEvent The key event. This must be released with AInputEvent_release. * * Available since API level 35. */ typedef bool (*AInputReceiver_onKeyEvent)(void *_Null_unspecified context, AInputEvent *_Nonnull keyEvent) __INTRODUCED_IN(__ANDROID_API_V__); struct AInputReceiverCallbacks; struct AInputReceiver; /** * The InputReceiver that holds the reference to the registered input channel. This must be released * using AInputReceiver_release * * Available since API level 35. */ typedef struct AInputReceiver AInputReceiver __INTRODUCED_IN(__ANDROID_API_V__); /** * Registers an input receiver for an ASurfaceControl that will receive batched input event. For * those events that are batched, the invocation will happen once per AChoreographer frame, and * other input events will be delivered immediately. * * This is different from AInputReceiver_createUnbatchedInputReceiver in that the input events are * received batched. The caller must invoke AInputReceiver_release to clean up the resources when * no longer needing to use the input receiver. * * \param aChoreographer The AChoreographer used for batching. This should match the * rendering AChoreographer. * \param hostInputTransferToken The host token to link the embedded. This is used to handle * transferring touch gesture from host to embedded and for ANRs * to ensure the host receives the ANR if any issues with * touch on the embedded. This can be retrieved for the host window * by calling AttachedSurfaceControl#getInputTransferToken() * \param aSurfaceControl The ASurfaceControl to register the InputChannel for * \param aInputReceiverCallbacks The SurfaceControlInputReceiver that will receive the input events * * Returns the reference to AInputReceiver to clean up resources when done. * * Available since API level 35. */ AInputReceiver* _Nonnull AInputReceiver_createBatchedInputReceiver(AChoreographer* _Nonnull aChoreographer, const AInputTransferToken* _Nonnull hostInputTransferToken, const ASurfaceControl* _Nonnull aSurfaceControl, AInputReceiverCallbacks* _Nonnull aInputReceiverCallbacks) __INTRODUCED_IN(__ANDROID_API_V__); /** * Registers an input receiver for an ASurfaceControl that will receive every input event. * This is different from AInputReceiver_createBatchedInputReceiver in that the input events are * received unbatched. The caller must invoke AInputReceiver_release to clean up the resources when * no longer needing to use the input receiver. * * \param aLooper The looper to use when invoking callbacks. * \param hostInputTransferToken The host token to link the embedded. This is used to handle * transferring touch gesture from host to embedded and for ANRs * to ensure the host receives the ANR if any issues with * touch on the embedded. This can be retrieved for the host window * by calling AttachedSurfaceControl#getInputTransferToken() * \param aSurfaceControl The ASurfaceControl to register the InputChannel for * \param aInputReceiverCallbacks The SurfaceControlInputReceiver that will receive the input events * * Returns the reference to AInputReceiver to clean up resources when done. * * Available since API level 35. */ AInputReceiver* _Nonnull AInputReceiver_createUnbatchedInputReceiver(ALooper* _Nonnull aLooper, const AInputTransferToken* _Nonnull hostInputTransferToken, const ASurfaceControl* _Nonnull aSurfaceControl, AInputReceiverCallbacks* _Nonnull aInputReceiverCallbacks) __INTRODUCED_IN(__ANDROID_API_V__); /** * Returns the AInputTransferToken that can be used to transfer touch gesture to or from other * windows. This InputTransferToken is associated with the SurfaceControl that registered an input * receiver and can be used with the host token for things like transfer touch gesture via * WindowManager#transferTouchGesture(). * * This must be released with AInputTransferToken_release. * * \param aInputReceiver The inputReceiver object to retrieve the AInputTransferToken for. * * Available since API level 35. */ const AInputTransferToken *_Nonnull AInputReceiver_getInputTransferToken(AInputReceiver *_Nonnull aInputReceiver) __INTRODUCED_IN(__ANDROID_API_V__); /** * Unregisters the input channel and deletes the AInputReceiver. This must be called on the same * looper thread it was created with. * * \param aInputReceiver The inputReceiver object to release. * * Available since API level 35. */ void AInputReceiver_release(AInputReceiver *_Nullable aInputReceiver) __INTRODUCED_IN(__ANDROID_API_V__); /** * Creates a AInputReceiverCallbacks object that is used when registering for an AInputReceiver. * This must be released using AInputReceiverCallbacks_release * * \param context Optional context provided by the client that will be passed into the callbacks. * * Available since API level 35. */ AInputReceiverCallbacks* _Nonnull AInputReceiverCallbacks_create(void* _Nullable context) __INTRODUCED_IN(__ANDROID_API_V__); /** * Releases the AInputReceiverCallbacks. This must be called on the same * looper thread the AInputReceiver was created with. The receiver will not invoke any callbacks * once it's been released. * * Available since API level 35 */ void AInputReceiverCallbacks_release(AInputReceiverCallbacks* _Nullable callbacks) __INTRODUCED_IN(__ANDROID_API_V__); /** * Sets a AInputReceiver_onMotionEvent callback for an AInputReceiverCallbacks * * \param callbacks The callback object to set the motion event on. * \param onMotionEvent The motion event that will be invoked * * Available since API level 35. */ void AInputReceiverCallbacks_setMotionEventCallback(AInputReceiverCallbacks* _Nonnull callbacks, AInputReceiver_onMotionEvent _Nonnull onMotionEvent) __INTRODUCED_IN(__ANDROID_API_V__); /** * Sets a AInputReceiver_onKeyEvent callback for an AInputReceiverCallbacks * * \param callbacks The callback object to set the motion event on. * \param onMotionEvent The key event that will be invoked * * Available since API level 35. */ void AInputReceiverCallbacks_setKeyEventCallback(AInputReceiverCallbacks* _Nonnull callbacks, AInputReceiver_onKeyEvent _Nonnull onKeyEvent) __INTRODUCED_IN(__ANDROID_API_V__); __END_DECLS