NotifyNotification: Libnotify Reference Manual

NotifyNotification

NotifyNotification — A passive pop-up notification.

Functions

void	(*NotifyActionCallback) ()
#define	NOTIFY_ACTION_CALLBACK()
NotifyNotification *	notify_notification_new ()
gboolean	notify_notification_update ()
gboolean	notify_notification_show ()
void	notify_notification_set_app_name ()
void	notify_notification_set_timeout ()
void	notify_notification_set_category ()
void	notify_notification_set_urgency ()
void	notify_notification_set_icon_from_pixbuf ()
void	notify_notification_set_image_from_pixbuf ()
void	notify_notification_set_hint ()
void	notify_notification_set_hint_int32 ()
void	notify_notification_set_hint_uint32 ()
void	notify_notification_set_hint_double ()
void	notify_notification_set_hint_string ()
void	notify_notification_set_hint_byte ()
void	notify_notification_set_hint_byte_array ()
void	notify_notification_clear_hints ()
void	notify_notification_add_action ()
void	notify_notification_clear_actions ()
gboolean	notify_notification_close ()
const char *	notify_notification_get_activation_token ()
gint	notify_notification_get_closed_reason ()

Properties

char *	app-name	Read / Write
char *	body	Read / Write / Construct
int	closed-reason	Read
char *	icon-name	Read / Write / Construct
int	id	Read / Write / Construct
char *	summary	Read / Write / Construct

Signals

void

closed

Run First

Types and Values

#define	NOTIFY_EXPIRES_DEFAULT
#define	NOTIFY_EXPIRES_NEVER
struct	NotifyNotification
enum	NotifyUrgency

Object Hierarchy

    GObject
    ╰── NotifyNotification

Description

NotifyNotification represents a passive pop-up notification. It can contain summary text, body text, and an icon, as well as hints specifying how the notification should be presented. The notification is rendered by a notification daemon, and may present the notification in any number of ways. As such, there is a clear separation of content and presentation, and this API enforces that.

Functions

NotifyActionCallback ()

void
(*NotifyActionCallback) (NotifyNotification *notification,
                         char *action,
                         gpointer user_data);

An action callback function.

NOTIFY_ACTION_CALLBACK()

#define NOTIFY_ACTION_CALLBACK(func) ((NotifyActionCallback)(func))

A convenience macro for casting a function to a NotifyActionCallback. This is much like G_CALLBACK().

Parameters

func

The function to cast.

notify_notification_new ()

NotifyNotification *
notify_notification_new (const char *summary,
                         const char *body,
                         const char *icon);

Creates a new NotifyNotification. The summary text is required, but all other parameters are optional.

Parameters

summary	The required summary text.
body	The optional body text.	[allow-none]
icon	The optional icon theme icon name or filename.	[allow-none]

Returns

The new NotifyNotification.

notify_notification_update ()

gboolean
notify_notification_update (NotifyNotification *notification,
                            const char *summary,
                            const char *body,
                            const char *icon);

Updates the notification text and icon. This won't send the update out and display it on the screen. For that, you will need to call notify_notification_show().

Parameters

notification	The notification to update.
summary	The new required summary text.
body	The optional body text.	[allow-none]
icon	The optional icon theme icon name or filename.	[allow-none]

Returns

TRUE, unless an invalid parameter was passed.

notify_notification_show ()

gboolean
notify_notification_show (NotifyNotification *notification,
                          GError **error);

Tells the notification server to display the notification on the screen.

Parameters

notification	The notification.
error	The returned error information.

Returns

TRUE if successful. On error, this will return FALSE and set error .

notify_notification_set_app_name ()

void
notify_notification_set_app_name (NotifyNotification *notification,
                                  const char *app_name);

Sets the application name for the notification. If this function is not called or if app_name is NULL, the application name will be set from the value used in notify_init() or overridden with notify_set_app_name().

Parameters

notification	a NotifyNotification
app_name	the localised application name

Since: 0.7.3

notify_notification_set_timeout ()

void
notify_notification_set_timeout (NotifyNotification *notification,
                                 gint timeout);

