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