B4A Library Notification Builder Library.

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.



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

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:
And use the 'NotificationBuilder.xml' file added separately below.

Files