A class that represents a notification. More...

Inheritance diagram for MNotification:

Collaboration diagram for MNotification:

Public Member Functions
	MNotification (const QString &eventType, const QString &summary=QString(), const QString &body=QString())
virtual	~MNotification ()
void	setGroup (const MNotificationGroup &group)
QString	eventType () const
void	setSummary (const QString &summary)
QString	summary () const
void	setBody (const QString &body)
QString	body () const
void	setImage (const QString &image)
QString	image () const
void	setAction (const MRemoteAction &action)
void	setCount (uint count)
uint	count () const
virtual bool	publish ()
virtual bool	remove ()
bool	isPublished () const
Static Public Member Functions
static QList< MNotification * >	notifications ()
Static Public Attributes
static const QString	DeviceEvent = "device"
static const QString	DeviceAddedEvent = "device.added"
static const QString	DeviceErrorEvent = "device.error"
static const QString	DeviceRemovedEvent = "device.removed"
static const QString	EmailEvent = "email"
static const QString	EmailArrivedEvent = "email.arrived"
static const QString	EmailBouncedEvent = "email.bounced"
static const QString	ImEvent = "im"
static const QString	ImErrorEvent = "im.error"
static const QString	ImReceivedEvent = "im.received"
static const QString	NetworkEvent = "network"
static const QString	NetworkConnectedEvent = "network.connected"
static const QString	NetworkDisconnectedEvent = "network.disconnected"
static const QString	NetworkErrorEvent = "network.error"
static const QString	PresenceEvent = "presence"
static const QString	PresenceOfflineEvent = "presence.offline"
static const QString	PresenceOnlineEvent = "presence.online"
static const QString	TransferEvent = "transfer"
static const QString	TransferCompleteEvent = "transfer.complete"
static const QString	TransferErrorEvent = "transfer.error"
static const QString	MessageEvent = "x-nokia.message"
static const QString	MessageArrivedEvent = "x-nokia.message.arrived"
Properties
QString	summary
QString	body
QString	image
uint	count

Detailed Description

A class that represents a notification.

Overview

Notifications provide means to communicate system information and status updates to the user, without blocking the UI or requiring the user to switch to another view. Notifications can be done through visual, audio or haptic means.

Dialogs and notifications are related to each other, but separate components. All Dialogs are modal, i.e. elements that do not go away from the screen without requiring user interactions, whereas all notifications are temporal elements (i.e. modeless) that do not require interactions from the user (although they can sometimes also provide them).

Certain notifications are related to the communication activities (like SMS, email, feed updates etc.), and notifications relating to application and system behaviour (like connection lost, battery low etc.). Communication activities display incoming event notifications.

A notification is not created or updated until the publish() function is called.

A list of notifications already created can be requested. A QCoreApplication must be created before doing the request.

See also:: Notifications System

Interactions

Notifications can be non-interactive (for information only) or interactive: the interactive notifications provide information, but they also provide a way for interacting with the notification, for example to fix a connectivity problem. Notifications are always modeless components - modal "notifications" are specified with Dialogs. Images on this page are for illustrational purposes only. In case that images and text conflict each other, the text should be followed.

Usage guidelines

Notifications are intended to communicate information when the foreground application UI is not able to do this. If the foreground application UI can already communicate the information, a separate Notification shouldn't be shown anymore.
Notifications are temporal elements, i.e. they are dismissed from screen after a certain time (or timeout).
Incoming events aim to provide a centralized method for applications to provide persistent notifications to the users.
Use non-interactive notifications (status banners) to display feedback/progress/notifications for successful actions, if other parts of the foreground UI cannot be directly utilized.
Consider using interactive status banners for notifications in error cases, exceptions etc. that can either be dismissed or then reacted upon. The interactive elements are essentially shortcut functions, intended to save time from the users. No use case should fail because the user fails to press the interactive status banner.
MInfoBanner class can be used to show information banners in a single application. However, such banners are only shown inside the application using them, no sounds or other feedbacks are played and the banners are not aware of the current policy or profile in any way.

Persistence

Notifications created as persistent are stored by the notification system and are returned by the MNotification::notifications() even after a reboot. It should be noted that currently all properties of such notifications need to be set before publishing changes to the notification. Otherwise the properties of the notification will be lost.

Note:: A QCoreApplication instance must be created before creating any persistent notifications.

Definition at line 92 of file corelib/notification/mnotification.h.

Constructor & Destructor Documentation

MNotification::MNotification	(	const QString &	eventType,
		const QString &	summary = `QString()`,
		const QString &	body = `QString()`
	)			`[explicit]`

