1 /*
2  * Copyright (C) 2019 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.android.systemui.plugins;
18 
19 import android.annotation.Nullable;
20 import android.app.PendingIntent;
21 import android.graphics.drawable.Drawable;
22 import android.view.View;
23 
24 import com.android.systemui.plugins.annotations.DependsOn;
25 import com.android.systemui.plugins.annotations.ProvidesInterface;
26 
27 /**
28  * Plugin which provides a "Panel" {@link View} to be rendered inside of the GlobalActions menu.
29  *
30  * Implementations should construct a new {@link PanelViewController} with the given
31  * {@link Callbacks} instance inside of {@link #onPanelShown(Callbacks, boolean)}, and should not
32  * hold onto a reference, instead allowing Global Actions to manage the lifetime of the object.
33  *
34  * Under this assumption, {@link PanelViewController} represents the lifetime of a single invocation
35  * of the Global Actions menu. The {@link View} for the Panel is generated when the
36  * {@link PanelViewController} is constructed, and {@link PanelViewController#getPanelContent()}
37  * serves as a simple getter. When Global Actions is dismissed,
38  * {@link PanelViewController#onDismissed()} can be used to cleanup any resources allocated when
39  * constructed. Global Actions will then release the reference, and the {@link PanelViewController}
40  * will be garbage-collected.
41  */
42 @ProvidesInterface(
43         action = GlobalActionsPanelPlugin.ACTION, version = GlobalActionsPanelPlugin.VERSION)
44 @DependsOn(target = GlobalActionsPanelPlugin.Callbacks.class)
45 @DependsOn(target = GlobalActionsPanelPlugin.PanelViewController.class)
46 public interface GlobalActionsPanelPlugin extends Plugin {
47     String ACTION = "com.android.systemui.action.PLUGIN_GLOBAL_ACTIONS_PANEL";
48     int VERSION = 0;
49 
50     /**
51      * Invoked when the GlobalActions menu is shown.
52      *
53      * @param callbacks {@link Callbacks} instance that can be used by the Panel to interact with
54      *                  the Global Actions menu.
55      * @param deviceLocked Indicates whether or not the device is currently locked.
56      * @return A {@link PanelViewController} instance used to receive Global Actions events.
57      */
onPanelShown(Callbacks callbacks, boolean deviceLocked)58     PanelViewController onPanelShown(Callbacks callbacks, boolean deviceLocked);
59 
60     /**
61      * Provides methods to interact with the Global Actions menu.
62      */
63     @ProvidesInterface(version = Callbacks.VERSION)
64     interface Callbacks {
65         int VERSION = 0;
66 
67         /** Dismisses the Global Actions menu. */
dismissGlobalActionsMenu()68         void dismissGlobalActionsMenu();
69 
70         /** Starts a PendingIntent, dismissing the keyguard if necessary. */
startPendingIntentDismissingKeyguard(PendingIntent pendingIntent)71         default void startPendingIntentDismissingKeyguard(PendingIntent pendingIntent) {
72             try {
73                 pendingIntent.send();
74             } catch (PendingIntent.CanceledException e) {
75                 // no-op
76             }
77         }
78     }
79 
80     /**
81      * Receives Global Actions events, and provides the Panel {@link View}.
82      */
83     @ProvidesInterface(version = PanelViewController.VERSION)
84     interface PanelViewController {
85         int VERSION = 0;
86 
87         /**
88          * Returns the {@link View} for the Panel to be rendered in Global Actions. This View can be
89          * any size, and will be rendered above the Global Actions menu when z-ordered.
90          */
getPanelContent()91         View getPanelContent();
92 
93         /**
94          * Invoked when the Global Actions menu (containing the View returned from
95          * {@link #getPanelContent()}) is dismissed.
96          */
onDismissed()97         void onDismissed();
98 
99         /**
100          * Invoked when the device is either locked or unlocked.
101          */
onDeviceLockStateChanged(boolean locked)102         void onDeviceLockStateChanged(boolean locked);
103 
104         /**
105          * Optionally returns a drawable to be used as the background for Global Actions.
106          */
107         @Nullable
getBackgroundDrawable()108         default Drawable getBackgroundDrawable() {
109             return null;
110         }
111     }
112 }
113