All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Public Member Functions | Static Public Member Functions | List of all members
BNotification Class Reference

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 BBitmapIcon () 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_refOnClickFile () const
 Returns the reference to the file that will be opened when the notification is clicked.
 
const entry_refOnClickRefAt (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 BArchivableInstantiate (BMessage *archive)
 Returns a new BNotification object from archive.
 
- Static Public Member Functions inherited from BArchivable
static BArchivableInstantiate (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:

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

notification.SetGroup("Group");
notification.SetTitle("Title");
notification.SetContent("This is the content");
notification.SetMessageID("mainwindow_progress");
notification.SetProgress(0.5);
notification.Send();
@ B_PROGRESS_NOTIFICATION
Progress type.
Definition: Notification.h:20
Construct system-default notifications to be displayed to the user.
Definition: Notification.h:26

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
timeoutThe 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
iconThe 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