Creates a new representation of a notification. The notification will not be published until publish() is called. Only the event type needs to be defined. If no summary or body text is defined the notification will not have a visual representation.

Parameters:

	eventType	the event type of the notification. Types are in the format defined in Desktop Notifications Specification. Known constants (such as EmailArrivedEvent) are provided by the MNotification class but custom strings can also be used.
	summary	the summary text to be used in the notification. Can be omitted (defaults to no summary text).
	body	the body text to be used in the notification. Can be omitted (defaults to no body text).

Definition at line 71 of file mnotification.cpp.

                                                                                                  :
    d_ptr(new MNotificationPrivate)
{
    Q_D(MNotification);
    d->eventType = eventType;
    d->summary = summary;
    d->body = body;
}

MNotification::~MNotification ( ) [virtual]

Destroys the class that represents a notification.

Definition at line 93 of file mnotification.cpp.

{
    delete d_ptr;
}

Member Function Documentation

QString MNotification::body ( ) const

Gets the body text to be used in the notification.

Returns:: the body text to be used in the notification.

uint MNotification::count ( ) const

Gets the number of items represented by this notification (cardinality).

Returns:: the number of items represented by this notification

QString MNotification::eventType ( ) const

Gets the event type of the notification.

Returns:: the event type of the notification.

Definition at line 116 of file mnotification.cpp.

{
    Q_D(const MNotification);
    return d->eventType;
}

QString MNotification::image ( ) const

Gets the name of the image to be used in the notification.

Returns:: the name of the image to be used in the notification.

bool MNotification::isPublished ( ) const

Returns whether the notification is published

Returns:: true if the notification is published, false otherwise

Definition at line 214 of file mnotification.cpp.

{
    Q_D(const MNotification);
    return d->id != 0;
}

QList< MNotification * > MNotification::notifications ( ) [static]

Returns a list of notifications created by this application but which have not been dismissed by the user yet. Caller of this function gets the ownership of the notifications, and is responsible for freeing them.

Returns:: list of notifications

Definition at line 220 of file mnotification.cpp.

{
    QList<MNotification> list = MNotificationManager::instance()->notificationList();
    QList<MNotification *> notifications;
    foreach(const MNotification &notification, list) {
        notifications.append(new MNotification(notification));
    }
    return notifications;
}

Here is the call graph for this function:

bool MNotification::publish ( ) [virtual]

Publishes the notification. If the notification has not yet been published a notification is created into the given notification group (if any) and is given an ID by the notification manager. Otherwise the existing notification is updated.

Returns:: true if the publishing succeeded, false otherwise

Definition at line 176 of file mnotification.cpp.

{
    Q_D(MNotification);

    bool success = false;
    if (d->id == 0) {
        if (!d->summary.isNull() || !d->body.isNull() || !d->image.isNull() || !d->action.isNull()) {
            d->id = MNotificationManager::instance()->addNotification(d->groupId, d->eventType, d->summary, d->body, d->action, d->image, d->count);
        } else {
            d->id = MNotificationManager::instance()->addNotification(d->groupId, d->eventType);
        }

        success = d->id != 0;
    } else {
        if (!d->summary.isNull() || !d->body.isNull() || !d->image.isNull() || !d->action.isNull()) {
            success = MNotificationManager::instance()->updateNotification(d->id, d->eventType, d->summary, d->body, d->action, d->image, d->count);
        } else {
            success = MNotificationManager::instance()->updateNotification(d->id, d->eventType);
        }
    }

    return success;
}

bool MNotification::remove ( ) [virtual]

Removes a notification.

Returns:: true if the removal succeeded, false otherwise

Definition at line 200 of file mnotification.cpp.

{
    bool success = false;

    if (isPublished()) {
        Q_D(MNotification);
        uint id = d->id;
        d->id = 0;
        success = MNotificationManager::instance()->removeNotification(id);
    }

    return success;
}

Here is the call graph for this function:

void MNotification::setAction ( const MRemoteAction & action )

Sets the action to be executed when the notification is activated.

Parameters:

action

the action to be executed when the notification is activated.

Definition at line 158 of file mnotification.cpp.

{
    Q_D(MNotification);
    d->action = action.toString();
}

Here is the call graph for this function:

void MNotification::setBody ( const QString & body )

Sets the body text to be used in the notification.

Parameters:

body

the body text to be used in the notification.

Definition at line 134 of file mnotification.cpp.

{
    Q_D(MNotification);
    d->body = body;
}

