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