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      * Whether or not summary comes from something dynamic (ie, not hardcoded in xml)
93      */
useDynamicSliceSummary()94     default boolean useDynamicSliceSummary() {
95         return false;
96     }
97 
98     /**
99      * Set the copy content to the clipboard and show the toast.
100      */
setCopyContent(Context context, CharSequence copyContent, CharSequence messageTitle)101     static void setCopyContent(Context context, CharSequence copyContent,
102             CharSequence messageTitle) {
103         final ClipboardManager clipboard = (ClipboardManager) context.getSystemService(
104                 CLIPBOARD_SERVICE);
105         final ClipData clip = ClipData.newPlainText("text", copyContent);
106         clipboard.setPrimaryClip(clip);
107 
108         final String toast = context.getString(R.string.copyable_slice_toast, messageTitle);
109         Toast.makeText(context, toast, Toast.LENGTH_SHORT).show();
110     }
111 
112     /**
113      * Settings Slices which require background work, such as updating lists should implement a
114      * {@link SliceBackgroundWorker} and return it here. An example of background work is updating
115      * a list of Wifi networks available in the area.
116      *
117      * @return a {@link Class<? extends SliceBackgroundWorker>} to perform background work for the
118      * slice.
119      */
getBackgroundWorkerClass()120     default Class<? extends SliceBackgroundWorker> getBackgroundWorkerClass() {
121         return null;
122     }
123 
124     /**
125      * Used to mark a {@link Sliceable} that has no highlight menu string resource.
126      */
127     int NO_RES = 0;
128 
129     /**
130      * @return a string resource declared in res/values/menu_keys.xml that indicates which menu
131      * entry should be highlighted in two-pane mode, or {@link #NO_RES} representing highlighting is
132      * not applicable.
133      */
getSliceHighlightMenuRes()134     @StringRes default int getSliceHighlightMenuRes() {
135         return NO_RES;
136     }
137 }
138