1 /* 2 * Copyright (C) 2017 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 package com.android.wallpaper.module; 17 18 import static android.app.WallpaperManager.FLAG_LOCK; 19 import static android.app.WallpaperManager.FLAG_SYSTEM; 20 import static android.app.WallpaperManager.SetWallpaperFlags; 21 22 import android.app.Activity; 23 import android.graphics.Bitmap; 24 import android.graphics.Rect; 25 26 import androidx.annotation.IntDef; 27 import androidx.annotation.Nullable; 28 29 import com.android.wallpaper.asset.Asset; 30 import com.android.wallpaper.compat.WallpaperManagerCompat; 31 import com.android.wallpaper.model.WallpaperInfo; 32 33 import java.util.List; 34 35 /** 36 * Interface for classes which persist wallpapers to the system. 37 */ 38 public interface WallpaperPersister { 39 40 int DEST_HOME_SCREEN = 0; 41 int DEST_LOCK_SCREEN = 1; 42 int DEST_BOTH = 2; 43 int WALLPAPER_POSITION_CENTER = 0; 44 int WALLPAPER_POSITION_CENTER_CROP = 1; 45 int WALLPAPER_POSITION_STRETCH = 2; 46 47 /** 48 * Sets a static individual wallpaper to the system via the WallpaperManager. 49 * 50 * @param wallpaper Wallpaper model object. Wallpaper image will be set from the asset provided 51 * to this method. 52 * @param asset Wallpaper asset from which to retrieve image data. 53 * @param cropRect Desired crop area of the wallpaper in post-scale units. If null, then the 54 * wallpaper image will be set without any scaling or cropping. 55 * @param scale Scaling factor applied to the source image before setting the wallpaper to the 56 * device. 57 * @param destination The destination - where to set the wallpaper to. 58 * @param callback Called once the wallpaper was set or if an error occurred. 59 */ setIndividualWallpaper(WallpaperInfo wallpaper, Asset asset, @Nullable Rect cropRect, float scale, @Destination int destination, SetWallpaperCallback callback)60 void setIndividualWallpaper(WallpaperInfo wallpaper, Asset asset, @Nullable Rect cropRect, 61 float scale, @Destination int destination, SetWallpaperCallback callback); 62 63 /** 64 * Sets a static individual wallpaper to the system with the provided wallpaper position 65 * preference to fit the device display. This method does not provide a destination option since 66 * the UI that calls this interface does not support separate home and lock screens. 67 * 68 * @param wallpaper Wallpaper model object. Wallpaper image will be set from the asset provided 69 * by the wallpaper's default asset. 70 * @param wallpaperPosition Crop strategy for fitting the wallpaper asset to the device display. 71 * @param callback Called once the wallpaper was set or if an error occurred. 72 */ setIndividualWallpaperWithPosition(Activity activity, WallpaperInfo wallpaper, @WallpaperPosition int wallpaperPosition, SetWallpaperCallback callback)73 void setIndividualWallpaperWithPosition(Activity activity, WallpaperInfo wallpaper, 74 @WallpaperPosition int wallpaperPosition, SetWallpaperCallback callback); 75 76 /** 77 * Sets an individual wallpaper to the system as the wallpaper in the current rotation along with 78 * its metadata. Prevents automatic wallpaper backup to conserve user data. 79 * <p> 80 * This method should only be called off the main UI thread because it will compress and set the 81 * bitmap on the same thread as the caller. 82 * 83 * @param wallpaperBitmap Cropped and scaled wallpaper bitmap. This bitmap will be persisted as-is 84 * with no additional processing. 85 * @param attributions List of attribution items. 86 * @param actionUrl The action or "explore" URL for the wallpaper. 87 * @param collectionId ID of this wallpaper's collection. 88 * @return Whether the set wallpaper operation was successful. 89 */ setWallpaperInRotation(Bitmap wallpaperBitmap, List<String> attributions, int actionLabelRes, int actionIconRes, String actionUrl, String collectionId)90 boolean setWallpaperInRotation(Bitmap wallpaperBitmap, List<String> attributions, 91 int actionLabelRes, int actionIconRes, 92 String actionUrl, String collectionId); 93 94 /** 95 * Sets only the bitmap of a rotating wallpaper of the next rotation to the system and stores 96 * the given static wallpaper data in the recent wallpapers list (and not metadata). 97 * 98 * @param wallpaperBitmap The rotating wallpaper's bitmap. 99 * @param attributions List of attribution items. 100 * @param actionUrl The action or "explore" URL for the wallpaper. 101 * @param collectionId ID of this wallpaper's collection. 102 * @return wallpaper ID, which is a positive integer if the set wallpaper operation was 103 * successful, or 0 otherwise. On Android versions prior to N, this method will always return 104 * 1 if the operation was successful because wallpaper IDs are not supported prior to N. 105 */ setWallpaperBitmapInNextRotation(Bitmap wallpaperBitmap, List<String> attributions, String actionUrl, String collectionId)106 int setWallpaperBitmapInNextRotation(Bitmap wallpaperBitmap, List<String> attributions, 107 String actionUrl, String collectionId); 108 109 /** 110 * Persists rotating wallpaper metadata for the next rotation and finalizes the preview wallpaper 111 * image so that it's visible as the actual device wallpaper. 112 * 113 * @param attributions List of attribution items. 114 * @param actionUrl The action or "explore" URL for the wallpaper. 115 * @param collectionId ID of this wallpaper's collection. 116 * @param wallpaperId Wallpaper ID that on Android N and later uniquely identifies the wallpaper 117 * image. 118 * @return Whether the operation succeeded. 119 */ finalizeWallpaperForNextRotation(List<String> attributions, String actionUrl, int actionLabelRes, int actionIconRes, String collectionId, int wallpaperId)120 boolean finalizeWallpaperForNextRotation(List<String> attributions, String actionUrl, 121 int actionLabelRes, int actionIconRes, 122 String collectionId, int wallpaperId); 123 124 /** 125 * Finalizes wallpaper metadata by persisting them to SharedPreferences and finalizes the 126 * wallpaper image for live rotating components by copying the "preview" image to the "final" 127 * image file location. 128 * 129 * @param attributions List of attribution items. 130 * @param actionUrl The action or "explore" URL for the wallpaper. 131 * @param actionLabelRes Resource ID of the action label 132 * @param actionIconRes Resource ID of the action icon 133 * @param collectionId ID of this wallpaper's collection. 134 * @param wallpaperId Wallpaper ID that uniquely identifies the wallpaper image. 135 * @return Whether the operation was successful. 136 */ saveStaticWallpaperMetadata(List<String> attributions, String actionUrl, int actionLabelRes, int actionIconRes, String collectionId, int wallpaperId)137 boolean saveStaticWallpaperMetadata(List<String> attributions, 138 String actionUrl, 139 int actionLabelRes, 140 int actionIconRes, 141 String collectionId, 142 int wallpaperId); 143 144 /** 145 * @return the flag indicating which wallpaper to set when we're trying to set a wallpaper with 146 * no user intervention. The idea is that if there's a static wallpaper on lock, we will only 147 * override home, otherwise both 148 */ getDefaultWhichWallpaper()149 int getDefaultWhichWallpaper(); 150 151 /** 152 * Sets a wallpaper bitmap to the {@link WallpaperManagerCompat}. 153 * 154 * @return an integer wallpaper ID. This is an actual wallpaper ID on N and later versions of 155 * Android, otherwise on pre-N versions of Android will return a positive integer when the 156 * operation was successful and zero if the operation encountered an error. 157 */ setBitmapToWallpaperManagerCompat(Bitmap wallpaperBitmap, boolean allowBackup, int whichWallpaper)158 int setBitmapToWallpaperManagerCompat(Bitmap wallpaperBitmap, boolean allowBackup, 159 int whichWallpaper); 160 161 /** 162 * Saves the last wallpaper which showed a preview from this app. 163 */ setWallpaperInfoInPreview(WallpaperInfo wallpaper)164 void setWallpaperInfoInPreview(WallpaperInfo wallpaper); 165 166 /** 167 * Saves attributions to WallpaperPreferences for the last previewed wallpaper if it has an 168 * {@link android.app.WallpaperInfo} component matching the one currently set to the 169 * {@link android.app.WallpaperManager}. 170 * 171 * @param destination Live wallpaper destination (home/lock/both) 172 */ onLiveWallpaperSet(@estination int destination)173 void onLiveWallpaperSet(@Destination int destination); 174 175 /** 176 * Updates lie wallpaper metadata by persisting them to SharedPreferences. 177 * 178 * @param wallpaperInfo Wallpaper model for the live wallpaper 179 * @param effects Comma-separate list of effect (see {@link WallpaperInfo#getEffectNames}) 180 * @param destination Live wallpaper destination (home/lock/both) 181 */ setLiveWallpaperMetadata(WallpaperInfo wallpaperInfo, String effects, @Destination int destination)182 void setLiveWallpaperMetadata(WallpaperInfo wallpaperInfo, String effects, 183 @Destination int destination); 184 185 /** 186 * Interface for tracking success or failure of set wallpaper operations. 187 */ 188 interface SetWallpaperCallback { onSuccess(WallpaperInfo wallpaperInfo, @Destination int destination)189 void onSuccess(WallpaperInfo wallpaperInfo, @Destination int destination); 190 onError(@ullable Throwable throwable)191 void onError(@Nullable Throwable throwable); 192 } 193 194 /** 195 * The possible destinations to which a wallpaper may be set. 196 */ 197 @IntDef({ 198 DEST_HOME_SCREEN, 199 DEST_LOCK_SCREEN, 200 DEST_BOTH}) 201 @interface Destination { 202 } 203 204 /** 205 * Possible wallpaper positions for setting an image wallpaper on desktop. 206 */ 207 @IntDef({ 208 WALLPAPER_POSITION_CENTER, 209 WALLPAPER_POSITION_CENTER_CROP, 210 WALLPAPER_POSITION_STRETCH}) 211 @interface WallpaperPosition { 212 } 213 214 /** 215 * Converts a {@link Destination} to the corresponding set of {@link SetWallpaperFlags}. 216 */ 217 @SetWallpaperFlags destinationToFlags(@estination int destination)218 static int destinationToFlags(@Destination int destination) { 219 switch (destination) { 220 case DEST_HOME_SCREEN: 221 return FLAG_SYSTEM; 222 case DEST_LOCK_SCREEN: 223 return FLAG_LOCK; 224 case DEST_BOTH: 225 return FLAG_SYSTEM | FLAG_LOCK; 226 default: 227 throw new AssertionError("Unknown @Destination"); 228 } 229 } 230 231 /** 232 * Converts a set of {@link SetWallpaperFlags} to the corresponding {@link Destination}. 233 */ 234 @Destination flagsToDestination(@etWallpaperFlags int flags)235 static int flagsToDestination(@SetWallpaperFlags int flags) { 236 if (flags == (FLAG_SYSTEM | FLAG_LOCK)) { 237 return DEST_BOTH; 238 } else if (flags == FLAG_SYSTEM) { 239 return DEST_HOME_SCREEN; 240 } else if (flags == FLAG_LOCK) { 241 return DEST_LOCK_SCREEN; 242 } else { 243 throw new AssertionError("Unknown @SetWallpaperFlags value"); 244 } 245 } 246 } 247