summaryrefslogtreecommitdiffstats
path: root/src/com/android/launcher/home/Home.java
blob: e6fedc8db104c110bb5a1ac42788aeff47b40b58 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
/*
 * Copyright (C) 2014 The CyanogenMod Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.android.launcher.home;

import android.content.Context;
import android.view.View;
import android.view.ViewGroup.LayoutParams;

/**
 * The generic contract that should supports a <code>Home</code> app to could
 * be invoked and registered by an Android launcher.<br/>
 * <br/>
 * This interface contains the version 1 of the <code>Home Host App</code> protocol.<br/>
 * <br/>
 * <br/>
 * A <code>Home</code> app should:
 * <ul>
 *  <li>
 *    should have at least a constructor with no arguments
 *  </li>
 *  <li>
 *    declares inside its manifest a <code>com.android.launcher.home</code> metadata with the
 *    full qualified that contains this interface<br/>
 *    <pre>
 *    &lt;meta-data android:name="com.android.launcher.home" value="org.cyanogenmod.launcher.home.HomeStub"/&gt;
 *    </pre>
 *  </li>
 *  <li>
 *    define the "com.android.launcher.home.permissions.HOME_APP" permission<br/>
 *    <pre>
 *    &lt;uses-permission android:name="com.android.launcher.home.permissions.HOME_APP"/&gt;
 *    </pre>
 *  </li>
 *  <li>
 *    implements the contract defined by this protocol.
 *  </li>
 * </ul>
 * <br/>
 * Implementors classes of this protocol should be aware that all the {@link Context} references
 * passed to this class owns to the host launcher app. This means that you cannot access
 * to settings defined by the <code>Home</code> app inside its shared context.
 */
public interface Home {

    /**
     * A SHA-1 hash of all declared method of this interface. Home apps should compute as:<br/>
     * <br/>
     * <pre>
     *   for method in Home.class.getDeclaredMehod
     *      sha1.update method.toString.bytes
     * </pre><br/>
     * DO NOT MODIFY!
     */
    public static final String SIGNATURE = "sZFp8JclUBYdIw0QaJZDosZ8SWM=";

    /**
     * Defines the name of the metadata used to declared the full qualified Home stub class
     * that implements this protocol.
     */
    public static final String METADATA_HOME_STUB = "com.android.launcher.home";

    /**
     * Defines the name of the permission that the Home app should explicitly declare.
     */
    public static final String PERMISSION_HOME_APP = "com.android.launcher.home.permissions.HOME_APP";

    // Notification flags
    public static final int FLAG_NOTIFY_MASK = 0x0000;
    public static final int FLAG_NOTIFY_ON_RESUME = FLAG_NOTIFY_MASK + 0x0002;
    public static final int FLAG_NOTIFY_ON_PAUSE = FLAG_NOTIFY_MASK +  0x0004;
    public static final int FLAG_NOTIFY_ON_SHOW = FLAG_NOTIFY_MASK + 0x0008;
    public static final int FLAG_NOTIFY_ON_SCROLL_PROGRESS_CHANGED = FLAG_NOTIFY_MASK + 0x0010;
    public static final int FLAG_NOTIFY_ON_HIDE = FLAG_NOTIFY_MASK + 0x0020;
    public static final int FLAG_NOTIFY_ALL = FLAG_NOTIFY_ON_RESUME | FLAG_NOTIFY_ON_PAUSE |
            FLAG_NOTIFY_ON_SHOW | FLAG_NOTIFY_ON_SCROLL_PROGRESS_CHANGED | FLAG_NOTIFY_ON_HIDE;

    // Operation support flags
    public static final int FLAG_OP_MASK = 0x1000;
    public static final int FLAG_OP_CUSTOM_SEARCH = FLAG_OP_MASK + 0x0002;
    public static final int FLAG_OP_ALL = FLAG_OP_CUSTOM_SEARCH;

