Construct system-default notifications to be displayed to the user. More...

Inherits BArchivable.

Public Member Functions
	BNotification (BMessage *archive)
	Construct a notification from an archive.

	BNotification (notification_type type)
	Construct an empty message, with the specified type.

virtual	~BNotification ()
	Frees all resources associated with the object.

status_t	AddOnClickArg (const BString &arg)
	Add to a list of arguments that are passed to an application when the user clicks on the notification.

status_t	AddOnClickRef (const entry_ref *ref)
	Add a `ref` to the list of arguments passed when a user clicks the notification.

virtual status_t	Archive (BMessage *archive, bool deep=true) const
	Archives the BNotification in the `archive`.

const char *	Content () const
	Returns the message of the notification.

int32	CountOnClickArgs () const
	Returns the number of args to be passed when the user clicks on the notification.

int32	CountOnClickRefs () const
	Returns the number of refs to be passed when the user clicks on the notification.

const char *	Group () const
	Returns the group of the notification.

const BBitmap *	Icon () const
	Returns the icon for the notification.

status_t	InitCheck () const
	Returns the status of the constructor.

const char *	MessageID () const
	Returns the identifier of the notification.

const char *	OnClickApp () const
	Returns the signature of the application that will be called when the notification is clicked.

const char *	OnClickArgAt (int32 index) const
	Returns the arg that is stored at `index`.

const entry_ref *	OnClickFile () const
	Returns the reference to the file that will be opened when the notification is clicked.

const entry_ref *	OnClickRefAt (int32 index) const
	Returns the ref that is stored at `index`.

float	Progress () const
	Returns the progress for the notification.

status_t	Send (bigtime_t timeout=-1)
	Send the notification to the notification_server.

void	SetContent (const BString &content)
	Set a message for the notification.

void	SetGroup (const BString &group)
	Set a group for the notifcation.

status_t	SetIcon (const BBitmap *icon)
	Set the icon of the notification.

void	SetMessageID (const BString &id)
	Sets notification's message identifier.

void	SetOnClickApp (const BString &app)
	Set which application should be called when the notification is clicked by the user.

status_t	SetOnClickFile (const entry_ref *file)
	Set which file should be opened when the notification is clicked by the user.

void	SetProgress (float progress)
	Sets progress information.

void	SetTitle (const BString &title)
	Set a title for the notification.

const char *	SourceName () const
	Returns the name of the application where the notification originated.

const char *	SourceSignature () const
	Returns signature of the application where the notification originated.

const char *	Title () const
	Returns the title of the notification.

notification_type	Type () const
	Returns the type of the notification.

Public Member Functions inherited from BArchivable
	BArchivable ()
	Constructor. Does nothing.

	BArchivable (BMessage *from)
	Constructor. Does important behind-the-scenes work in the unarchiving process.

virtual	~BArchivable ()
	Destructor. Does nothing.

virtual status_t	AllArchived (BMessage *archive) const
	Method relating to the use of `BArchiver`.

virtual status_t	AllUnarchived (const BMessage *archive)
	Method relating to the use of `BUnarchiver`.

virtual status_t	Archive (BMessage *into, bool deep=true) const
	Archive the object into a BMessage.

virtual status_t	Perform (perform_code d, void *arg)
	Perform some action (Internal method defined for binary compatibility purposes).

Static Public Member Functions
static BArchivable *	Instantiate (BMessage *archive)
	Returns a new BNotification object from archive.

Static Public Member Functions inherited from BArchivable
static BArchivable *	Instantiate (BMessage *archive)
	Static member to restore objects from messages.

Detailed Description

Construct system-default notifications to be displayed to the user.

Haiku provides a notification system that allows you to display messages to the user. There is quite some flexibility in how the message is presented. You may use this class to build and send the notification. The properties you can set are:

The type of notification, which can be an information message, a warning, an error, or a progress message.
The group, which allows you to organize notification display into different categories.
A title, which is a distinct text element at the top of a notification view.
The content, which is the text message that is shown to the user.
A message identifier that allows you to modify the contents of a message that is being displayed, which is particularly useful for progress notifications.
For progress notifications, the percentage of completion can be set.
By default the notification uses the application's icon, but you may set an alternative icon.
Finally there are a few ways you can configure the actions that happen when a user clicks the notification. More on that below.

For example, with the following code, you may display a notification:

BNotification notification(B_PROGRESS_NOTIFICATION);
notification.SetGroup("Group");
notification.SetTitle("Title");
notification.SetContent("This is the content");
notification.SetMessageID("mainwindow_progress");
notification.SetProgress(0.5);
notification.Send();

Note that in the previous code example, we set a message identifier, which will allow to update the notification when we have progressed. The use would be:

// After sending the notification, you retain ownership so that you can update it
notification.SetProgress(0.7);
 
// In order to display the update, you send it again
notification.Send();

