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