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 * Display area that includes all areas which can have windows. It is used to separate the 116 * window content to provide the ability of display level animation and display recording. 117 * It is usually only a placeholder that organizer should not control it. This only exists 118 * if {@link #FEATURE_WINDOWED_MAGNIFICATION} is not available to be the windowing layer. 119 * @hide 120 */ 121 public static final int FEATURE_WINDOWING_LAYER = FEATURE_SYSTEM_FIRST + 9; 122 123 /** 124 * Display area for rendering app zoom out. When there are multiple layers on the screen, 125 * we want to render these layers based on a depth model. Here we zoom out the layer behind, 126 * whether it's an app or the homescreen. 127 * @hide 128 */ 129 public static final int FEATURE_APP_ZOOM_OUT = FEATURE_SYSTEM_FIRST + 10; 130 131 /** 132 * The last boundary of display area for system features 133 */ 134 public static final int FEATURE_SYSTEM_LAST = 10_000; 135 136 /** 137 * Vendor specific display area definition can start with this value. 138 */ 139 public static final int FEATURE_VENDOR_FIRST = FEATURE_SYSTEM_LAST + 1; 140 141 /** 142 * Last possible vendor specific display area id. 143 * @hide 144 */ 145 public static final int FEATURE_VENDOR_LAST = FEATURE_VENDOR_FIRST + 10_000; 146 147 /** 148 * Task display areas that can be created at runtime start with this value. 149 * @see #createTaskDisplayArea(int, int, String) 150 * @hide 151 */ 152 public static final int FEATURE_RUNTIME_TASK_CONTAINER_FIRST = FEATURE_VENDOR_LAST + 1; 153 154 // Callbacks WM Core are posted on this executor if it isn't null, otherwise direct calls are 155 // made on the incoming binder call. 156 private final Executor mExecutor; 157 158 /** @hide */ DisplayAreaOrganizer(@onNull Executor executor)159 public DisplayAreaOrganizer(@NonNull Executor executor) { 160 mExecutor = executor; 161 } 162 163 /** 164 * Gets the executor to run callbacks on. 165 * @hide 166 */ 167 @NonNull getExecutor()168 public Executor getExecutor() { 169 return mExecutor; 170 } 171 172 /** 173 * Registers a DisplayAreaOrganizer to manage display areas for a given feature. A feature can 174 * not be registered by multiple organizers at the same time. 175 * 176 * @return a list of display areas that should be managed by the organizer. 177 * @throws IllegalStateException if the feature has already been registered. 178 */ 179 @RequiresPermission(android.Manifest.permission.MANAGE_ACTIVITY_TASKS) 180 @CallSuper 181 @NonNull registerOrganizer(int displayAreaFeature)182 public List<DisplayAreaAppearedInfo> registerOrganizer(int displayAreaFeature) { 183 try { 184 return getController().registerOrganizer(mInterface, displayAreaFeature).getList(); 185 } catch (RemoteException e) { 186 throw e.rethrowFromSystemServer(); 187 } 188 } 189 190 /** 191 * @hide 192 */ 193 @RequiresPermission(android.Manifest.permission.MANAGE_ACTIVITY_TASKS) 194 @CallSuper unregisterOrganizer()195 public void unregisterOrganizer() { 196 try { 197 getController().unregisterOrganizer(mInterface); 198 } catch (RemoteException e) { 199 throw e.rethrowFromSystemServer(); 200 } 201 } 202 203 /** 204 * Creates a persistent {@link com.android.server.wm.TaskDisplayArea}. 205 * 206 * The new created TDA is organized by the organizer, and will be deleted on calling 207 * {@link #deleteTaskDisplayArea(WindowContainerToken)} or {@link #unregisterOrganizer()}. 208 * 209 * @param displayId the display to create the new TDA in. 210 * @param parentFeatureId the parent to create the new TDA in. If it is a 211 * {@link com.android.server.wm.RootDisplayArea}, the new TDA will be 212 * placed as the topmost TDA. If it is another TDA, the new TDA will be 213 * placed as the topmost child. 214 * Caller can use {@link #FEATURE_ROOT} as the root of the logical 215 * display, or {@link #FEATURE_DEFAULT_TASK_CONTAINER} as the default 216 * TDA. 217 * @param name the name for the new task display area. 218 * @return the new created task display area. 219 * @throws IllegalArgumentException if failed to create a new task display area. 220 * @hide 221 */ 222 @RequiresPermission(android.Manifest.permission.MANAGE_ACTIVITY_TASKS) 223 @CallSuper 224 @NonNull createTaskDisplayArea(int displayId, int parentFeatureId, @NonNull String name)225 public DisplayAreaAppearedInfo createTaskDisplayArea(int displayId, int parentFeatureId, 226 @NonNull String name) { 227 try { 228 return getController().createTaskDisplayArea( 229 mInterface, displayId, parentFeatureId, name); 230 } catch (RemoteException e) { 231 throw e.rethrowFromSystemServer(); 232 } 233 } 234 235 /** 236 * Deletes a persistent task display area. It can only be one that created by an organizer. 237 * 238 * @throws IllegalArgumentException if failed to delete the task display area. 239 * @hide 240 */ 241 @RequiresPermission(android.Manifest.permission.MANAGE_ACTIVITY_TASKS) 242 @CallSuper deleteTaskDisplayArea(@onNull WindowContainerToken taskDisplayArea)243 public void deleteTaskDisplayArea(@NonNull WindowContainerToken taskDisplayArea) { 244 try { 245 getController().deleteTaskDisplayArea(taskDisplayArea); 246 } catch (RemoteException e) { 247 throw e.rethrowFromSystemServer(); 248 } 249 } 250 251 /** 252 * Called when a DisplayArea of the registered window type can be controlled by this organizer. 253 * It will not be called for the DisplayAreas that exist when {@link #registerOrganizer(int)} is 254 * called. 255 */ onDisplayAreaAppeared(@onNull DisplayAreaInfo displayAreaInfo, @NonNull SurfaceControl leash)256 public void onDisplayAreaAppeared(@NonNull DisplayAreaInfo displayAreaInfo, 257 @NonNull SurfaceControl leash) {} 258 onDisplayAreaVanished(@onNull DisplayAreaInfo displayAreaInfo)259 public void onDisplayAreaVanished(@NonNull DisplayAreaInfo displayAreaInfo) {} 260 261 /** 262 * @hide 263 */ onDisplayAreaInfoChanged(@onNull DisplayAreaInfo displayAreaInfo)264 public void onDisplayAreaInfoChanged(@NonNull DisplayAreaInfo displayAreaInfo) {} 265 266 private final IDisplayAreaOrganizer mInterface = new IDisplayAreaOrganizer.Stub() { 267 268 @Override 269 public void onDisplayAreaAppeared(@NonNull DisplayAreaInfo displayAreaInfo, 270 @NonNull SurfaceControl leash) { 271 mExecutor.execute( 272 () -> DisplayAreaOrganizer.this.onDisplayAreaAppeared(displayAreaInfo, leash)); 273 } 274 275 @Override 276 public void onDisplayAreaVanished(@NonNull DisplayAreaInfo displayAreaInfo) { 277 mExecutor.execute( 278 () -> DisplayAreaOrganizer.this.onDisplayAreaVanished(displayAreaInfo)); 279 } 280 281 @Override 282 public void onDisplayAreaInfoChanged(@NonNull DisplayAreaInfo displayAreaInfo) { 283 mExecutor.execute( 284 () -> DisplayAreaOrganizer.this.onDisplayAreaInfoChanged(displayAreaInfo)); 285 } 286 }; 287 288 @RequiresPermission(android.Manifest.permission.MANAGE_ACTIVITY_TASKS) getController()289 private IDisplayAreaOrganizerController getController() { 290 try { 291 return getWindowOrganizerController().getDisplayAreaOrganizerController(); 292 } catch (RemoteException e) { 293 return null; 294 } 295 } 296 } 297