NotifyNotification

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