Furthermore, it is possible to support some form of follow-up action, when the user clicks the notification. First of all, you need to choose whether you want to open a specific application, or whether you want to open a specific file and have the system determine which application fits that. Additionally, you may specify command line arguments or pass additional file references for the receiving application to process.

Finally, a note about the notification_server and how it groups and handles messages coming from your application. The system is aware of the source of the notifications, and identifies your application by it's signature. That means that the identification of your application is consistent, even if it is restarted, or if you have multiple instances running. This impacts the grouping functionality and the message updating functionality. If you have an application that can have multiple instances, you will need to make sure that you properly manage your group names and identifiers if you want to keep things separate.

Since: Haiku R1

Constructor & Destructor Documentation

◆ BNotification() [1/2]

BNotification::BNotification ( notification_type type )

Construct an empty message, with the specified type.

The type influences the style of the notification view. See the notification_type enumerator for details.

Since: Haiku R1

◆ BNotification() [2/2]

BNotification::BNotification ( BMessage * archive )

Construct a notification from an archive.

Since: Haiku R1

◆ ~BNotification()

BNotification::~BNotification ( )

virtual

Frees all resources associated with the object.

Since: Haiku R1

Member Function Documentation

◆ AddOnClickArg()

status_t BNotification::AddOnClickArg ( const BString & arg )

Add to a list of arguments that are passed to an application when the user clicks on the notification.

This method allows you to construct a list of arguments, that will be sent to the application specified by BNotification::AddOnClickApp(), or the one that is associated with BNotification::AddOnClickFile(). The args will be handled by the application's BApplication::ArgvReceived() hook method.

Since: Haiku R1

◆ AddOnClickRef()

status_t BNotification::AddOnClickRef ( const entry_ref * ref )

Add a ref to the list of arguments passed when a user clicks the notification.

This method allows you to construct a list of refs, that will be sent to the application specified by BNotification::AddOnClickApp(), or the one that is associated with BNotification::AddOnClickFile(). The refs will be handled by the application's BApplication::RefsReceived() hook method.

Since: Haiku R1

◆ Archive()

status_t BNotification::Archive	(	BMessage *	archive,
		bool	deep = `true`
	)		const

virtual

Archives the BNotification in the archive.

See also: BArchivable::Archive(), Instantiate() static function.

Returns: B_OK: if everything went fine, or other errors that describe why archiving has failed.

Since: Haiku R1

Reimplemented from BArchivable.

◆ Content()

const char * BNotification::Content ( ) const

Returns the message of the notification.

Returns: The message of the notification as a string.

Since: Haiku R1

◆ CountOnClickArgs()

int32 BNotification::CountOnClickArgs ( ) const

Returns the number of args to be passed when the user clicks on the notification.

See also: BNotification::AddOnClickArg()

Since: Haiku R1

◆ CountOnClickRefs()

int32 BNotification::CountOnClickRefs ( ) const

Returns the number of refs to be passed when the user clicks on the notification.

See also: BNotification::AddOnClickRef()

Since: Haiku R1

◆ Group()

const char * BNotification::Group ( ) const

Returns the group of the notification.

See also: BNotification::SetGroup() for more information about groups.

Returns: The string of the notification's group.

Since: Haiku R1

◆ Icon()

const BBitmap * BNotification::Icon ( ) const

Returns the icon for the notification.

See also: BNotification::SetIcon() for more information on this property.

Returns: Returns a borrowed unchangeable reference to the icon.

Since: Haiku R1

◆ InitCheck()

status_t BNotification::InitCheck ( ) const

Returns the status of the constructor.

Since: Haiku R1

◆ Instantiate()

static BArchivable * BNotification::Instantiate ( BMessage * archive )

static

Returns a new BNotification object from archive.

This class implements the archiving API, and as such, you can build a new BNotification object from a previously created BMessage archive. However, if the message doesn't contain an archived data for a BNotification object, this method returns NULL.

Returns: BNotification object from archive or NULL if it doesn't contain a valid BNotification object.

Since: Haiku R1

◆ MessageID()

const char * BNotification::MessageID ( ) const

Returns the identifier of the notification.

See also: BNotification::SetMessageID() for the purpose of having an identifier.

Returns: The identifier of the notification as a string.

Since: Haiku R1

◆ OnClickApp()

const char * BNotification::OnClickApp ( ) const

Returns the signature of the application that will be called when the notification is clicked.

See also: More information about this property in BNotification::SetOnClickApp().

Since: Haiku R1

◆ OnClickArgAt()

const char * BNotification::OnClickArgAt ( int32 index ) const

Returns the arg that is stored at index.

See also: BNotification::AddOnClickArg()

Since: Haiku R1

◆ OnClickFile()

const entry_ref * BNotification::OnClickFile ( ) const

Returns the reference to the file that will be opened when the notification is clicked.

See also: More information about this property in BNotification::SetOnClickFile().

Since: Haiku R1

◆ OnClickRefAt()

const entry_ref * BNotification::OnClickRefAt ( int32 index ) const

Returns the ref that is stored at index.

