1 /* 2 * Copyright (C) 2023 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 17 package com.google.android.torus.core.wallpaper.listener 18 19 import android.app.WallpaperColors 20 import android.os.Bundle 21 22 /** 23 * Interface that is used to implement specific wallpaper callbacks like offset change (user swipes 24 * between home pages), when the preview state has changed or when the zoom state has changed. 25 */ 26 interface LiveWallpaperEventListener { 27 companion object { 28 const val WAKE_ACTION_LOCATION_X: String = "WAKE_ACTION_LOCATION_X" 29 const val WAKE_ACTION_LOCATION_Y: String = "WAKE_ACTION_LOCATION_Y" 30 const val SLEEP_ACTION_LOCATION_X: String = "SLEEP_ACTION_LOCATION_X" 31 const val SLEEP_ACTION_LOCATION_Y: String = "SLEEP_ACTION_LOCATION_Y" 32 } 33 34 /** 35 * Called when the wallpaper has been scrolled (usually when the user scroll between pages in 36 * the home of the launcher). This only tracts the horizontal scroll. 37 * 38 * @param xOffset The current offset of the scroll. The value is normalize between [0,1]. 39 * @param xOffsetStep How is stepped the scroll. If you invert [xOffsetStep] you get the number 40 * of pages in the scrolling area. 41 */ onOffsetChangednull42 fun onOffsetChanged(xOffset: Float, xOffsetStep: Float) 43 44 /** 45 * Called when the zoom level of the wallpaper is changing. 46 * 47 * @param zoomLevel A value between 0 and 1 that tells how much the wallpaper should be zoomed 48 * out: if 0, the wallpaper should be in normal state; if 1 the wallpaper should be zoomed 49 * out. 50 */ 51 fun onZoomChanged(zoomLevel: Float) 52 53 /** 54 * Call when the wallpaper was set, and then is reapplied. This means that the wallpaper was set 55 * and is being set again. This is useful to know if the wallpaper settings have to be reapplied 56 * again (i.e. if the user enters the wallpaper picker and picks the same wallpaper, changes the 57 * settings and sets the wallpaper again). 58 */ 59 fun onWallpaperReapplied() 60 61 /** 62 * Called when the Wallpaper colors need to be computed you can create a [WallpaperColors] 63 * instance using the [WallpaperColors.fromBitmap] function and passing a bitmap that represents 64 * the wallpaper (i.e. the gallery thumbnail) or use the [WallpaperColors] constructor and pass 65 * the primary, secondary and tertiary colors. This method is specially important since the UI 66 * will change their colors based on what is returned here. 67 * 68 * @return The colors that represent the wallpaper; null if you want the System to take care of 69 * the colors. 70 */ 71 fun computeWallpaperColors(): WallpaperColors? 72 73 /** 74 * Called when the wallpaper receives the preview information (asynchronous call). 75 * 76 * @param extras the bundle of the preview information. The key "which_preview" can be used to 77 * retrieve a string value (ex. main_preview_home) that specifies which preview the engine is 78 * referring to. 79 */ 80 fun onPreviewInfoReceived(extras: Bundle?) {} 81 82 /** 83 * Called when the device is activated from a sleep/AOD state. 84 * 85 * @param extras contains the location of the action that caused the wake event: 86 * - [LiveWallpaperEventListener.WAKE_ACTION_LOCATION_X]: the X screen location (in Pixels). if 87 * the value is not included or is -1, the X screen location is unknown. 88 * - [LiveWallpaperEventListener.WAKE_ACTION_LOCATION_Y]: the Y screen location (in Pixels). if 89 * the value is not included or is -1, the Y screen location is unknown. 90 */ onWakenull91 fun onWake(extras: Bundle) 92 93 /** 94 * Called when the device enters a sleep/AOD state. 95 * 96 * @param extras contains the location of the action that caused the sleep event: 97 * - [LiveWallpaperEventListener.SLEEP_ACTION_LOCATION_X]: the X screen location (in Pixels). if 98 * the value is not included or is -1, the X screen location is unknown. 99 * - [LiveWallpaperEventListener.SLEEP_ACTION_LOCATION_Y]: the Y screen location (in Pixels). if 100 * the value is not included or is -1, the Y screen location is unknown. 101 */ 102 fun onSleep(extras: Bundle) 103 104 /** 105 * Indicates whether the zoom animation should be handled in WindowManager. Preferred to be set 106 * to true to avoid pressuring GPU. 107 * 108 * See [WallpaperService.shouldZoomOutWallpaper]. 109 */ 110 fun shouldZoomOutWallpaper() = false 111 112 /** 113 * React to COMMAND_LOCKSCREEN_LAYOUT_CHANGED from SystemUI to give wallpaper focal area on 114 * lockscreen 115 * 116 * @param extras contains the wallpaper focal area bounds from lockscreen 117 * 118 * For handheld, 119 * 120 * when there's notification, the focal area should be below notification stack, and above 121 * shortcut, and horizontally constrained by screen width. i.e. (screenLeft, 122 * notificationStackBottom, screenRight, shortcutTop) 123 * 124 * when there's no notification, the only difference is the top of focal area, which is below 125 * smartspace. i.e. (screenLeft, smartspaceBottom, screenRight, shortcutTop) 126 * 127 * For tablet portrait, we have the similar logic with handheld, but we have its width 128 * constrained by a maxFocalAreaWidth, which is 500dp. i.e. left = screenCenterX - 129 * maxFocalAreaWidth / 2, top = smartspaceBottom or notificationStackBottom, right = 130 * screenCenterX + maxFocalAreaWidth / 2, bottom = shortcutTop. 131 * 132 * For tablet landscape, focal area is always in the center of screen, and we need to have a top 133 * margin as margin from the shortcut top to the screen bottom to make focal area vertically 134 * symmetric i.e. left = screenCenterX - maxFocalAreaWidth / 2, top = 135 * shortcutMarginToScreenBottom, right = screenCenterX + maxFocalAreaWidth / 2, bottom = 136 * shortcutTop 137 * 138 * For foldable fold mode, we have the same logic with handheld. 139 * 140 * For foldable unfold portrait, we have same logic with tablet portrait. 141 * 142 * For foldable unfold landscape, when there's notification, focal area is in left half screen, 143 * top to bottom of smartspace, bottom to top of shortcut, left and right is constrained by half 144 * screen width, i.e. (screenLeft, smartspaceBottom, screenCenterX, shortcutTop) 145 * 146 * when there's no notification, focal area is in right half screen, top to bottom of 147 * smartspace, bottom to top of shortcut, left and right is constrained by half screen width. 148 * i.e. (screenCenterX, smartspaceBottom, screenRight, shortcutTop) 149 */ 150 // TODO: when smartspace is moved from below small clock to the right of the clock, we need to 151 // change all smartspace bottom mentioned above to small clock bottom 152 fun onLockscreenLayoutChanged(extras: Bundle) {} 153 } 154