/*
* 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 Home
app to could
* be invoked and registered by an Android launcher.
*
* This interface contains the version 1 of the Home Host App
protocol.
*
*
* A Home
app should:
*
*
* 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 Home
app inside its shared context.
*/
public interface Home {
/**
* A SHA-1 hash of all declared method of this interface. Home apps should compute as:
*
*
* for method in Home.class.getDeclaredMehod
* sha1.update method.toString.bytes
*
* 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 Home
app is created.
* 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 Home
app should be destroy.
* 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 Home
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:
*
* - {@link #MODE_SEARCH_TEXT}: Textual mode
* - {@link #MODE_SEARCH_VOICE}: Voice mode
*
*/
void onRequestSearch(Context context, int mode);
/**
* Returns an instance of a {@link View} that holds the custom content to be displayed
* by this Home
app.
* @param context the current {@link Context} of the host launcher.
* @return View The custom content view that will be enclosed inside a
* com.android.launcher3.Launcher.QSBScroller
.
* 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();
}