Sets the timeout of the notification. To set the default time, pass NOTIFY_EXPIRES_DEFAULT as timeout . To set the notification to never expire, pass NOTIFY_EXPIRES_NEVER.

Note that the timeout may be ignored by the server.

Parameters

notification	The notification.
timeout	The timeout in milliseconds.

notify_notification_set_category ()

void
notify_notification_set_category (NotifyNotification *notification,
                                  const char *category);

Sets the category of this notification. This can be used by the notification server to filter or display the data in a certain way.

Parameters

notification	The notification.
category	The category.

notify_notification_set_urgency ()

void
notify_notification_set_urgency (NotifyNotification *notification,
                                 NotifyUrgency urgency);

Sets the urgency level of this notification.

See: NotifyUrgency

Parameters

notification	The notification.
urgency	The urgency level.

notify_notification_set_icon_from_pixbuf ()

void
notify_notification_set_icon_from_pixbuf
                               (NotifyNotification *notification,
                                GdkPixbuf *icon);

notify_notification_set_icon_from_pixbuf is deprecated and should not be used in newly-written code.

use notify_notification_set_image_from_pixbuf() instead.

Sets the icon in the notification from a GdkPixbuf.

Parameters

notification	The notification.
icon	The icon.

notify_notification_set_image_from_pixbuf ()

void
notify_notification_set_image_from_pixbuf
                               (NotifyNotification *notification,
                                GdkPixbuf *pixbuf);

Sets the image in the notification from a GdkPixbuf.

Parameters

notification	The notification.
pixbuf	The image.

notify_notification_set_hint ()

void
notify_notification_set_hint (NotifyNotification *notification,
                              const char *key,
                              GVariant *value);

Sets a hint for key with value value . If value is NULL, a previously set hint for key is unset.

If value is floating, it is consumed.

Parameters

notification	a NotifyNotification
key	the hint key
value	the hint value, or `NULL` to unset the hint.	[allow-none]

Since: 0.6

notify_notification_set_hint_int32 ()

void
notify_notification_set_hint_int32 (NotifyNotification *notification,
                                    const char *key,
                                    gint value);

notify_notification_set_hint_int32 has been deprecated since version 0.6. and should not be used in newly-written code.

Use notify_notification_set_hint() instead

Sets a hint with a 32-bit integer value.

Parameters

notification	The notification.
key	The hint.
value	The hint's value.

notify_notification_set_hint_uint32 ()

void
notify_notification_set_hint_uint32 (NotifyNotification *notification,
                                     const char *key,
                                     guint value);

notify_notification_set_hint_uint32 has been deprecated since version 0.6. and should not be used in newly-written code.

Use notify_notification_set_hint() instead

Sets a hint with an unsigned 32-bit integer value.

Parameters

notification	The notification.
key	The hint.
value	The hint's value.

notify_notification_set_hint_double ()

void
notify_notification_set_hint_double (NotifyNotification *notification,
                                     const char *key,
                                     gdouble value);

notify_notification_set_hint_double has been deprecated since version 0.6. and should not be used in newly-written code.

Use notify_notification_set_hint() instead

Sets a hint with a double value.

Parameters

notification	The notification.
key	The hint.
value	The hint's value.

notify_notification_set_hint_string ()

void
notify_notification_set_hint_string (NotifyNotification *notification,
                                     const char *key,
                                     const char *value);

notify_notification_set_hint_string has been deprecated since version 0.6. and should not be used in newly-written code.

Use notify_notification_set_hint() instead

Sets a hint with a string value.

Parameters

notification	The notification.
key	The hint.
value	The hint's value.

notify_notification_set_hint_byte ()

void
notify_notification_set_hint_byte (NotifyNotification *notification,
                                   const char *key,
                                   guchar value);

notify_notification_set_hint_byte has been deprecated since version 0.6. and should not be used in newly-written code.

Use notify_notification_set_hint() instead

Sets a hint with a byte value.

Parameters

notification	The notification.
key	The hint.
value	The hint's value.

notify_notification_set_hint_byte_array ()

void
notify_notification_set_hint_byte_array
                               (NotifyNotification *notification,
                                const char *key,
                                const guchar *value,
                                gsize len);

