• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2020 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.CallSuper;
20 import android.annotation.NonNull;
21 import android.annotation.RequiresPermission;
22 import android.annotation.TestApi;
23 import android.os.RemoteException;
24 import android.view.SurfaceControl;
25 
26 import java.util.List;
27 import java.util.concurrent.Executor;
28 
29 /**
30  * Interface for WindowManager to delegate control of display areas.
31  * @hide
32  */
33 @TestApi
34 public class DisplayAreaOrganizer extends WindowOrganizer {
35 
36     /**
37      * Key to specify the {@link com.android.server.wm.RootDisplayArea} to attach a window to.
38      * It will be used by the function passed in from
39      * {@link com.android.server.wm.DisplayAreaPolicyBuilder#setSelectRootForWindowFunc(BiFunction)}
40      * to find the Root DA to attach the window.
41      * @hide
42      */
43     public static final String KEY_ROOT_DISPLAY_AREA_ID = "root_display_area_id";
44 
45     /**
46      * The value in display area indicating that no value has been set.
47      */
48     public static final int FEATURE_UNDEFINED = -1;
49 
50     /**
51      * The Root display area on a display
52      */
53     public static final int FEATURE_SYSTEM_FIRST = 0;
54 
55     /**
56      * The Root display area on a display
57      */
58     public static final int FEATURE_ROOT = FEATURE_SYSTEM_FIRST;
59 
60     /**
61      * Display area hosting the default task container.
62      */
63     public static final int FEATURE_DEFAULT_TASK_CONTAINER = FEATURE_SYSTEM_FIRST + 1;
64 
65     /**
66      * Display area hosting non-activity window tokens.
67      */
68     public static final int FEATURE_WINDOW_TOKENS = FEATURE_SYSTEM_FIRST + 2;
69 
70     /**
71      * Display area for one handed feature
72      */
73     public static final int FEATURE_ONE_HANDED = FEATURE_SYSTEM_FIRST + 3;
74 
75     /**
76      * Display area that can be magnified in
77      * {@link Settings.Secure.ACCESSIBILITY_MAGNIFICATION_MODE_WINDOW}. It contains all windows
78      * below {@link WindowManager.LayoutParams#TYPE_ACCESSIBILITY_MAGNIFICATION_OVERLAY}.
79      */
80     public static final int FEATURE_WINDOWED_MAGNIFICATION = FEATURE_SYSTEM_FIRST + 4;
81 
82     /**
83      * Display area that can be magnified in
84      * {@link Settings.Secure.ACCESSIBILITY_MAGNIFICATION_MODE_FULLSCREEN}. This is different from
85      * {@link #FEATURE_WINDOWED_MAGNIFICATION} that the whole display will be magnified.
86      * @hide
87      */
88     public static final int FEATURE_FULLSCREEN_MAGNIFICATION = FEATURE_SYSTEM_FIRST + 5;
89 
90     /**
91      * Display area for hiding display cutout feature
92      * @hide
93      */
94     public static final int FEATURE_HIDE_DISPLAY_CUTOUT = FEATURE_SYSTEM_FIRST + 6;
95 
96     /**
97      * Display area that the IME container can be placed in. Should be enabled on every root
98      * hierarchy if IME container may be reparented to that hierarchy when the IME target changed.
99      * @hide
100      */
101     public static final int FEATURE_IME_PLACEHOLDER = FEATURE_SYSTEM_FIRST + 7;
102 
103     /**
104      * Display area hosting IME window tokens (@see ImeContainer). By default, IMEs are parented
105      * to FEATURE_IME_PLACEHOLDER but can be reparented under other RootDisplayArea.
106      *
107      * This feature can register organizers in order to disable the reparenting logic and manage
108      * the position and settings of the container manually. This is useful for foldable devices
109      * which require custom UX rules for the IME position (e.g. IME on one screen and the focused
110      * app on another screen).
111      */
112     public static final int FEATURE_IME = FEATURE_SYSTEM_FIRST + 8;
113 
114     /**
115      * The last boundary of display area for system features
116      */
117     public static final int FEATURE_SYSTEM_LAST = 10_000;
118 
119     /**
120      * Vendor specific display area definition can start with this value.
121      */
122     public static final int FEATURE_VENDOR_FIRST = FEATURE_SYSTEM_LAST + 1;
123 
124     /**
125      * Last possible vendor specific display area id.
126      * @hide
127      */
128     public static final int FEATURE_VENDOR_LAST = FEATURE_VENDOR_FIRST + 10_000;
129 
130     /**
131      * Task display areas that can be created at runtime start with this value.
132      * @see #createTaskDisplayArea(int, int, String)
133      * @hide
134      */
135     public static final int FEATURE_RUNTIME_TASK_CONTAINER_FIRST = FEATURE_VENDOR_LAST + 1;
136 
137     // Callbacks WM Core are posted on this executor if it isn't null, otherwise direct calls are
138     // made on the incoming binder call.
139     private final Executor mExecutor;
140 
141     /** @hide */
DisplayAreaOrganizer(@onNull Executor executor)142     public DisplayAreaOrganizer(@NonNull Executor executor) {
143         mExecutor = executor;
144     }
145 
146     /**
147      * Gets the executor to run callbacks on.
148      * @hide
149      */
150     @NonNull
getExecutor()151     public Executor getExecutor() {
152         return mExecutor;
153     }
154 
155     /**
156      * Registers a DisplayAreaOrganizer to manage display areas for a given feature. A feature can
157      * not be registered by multiple organizers at the same time.
158      *
159      * @return a list of display areas that should be managed by the organizer.
160      * @throws IllegalStateException if the feature has already been registered.
161      */
162     @RequiresPermission(android.Manifest.permission.MANAGE_ACTIVITY_TASKS)
163     @CallSuper
164     @NonNull
registerOrganizer(int displayAreaFeature)165     public List<DisplayAreaAppearedInfo> registerOrganizer(int displayAreaFeature) {
166         try {
167             return getController().registerOrganizer(mInterface, displayAreaFeature).getList();
168         } catch (RemoteException e) {
169             throw e.rethrowFromSystemServer();
170         }
171     }
172 
173     /**
174      * @hide
175      */
176     @RequiresPermission(android.Manifest.permission.MANAGE_ACTIVITY_TASKS)
177     @CallSuper
unregisterOrganizer()178     public void unregisterOrganizer() {
179         try {
180             getController().unregisterOrganizer(mInterface);
181         } catch (RemoteException e) {
182             throw e.rethrowFromSystemServer();
183         }
184     }
185 
186     /**
187      * Creates a persistent {@link com.android.server.wm.TaskDisplayArea}.
188      *
189      * The new created TDA is organized by the organizer, and will be deleted on calling
190      * {@link #deleteTaskDisplayArea(WindowContainerToken)} or {@link #unregisterOrganizer()}.
191      *
192      * @param displayId the display to create the new TDA in.
193      * @param parentFeatureId the parent to create the new TDA in. If it is a
194      *                        {@link com.android.server.wm.RootDisplayArea}, the new TDA will be
195      *                        placed as the topmost TDA. If it is another TDA, the new TDA will be
196      *                        placed as the topmost child.
197      *                        Caller can use {@link #FEATURE_ROOT} as the root of the logical
198      *                        display, or {@link #FEATURE_DEFAULT_TASK_CONTAINER} as the default
199      *                        TDA.
200      * @param name the name for the new task display area.
201      * @return the new created task display area.
202      * @throws IllegalArgumentException if failed to create a new task display area.
203      * @hide
204      */
205     @RequiresPermission(android.Manifest.permission.MANAGE_ACTIVITY_TASKS)
206     @CallSuper
207     @NonNull
createTaskDisplayArea(int displayId, int parentFeatureId, @NonNull String name)208     public DisplayAreaAppearedInfo createTaskDisplayArea(int displayId, int parentFeatureId,
209             @NonNull String name) {
210         try {
211             return getController().createTaskDisplayArea(
212                     mInterface, displayId, parentFeatureId, name);
213         } catch (RemoteException e) {
214             throw e.rethrowFromSystemServer();
215         }
216     }
217 
218     /**
219      * Deletes a persistent task display area. It can only be one that created by an organizer.
220      *
221      * @throws IllegalArgumentException if failed to delete the task display area.
222      * @hide
223      */
224     @RequiresPermission(android.Manifest.permission.MANAGE_ACTIVITY_TASKS)
225     @CallSuper
deleteTaskDisplayArea(@onNull WindowContainerToken taskDisplayArea)226     public void deleteTaskDisplayArea(@NonNull WindowContainerToken taskDisplayArea) {
227         try {
228             getController().deleteTaskDisplayArea(taskDisplayArea);
229         } catch (RemoteException e) {
230             throw e.rethrowFromSystemServer();
231         }
232     }
233 
234     /**
235      * Called when a DisplayArea of the registered window type can be controlled by this organizer.
236      * It will not be called for the DisplayAreas that exist when {@link #registerOrganizer(int)} is
237      * called.
238      */
onDisplayAreaAppeared(@onNull DisplayAreaInfo displayAreaInfo, @NonNull SurfaceControl leash)239     public void onDisplayAreaAppeared(@NonNull DisplayAreaInfo displayAreaInfo,
240             @NonNull SurfaceControl leash) {}
241 
onDisplayAreaVanished(@onNull DisplayAreaInfo displayAreaInfo)242     public void onDisplayAreaVanished(@NonNull DisplayAreaInfo displayAreaInfo) {}
243 
244     /**
245      * @hide
246      */
onDisplayAreaInfoChanged(@onNull DisplayAreaInfo displayAreaInfo)247     public void onDisplayAreaInfoChanged(@NonNull DisplayAreaInfo displayAreaInfo) {}
248 
249     private final IDisplayAreaOrganizer mInterface = new IDisplayAreaOrganizer.Stub() {
250 
251         @Override
252         public void onDisplayAreaAppeared(@NonNull DisplayAreaInfo displayAreaInfo,
253                 @NonNull SurfaceControl leash) {
254             mExecutor.execute(
255                     () -> DisplayAreaOrganizer.this.onDisplayAreaAppeared(displayAreaInfo, leash));
256         }
257 
258         @Override
259         public void onDisplayAreaVanished(@NonNull DisplayAreaInfo displayAreaInfo) {
260             mExecutor.execute(
261                     () -> DisplayAreaOrganizer.this.onDisplayAreaVanished(displayAreaInfo));
262         }
263 
264         @Override
265         public void onDisplayAreaInfoChanged(@NonNull DisplayAreaInfo displayAreaInfo) {
266             mExecutor.execute(
267                     () -> DisplayAreaOrganizer.this.onDisplayAreaInfoChanged(displayAreaInfo));
268         }
269     };
270 
271     @RequiresPermission(android.Manifest.permission.MANAGE_ACTIVITY_TASKS)
getController()272     private IDisplayAreaOrganizerController getController() {
273         try {
274             return getWindowOrganizerController().getDisplayAreaOrganizerController();
275         } catch (RemoteException e) {
276             return null;
277         }
278     }
279 }
280