NotifyNotification: Libnotify Reference Manual

## NotifyNotification NotifyNotification — A passive pop-up notification. |

## Functions

void | (*NotifyActionCallback) ()
#define | NOTIFY_ACTION_CALLBACK()
NotifyNotification * | notify_notification_new ()
gboolean | notify_notification_update ()
gboolean | notify_notification_show ()
void | notify_notification_set_app_name ()
void | notify_notification_set_timeout ()
void | notify_notification_set_category ()
void | notify_notification_set_urgency ()
void | notify_notification_set_icon_from_pixbuf ()
void | notify_notification_set_image_from_pixbuf ()
void | notify_notification_set_hint ()
void | notify_notification_set_hint_int32 ()
void | notify_notification_set_hint_uint32 ()
void | notify_notification_set_hint_double ()
void | notify_notification_set_hint_string ()
void | notify_notification_set_hint_byte ()
void | notify_notification_set_hint_byte_array ()
void | notify_notification_clear_hints ()
void | notify_notification_add_action ()
void | notify_notification_clear_actions ()
gboolean | notify_notification_close ()
gint | notify_notification_get_closed_reason ()

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

void | closed | Run First

## Types and Values

#define | NOTIFY_EXPIRES_DEFAULT
#define | NOTIFY_EXPIRES_NEVER
struct | NotifyNotification
enum | NotifyUrgency

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

Owner: NotifyNotification

Flags: Read / Write

Default value: NULL

### The `“body”` property

      “body”                     gchar *

The message body text.

Owner: NotifyNotification

Flags: Read / Write / Construct

Default value: NULL

### The `“closed-reason”` property

      “closed-reason”            gint

The reason code for why the notification was closed.

Owner: NotifyNotification

Flags: Read

Allowed values: >= -1

Default value: -1

### The `“icon-name”` property

      “icon-name”                gchar *

The icon filename or icon theme-compliant name.

Owner: NotifyNotification

Flags: Read / Write / Construct

Default value: NULL

### The `“id”` property

      “id”                       gint

The notification ID.

Owner: NotifyNotification

Flags: Read / Write / Construct

Allowed values: >= 0

Default value: 0

### The `“summary”` property

      “summary”                  gchar *

The summary text.

Owner: NotifyNotification

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