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