See also: BNotification::AddOnClickRef()

Since: Haiku R1

◆ Progress()

float BNotification::Progress ( ) const

Returns the progress for the notification.

See also: BNotification::SetProgress() for more information about this value.

Returns: A value between 0.0 and 1.0 if notification's type is B_PROGRESS_NOTIFICATION, or otherwise -1.

Since: Haiku R1

◆ Send()

status_t BNotification::Send ( bigtime_t timeout = -1 )

Send the notification to the notification_server.

The notification is delivered asynchronously to the notification_server, which will display it according to its settings and filters.

After sending, you retain ownership of the notification. The advantage is that you can re-use the notification at a later moment, or use the object to update the notification. See BNotification::SetMessageID() about updating displayed notifications. If you allocate the notification on the heap, be sure to free the memory.

Parameters

timeout The timeout in microsecond that the notification should be displayed. If you want to use the default timing, use the default argument or pass -1.

Returns: B_OK if everything went fine, B_BAD_PORT_ID if there was a problem connecting to the notification_server, or any other errors if something went wrong transmitting the notification.

Since: Haiku R1

◆ SetContent()

void BNotification::SetContent ( const BString & content )

Set a message for the notification.

Since: Haiku R1

◆ SetGroup()

void BNotification::SetGroup ( const BString & group )

Set a group for the notifcation.

The default behaviour of the notification_server is group the visible notifications per running application, and then in order in which they have been received. There may be situations where you want to override that behavior and group related notifications. When you set a group name, the notification_server will create a box with the group name as label, and insert all related notifications in that box.

Since: Haiku R1

◆ SetIcon()

status_t BNotification::SetIcon ( const BBitmap * icon )

Set the icon of the notification.

Set the icon for the notification. By default, the application icon is used. This method makes a copy of the icon.

Parameters

icon	The icon that should be displayed with the notification.

Returns: B_OK if everything went fine, B_NO_MEMORY when the icon could not be copied, or another error if something else went wrong.

Since: Haiku R1

◆ SetMessageID()

void BNotification::SetMessageID ( const BString & id )

Sets notification's message identifier.

If you want to update the contents of an existing notification, you can set a identifier for this message. When you send a new or updated message with the same identifier, the notification_server will update the existing message with the new content.

In order to effectively use this feature, you will have to make sure the identifier is unique within the current application.

Since: Haiku R1

◆ SetOnClickApp()

void BNotification::SetOnClickApp ( const BString & app )

Set which application should be called when the notification is clicked by the user.

The value app should be a valid application signature, for example 'application/x-vnd.Haiku-StyledEdit'.

Using this property has precedence on when BNotification::SetOnClickFile() is used. If you want interacting with the notification opening a specific file, then you should use this method in combination with BNotification::AddOnClickRef().

See also: Additional actions and parameters can be set through BNotification::SetOnClickFile(), BNotification::AddOnClickRef() and BNotification::AddOnClickArg().

Since: Haiku R1

◆ SetOnClickFile()

status_t BNotification::SetOnClickFile ( const entry_ref * file )

Set which file should be opened when the notification is clicked by the user.

The file will be opened by the default application for this file type.

You cannot use this action in combination with BNotification::SetOnClickApp(). If you use this way of setting an action, this action will be ignored.

See also: Additional actions and parameters can be set through BNotification::SetOnClickApp(), BNotification::AddOnClickRef() and BNotification::AddOnClickArg().

Since: Haiku R1

◆ SetProgress()

void BNotification::SetProgress ( float progress )

Sets progress information.

When you are building a notification of the type B_PROGRESS_NOTIFICATION the notification view will show a progress bar and a label that expresses the progress in a percentage. Using this method you can set what the bar and label express.

The valid range is between 0.0 and 1.0. If progress is lower than 0.0 (i.e. negative), the value will be set to 0.0. If it is higher than 1.0, it will be set to 1.0.

Since: Haiku R1

◆ SetTitle()

void BNotification::SetTitle ( const BString & title )

Set a title for the notification.

Since: Haiku R1

◆ SourceName()

const char * BNotification::SourceName ( ) const

Returns the name of the application where the notification originated.

When you build your own notifications, this will contain the name of the current application. If you receive notifications from other applications, it will include theirs.

Returns: Name of the source application.

Since: Haiku R1

◆ SourceSignature()

const char * BNotification::SourceSignature ( ) const

Returns signature of the application where the notification originated.

When you build your own notifications, this will contain the signature of the current application. If you receive notifications from other applications, it will include theirs.

Returns: Signature of the source application.

Since: Haiku R1

◆ Title()

const char * BNotification::Title ( ) const

Returns the title of the notification.

Returns: The title of the notification as a string.

Since: Haiku R1

◆ Type()

notification_type BNotification::Type ( ) const

Returns the type of the notification.

Returns: A value of the notification_type enum that represents notification type.

Since: Haiku R1

Public Member Functions

Static Public Member Functions