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