1  /*
2   * Copyright (C) 2022 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  package android.window;
18  
19  import android.annotation.IntDef;
20  import android.annotation.IntRange;
21  import android.annotation.NonNull;
22  import android.annotation.SuppressLint;
23  
24  import java.lang.annotation.Retention;
25  import java.lang.annotation.RetentionPolicy;
26  
27  /**
28   * Dispatcher to register {@link OnBackInvokedCallback} instances for handling
29   * back invocations.
30   *
31   * It also provides interfaces to update the attributes of {@link OnBackInvokedCallback}.
32   * Attribute updates are proactively pushed to the window manager if they change the dispatch
33   * target (a.k.a. the callback to be invoked next), or its behavior.
34   */
35  public interface OnBackInvokedDispatcher {
36      /** @hide */
37      String TAG = "OnBackInvokedDispatcher";
38  
39      /** @hide */
40      boolean DEBUG = false;
41  
42      /** @hide */
43      @IntDef({
44              PRIORITY_DEFAULT,
45              PRIORITY_OVERLAY,
46      })
47      @Retention(RetentionPolicy.SOURCE)
48      @interface Priority{}
49  
50      /**
51       * Priority level of {@link OnBackInvokedCallback}s for overlays such as menus and
52       * navigation drawers that should receive back dispatch before non-overlays.
53       */
54      int PRIORITY_OVERLAY = 1000000;
55  
56      /**
57       * Default priority level of {@link OnBackInvokedCallback}s.
58       */
59      int PRIORITY_DEFAULT = 0;
60  
61      /**
62       * Priority level of {@link OnBackInvokedCallback}s registered by the system.
63       *
64       * System back animation will play when the callback to receive dispatch has this priority.
65       * @hide
66       */
67      int PRIORITY_SYSTEM = -1;
68  
69      /**
70       * Registers a {@link OnBackInvokedCallback}.
71       *
72       * Within the same priority level, callbacks are invoked in the reverse order in which
73       * they are registered. Higher priority callbacks are invoked before lower priority ones.
74       *
75       * @param priority The priority of the callback.
76       * @param callback The callback to be registered. If the callback instance has been already
77       *                 registered, the existing instance (no matter its priority) will be
78       *                 unregistered and registered again.
79       * @throws {@link IllegalArgumentException} if the priority is negative.
80       */
81      @SuppressLint({"ExecutorRegistration"})
registerOnBackInvokedCallback( @riority @ntRangefrom = 0) int priority, @NonNull OnBackInvokedCallback callback)82      void registerOnBackInvokedCallback(
83              @Priority @IntRange(from = 0) int priority, @NonNull OnBackInvokedCallback callback);
84  
85      /**
86       * Unregisters a {@link OnBackInvokedCallback}.
87       *
88       * @param callback The callback to be unregistered. Does nothing if the callback has not been
89       *                 registered.
90       */
unregisterOnBackInvokedCallback(@onNull OnBackInvokedCallback callback)91      void unregisterOnBackInvokedCallback(@NonNull OnBackInvokedCallback callback);
92  
93      /**
94       * Registers a {@link OnBackInvokedCallback} with system priority.
95       * @hide
96       */
registerSystemOnBackInvokedCallback(@onNull OnBackInvokedCallback callback)97      default void registerSystemOnBackInvokedCallback(@NonNull OnBackInvokedCallback callback) { }
98  
99  
100      /**
101       * Sets an {@link ImeOnBackInvokedDispatcher} to forward {@link OnBackInvokedCallback}s
102       * from IME to the app process to be registered on the app window.
103       *
104       * Only call this on the IME window. Create the {@link ImeOnBackInvokedDispatcher} from
105       * the application process and override
106       * {@link ImeOnBackInvokedDispatcher#getReceivingDispatcher()} to point to the app
107       * window's {@link WindowOnBackInvokedDispatcher}.
108       *
109       * @hide
110       */
setImeOnBackInvokedDispatcher( @onNull ImeOnBackInvokedDispatcher imeDispatcher)111      default void setImeOnBackInvokedDispatcher(
112              @NonNull ImeOnBackInvokedDispatcher imeDispatcher) { }
113  }
114