JUCE  v5.4.1-191-g0ab5e696f
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::PushNotifications::Notification Struct Reference

Represents a notification that can be sent or received. More...

#include <juce_PushNotifications.h>

Collaboration diagram for juce::PushNotifications::Notification:

Classes

struct  Action
 Represents an action on a notification that can be presented as a button or a text input. More...
 
struct  LedBlinkPattern
 Allows to control the time the device's led is on and off. More...
 
struct  Progress
 Used to represent a progress of some operation. More...
 

Public Member Functions

 Notification ()=default
 
 Notification (const Notification &other)
 
bool isValid () const noexcept
 Checks whether a given notification is correctly configured for a given OS. More...
 

Public Attributes

Common fields
String identifier
 Required: unique id that can be used to later dismiss the notification (on iOS available from version 10). More...
 
String title
 Required: the title of the notification, usually displayed in the first row. More...
 
String body
 Required: the content of the notification, usually displayed in the second row. More...
 
String subtitle
 Optional: additional text, that may be displayed e.g. More...
 
String groupId
 Optional: allows the OS to visually group, collapse, and expand a set of notifications, note that OS may automatically group notifications if no groupId is specified. More...
 
int badgeNumber = 0
 Optional: on platforms that support it, can set a number this notification represents. More...
 
URL soundToPlay
 Optional: empty when the notification should be silent. More...
 
var properties
 Optional: collection of additional properties that may be passed as a dictionary. More...
 
iOS only fields
String category
 Required: determines set of actions that will appear (as per setup done in requestPermissionsWithSettings()). More...
 
double triggerIntervalSec = 0.
 Optional: specifies number of seconds before the notification should trigger. More...
 
bool repeat = false
 Optional: allows the notification to continuously retrigger after triggerIntervalSec seconds. More...
 

Android only fields

enum  Type {
  unspecified,
  alarm,
  call,
  email,
  error,
  event,
  message,
  taskProgress,
  promo,
  recommendation,
  reminder,
  service,
  social,
  status,
  system,
  transport
}
 Metadata that can be used by the OS to better handle the notification, depending on its priority. More...
 
enum  Priority {
  veryLow = -2,
  low = -1,
  medium = 0,
  high = 1,
  veryHigh = 2
}
 Metadata used as a hint to the OS about the priority of the notification. More...
 
enum  LockScreenAppearance {
  dontShow = -1,
  showPartially = 0,
  showCompletely = 1
}
 Describes how to show the notification when the screen is locked. More...
 
enum  TimestampVisibility {
  off,
  normal,
  chronometer,
  countDownChronometer
}
 Controls timestamp visibility and format. More...
 
enum  BadgeIconType {
  none,
  small,
  large
}
 Controls badge icon type to use if a notification is shown as a badge. More...
 
enum  GroupAlertBehaviour {
  alertAll,
  AlertSummary,
  AlertChildren
}
 Controls sound and vibration behaviour for group notifications. More...
 
String icon
 Required: name of an icon file (without an extension) to be used for this notification. More...
 
String channelId
 Required for Android API level 26 or above: specifies notification channel id. More...
 
Image largeIcon
 Optional: an additional large icon displayed in the notification content view. More...
 
String tickerText
 Optional: ticker text used for accessibility services. More...
 
Array< Actionactions
 Optional: actions associated with the notification. More...
 
Progress progress
 Optional: set to default (0, 0, false), to disable progress display. More...
 
String person
 Optional: additional metadata used as a hint to OS that a notification is related to a specific person. More...
 
Type type = unspecified
 Optional. More...
 
Priority priority = medium
 Optional. More...
 
LockScreenAppearance lockScreenAppearance = showPartially
 Optional. More...
 
std::unique_ptr< NotificationpublicVersion
 Optional: if you set lockScreenAppearance to showPartially, then you can provide "public version" of your notification that will be displayed on the lock screen. More...
 
String groupSortKey
 Optional: Used to order notifications within the same group. More...
 
bool groupSummary = false
 Optional: if true, then this notification will be a group summary of the group set with groupId. More...
 
Colour accentColour
 Optional: sets accent colour. More...
 
Colour ledColour
 Optional: Sets the led colour. More...
 
LedBlinkPattern ledBlinkPattern
 Optional. More...
 
Array< intvibrationPattern
 Optional: sets the vibration pattern in milliseconds. More...
 
bool shouldAutoCancel = true
 Optional: If true, the notification will be automatically cancelled when a user clicks it in the panel. More...
 
bool localOnly = true
 Optional: whether or not the notification should bridge to other devices. More...
 
bool ongoing = false
 Optional: If true, then it cannot be dismissed by the user and it must be dimissed manually. More...
 
bool alertOnlyOnce = false
 Optional: Set this flag if you would only like the sound, vibrate and ticker to be played if the notification is not already showing. More...
 
TimestampVisibility timestampVisibility = normal
 Optional. More...
 
BadgeIconType badgeIconType = large
 Metadata that can be used by the OS to better handle the notification, depending on its priority. More...
 
GroupAlertBehaviour groupAlertBehaviour = alertAll
 Metadata that can be used by the OS to better handle the notification, depending on its priority. More...
 
