NotifyNotification

NotifyNotification — A passive pop-up notification.

Properties

gchar * app-name Read / Write
gchar * body Read / Write / Construct
gint closed-reason Read
gchar * icon-name Read / Write / Construct
gint id Read / Write / Construct
gchar * summary Read / Write / Construct

Signals

Types and Values

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_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”                 gchar *

The application name to use for this notification.

Flags: Read / Write

Default value: NULL


The “body” property

  “body”                     gchar *

The message body text.

Flags: Read / Write / Construct

Default value: NULL


The “closed-reason” property

  “closed-reason”            gint

The reason code for why the notification was closed.

Flags: Read

Allowed values: >= -1

Default value: -1


The “icon-name” property

  “icon-name”                gchar *

The icon filename or icon theme-compliant name.

Flags: Read / Write / Construct

Default value: NULL


The “id” property

  “id”                       gint

The notification ID.

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 0


The “summary” property

  “summary”                  gchar *

The summary text.

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