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