B4A Library Notification Builder Library.

barx

Well-Known Member
Licensed User
Notification Builder Library. Now With JellyBean style expanding notifications

Now we can make 'JellyBean Style' expanding Notifications.
That's right, this is the long awaited library that allows users to include expanding notifications in their Basic4Android apps. Check out the demo app, it shows you how easy the library is to use.

screen1.jpgscreen2.jpgscreen3.jpgscreen4.jpgscreen5.jpgscreen7.jpg

What is it?
This library uses the new NotificationCompat.Builder which is part of googles support library v4.

Why?
All previous notification objects (b4a's built in and both my previous libraries) use a, now, old standard notification object; And while it still works, new features are not supported. Also the 'number' stamp breaks on new versions of Android (HoneyComb+) why? Google changed their ways, now, instead of showing the number on the status bar icon, it is shown in the notification itself. Also, these newer versions support additional features like progress bars without custom layouts, a 3rd text element named Sub Text, a small text area that can replace the Number (Info Text). We can also hide the Time Stamp or even use it as a chronometer (JellyBean+). Check out the documentation below for a full list of currently supported features.

How?
Download the library files below and copy the .jar and .xml to your additional library folder as usual. Also make sure you have a copy of the v4 support jar in there too. This can be found in your Android SDK installation under '..\Android\sdk\extras\android\support\v4\'.
If this doesn't exist, you need to open the Android SDK manager and install the 'Android Support Library' found under the 'Extras' section.

I have also created a demo app that shows off some of the features and generates the code to show you how to use it. Attached below AND uploaded to Google Play store. The app also outputs the code to the B4A log when connected.

The Gesture - Expanding notifications are a new thing to us all and so many won't know how to show them. When you open your notification drawer, if your notification isn't the first on the list it won't be expanded. To expand you need to use a gesture. Place 2 fingers on the notification and swipe open (sideways). Also, I believe this gesture changes in Android 4.2 to a more intuitive swipe down. (This is now confirmed, but the original gesture still works too)

Change Log

Version 3 (Wear Device Support)
Notification Builder Class additional methods -
Group, GroupSummary, LocalOnly, SortKey, Extend.
NotificationCustomLayout Class additional method -
setEnableClickEvent
New Class - NotificationWearExtender
New Class - NotificationRemoteInput

Version 2.31

Added method - DeleteService

Version 2.3

Added - Class - NotificationCustomLayout
Added - CustomLayout

Version 2.2
Fixed - Tags returning the wrong value or no value at all.
Added - GetNotification method - returns the notification object so it can be passed to things like foreground services

Version 2.1:
Fixed - When using .setParentActivity(). The Tag is now accessible in both the Parent Activity AND the Called Activity.
Fixed - Action Tag setting (was always setting to the Action Title)

Version 2.01 (Not Tested yet, Feel free to test and report):
Possible fix for - No access to Tag when setting ParentAcivity

Version 2:
Added method - setStyle.
Added methods - AddAction, AddAction2
Added style classes - InboxStyle, BigTextStyle, BigPictureStyle
Fixed a few typos in documentation

NotificationBuilder
Author:
BarxDroid
Version: 3
  • NotificationBigPictureStyle
    Methods:
    • Initialize
      Helper class for generating large-format notifications that include a large image attachment.
      If the platform does not provide large-format notifications, this method has no effect
    • BigContentTitle As String [write only]
      Overrides the ContentTitle set in the Notification Builder.
    • BigPicture As Bitmap [write only]
      Provides the Big Picture to be used in the BigPicture notification.
    • SummaryText As String [write only]
      Sets the first line of text after the details section
  • NotificationBigTextStyle
    Methods:
    • Initialize
      Helper class for generating large-format notifications that include a lot of text.
      If the platform does not provide large-format notifications, this method has no effect
    • BigContentTitle As String [write only]
      Overrides the ContentTitle set in the Notification Builder.
    • BigText As String [write only]
      Provides the longer text to displayed in the content area. Replaces ContextText.
    • SummaryText As String [write only]
      Sets the first line of text after the details section
  • NotificationBuilder
    Methods:
    • AddAction (icon As String, title As String, tag As String, Activity As Object)
      Adds an Action to the notification.
      Actions are buttons displayed on the notification that can allow users to do something without starting the app. e.g Call back a missed call, pause a sound track, etc

      The icon file should manually copied to the Objects\res\drawable\ folder and set to read-only.
      The file name is case sensitive and should not contain the file extension.
      If tag is set to "" then it will default to the passed title.
      tags are named 'Notification_Action_Tag'
      Use AddAction2 to pass a Service module instead of an Activity.
      MAXIMUM of 3 Actions can be added to each notification.
      API 16+
    • AddAction2 (icon As String, title As String, tag As String, Service As Object)
      Similar to AddAction, but you pass a Service Module rather than an Activity Module.
    • Cancel (id As Int)
      Cancels the notification with the given id
    • Extend (NotificationWearableExtender As Extender)
      Applies an Extender to the Notification.
      i.e NotificationWearableExtender is used to extend the notification with functions only available to Wearable devices.
    • GetNotification As Notification
      Gets the Notification Object. Useful for things like Foreground Services
    • Initialize
    • Notify (id As Int)
      Displays the notification.
      id - The notification id. This id can be used later to update the notification (by calling Notify again with the same id),
      or to cancel the notification
    • SetStyle (style As Style)
      Add an extended style to the notification.
      Must be passed a style object:-
      NotificationInboxStyle
      NotificationBigTextStyle
      NotificationBigPictureStyle
      API 16+
    • setActivity (Activity As Object)
      Sets the activity that will be launched when the Notification is tapped.
      Use <code>nb.Intent</code> to use your own calling intent
    • setCustomLight (argb As Int, onMs As Int, offMs As Int)
      Sets a custom argb value for the notification light, also sets the rates at which it flashes.
      argb - The color that the devices led will flash.
      onMs - The time in milliseconds that the led will stay on each blink.
      offMs - The time in millliseconds that the led will be off after each blink.
      NOTE: Not all devices will honour these settings, it is dependent on hardware abilities.
    • setDeleteActivity (Activity As Object)
      Experimental - Setting a DeleteActivity will (should) show the activity when the user clears the notification manually.
      API 11+
    • setDeleteService (Service As Object)
      Experimental - Setting a DeleteService will (should) show the service when the user clears the notification manually.
      A{PI 11+
    • setIntent (intent As Intent)
      Sets the Intent that will be called when the Notification is tapped.
      Use <code>nb.Activity</code> to call an activity in your project.
    • setParentActivity (Activity As Object)
      Sets a Parent Activity to add to the 'Back Stack'. If this method is used then once you have entered
      an Activity from your notification, pressing back will return to the Parent Activity, rather than exiting the App.
      API 11+
    • setProgress (Max As Int, Progress As Int, Indeterminate As Boolean)
      Sets the progress the notification represents. This may be shown as a progress bar dependent on SDK version.
      API 14+
    • setSmallIcon2 (Icon As String, Level As Int)
      Similar to .SmallIcon but takes a 'Level' parameter for when a LevelListDrawable is used.
    Permissions:
    • android.permission.VIBRATE
    Properties:
    • AutoCancel As Boolean [write only]
      Sets whether the notification will be cancelled automatically when the user taps it.
    • ContentInfo As String [write only]
      Sets the text in the right-hand side of the notification.
    • ContentText As String [write only]
      Set the text in the Text field.
    • ContentTitle As String [write only]
      Sets the text in the Title field.
    • CustomLayout As RemoteViews [write only]
      Sets a custom layout for the notification.
      Pass a NotificationCustomLayout object.
      API 11+
    • CustomSound As String [write only]
      Sets a custom sound to be played on new notification
      Example:
      <code>cn.CustomSound = "file:///sdcard/notification/ringer.mp3"</code>
    • CustomVibrate() As Long [write only]
      Sets a custom vibrate pattern for new notification
      The Array of values can be as long as you wish.
      The first Value is the pause before vibration starts, then its ON, OFF, ON, OFF,........
      Example:
      <code>
      Dim nb as NotificationBuilder
      Dim v() as Long
      v = Array as Long(0, 100, 200, 300, 400)
      nb.CustomVibrate(v)
      </code>
    • DefaultLight As Boolean [write only]
      Sets whether the notification will show a light.
      Setting to True will over ride any custom light settings.
      Example:
      <code>nb.DefaultLight = True</code>
    • DefaultSound As Boolean [write only]
      Sets whether the notification will play a sound.
      Note: Setting to True will over ride any custom sound set.
      Example:
      <code>nb.DefaultSound = False</code>
    • DefaultVibrate As Boolean [write only]
      Sets whether the notification will vibrate the device.
      Note: Setting to True will over ride any custom vibration settings.
      Example:
      <code>nb.Vibrate = True</code>
    • Group As String [write only]
      Set this notification to be part of a group of notifications sharing the same key.
      Grouped notifications may display in a cluster or stack on devices which support such rendering.
      To make this notification the summary for its group, also call
      <code>nb.GroupSummary = True</code>
      A sort order can be specified by using
      <code>nb.SortKey(Key)</code>
    • GroupSummary As Boolean [write only]
      Set this notification to be the group summary for a group of notifications.
      Grouped notifications may display in a cluster or stack on devices which support such rendering.
      The GroupSummary notification will not show on the notification stack on Wearables, but will show as the only notification on handheld devices.
      See URL https://developer.android.com/training/wearables/notifications/stacks.html
      Requires a group key also be set using
      <code>nb.Group(GroupKey)</code>
    • LargeIcon As Bitmap [write only]
      Add a large icon to the notification (and the ticker on some devices).
      In the platform template, this image will be shown on the left of the notification view in place of the small icon (which will move to the right side).
    • LocalOnly As Boolean [write only]
      Sets whether or not this notification is only relevant to the current device.
      Some notifications can be bridged to other devices for remote display. I.E Wear Devices
    • Number As Int
      Gets or Sets the number to be shown on the notification.
      This is useful to represent multiple events in a single notification.
    • OnGoingEvent As Boolean [write only]
      Sets whether the notification is an 'ongoing event'.
      The notification will be shown in the ongoing section and will not be cleared.
    • OnlyAlertOnce As Boolean [write only]
      Sets whether the notification will only play sound / vibrate /show light if the notification is not already showing.
    • Priority As Int [write only]
      Experimental - Googles' notes:-
      'Set the relative priority for this notification.
      Priority is an indication of how much of the user's valuable attention should be consumed by this notification.
      Low-priority notifications may be hidden from the user in certain situations, while the user might be interrupted for a higher-priority notification.
      The system sets a notification's priority based on various factors including the setPriority value.
      The effect may differ slightly on different platforms.'
      API 16+
    • ShowTime As Boolean [write only]
      Sets whether the time stamp (known as 'When' in Google documentation) is shown on the notification.
      Default is 'true'
    • SmallIcon As String [write only]
      Sets the Small Icon to be displayed.
      The image file should manually copied to the Objects\res\drawable\ folder and set to read-only.
      The file name is case sensitive and should not contain the file extension.
      You can use "icon" to use the applications icon.
    • SortKey As String [write only]
      Set a sort key that orders this notification among other notifications from the same package.
      This can be useful if an external sort was already applied and an app would like to preserve this.
      Notifications will be sorted lexicographically using this value.
      This sort key can also be used to order members of a notification group.
    • SubText As String [write only]
      Set the third line of text in the platform notification template.
      Don't use if you're also using setProgress(); they occupy the same location in the standard template.
      If the platform does not provide large-format notifications, this method has no effect. The third line of text only appears in expanded view.
      API 16+
    • Tag As String [write only]
      The Tag is a string that can be extracted later on Activity_Resume.
      This can be used to determine which notification has been clicked by the user when multiple notifications exist.
      Example of extracting the Tag:
      <code>
      Sub Activity_Resume
      Dim in as Intent
      Dim intentExtra as String

      in = Activity.GetStartingIntent
      If in.HasExtra("Notification_Tag") Then
      intentExtra = in.GetExtra("Notification_Tag")
      End If
      End Sub
      </code>
    • Ticker As String [write only]
      Sets the Ticker Text which shows along side the status bar icon of new Notifications.
    • UsesChrono As Boolean [write only]
      If set the timestamp place on the notification will be used as a stopwatch. It will automatically update the minutes and seconds since .When()
      API 16+
    • When As Long [write only]
      Sets the time stamp that shows on the notification. This should indicate the time the event occurred.
      Default is the current time.
      Setting to 0 will reset to current time.
  • NotificationCustomLayout
    Fields:
    • EXPANDED_HEIGHT As Int
    • NORMAL_HEIGHT As Int
    Methods:
    • BuildLayout As RemoteViews
      Returns the CustomLayout object
    • Initialize (LayoutFile As String)
      Initilizes the Object
      LayoutFile - The name of the .xml file containing the layout (do not add '.xml')
    • Initialize2 (Panel As String)
      !!! NOT WORKING !!!
      Initializes the object, using a Panel of views for the layout
    • SetImage (Image As String, Bitmap As Bitmap)
      Sets an image within a custom layout
      Image - The name of the image element as defined in the xml layout
      Bitmap - The image to apply
    • SetProgress (ProgressBar As String, MaxProgress As Int, Progress As Int, Indeterminate As Boolean)
      Sets the parameters for a progress bar used in a notification
      ProgressBar - The name of the progress bar as defined in the xml layout
      MaxProgress - the upper limit of the progress bar. A good value is 100
      Progress - the current level of progress to be shown. Must be <= maxProgress.
      Indeterminate - set the progress bar as indeterminate
    • SetTextColor (TextField As String, Color As Int)
      Sets the color of the text in a text field in a custom layout
      TextField - The name of the text element as defined in the xml layout
      Color - The color that will be assigned to the text element
    • SetTextField (TextField As String, Text As String)
      Sets the text field in a custom layout
      TextField - The name of the text element as defined in the xml layout
      Text - The string that will be assigned to the text element
    • setEnableClickEvent (View As String, Activity As Object, Tag As String)
      Enables the Click action for a view in a custom layout.
      View - The name of the view as defined in the xml layout
      Activity - The activity that will be launched when the view is clicked (Maybe service will work too)
      Tag - The tag that will be returned as an extra in the starting intent
      Implements setOnClickPendingIntent
      Android V3+
  • NotificationInboxStyle
    Methods:
    • Initialize
      Helper class for generating large-format notifications that include a list of (up to 5) strings.
      If the platform does not provide large-format notifications, this method has no effect
    • AddLine As String [write only]
      Adds a line to the details section.
      You can add a MAXIMUM of 5 lines.
    • BigContentTitle As String [write only]
      Overrides the ContentTitle set in the Notification Builder.
    • SummaryText As String [write only]
      Sets the first line of text after the details section
  • NotificationRemoteInput
    Methods:
    • GetRemoteInput (intent As Intent, key As String) As String
      Extracts a RemoteInput (voice) string from starting intent
      Use this in the Activity_Resume of the Activity called by the Action.
      Example:
      <code>
      Dim In as intent
      In = Activity.GetStartingIntent
      If In.HasExtra("Notification_Wear_Action_Tag") Then
      If In.GetExtra("Notification_Wear_Action_Tag") = Tag Then 'Tag set when adding Action to Notification
      Dim Rem as NotificationRemoteInput

      ToastMessageShow(Rem.GetRemoteInput(In, Label), false) 'Label set on Initialize
      End If
      End If
      </code>
    • Initialize (Label As String)
      Initializes the object.
      Label - Used to retrieve the reply later.
      See GetRemoteInput for details on how to get the input.
      NOTE: you do not need to call Initialize in order to use GetRemoteInput.
    • Choices() As String [write only]
      Set a list of preset choices to show when requesting for voice input
      example:
      <code>RemoteInput1.Choices = Array as String("Yes", "No", "Maybe")</code>
    • Label As String [write only]
      Sets the label to show when requesting for voice input
  • NotificationWearableExtender
    Fields:
    • BOTTOM As Int
    • CENTER_VERTICAL As Int
    • END As Int
    • SIZE_DEFAULT As Int
    • SIZE_FULL_SCREEN As Int
    • SIZE_LARGE As Int
    • SIZE_MEDIUM As Int
    • SIZE_SMALL As Int
    • SIZE_XSMALL As Int
    • START As Int
    • TOP As Int
    Methods:
    • AddAction (icon As String, title As String, tag As String, object As Object)
      Similar to NotificatioBuilder.AddAction, but the Action will show on Wear Devices only.
      If this method is used the Wear device will NOT display any of the other actions.
      Tags are named 'Notification_Wear_Action_Tag
    • AddAction2 (icon As String, title As String, tag As String, object As Object, RemoteInput As Builder)
      Similar to AddAction but allows you to pass a RemoteInput object for voice input.
    • AddPage (Page As Builder)
      Adds an additional page to notifications shown on Wear Device
      Page - A new notification.
      Example:
      <code>
      Dim Notification1, Notification2 as NotificationBuilder
      'code to build notifications
      ...
      Notification1.AddPage(Notification2.build())
      ...
      </code>
    • ClearActions
      Clears any previously added Actions.
    • ClearPages
      Clears any previously added Pages.
    • Initialize
      Initializes the object
    • setDisplayIntent (Activity As Object)
      Googles Docs
      ------------
      Set an activity to be displayed while viewing the notification.
      My Version after doing a little research
      ----------------------------------------
      When creating a notification directly from an App on the Wear device, you can use custom layouts. This is done by creating the layout
      in an activity in the App. Then call this method, passing the layout activity as the Parameter.
      The activity to launch needs to allow embedding, must be exported and should have an empty task affinity.
      It is also recommended to use the device default light theme.
      This is achieved by adding the following to the Manifest Editor

      B4X:
      SetActivityAttribute (DisplayActivity, android:exported, "true")
      SetActivityAttribute (DisplayActivity, android:allowEmbedded, "true")
      SetActivityAttribute (DisplayActivity, android:taskAffinity, "")
      SetActivityAttribute (DisplayActivity, android:theme, "@android:style/Theme.DeviceDefault.Light")
    Properties:
    • Background As Bitmap
      Set or Get the background of the Wear Notification (no matter what the Style)
    • ContentAction As Int [write only]
      Sets the action to be clickable with the content of this notification. i.e. When you click the main notification, it will trigger the Action.
      This action will no longer display separately from this notification's content.
      For notifications with multiple pages, child pages can also have content actions set,
      although the list of available actions comes from the main notification and not from the child page's notification.
      ActionIndex is the ID of the Action to use. ID's start at 0
    • ContentIcon As String [write only]
      Sets the Icon that goes with the content of this notification
      The image file should manually copied to the Objects\res\drawable\ folder and set to read-only.
      The file name is case sensitive and should not contain the file extension.
      You can use "icon" to use the applications icon.
    • ContentIconGravity As Int [write only]
      Sets the gravity for the ContentIcon.
      Supported values START, END
      Use the built in constants. e.g <code>WearExtender.START</code>
    • ContentIntentAvailableOffline As Boolean [write only]
      Sets whether the content intent is available when the wearable device is not connected to a companion device.
    • CustomContentHeight As Int
      Sets or Gets the custom height for the display of this notifications content.
      NOTE: This option is only available for custom display notifications created using DisplayIntent
    • CustomSizePreset As Int
      Sets or Gets the custom size preset for the display of this notification out of the available presents.
      Use the built in constants. e.g. WearExtender1.SIZE_LARGE
      Possible values - SIZE_DEFAULT, SIZE_FULL_SCREEN, SIZE_LARGE, SIZE_MEDIUM, SIZE_SMALL, SIZE_XSMALL
    • Gravity As Int [write only]
      Sets the gravity of the Notification on the device.
      Supported values BOTTOM, CENTER_VERTICALLY, TOP
      Use the built in constants. e.g WearExtender.TOP
    • HideIcon As Boolean [write only]
      Hides the Icon if set to true.
    • ShowBackgroundOnly As Boolean [write only]
      Only the background image of this notification should be displayed, and other semantic content should be hidden.
      This method only applies to sub Pages.
    • StartScrollBottom As Boolean [write only]
      Sets whether the scrolling position for the contents of this notification should start at the bottom of the contents
      instead of the top when the contents are too long to display within the screen. Default is false (start scroll at the top)
What If?
What if you have any issues? Let me know and I will try my best to solve them. I appreciate ALL feedback, good and bad.
What if you love the library? well, I will be adding a donate button to my forum signature, It's not mandatory, but if you would like to donate to show appreciation. Feel free. After-all, these things take blood, sweat and tears. If you use the library in an app that you sell and make money from, then I think it is fair play to donate a little something :cool:

NOTE: Please don't forget to add the android-support-v4.jar file to your additional library folder.

NOTE 2: If you are using B4A version 6+ you have to take a little different approach.

Add the following line to the main module:
B4X:
#additionaljar: com.android.support:support-v4
And use the 'NotificationBuilder.xml' file added separately below.

Files
 

Attachments

Last edited by a moderator:

thedesolatesoul

Expert
Licensed User
Excellent work Barx! Really appreciated, this wasnt an easy thing to do, but your retain your title of notifications master :sign0027:
All functions work great on my S3
 

bluedude

Well-Known Member
Licensed User
Will this also support actions?

Hi,

Cool, will this also support notification actions like new apps. have?

Cheers,
 

barx

Well-Known Member
Licensed User
Hi,

Cool, will this also support notification actions like new apps. have?

Cheers,
Yes, I have managed to add the 3 expanding styles (InboxStyle, BigTextStyle, BigPictureStyle). Add Actions is next on the list. Don't there is much more to go at after that.
 

barx

Well-Known Member
Licensed User
Version 2 is almost ready for release, quicker than I thought. I just need to update the demo app to show the cool new features.

Added:
-------

The 3 expanding style that are available:-
InboxStyle
BigTextSyle
BigPictureStyle

AddAction()

Will update the app hopefully over the next 24h and release the update.
 

barx

Well-Known Member
Licensed User
I updated this library to Version 2 this morning and forgot to add this to flag it up. So here it is. Version 2 is now available in the original post.

Enjoy
 

barx

Well-Known Member
Licensed User
Sadly the cool stuff doesnt work on my S3 with 4.1.2.
I am sure you are happy :(
It doesn't work? It should as I tested it all on an s3. What are you testing? The demo app or writing you own code? If you own code, please show me the code.
 

thedesolatesoul

Expert
Licensed User
It works!!!
I think you should put some info for a :sign0104: like me who doesnt know how to expand a notification using two fingers and pulling sideways!
 

barx

Well-Known Member
Licensed User
For those that like eye-candy, I have added some screenshots to the original post of the demo app in action.
 

thedesolatesoul

Expert
Licensed User
Barx, this is awesome.
I have one question, after I use setProgress and I reach 100% I want to remove the progressbar. How do I do that?
I tried notif.Cancel(1) and create another notification with that same id, but the progressbar remained.

EDIT: I worked it out. My timer was throwing me another notif.notify(1) even though i thought it was cancelled. I made sure the timer was disabled first.
 
Last edited:

barx

Well-Known Member
Licensed User
Barx, this is awesome.
I have one question, after I use setProgress and I reach 100% I want to remove the progressbar. How do I do that?
I tried notif.Cancel(1) and create another notification with that same id, but the progressbar remained.

EDIT: I worked it out. My timer was throwing me another notif.notify(1) even though i thought it was cancelled. I made sure the timer was disabled first.
Glad you managed to get sorted :)
 

Inman

Well-Known Member
Licensed User
Excellent! Works well. I have been waiting for this for months. You really are the king of notifications :)

One doubt. Using NotificationBigTextStyle, when I set the large icon, the small icon disappears completely, instead of moving to the right side. Did you check it out?

EDIT:

I noticed that the smallicon does show up in normal mode. But if you expand the notification with 2 finger gesture, the smallicon on the right disappears. I am not sure if that is the default behaviour on Android. Never really noticed it.
 
Last edited:
Top