/*
 * Copyright (C) 2022 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.
 */
package android.window;
import android.annotation.NonNull;
import android.app.Activity;
import android.app.Dialog;
import android.view.View;
import android.view.Window;

/**
 * Interface for applications to register back animation callbacks along their custom back
 * handling.
 * <p>
 * This allows the client to customize various back behaviors by overriding the corresponding
 * callback methods.
 * <p>
 * Callback instances can be added to and removed from {@link OnBackInvokedDispatcher}, which
 * is held at window level and accessible through {@link Activity#getOnBackInvokedDispatcher()},
 * {@link Dialog#getOnBackInvokedDispatcher()}, {@link Window#getOnBackInvokedDispatcher()}
 * and {@link View#findOnBackInvokedDispatcher()}.
 * <p>
 * When back is triggered, callbacks on the in-focus window are invoked in reverse order in which
 * they are added within the same priority. Between different priorities, callbacks with higher
 * priority are invoked first.
 * <p>
 * @see OnBackInvokedCallback
 */
public interface OnBackAnimationCallback extends OnBackInvokedCallback {
    /**
     * Called when a back gesture has been started, or back button has been pressed down.
     *
     * @param backEvent The {@link BackEvent} containing information about the touch or
     *                  button press.
     * @see BackEvent
     */
    default void onBackStarted(@NonNull BackEvent backEvent) {}

    /**
     * Called when a back gesture progresses.
     *
     * @param backEvent An {@link BackEvent} object describing the progress event.
     *
     * @see BackEvent
     */
    default void onBackProgressed(@NonNull BackEvent backEvent) { }
    /**
     * Called when a back gesture or back button press has been cancelled.
     */
    default void onBackCancelled() { }
}