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