void MNotification::setCount ( uint count )

Sets the number of items represented by this notification (cardinality). For example a single notification may represent 5 new e-mails, in which case the count of the notification should be 5.

Parameters:

count

the number of items represented by this notification

Definition at line 164 of file mnotification.cpp.

{
    Q_D(MNotification);
    d->count = count;
}

void MNotification::setGroup ( const MNotificationGroup & group )

Sets the notification group the notification belongs to. The notification group must be published before this function is called.

Parameters:

group

the notification group the notification belongs to.

Definition at line 104 of file mnotification.cpp.

{
    Q_D(MNotification);
    d->groupId = group.id();
}

void MNotification::setImage ( const QString & image )

Sets the name of the image to be used in the notification. If the name is an absolute path (begins with a /) an image located in that path is used. Otherwise the image name is interpreted to be an icon ID.

Parameters:

image

the name of the image to be used in the notification.

Definition at line 146 of file mnotification.cpp.

{
    Q_D(MNotification);
    d->image = image;
}

void MNotification::setSummary ( const QString & summary )

Sets the summary text to be used in the notification.

Parameters:

summary

the summary text to be used in the notification.

Definition at line 122 of file mnotification.cpp.

{
    Q_D(MNotification);
    d->summary = summary;
}

QString MNotification::summary ( ) const

Gets the summary text to be used in the notification.

Returns:: the summary text to be used in the notification.

Member Data Documentation

const QString MNotification::DeviceAddedEvent = "device.added" [static]

A device, such as a USB device, was added to the system.

Definition at line 128 of file corelib/notification/mnotification.h.

const QString MNotification::DeviceErrorEvent = "device.error" [static]

A device had some kind of error.

Definition at line 130 of file corelib/notification/mnotification.h.

const QString MNotification::DeviceEvent = "device" [static]

A generic device-related notification that doesn't fit into any other category.

Predefined event types. These are just the known types; applications may use other types as well if the event type string is known.

Definition at line 126 of file corelib/notification/mnotification.h.

const QString MNotification::DeviceRemovedEvent = "device.removed" [static]

A device, such as a USB device, was removed from the system.

Definition at line 132 of file corelib/notification/mnotification.h.

const QString MNotification::EmailArrivedEvent = "email.arrived" [static]

A new e-mail notification.

Definition at line 136 of file corelib/notification/mnotification.h.

const QString MNotification::EmailBouncedEvent = "email.bounced" [static]

A notification stating that an e-mail has bounced.

Definition at line 138 of file corelib/notification/mnotification.h.

const QString MNotification::EmailEvent = "email" [static]

A generic e-mail-related notification that doesn't fit into any other category.

Definition at line 134 of file corelib/notification/mnotification.h.

const QString MNotification::ImErrorEvent = "im.error" [static]

An instant message error notification.

Definition at line 142 of file corelib/notification/mnotification.h.

const QString MNotification::ImEvent = "im" [static]

A generic instant message-related notification that doesn't fit into any other category.

Definition at line 140 of file corelib/notification/mnotification.h.

const QString MNotification::ImReceivedEvent = "im.received" [static]

A received instant message notification.

Definition at line 144 of file corelib/notification/mnotification.h.

const QString MNotification::MessageArrivedEvent = "x-nokia.message.arrived" [static]

A new SMS/MMS notification.

Definition at line 168 of file corelib/notification/mnotification.h.

const QString MNotification::MessageEvent = "x-nokia.message" [static]

A generic SMS/MMS-related notification that doesn't fit into any other category.

Definition at line 166 of file corelib/notification/mnotification.h.

const QString MNotification::NetworkConnectedEvent = "network.connected" [static]

A network connection notification, such as successful sign-on to a network service. This should not be confused with device.added for new network devices.

Definition at line 148 of file corelib/notification/mnotification.h.

const QString MNotification::NetworkDisconnectedEvent = "network.disconnected" [static]

A network disconnected notification. This should not be confused with device.removed for disconnected network devices.

Definition at line 150 of file corelib/notification/mnotification.h.

const QString MNotification::NetworkErrorEvent = "network.error" [static]

A network-related or connection-related error.

Definition at line 152 of file corelib/notification/mnotification.h.

const QString MNotification::NetworkEvent = "network" [static]

A generic network notification that doesn't fit into any other category.

Definition at line 146 of file corelib/notification/mnotification.h.

const QString MNotification::PresenceEvent = "presence" [static]

A generic presence change notification that doesn't fit into any other category, such as going away or idle.