JarCastingAndroid Notification Library
A notification library for Android applications.
By using this library, you can easily manage your notifications.
- send remote/global notification when application is in background.
- send local/global notification when application is in foreground.
- register a
NotificationListenerfor updating the badge number of notification count. - display a
NotificationBoardwith a list of current notifications. - ...
Overview
There are 3 major components:
- Notification Local (managing in-layout notifications)
- Notification Global (managing floating notifications)
- Notification Remote (managing status-bar notifications)
and 2 minor components:
- Notification Board (holding a notification list)
- Notification Effect (managing ringtone, vibration, ...)
Each notification can have its own layout and background. If not specified, the default layout and background will be used.
If a notification is sent to more than one component, its status is synchronized between those components. Thus, canceling a notification in one component will trigger the cancel event in other components.
Demo
Sample code is also available in this repository.
Notification Local
Notification Global
Notification Board
Notification Remote
Programming Guide
Compatibility
- minSdkVersion: 11
Gradle
Android-Notification library is pushed to Maven Central as a AAR, so you just need to declare the following dependency to your build.gradle.
dependencies {
compile 'com.github.lamydev:android-notification:3.0'
}
Initialization
You need to tell NotificationDelegater the major components you want to use.
NotificationDelegater.initialize(context, components);
Available components:
- NotificationDelegater.LOCAL
- NotificationDelegater.GLOBAL
- NotificationDelegater.REMOTE
Once it has been inited, you can enable/disable a component at runtime.
For example, to disable the local notification:
NotificationLocal local = NotificationDelegater.getInstance().local();
local.setEnabled(false);
Notification Local (in-layout notifications)
You need to add NotificationView to your layout.
Otherwise, nothing will be presented if you try to send a local notification.
<zemin.notification.NotificationView
android:id="@+id/nv"
android:layout_width="match_parent"
android:layout_height="wrap_content"/>
Then attach it to NotificationLocal.
NotificationLocal local = NotificationDelegater.getInstance().local();
NotificationView view = (NotificationView) findViewById(R.id.nv);
local.setView(view);
To send a local notification:
NotificationBuilder.V1 builder = NotificationBuilder.local()
.setIconDrawable(icon)
.setTitle(title)
.setText(text);
NotificationDelegater delegater = NotificationDelegater.getInstance();
delegater.send(builder.getNotification());
Customization
- Refer to the JavaDoc of
NotificationView. - Refer to the JavaDoc of
NotificationGlobal. - Implement
NotificationViewCallbackorNotificationLocal#ViewCallback. Pass an instance toNotificationView#setCallback(NotificationViewCallback cb).
Notification Global (floating notifications)
For global notification, you don't need to attach any NotificationView. Instead, it will do that for you.
Once it has been fired, it is displayed on top of any screen and remains visible for its specified duration, regardless of the visibility of you application's main screen.
By default, all features are disabled. You need to manually enable them.
NotificationGlobal global = NotificationDelegater.getInstance().global();
global.setViewEnabled(true);
To send a global notification:
NotificationBuilder.V1 builder = NotificationBuilder.global()
.setIconDrawable(icon)
.setTitle(title)
.setText(text);
NotificationDelegater delegater = NotificationDelegater.getInstance();
delegater.send(builder.getNotification());
Customization
- Refer to the JavaDoc of
NotificationView. - Refer to the JavaDoc of
NotificationGlobal. - Implement
NotificationViewCallbackorNotificationGlobal#ViewCallback. Pass an instance toNotificationView#setCallback(NotificationViewCallback cb).
Notification Board (notification list)
A notification board shows a list of currently delivered notifications.
Initially, the board is hidden. You can open it by:
- invoking method:
NotificationBoard#open(boolean anim) - user gesture: touches inside a rectangular area on the screen and performs a scroll down action.
By default, user gesture is not supported since the touch area is not defined.
To specify a touch area, you can call NotificationBoard#setInitialTouchArea(int l, int t, int r, int b).
Floating board
It is managed by the NotificationGlobal, so the board feature needs to be enabled before you can use it.
NotificationGlobal global = NotificationDelegater.getInstance().global();
global.setBoardEnabled(true);
In this case, the initial touch area is automatically set by NotificationRootView.
- if
NotificationViewis displayed, the initial touch area of the board would be the same as the view's dimension. - if
NotificationViewis not displayed, the initial touch area would be reset to 0.
Thus, the board can be opened only when the NotificationView is displayed, and the user scrolls it down.
In-layout board
You just need to simply add NotificationBoard to your layout.... without attaching it to any notification handler, such as NotificationLocal, NotificationGlobal.
<zemin.notification.NotificationBoard
android:id="@+id/board"
android:layout_width="match_parent"
android:layout_height="wrap_content"/>
Customization
- Refer to the JavaDoc of
NotificationBoard. - Implement
NotificationBoardCallback. Pass an instance toNotificationBoard#setCallback(NotificationBoardCallback cb).
Notification Remote (status-bar notifications)
This is eventually a StatusBar Notification.
NotificationBuilder.V2 builder = NotificationBuilder.remote()
.setSmallIconResource(icon)
.setTicker(tickerText)
.setTitle(title)
.setText(text);
NotificationDelegater delegater = NotificationDelegater.getInstance();
delegater.send(builder.getNotification());
Customization
- Refer to the JavaDoc of
NotificationRemote. - Implement
NotificationRemoteCallback. Pass an instance toNotificationRemote#setCallback.
Notification Listener
Implement this interface to listen to overall Notification status.
By default, all notifications will be delivered to all listeners.
Here's an example.
If you have a badge showing notification count, you may need register a NotificationListener to help keep it up-to-date.
public class MainActivity extends Activity {
@Override
protected void onResume() {
super.onResume();
NotificationDelegater.getInstance().addListener(mListener);
}
@Override
protected void onPause() {
super.onPause();
NotificationDelegater.getInstance().removeListener(mListener);
}
private final NotificationListener mListener = new NotificationListener() {
@Override
public void onArrival(NotificationEntry entry) {
updateNotificationCount();
}
@Override
public void onCancel(NotificationEntry entry) {
updateNotificationCount();
}
}
private void updateNotificationCount() {
final int count = NotificationDelegater.getInstance().getNotificationCount();
// do something ...
}
}
Notification Effect
By default, notification effect is disabled for all components.
To enable it for a specific component, for example, for global notification:
NotificationGlobal global = NotificationDelegater.getInstance().global();
global.enableEffect(true);
Then you can play a ringtone when sending a global notification:
NotificationBuilder.V1 builder = NotificationBuilder.global()
.setIconDrawable(icon)
.setTitle(title)
.setText(text)
.setPlayRingtone(true)
.setRingtone(context, resId);
NotificationDelegater delegater = NotificationDelegater.getInstance();
delegater.send(builder.getNotification());
Developers
- Zemin Liu ([email protected])
Any questions, contributions, bug fixes, and patches are welcomed. ^_^
License
Copyright (C) 2015 Zemin Liu
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.