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