NotifyNotification

NotifyNotification — A passive pop-up notification.

Synopsis




#define     NOTIFY_EXPIRES_DEFAULT
#define     NOTIFY_EXPIRES_NEVER
            NotifyNotification;
enum        NotifyUrgency;
void        (*NotifyActionCallback)         (NotifyNotification *,
                                             gchar *,
                                             gpointer );
#define     NOTIFY_ACTION_CALLBACK          (func)
NotifyNotification* notify_notification_new (const gchar *summary,
                                             const gchar *body,
                                             const gchar *icon,
                                             GtkWidget *attach);
NotifyNotification* notify_notification_new_with_status_icon
                                            (const gchar *summary,
                                             const gchar *body,
                                             const gchar *icon,
                                             GtkStatusIcon *status_icon);
gboolean    notify_notification_update      (NotifyNotification *notification,
                                             const gchar *summary,
                                             const gchar *body,
                                             const gchar *icon);
void        notify_notification_attach_to_widget
                                            (NotifyNotification *notification,
                                             GtkWidget *attach);
void        notify_notification_attach_to_status_icon
                                            (NotifyNotification *notification,
                                             GtkStatusIcon *status_icon);
void        notify_notification_set_geometry_hints
                                            (NotifyNotification *notification,
                                             GdkScreen *screen,
                                             gint x,
                                             gint y);
gboolean    notify_notification_show        (NotifyNotification *notification,
                                             GError **error);
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_hint_int32
                                            (NotifyNotification *notification,
                                             const gchar *key,
                                             gint value);
void        notify_notification_set_hint_double
                                            (NotifyNotification *notification,
                                             const gchar *key,
                                             gdouble value);
void        notify_notification_set_hint_string
                                            (NotifyNotification *notification,
                                             const gchar *key,
                                             const gchar *value);
void        notify_notification_set_hint_byte
                                            (NotifyNotification *notification,
                                             const gchar *key,
                                             guchar value);
void        notify_notification_set_hint_byte_array
                                            (NotifyNotification *notification,
                                             const gchar *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);

Object Hierarchy


  GObject
   +----NotifyNotification

Properties


  "attach-widget"        GtkWidget             : Read / Write / Construct
  "body"                 gchararray            : Read / Write / Construct
  "icon-name"            gchararray            : Read / Write / Construct
  "status-icon"          GtkStatusIcon         : Read / Write / Construct
  "summary"              gchararray            : Read / Write / Construct

Signals


"closed"    void        user_function      (NotifyNotification *notification,
                                            gpointer            user_data)         : 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.

NotifyNotification

typedef struct _NotifyNotification NotifyNotification;

This is an opaque structure representing a notification. This should not be used directly. Use the accessor functions below.

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 *,
                                             gchar *,
                                             gpointer );

An action callback function.

Param1 : The notification.
Param2 : The action ID.
Param3 : User data.

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 gchar *summary,
                                             const gchar *body,
                                             const gchar *icon,
                                             GtkWidget *attach);

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.
icon : The optional icon theme icon name or filename.
attach : The optional widget to attach to.
Returns : The new NotifyNotification.

notify_notification_new_with_status_icon ()

NotifyNotification* notify_notification_new_with_status_icon
                                            (const gchar *summary,
                                             const gchar *body,
                                             const gchar *icon,
                                             GtkStatusIcon *status_icon);

Creates a new NotifyNotification and attaches to a GtkStatusIcon. The summary text and status_icon is required, but all other parameters are optional.

summary : The required summary text.
body : The optional body text.
icon : The optional icon theme icon name or filename.
status_icon : The required GtkStatusIcon.
Returns : The new NotifyNotification.

Since 0.4.1

notify_notification_update ()

gboolean    notify_notification_update      (NotifyNotification *notification,
                                             const gchar *summary,
                                             const gchar *body,
                                             const gchar *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.
icon : The optional icon theme icon name or filename.
Returns : TRUE, unless an invalid parameter was passed.

notify_notification_attach_to_widget ()

void        notify_notification_attach_to_widget
                                            (NotifyNotification *notification,
                                             GtkWidget *attach);

Attaches the notification to a widget. This will set hints on the notification requesting that the notification point to the widget's location. If attach is NULL, the widget will be unset.

notification : The notification.
attach : The widget to attach to, or NULL.

notify_notification_attach_to_status_icon ()

void        notify_notification_attach_to_status_icon
                                            (NotifyNotification *notification,
                                             GtkStatusIcon *status_icon);

Attaches the notification to a GtkStatusIcon. This will set hints on the notification requesting that the notification point to the status icon's location. If status_icon is NULL, the status icon will be unset.

notification : The notification.
status_icon : The GtkStatusIcon to attach to, or NULL.

Since 0.4.1

notify_notification_set_geometry_hints ()

void        notify_notification_set_geometry_hints
                                            (NotifyNotification *notification,
                                             GdkScreen *screen,
                                             gint x,
                                             gint y);

Sets the geometry hints on the notification. This sets the screen the notification should appear on and the X, Y coordinates it should point to, if the particular notification supports X, Y hints.

notification : The notification.
screen : The GdkScreen the notification should appear on.
x : The X coordinate to point to.
y : The Y coordinate to point to.

Since 0.4.1

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_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.

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

Sets the icon in the notification from a GdkPixbuf.

This will only work when libnotify is compiled against D-BUS 0.60 or higher.

notification : The notification.
icon : The icon.

notify_notification_set_hint_int32 ()

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

Sets a hint with a 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 gchar *key,
                                             gdouble value);

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 gchar *key,
                                             const gchar *value);

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 gchar *key,
                                             guchar value);

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 gchar *key,
                                             const guchar *value,
                                             gsize len);

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.

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

Tells the notification server to hide 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.

Property Details

The "attach-widget" property

  "attach-widget"        GtkWidget             : Read / Write / Construct

The widget to attach the notification to.

The "body" property

  "body"                 gchararray            : Read / Write / Construct

The message body text.

Default value: NULL

The "icon-name" property

  "icon-name"            gchararray            : Read / Write / Construct

The icon filename or icon theme-compliant name.

Default value: NULL

The "status-icon" property

  "status-icon"          GtkStatusIcon         : Read / Write / Construct

The status icon to attach the notification to.

The "summary" property

  "summary"              gchararray            : 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.