1 /* 2 * Copyright (C) 2024 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.widget.photopicker; 18 19 import android.annotation.FlaggedApi; 20 import android.annotation.RequiresApi; 21 import android.annotation.SuppressLint; 22 import android.content.res.Configuration; 23 import android.net.Uri; 24 import android.os.Build; 25 import android.view.SurfaceControlViewHost; 26 import android.view.SurfaceView; 27 28 import androidx.annotation.NonNull; 29 30 import java.util.List; 31 32 /** 33 * Class that holds the embedded photopicker view wrapped in 34 * {@link SurfaceControlViewHost.SurfacePackage} that can be embedded by the caller in their 35 * view hierarchy by placing it in a {@link SurfaceView} via its 36 * {@link SurfaceView#setChildSurfacePackage} api. 37 * 38 * Callers of {@link EmbeddedPhotoPickerProvider#openSession} will asynchronously receive instance 39 * of this class from the service upon its successful execution via 40 * {@link EmbeddedPhotoPickerClient#onSessionOpened} callback. 41 * 42 * <p> Instance of this class can be then used by callers to notify PhotoPicker about 43 * different events for service to act upon them. 44 * 45 * <p> When a session is no longer being used, it should be closed by callers to help system 46 * release the resources. 47 * 48 * @see EmbeddedPhotoPickerProvider 49 * @see EmbeddedPhotoPickerClient 50 * 51 */ 52 @RequiresApi(Build.VERSION_CODES.UPSIDE_DOWN_CAKE) 53 @FlaggedApi("com.android.providers.media.flags.enable_embedded_photopicker") 54 @SuppressLint({"NotCloseable", "PackageLayering"}) 55 public interface EmbeddedPhotoPickerSession { 56 57 /** 58 * Returns the {@link SurfaceControlViewHost.SurfacePackage} that contains view representing 59 * embedded picker. 60 * 61 * <p> Callers can attach this view in their hierarchy using 62 * {@link SurfaceView#setChildSurfacePackage} api. 63 */ 64 @NonNull getSurfacePackage()65 SurfaceControlViewHost.SurfacePackage getSurfacePackage(); 66 67 /** 68 * Close the session, i.e. photopicker will release resources associated with this 69 * session. Any further notifications to this Session will be ignored by the service. 70 */ close()71 void close(); 72 73 /** 74 * Notify that embedded photopicker view is visible or not to the user. 75 * 76 * <p> This helps photopicker to close upstream work and manage the lifecycle 77 * of this Session instance. 78 * 79 * @param isVisible True if view visible to the user, false if not. 80 */ notifyVisibilityChanged(boolean isVisible)81 void notifyVisibilityChanged(boolean isVisible); 82 83 /** 84 * Notify that caller's presentation area has changed and photopicker's dimensions 85 * should change accordingly. 86 * 87 * @param width width of the view, in pixels 88 * @param height height of the view, in pixels 89 */ notifyResized(int width, int height)90 void notifyResized(int width, int height); 91 92 /** 93 * Notifies photopicker that host side configuration has changed. 94 * 95 * @param configuration new configuration of caller 96 */ notifyConfigurationChanged(@onNull Configuration configuration)97 void notifyConfigurationChanged(@NonNull Configuration configuration); 98 99 /** 100 * Notify that user switched photopicker between expanded/collapsed state. 101 * 102 * <p> Some photopicker features (like Profile selector, Album grid etc.) 103 * are only shown in full/expanded view and are hidden in collapsed view. 104 * 105 * @param isExpanded true if expanded, false if collapsed. 106 */ notifyPhotoPickerExpanded(boolean isExpanded)107 void notifyPhotoPickerExpanded(boolean isExpanded); 108 109 /** 110 * Notify that the user deselected some items. 111 * 112 * @param uris The {@link Uri} list of the deselected items. 113 */ requestRevokeUriPermission(@onNull List<Uri> uris)114 void requestRevokeUriPermission(@NonNull List<Uri> uris); 115 } 116