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