third_party/android_game_activity/include/game-text-input/gametextinput.h

/*
 * Copyright (C) 2021 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.
 */

/**
 * @defgroup game_text_input Game Text Input
 * The interface to use GameTextInput.
 * @{
 */

#pragma once

#include <android/rect.h>
#include <jni.h>
#include <stdint.h>

#include "gamecommon.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * This struct holds a span within a region of text from start (inclusive) to
 * end (exclusive). An empty span or cursor position is specified with
 * start==end. An undefined span is specified with start = end = SPAN_UNDEFINED.
 */
typedef struct GameTextInputSpan {
    /** The start of the region (inclusive). */
    int32_t start;
    /** The end of the region (exclusive). */
    int32_t end;
} GameTextInputSpan;

/**
 * Values with special meaning in a GameTextInputSpan.
 */
enum GameTextInputSpanFlag { SPAN_UNDEFINED = -1 };

/**
 * This struct holds the state of an editable section of text.
 * The text can have a selection and a composing region defined on it.
 * A composing region is used by IMEs that allow input using multiple steps to
 * compose a glyph or word. Use functions GameTextInput_getState and
 * GameTextInput_setState to read and modify the state that an IME is editing.
 */
typedef struct GameTextInputState {
    /**
     * Text owned by the state, as a modified UTF-8 string. Null-terminated.
     * https://en.wikipedia.org/wiki/UTF-8#Modified_UTF-8
     */
    const char *text_UTF8;
    /**
     * Length in bytes of text_UTF8, *not* including the null at end.
     */
    int32_t text_length;
    /**
     * A selection defined on the text.
     */
    GameTextInputSpan selection;
    /**
     * A composing region defined on the text.
     */
    GameTextInputSpan composingRegion;
} GameTextInputState;

/**
 * A callback called by GameTextInput_getState.
 * @param context User-defined context.
 * @param state State, owned by the library, that will be valid for the duration
 * of the callback.
 */
typedef void (*GameTextInputGetStateCallback)(
    void *context, const struct GameTextInputState *state);

/**
 * Opaque handle to the GameTextInput API.
 */
typedef struct GameTextInput GameTextInput;

/**
 * Initialize the GameTextInput library.
 * If called twice without GameTextInput_destroy being called, the same pointer
 * will be returned and a warning will be issued.
 * @param env A JNI env valid on the calling thread.
 * @param max_string_size The maximum length of a string that can be edited. If
 * zero, the maximum defaults to 65536 bytes. A buffer of this size is allocated
 * at initialization.
 * @return A handle to the library.
 */
GameTextInput *GameTextInput_init(JNIEnv *env, uint32_t max_string_size);

/**
 * When using GameTextInput, you need to create a gametextinput.InputConnection
 * on the Java side and pass it using this function to the library, unless using
 * GameActivity in which case this will be done for you. See the GameActivity
 * source code or GameTextInput samples for examples of usage.
 * @param input A valid GameTextInput library handle.
 * @param inputConnection A gametextinput.InputConnection object.
 */
void GameTextInput_setInputConnection(GameTextInput *input,
                                      jobject inputConnection);

/**
 * Unless using GameActivity, it is required to call this function from your
 * Java gametextinput.Listener.stateChanged method to convert eventState and
 * trigger any event callbacks. When using GameActivity, this does not need to
 * be called as event processing is handled by the Activity.
 * @param input A valid GameTextInput library handle.
 * @param eventState A Java gametextinput.State object.
 */
void GameTextInput_processEvent(GameTextInput *input, jobject eventState);

/**
 * Free any resources owned by the GameTextInput library.
 * Any subsequent calls to the library will fail until GameTextInput_init is
 * called again.
 * @param input A valid GameTextInput library handle.
 */
void GameTextInput_destroy(GameTextInput *input);

/**
 * Flags to be passed to GameTextInput_showIme.
 */
enum ShowImeFlags {
    SHOW_IME_UNDEFINED = 0,  // Default value.
    SHOW_IMPLICIT =
        1,  // Indicates that the user has forced the input method open so it
            // should not be closed until they explicitly do so.
    SHOW_FORCED = 2  // Indicates that this is an implicit request to show the
                     // input window, not as the result of a direct request by
                     // the user. The window may not be shown in this case.
};

/**
 * Show the IME. Calls InputMethodManager.showSoftInput().
 * @param input A valid GameTextInput library handle.
 * @param flags Defined in ShowImeFlags above. For more information see:
 * https://developer.android.com/reference/android/view/inputmethod/InputMethodManager
 */
void GameTextInput_showIme(GameTextInput *input, uint32_t flags);

/**
 * Flags to be passed to GameTextInput_hideIme.
 */