int timeoutAfterMs = 0
 specifies a duration in milliseconds, after which the notification should be cancelled, if it is not already canceled. More...
 

Detailed Description

Represents a notification that can be sent or received.

Member Enumeration Documentation

◆ BadgeIconType

Controls badge icon type to use if a notification is shown as a badge.

Available from Android API 26 or above.

Enumerator
none 
small 
large 

◆ GroupAlertBehaviour

Controls sound and vibration behaviour for group notifications.

Available from Android API 26 or above.

Enumerator
alertAll 

both child notifications and group notifications should produce sound and vibration.

AlertSummary 

all child notifications in the group should have no sound nor vibration, even if corresponding notification channel has sounds and vibrations enabled.

AlertChildren 

summary notifications in the group should have no sound nor vibration, even if corresponding notification channel has sounds and vibrations enabled.

◆ LockScreenAppearance

Describes how to show the notification when the screen is locked.

Available from Android API 21 or above.

Enumerator
dontShow 

The notification is not allowed on the lock screen.

showPartially 

Only some information is allowed on the lock screen.

showCompletely 

The entire notification is allowed on the lock screen.

◆ Priority

Metadata used as a hint to the OS about the priority of the notification.

Enumerator
veryLow 
low 
medium 
high 
veryHigh 

◆ TimestampVisibility

Controls timestamp visibility and format.

Enumerator
off 

Do not show timestamp.

normal 

Show normal timestamp.

chronometer 

Show chronometer as a stopwatch.

Available from Android API 16 or above.

countDownChronometer 

Set the chronometer to count down instead of counting up.

Available from Android API 24 or above.

◆ Type

Metadata that can be used by the OS to better handle the notification, depending on its priority.

Enumerator
unspecified 

Category not set.

alarm 

Alarm or timer.

call 

Incoming voice/video call or similar.

email 

Async message like email.

error 

Error in background operation or authentication status.

event 

Calendar event.

message 

Incoming message (sms, instant message etc.).

taskProgress 

Progress for a long-running background operation.

promo 

Promotion or advertisement.

recommendation 

Specific, single thing related recommendation.

reminder 

User-scheduled reminder.

service 

Running background service.

social 

Social network or sharing update.

status 

Ongoing information about device or contextual status.

system 

System or device status update.

transport 

Media transport control for playback.

Constructor & Destructor Documentation

◆ Notification() [1/2]

juce::PushNotifications::Notification::Notification ( )
default

◆ Notification() [2/2]

juce::PushNotifications::Notification::Notification ( const Notification other)

Member Function Documentation

◆ isValid()

bool juce::PushNotifications::Notification::isValid ( ) const
noexcept

Checks whether a given notification is correctly configured for a given OS.

Member Data Documentation

◆ accentColour

Colour juce::PushNotifications::Notification::accentColour

Optional: sets accent colour.

The default colour will be used if accentColour is not set. Available from Android API 21 or above.

◆ actions

Array<Action> juce::PushNotifications::Notification::actions

Optional: actions associated with the notification.

Note that the OS may allow only a limited number of actions to be presented, so always present most important actions first. Available from Android API 16 or above.

◆ alertOnlyOnce

bool juce::PushNotifications::Notification::alertOnlyOnce = false

Optional: Set this flag if you would only like the sound, vibrate and ticker to be played if the notification is not already showing.

◆ badgeIconType

BadgeIconType juce::PushNotifications::Notification::badgeIconType = large

Metadata that can be used by the OS to better handle the notification, depending on its priority.

◆ badgeNumber

int juce::PushNotifications::Notification::badgeNumber = 0

Optional: on platforms that support it, can set a number this notification represents.

◆ body

String juce::PushNotifications::Notification::body

Required: the content of the notification, usually displayed in the second row.

◆ category

String juce::PushNotifications::Notification::category

Required: determines set of actions that will appear (as per setup done in requestPermissionsWithSettings()).

◆ channelId

String juce::PushNotifications::Notification::channelId

Required for Android API level 26 or above: specifies notification channel id.

Refer to setupChannels(). Ignored on earlier Android versions.

◆ groupAlertBehaviour

GroupAlertBehaviour juce::PushNotifications::Notification::groupAlertBehaviour = alertAll

Metadata that can be used by the OS to better handle the notification, depending on its priority.

◆ groupId

String juce::PushNotifications::Notification::groupId

Optional: allows the OS to visually group, collapse, and expand a set of notifications, note that OS may automatically group notifications if no groupId is specified.

Available on Android API 20 or above and iOS 10 or above.

◆ groupSortKey

String juce::PushNotifications::Notification::groupSortKey

Optional: Used to order notifications within the same group.

Available from Android API 20 or above.

◆ groupSummary

bool juce::PushNotifications::Notification::groupSummary = false

Optional: if true, then this notification will be a group summary of the group set with groupId.

Available from Android API 20 or above.

◆ icon

String juce::PushNotifications::Notification::icon

Required: name of an icon file (without an extension) to be used for this notification.

This must be the name of one of the image files included into resources when exporting an Android project (see "Extra Android Raw Resources" setting in Projucer).