notify_notification_set_hint_byte_array has been deprecated since version 0.6. and should not be used in newly-written code.

Use notify_notification_set_hint() instead

Sets a hint with a byte array value. The length of value must be passed as len .

Parameters

notification	The notification.
key	The hint.
value	The hint's value.	[array length=len]
len	The length of the byte array.

notify_notification_clear_hints ()

void
notify_notification_clear_hints (NotifyNotification *notification);

Clears all hints from the notification.

Parameters

notification

The notification.

notify_notification_add_action ()

void
notify_notification_add_action (NotifyNotification *notification,
                                const char *action,
                                const char *label,
                                NotifyActionCallback callback,
                                gpointer user_data,
                                GFreeFunc free_func);

Adds an action to a notification. When the action is invoked, the specified callback function will be called, along with the value passed to user_data .

Parameters

notification	The notification.
action	The action ID.
label	The human-readable action label.
callback	The action's callback function.
user_data	Optional custom data to pass to `callback` .
free_func	An optional function to free `user_data` when the notification is destroyed.	[type GLib.DestroyNotify]

notify_notification_clear_actions ()

void
notify_notification_clear_actions (NotifyNotification *notification);

Clears all actions from the notification.

Parameters

notification

The notification.

notify_notification_close ()

gboolean
notify_notification_close (NotifyNotification *notification,
                           GError **error);

Synchronously tells the notification server to hide the notification on the screen.

Parameters

notification	The notification.
error	The returned error information.

Returns

TRUE on success, or FALSE on error with error filled in

notify_notification_get_activation_token ()

const char *
notify_notification_get_activation_token
                               (NotifyNotification *notification);

If an an action is currently being activated, return the activation token. This function is intended to be used in a NotifyActionCallback to get the activation token for the activated action, if the notification daemon supports it.

Returns

The current activation token, or NULL if none.

[transfer none]

Since: 0.7.10

notify_notification_get_closed_reason ()

gint
notify_notification_get_closed_reason (const NotifyNotification *notification);

Returns the closed reason code for the notification. This is valid only after the "closed" signal is emitted.

Parameters

notification

The notification.

Returns

The closed reason code.

Types and Values

NOTIFY_EXPIRES_DEFAULT

#define NOTIFY_EXPIRES_DEFAULT -1

The default expiration time on a notification.

NOTIFY_EXPIRES_NEVER

#define NOTIFY_EXPIRES_NEVER    0

The notification never expires. It stays open until closed by the calling API or the user.

struct NotifyNotification

struct NotifyNotification;

enum NotifyUrgency

The urgency level of the notification.

Members

NOTIFY_URGENCY_LOW	Low urgency. Used for unimportant notifications.
NOTIFY_URGENCY_NORMAL	Normal urgency. Used for most standard notifications.
NOTIFY_URGENCY_CRITICAL	Critical urgency. Used for very important notifications.

Property Details

The `“app-name”` property

  “app-name”                 char *

The application name to use for this notification.

Owner: NotifyNotification

Flags: Read / Write

Default value: NULL

The `“body”` property

  “body”                     char *

The message body text.

Owner: NotifyNotification

Flags: Read / Write / Construct

Default value: NULL

The `“closed-reason”` property

  “closed-reason”            int

The reason code for why the notification was closed.

Owner: NotifyNotification

Flags: Read

Allowed values: >= -1

Default value: -1

The `“icon-name”` property

  “icon-name”                char *

The icon filename or icon theme-compliant name.

Owner: NotifyNotification

Flags: Read / Write / Construct

Default value: NULL

The `“id”` property

  “id”                       int

The notification ID.

Owner: NotifyNotification

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 0

The `“summary”` property

  “summary”                  char *

The summary text.

Owner: NotifyNotification

Flags: Read / Write / Construct

Default value: NULL

Signal Details

The `“closed”` signal

void
user_function (NotifyNotification *notification,
               gpointer            user_data)

Emitted when the notification is closed.

Parameters

notification	The object which received the signal.
user_data	user data set when the signal handler was connected.

Flags: Run First