NotifyNotification

NotifyNotification — A passive pop-up notification.

Synopsis

#define             NOTIFY_EXPIRES_DEFAULT
#define             NOTIFY_EXPIRES_NEVER
struct              NotifyNotification;
enum                NotifyUrgency;
void                (*NotifyActionCallback)             (NotifyNotification *notification,
                                                         char *action,
                                                         gpointer user_data);
#define             NOTIFY_ACTION_CALLBACK              (func)
NotifyNotification * notify_notification_new            (const char *summary,
                                                         const char *body,
                                                         const char *icon);
gboolean            notify_notification_update          (NotifyNotification *notification,
                                                         const char *summary,
                                                         const char *body,
                                                         const char *icon);
gboolean            notify_notification_show            (NotifyNotification *notification,
                                                         GError **error);
void                notify_notification_set_app_name    (NotifyNotification *notification,
                                                         const char *app_name);
void                notify_notification_set_timeout     (NotifyNotification *notification,
                                                         gint timeout);
void                notify_notification_set_category    (NotifyNotification *notification,
                                                         const char *category);
void                notify_notification_set_urgency     (NotifyNotification *notification,
                                                         NotifyUrgency urgency);
void                notify_notification_set_icon_from_pixbuf
                                                        (NotifyNotification *notification,
                                                         GdkPixbuf *icon);
void                notify_notification_set_image_from_pixbuf
                                                        (NotifyNotification *notification,
                                                         GdkPixbuf *pixbuf);
void                notify_notification_set_hint        (NotifyNotification *notification,
                                                         const char *key,
                                                         GVariant *value);
void                notify_notification_set_hint_int32  (NotifyNotification *notification,
                                                         const char *key,
                                                         gint value);
void                notify_notification_set_hint_uint32 (NotifyNotification *notification,
                                                         const char *key,
                                                         guint value);
void                notify_notification_set_hint_double (NotifyNotification *notification,
                                                         const char *key,
                                                         gdouble value);
void                notify_notification_set_hint_string (NotifyNotification *notification,
                                                         const char *key,
                                                         const char *value);
void                notify_notification_set_hint_byte   (NotifyNotification *notification,
                                                         const char *key,
                                                         guchar value);
void                notify_notification_set_hint_byte_array
                                                        (NotifyNotification *notification,
                                                         const char *key,
                                                         const guchar *value,
                                                         gsize len);
void                notify_notification_clear_hints     (NotifyNotification *notification);
void                notify_notification_add_action      (NotifyNotification *notification,
                                                         const char *action,
                                                         const char *label,
                                                         NotifyActionCallback callback,
                                                         gpointer user_data,
                                                         GFreeFunc free_func);
void                notify_notification_clear_actions   (NotifyNotification *notification);
gboolean            notify_notification_close           (NotifyNotification *notification,
                                                         GError **error);
gint                notify_notification_get_closed_reason
                                                        (const NotifyNotification *notification);

Object Hierarchy

  GObject
   +----NotifyNotification

Properties

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

Signals

  "closed"                                         : Run First

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.

Details

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

typedef enum {
        NOTIFY_URGENCY_LOW,
        NOTIFY_URGENCY_NORMAL,
        NOTIFY_URGENCY_CRITICAL,
} NotifyUrgency;

The urgency level of the notification.

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.

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().

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.

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().

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.

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().

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.

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.

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

notification :

The notification.

urgency :

The urgency level.

notify_notification_set_icon_from_pixbuf ()

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

Warning

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.

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.

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.

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);

Warning

notify_notification_set_hint_int32 is deprecated and should not be used in newly-written code. 0.6. Use notify_notification_set_hint() instead

Sets a hint with a 32-bit integer value.

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);

Warning

notify_notification_set_hint_uint32 is deprecated and should not be used in newly-written code. 0.6. Use notify_notification_set_hint() instead

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

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);

Warning

notify_notification_set_hint_double is deprecated and should not be used in newly-written code. 0.6. Use notify_notification_set_hint() instead

Sets a hint with a double value.

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);

Warning

notify_notification_set_hint_string is deprecated and should not be used in newly-written code. 0.6. Use notify_notification_set_hint() instead

Sets a hint with a string value.

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);

Warning

notify_notification_set_hint_byte is deprecated and should not be used in newly-written code. 0.6. Use notify_notification_set_hint() instead

Sets a hint with a byte value.

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);

Warning

notify_notification_set_hint_byte_array is deprecated and should not be used in newly-written code. 0.6. Use notify_notification_set_hint() instead

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

notification :

The notification.

key :

The hint.

value :

The hint's value.

len :

The length of the byte array.

notify_notification_clear_hints ()

void                notify_notification_clear_hints     (NotifyNotification *notification);

Clears all hints from the notification.

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.

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.

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.

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.

notification :

The notification.

Returns :

The closed reason code.

Property Details

The "app-name" property

  "app-name"                 gchar*                : Read / Write

The application name to use for this notification.

Default value: NULL


The "body" property

  "body"                     gchar*                : Read / Write / Construct

The message body text.

Default value: NULL


The "closed-reason" property

  "closed-reason"            gint                  : Read

The reason code for why the notification was closed.

Allowed values: >= -1

Default value: -1


The "icon-name" property

  "icon-name"                gchar*                : Read / Write / Construct

The icon filename or icon theme-compliant name.

Default value: NULL


The "id" property

  "id"                       gint                  : Read / Write / Construct

The notification ID.

Allowed values: >= 0

Default value: 0


The "summary" property

  "summary"                  gchar*                : Read / Write / Construct

The summary text.

Default value: NULL

Signal Details

The "closed" signal

void                user_function                      (NotifyNotification *notification,
                                                        gpointer            user_data)         : Run First

Emitted when the notification is closed.

notification :

The object which received the signal.

user_data :

user data set when the signal handler was connected.