    // Search modes
    public static final int MODE_SEARCH_TEXT = 0x0000;
    public static final int MODE_SEARCH_VOICE = 0x0001;

    /**
     * Invoked when creating the Home object to set
     * a reference to the host Activity that will
     * contain this instance.
     * @param context The Activity Context of the host activity.
     */
    void setHostActivityContext(Context context);

    /**
     * Invoked the first time the <code>Home</code> app is created.<br/>
     * This method should be used by implementors classes of this protocol to load the needed
     * resources.
     * @param context the current {@link Context} of the host launcher.
     */
    void onStart(Context context);

    /**
     * Load and show the content of this home app if true,
     * hide and remove providers if false.
     * @param showContent Should content be shown
     */
    void setShowContent(boolean showContent);

    /**
     * Invoked when the <code>Home</code> app should be destroy.<br/>
     * This method should be used by implementors classes of this protocol to unload all unneeded
     * resources.
     * @param context the current {@link Context} of the host launcher.
     */
    void onDestroy(Context context);

    /**
     * Invoked when the host launcher enters in resume mode.
     * @param context the current {@link Context} of the host launcher.
     */
    void onResume(Context context);

    /**
     * Invoked when the host launcher enters in pause mode.
     * @param context the current {@link Context} of the host launcher.
     */
    void onPause(Context context);

    /**
     * Invoked when the custom content page is totally displayed.
     * @param context the current {@link Context} of the host launcher.
     */
    void onShow(Context context);

    /**
     * Invoked when the custom content page is scrolled.
     * @param context the current {@link Context} of the host launcher.
     * @param progress the current scroll progress.
     */
    void onScrollProgressChanged(Context context, float progress);

    /**
     * Invoked when the custom content page is totally hidden.
     * @param context the current {@link Context} of the host launcher.
     */
    void onHide(Context context);

    /**
     * Invoked by the host launcher to request an invalidation of the ui elements and data used by
     * the <code>Home</code> implementation class.
     * @param context the current {@link Context} of the host launcher.
     */
    void onInvalidate(Context context);

    /**
     * Invoked when the host launcher request enter in search mode.
     * @param context the current {@link Context} of the host launcher.
     * @param mode the requested search mode. Must be one of:
     * <ul>
     * <li>{@link #MODE_SEARCH_TEXT}: Textual mode</li>
     * <li>{@link #MODE_SEARCH_VOICE}: Voice mode</li>
     * </ul>
     */
    void onRequestSearch(Context context, int mode);

    /**
     * Returns an instance of a {@link View} that holds the custom content to be displayed
     * by this <code>Home</code> app.
     * @param context the current {@link Context} of the host launcher.
     * @return View The custom content view that will be enclosed inside a
     * <code>com.android.launcher3.Launcher.QSBScroller</code>.<br/>
     * Be aware the the height layout of the returned should be defined as
     * {link {@link LayoutParams#WRAP_CONTENT}, so the view could be scrolled inside the
     * custom content page.
     */
    View createCustomView(Context context);

    /**
     * Returns the name of the Home app (LIMIT: 30 characters).
     * @param context the current {@link Context} of the host launcher.
     */
    String getName(Context context);

    /**
     * Implementations should return the combination of notification flags that want to listen to.
     * @see #FLAG_NOTIFY_ON_RESUME
     * @see #FLAG_NOTIFY_ON_PAUSE
     * @see #FLAG_NOTIFY_ON_SHOW
     * @see #FLAG_NOTIFY_ON_SCROLL_PROGRESS_CHANGED
     * @see #FLAG_NOTIFY_ON_HIDE
     * @see #FLAG_NOTIFY_ALL
     */
    int getNotificationFlags();

    /**
     * Implementations should return the combination of operation flags that want they want
     * to support to.
     * @see #FLAG_OP_CUSTOM_SEARCH
     * @see #FLAG_OP_ALL
     */
    int getOperationFlags();
}