enum HideImeFlags {
    HIDE_IME_UNDEFINED = 0,  // Default value.
    HIDE_IMPLICIT_ONLY =
        1,  // Indicates that the soft input window should only be hidden if it
            // was not explicitly shown by the user.
    HIDE_NOT_ALWAYS =
        2,  // Indicates that the soft input window should normally be hidden,
            // unless it was originally shown with SHOW_FORCED.
};

/**
 * Show the IME. Calls InputMethodManager.hideSoftInputFromWindow().
 * @param input A valid GameTextInput library handle.
 * @param flags Defined in HideImeFlags above. For more information see:
 * https://developer.android.com/reference/android/view/inputmethod/InputMethodManager
 */
void GameTextInput_hideIme(GameTextInput *input, uint32_t flags);

/**
 * Call a callback with the current GameTextInput state, which may have been
 * modified by changes in the IME and calls to GameTextInput_setState. We use a
 * callback rather than returning the state in order to simplify ownership of
 * text_UTF8 strings. These strings are only valid during the calling of the
 * callback.
 * @param input A valid GameTextInput library handle.
 * @param callback A function that will be called with valid state.
 * @param context Context used by the callback.
 */
void GameTextInput_getState(GameTextInput *input,
                            GameTextInputGetStateCallback callback,
                            void *context);

/**
 * Set the current GameTextInput state. This state is reflected to any active
 * IME.
 * @param input A valid GameTextInput library handle.
 * @param state The state to set. Ownership is maintained by the caller and must
 * remain valid for the duration of the call.
 */
void GameTextInput_setState(GameTextInput *input,
                            const GameTextInputState *state);

/**
 * Type of the callback needed by GameTextInput_setEventCallback that will be
 * called every time the IME state changes.
 * @param context User-defined context set in GameTextInput_setEventCallback.
 * @param current_state Current IME state, owned by the library and valid during
 * the callback.
 */
typedef void (*GameTextInputEventCallback)(
    void *context, const GameTextInputState *current_state);

/**
 * Optionally set a callback to be called whenever the IME state changes.
 * Not necessary if you are using GameActivity, which handles these callbacks
 * for you.
 * @param input A valid GameTextInput library handle.
 * @param callback Called by the library when the IME state changes.
 * @param context Context passed as first argument to the callback.
 */
void GameTextInput_setEventCallback(GameTextInput *input,
                                    GameTextInputEventCallback callback,
                                    void *context);

/**
 * Type of the callback needed by GameTextInput_setImeInsetsCallback that will
 * be called every time the IME window insets change.
 * @param context User-defined context set in
 * GameTextInput_setImeWIndowInsetsCallback.
 * @param current_insets Current IME insets, owned by the library and valid
 * during the callback.
 */
typedef void (*GameTextInputImeInsetsCallback)(void *context,
                                               const ARect *current_insets);

/**
 * Optionally set a callback to be called whenever the IME insets change.
 * Not necessary if you are using GameActivity, which handles these callbacks
 * for you.
 * @param input A valid GameTextInput library handle.
 * @param callback Called by the library when the IME insets change.
 * @param context Context passed as first argument to the callback.
 */
void GameTextInput_setImeInsetsCallback(GameTextInput *input,
                                        GameTextInputImeInsetsCallback callback,
                                        void *context);

/**
 * Get the current window insets for the IME.
 * @param input A valid GameTextInput library handle.
 * @param insets Filled with the current insets by this function.
 */
void GameTextInput_getImeInsets(const GameTextInput *input, ARect *insets);

/**
 * Unless using GameActivity, it is required to call this function from your
 * Java gametextinput.Listener.onImeInsetsChanged method to
 * trigger any event callbacks. When using GameActivity, this does not need to
 * be called as insets processing is handled by the Activity.
 * @param input A valid GameTextInput library handle.
 * @param eventState A Java gametextinput.State object.
 */
void GameTextInput_processImeInsets(GameTextInput *input, const ARect *insets);

/**
 * Convert a GameTextInputState struct to a Java gametextinput.State object.
 * Don't forget to delete the returned Java local ref when you're done.
 * @param input A valid GameTextInput library handle.
 * @param state Input state to convert.
 * @return A Java object of class gametextinput.State. The caller is required to
 * delete this local reference.
 */
jobject GameTextInputState_toJava(const GameTextInput *input,
                                  const GameTextInputState *state);

/**
 * Convert from a Java gametextinput.State object into a C GameTextInputState
 * struct.
 * @param input A valid GameTextInput library handle.
 * @param state A Java gametextinput.State object.
 * @param callback A function called with the C struct, valid for the duration
 * of the call.
 * @param context Context passed to the callback.
 */
void GameTextInputState_fromJava(const GameTextInput *input, jobject state,
                                 GameTextInputGetStateCallback callback,
                                 void *context);

#ifdef __cplusplus
}
#endif

/** @} */