1 /*
2  * Copyright (C) 2018 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
5  * except in compliance with the License. You may obtain a copy of the License at
6  *
7  *      http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software distributed under the
10  * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
11  * KIND, either express or implied. See the License for the specific language governing
12  * permissions and limitations under the License.
13  */
14 package com.android.systemui.plugins;
15 
16 import android.graphics.Bitmap;
17 import android.graphics.Paint.Style;
18 import android.view.View;
19 
20 import com.android.systemui.plugins.annotations.ProvidesInterface;
21 
22 import java.util.TimeZone;
23 
24 /**
25  * Plugin used to replace main clock in keyguard.
26  */
27 @ProvidesInterface(action = ClockPlugin.ACTION, version = ClockPlugin.VERSION)
28 public interface ClockPlugin extends Plugin {
29 
30     String ACTION = "com.android.systemui.action.PLUGIN_CLOCK";
31     int VERSION = 5;
32 
33     /**
34      * Get the name of the clock face.
35      *
36      * This name should not be translated.
37      */
getName()38     String getName();
39 
40     /**
41      * Get the title of the clock face to be shown in the picker app.
42      */
getTitle()43     String getTitle();
44 
45     /**
46      * Get thumbnail of clock face to be shown in the picker app.
47      */
getThumbnail()48     Bitmap getThumbnail();
49 
50     /**
51      * Get preview images of clock face to be shown in the picker app.
52      *
53      * Preview image should be realistic and show what the clock face will look like on AOD and lock
54      * screen.
55      *
56      * @param width width of the preview image, should be the same as device width in pixels.
57      * @param height height of the preview image, should be the same as device height in pixels.
58      */
getPreview(int width, int height)59     Bitmap getPreview(int width, int height);
60 
61     /**
62      * Get clock view.
63      * @return clock view from plugin.
64      */
getView()65     View getView();
66 
67     /**
68      * Get clock view for a large clock that appears behind NSSL.
69      */
getBigClockView()70     default View getBigClockView() {
71         return null;
72     }
73 
74     /**
75      * Returns the preferred Y position of the clock.
76      *
77      * @param totalHeight Height of the parent container.
78      * @return preferred Y position.
79      */
getPreferredY(int totalHeight)80     int getPreferredY(int totalHeight);
81 
82     /**
83      * Allows the plugin to clean up resources when no longer needed.
84      *
85      * Called when the view previously created by {@link ClockPlugin#getView()} has been detached
86      * from the view hierarchy.
87      */
onDestroyView()88     void onDestroyView();
89 
90     /**
91      * Set clock paint style.
92      * @param style The new style to set in the paint.
93      */
setStyle(Style style)94     void setStyle(Style style);
95 
96     /**
97      * Set clock text color.
98      * @param color A color value.
99      */
setTextColor(int color)100     void setTextColor(int color);
101 
102     /**
103      * Sets the color palette for the clock face.
104      * @param supportsDarkText Whether dark text can be displayed.
105      * @param colors Colors that should be used on the clock face, ordered from darker to lighter.
106      */
setColorPalette(boolean supportsDarkText, int[] colors)107     default void setColorPalette(boolean supportsDarkText, int[] colors) {}
108 
109     /**
110      * Set the amount (ratio) that the device has transitioned to doze.
111      * @param darkAmount Amount of transition to doze: 1f for doze and 0f for awake.
112      */
setDarkAmount(float darkAmount)113     default void setDarkAmount(float darkAmount) {}
114 
115     /**
116      * Notifies that time tick alarm from doze service fired.
117      *
118      * Implement this method instead of registering a broadcast listener for TIME_TICK.
119      */
onTimeTick()120     default void onTimeTick() {}
121 
122     /**
123      * Notifies that the time zone has changed.
124      *
125      * Implement this method instead of registering a broadcast listener for TIME_ZONE_CHANGED.
126      */
onTimeZoneChanged(TimeZone timeZone)127     default void onTimeZoneChanged(TimeZone timeZone) {}
128 
129     /**
130      * Indicates whether the keyguard status area (date) should be shown below
131      * the clock.
132      */
shouldShowStatusArea()133     default boolean shouldShowStatusArea() {
134         return true;
135     }
136 }
137