◆ identifier

String juce::PushNotifications::Notification::identifier

Required: unique id that can be used to later dismiss the notification (on iOS available from version 10).

◆ largeIcon

Image juce::PushNotifications::Notification::largeIcon

Optional: an additional large icon displayed in the notification content view.

◆ ledBlinkPattern

LedBlinkPattern juce::PushNotifications::Notification::ledBlinkPattern

Optional.

◆ ledColour

Colour juce::PushNotifications::Notification::ledColour

Optional: Sets the led colour.

The hardware will do its best to approximate the colour. The default colour will be used if ledColour is not set.

◆ localOnly

bool juce::PushNotifications::Notification::localOnly = true

Optional: whether or not the notification should bridge to other devices.

Available from Android API 20 or above.

◆ lockScreenAppearance

LockScreenAppearance juce::PushNotifications::Notification::lockScreenAppearance = showPartially

Optional.

◆ ongoing

bool juce::PushNotifications::Notification::ongoing = false

Optional: If true, then it cannot be dismissed by the user and it must be dimissed manually.

Typically used for ongoing background tasks that the user is actively engaged with. To dismiss such notification, you need to call removeDeliveredNotification() or removeAllDeliveredNotifications().

◆ person

String juce::PushNotifications::Notification::person

Optional: additional metadata used as a hint to OS that a notification is related to a specific person.

Can be useful for instance messaging apps. Available from Android API 21 or above.

◆ priority

Priority juce::PushNotifications::Notification::priority = medium

Optional.

Available from Android API 16 or above.

◆ progress

Progress juce::PushNotifications::Notification::progress

Optional: set to default (0, 0, false), to disable progress display.

◆ properties

var juce::PushNotifications::Notification::properties

Optional: collection of additional properties that may be passed as a dictionary.

◆ publicVersion

std::unique_ptr<Notification> juce::PushNotifications::Notification::publicVersion

Optional: if you set lockScreenAppearance to showPartially, then you can provide "public version" of your notification that will be displayed on the lock screen.

This way you can control what information is visible when the screen is locked.

◆ repeat

bool juce::PushNotifications::Notification::repeat = false

Optional: allows the notification to continuously retrigger after triggerIntervalSec seconds.

Available from iOS 10.

◆ shouldAutoCancel

bool juce::PushNotifications::Notification::shouldAutoCancel = true

Optional: If true, the notification will be automatically cancelled when a user clicks it in the panel.

◆ soundToPlay

URL juce::PushNotifications::Notification::soundToPlay

Optional: empty when the notification should be silent.

When the name is set to "default_os_sound", then a default sound will be used.

For a custom sound on OSX, set the URL to the name of a sound file (preferably without an extension) and place the sound file directly in bundle's "Resources" directory (you can use "Xcode Resource" tickbox in Projucer to achieve that), i.e. it cannot be in a subdirectory of "Resources" like "Resources/sound". Alternatively, if a sound file cannot be found in bundle's "Resources" directory, the OS may look for the sound in the following paths: "~/Library/Sounds", "/Library/Sounds", "/Network/Library/Sounds", "/System/Library/Sounds".

For a custom sound on iOS, set the URL to a relative path within your bundle, including file extension. For instance, if your bundle contains "sounds" folder with "my_sound.caf" file, then the URL should be "sounds/my_sound.caf".

For a custom sound on Android, set URL to the name of a raw resource file (without an extension) that was included when exporting an Android project in Projucer (see "Extra Android Raw Resources" setting).

◆ subtitle

String juce::PushNotifications::Notification::subtitle

Optional: additional text, that may be displayed e.g.

in the third row or in the header area. Note that on Android, depending on OS version, this may fight for space with other components of the notification, so use this field judiciously. On iOS available from version 10. On Android available from API 16.

◆ tickerText

String juce::PushNotifications::Notification::tickerText

Optional: ticker text used for accessibility services.

◆ timeoutAfterMs

int juce::PushNotifications::Notification::timeoutAfterMs = 0

specifies a duration in milliseconds, after which the notification should be cancelled, if it is not already canceled.

Available from Android API 26 or above.

◆ timestampVisibility

TimestampVisibility juce::PushNotifications::Notification::timestampVisibility = normal

Optional.

◆ title

String juce::PushNotifications::Notification::title

Required: the title of the notification, usually displayed in the first row.

◆ triggerIntervalSec

double juce::PushNotifications::Notification::triggerIntervalSec = 0.

Optional: specifies number of seconds before the notification should trigger.

◆ type

Type juce::PushNotifications::Notification::type = unspecified

Optional.

Available from Android API 21 or above.

◆ vibrationPattern

Array<int> juce::PushNotifications::Notification::vibrationPattern

Optional: sets the vibration pattern in milliseconds.

The first value indicates how long to wait until vibration starts. The second value indicates how long to vibrate. The third value will say how long to not vibrate and so on. For instance, if the pattern is: 1000, 2000, 3000, 4000 - then one second after receiving a notification the device will vibrate for two seconds, followed by 3 seconds of no vibration and finally, 4 seconds of vibration.


The documentation for this struct was generated from the following file: