NotifyNotification

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