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.settings.slices;
18 
19 import static android.content.Context.CLIPBOARD_SERVICE;
20 
21 import android.content.ClipData;
22 import android.content.ClipboardManager;
23 import android.content.Context;
24 import android.content.IntentFilter;
25 import android.net.Uri;
26 import android.widget.Toast;
27 
28 import androidx.annotation.StringRes;
29 import androidx.slice.Slice;
30 
31 import com.android.settings.R;
32 
33 /**
34  * A collection of API making a PreferenceController "sliceable"
35  */
36 public interface Sliceable {
37     /**
38      * @return an {@link IntentFilter} that includes all broadcasts which can affect the state of
39      * this Setting.
40      */
getIntentFilter()41     default IntentFilter getIntentFilter() {
42         return null;
43     }
44 
45     /**
46      * Determines if the controller should be used as a Slice.
47      * <p>
48      * Important criteria for a Slice are:
49      * - Must be secure
50      * - Must not be a privacy leak
51      * - Must be understandable as a stand-alone Setting.
52      * <p>
53      * This does not guarantee the setting is available.
54      * <p>
55      * {@link #getSliceHighlightMenuRes} should also be overridden when returning true.
56      *
57      * @return {@code true} if the controller should be used as a Slice.
58      */
isSliceable()59     default boolean isSliceable() {
60         return false;
61     }
62 
63     /**
64      * Determines if the {@link Slice} should be public to other apps.
65      * This does not guarantee the setting is available.
66      *
67      * @return {@code true} if the controller should be used as a Slice, and is
68      * publicly visible to other apps.
69      */
isPublicSlice()70     default boolean isPublicSlice() {
71         return false;
72     }
73 
74     /**
75      * Returns uri for this slice (if it's a slice).
76      */
getSliceUri()77     default Uri getSliceUri() {
78         return null;
79     }
80 
81     /**
82      * @return {@code true} if the setting update asynchronously.
83      * <p>
84      * For example, a Wifi controller would return true, because it needs to update the radio
85      * and wait for it to turn on.
86      */
hasAsyncUpdate()87     default boolean hasAsyncUpdate() {
88         return false;
89     }
90 
91     /**
92      * Copy the key slice information to the clipboard.
93      * It is highly recommended to show the toast to notify users when implemented this function.
94      */
copy()95     default void copy() {
96     }
97 
98     /**
99      * Whether or not it's a copyable slice.
100      */
isCopyableSlice()101     default boolean isCopyableSlice() {
102         return false;
103     }
104 
105     /**
106      * Whether or not summary comes from something dynamic (ie, not hardcoded in xml)
107      */
useDynamicSliceSummary()108     default boolean useDynamicSliceSummary() {
109         return false;
110     }
111 
112     /**
113      * Set the copy content to the clipboard and show the toast.
114      */
setCopyContent(Context context, CharSequence copyContent, CharSequence messageTitle)115     static void setCopyContent(Context context, CharSequence copyContent,
116             CharSequence messageTitle) {
117         final ClipboardManager clipboard = (ClipboardManager) context.getSystemService(
118                 CLIPBOARD_SERVICE);
119         final ClipData clip = ClipData.newPlainText("text", copyContent);
120         clipboard.setPrimaryClip(clip);
121 
122         final String toast = context.getString(R.string.copyable_slice_toast, messageTitle);
123         Toast.makeText(context, toast, Toast.LENGTH_SHORT).show();
124     }
125 
126     /**
127      * Settings Slices which require background work, such as updating lists should implement a
128      * {@link SliceBackgroundWorker} and return it here. An example of background work is updating
129      * a list of Wifi networks available in the area.
130      *
131      * @return a {@link Class<? extends SliceBackgroundWorker>} to perform background work for the
132      * slice.
133      */
getBackgroundWorkerClass()134     default Class<? extends SliceBackgroundWorker> getBackgroundWorkerClass() {
135         return null;
136     }
137 
138     /**
139      * Used to mark a {@link Sliceable} that has no highlight menu string resource.
140      */
141     int NO_RES = 0;
142 
143     /**
144      * @return a string resource declared in res/values/menu_keys.xml that indicates which menu
145      * entry should be highlighted in two-pane mode, or {@link #NO_RES} representing highlighting is
146      * not applicable.
147      */
getSliceHighlightMenuRes()148     @StringRes default int getSliceHighlightMenuRes() {
149         return NO_RES;
150     }
151 }
152