## GNotification GNotification — User Notifications (pop up messages) |

## Functions

GNotification * | g_notification_new ()
void | g_notification_set_title ()
void | g_notification_set_body ()
void | g_notification_set_icon ()
void | g_notification_set_priority ()
void | g_notification_set_urgent ()
void | g_notification_set_category ()
void | g_notification_set_default_action ()
void | g_notification_set_default_action_and_target ()
void | g_notification_set_default_action_and_target_value ()
void | g_notification_add_button ()
void | g_notification_add_button_with_target ()
void | g_notification_add_button_with_target_value ()

## Types and Values

| GNotification
enum | GNotificationPriority

## Object Hierarchy

        GEnum
        ╰── GNotificationPriority
        GObject
        ╰── GNotification

## Includes

    #include <gio/gio.h>

## Description

GNotification is a mechanism for creating a notification to be shown to the user -- typically as a pop-up notification presented by the desktop environment shell.

The key difference between GNotification and other similar APIs is that, if supported by the desktop environment, notifications sent with GNotification will persist after the application has exited, and even across system reboots.

Since the user may click on a notification while the application is not running, applications using GNotification should be able to be started as a D-Bus service, using GApplication.

In order for GNotification to work, the application must have installed a `.desktop` file. For example:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    [Desktop Entry]
     Name=Test Application
     Comment=Description of what Test Application does
     Exec=gnome-test-application
     Icon=org.gnome.TestApplication
     Terminal=false
     Type=Application
     Categories=GNOME;GTK;TestApplication Category;
     StartupNotify=true
     DBusActivatable=true
     X-GNOME-UsesNotifications=true

The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center that this application uses notifications, so it can be listed in the Control Center’s ‘Notifications’ panel.

The `.desktop` file must be named as `org.gnome.TestApplication.desktop`, where `org.gnome.TestApplication` is the ID passed to `g_application_new()`.

User interaction with a notification (either the default action, or buttons) must be associated with actions on the application (ie: "app." actions). It is not possible to route user interaction through the notification itself, because the object will not exist if the application is autostarted as a result of a notification being clicked.

A notification can be sent with `g_application_send_notification()`.

## Functions

### g_notification_new ()

    GNotification *
    g_notification_new (const gchar *title);

Creates a new GNotification with `title` as its title.

After populating `notification` with more details, it can be sent to the desktop shell with `g_application_send_notification()`. Changing any properties after this call will not have any effect until resending `notification` .

#### Parameters

title | the title of the notification |

#### Returns

a new GNotification instance

Since: 2.40

### g_notification_set_title ()

    void
    g_notification_set_title (GNotification *notification,
                              const gchar *title);

Sets the title of `notification` to `title` .

#### Parameters

notification | a GNotification |
title | the new title for `notification` |

Since: 2.40

### g_notification_set_body ()

    void
    g_notification_set_body (GNotification *notification,
                             const gchar *body);

Sets the body of `notification` to `body` .

#### Parameters

notification | a GNotification |
body | the new body for `notification` , or `NULL`. | [nullable]

Since: 2.40

### g_notification_set_icon ()

    void
    g_notification_set_icon (GNotification *notification,
                             GIcon *icon);

Sets the icon of `notification` to `icon` .

#### Parameters

notification | a GNotification |
icon | the icon to be shown in `notification` , as a GIcon |

Since: 2.40

### g_notification_set_priority ()

    void
    g_notification_set_priority (GNotification *notification,
                                 GNotificationPriority priority);

Sets the priority of `notification` to `priority` . See GNotificationPriority for possible values.

#### Parameters

notification | a GNotification |
priority | a GNotificationPriority |

### g_notification_set_urgent ()

    void
    g_notification_set_urgent (GNotification *notification,
                               gboolean urgent);

`g_notification_set_urgent` has been deprecated since version 2.42 and should not be used in newly-written code.

Since 2.42, this has been deprecated in favour of `g_notification_set_priority()`.

Deprecated in favor of `g_notification_set_priority()`.

#### Parameters

notification | a GNotification |
urgent | `TRUE` if `notification` is urgent |

Since: 2.40

### g_notification_set_category ()

    void
    g_notification_set_category (GNotification *notification,
                                 const gchar *category);

Sets the type of `notification` to `category` . Categories have a main type like `email`, `im` or `device` and can have a detail separated by a `.`, e.g. `im.received` or `email.arrived`. Setting the category helps the notification server to select proper feedback to the user.

Standard categories are listed in the specification.

#### Parameters

notification | a GNotification |
category | the category for `notification` , or `NULL` for no category. | [nullable]

Since: 2.70

### g_notification_set_default_action ()

    void
    g_notification_set_default_action (GNotification *notification,
                                       const gchar *detailed_action);

Sets the default action of `notification` to `detailed_action` . This action is activated when the notification is clicked on.

The action in `detailed_action` must be an application-wide action (it must start with "app."). If `detailed_action` contains a target, the given action will be activated with that target as its parameter. See `g_action_parse_detailed_name()` for a description of the format for `detailed_action` .

When no default action is set, the application that the notification was sent on is activated.

#### Parameters

notification | a GNotification |
detailed_action | a detailed action name |

Since: 2.40

### g_notification_set_default_action_and_target ()

    void
    g_notification_set_default_action_and_target
                                   (GNotification *notification,
                                    const gchar *action,
                                    const gchar *target_format,
                                    ...);

Sets the default action of `notification` to `action` . This action is activated when the notification is clicked on. It must be an application-wide action (it must start with "app.").

If `target_format` is given, it is used to collect remaining positional parameters into a GVariant instance, similar to `g_variant_new()`. `action` will be activated with that GVariant as its parameter.

When no default action is set, the application that the notification was sent on is activated.

[skip]

#### Parameters

notification | a GNotification |
action | an action name |
target_format | a GVariant format string, or `NULL`. | [nullable]
... | positional parameters, as determined by `target_format` |

Since: 2.40

### g_notification_set_default_action_and_target_value ()

    void
    g_notification_set_default_action_and_target_value
                                   (GNotification *notification,
                                    const gchar *action,
                                    GVariant *target);

Sets the default action of `notification` to `action` . This action is activated when the notification is clicked on. It must be an application-wide action (start with "app.").

If `target` is non-`NULL`, `action` will be activated with `target` as its parameter.

When no default action is set, the application that the notification was sent on is activated.

[rename-to g_notification_set_default_action_and_target]

#### Parameters

notification | a GNotification |
action | an action name |
target | a GVariant to use as `action` 's parameter, or `NULL`. | [nullable]

Since: 2.40

### g_notification_add_button ()

    void
    g_notification_add_button (GNotification *notification,
                               const gchar *label,
                               const gchar *detailed_action);

Adds a button to `notification` that activates the action in `detailed_action` when clicked. That action must be an application-wide action (starting with "app."). If `detailed_action` contains a target, the action will be activated with that target as its parameter.

See `g_action_parse_detailed_name()` for a description of the format for `detailed_action` .

#### Parameters

notification | a GNotification |
label | label of the button |
detailed_action | a detailed action name |

Since: 2.40

### g_notification_add_button_with_target ()

    void
    g_notification_add_button_with_target (GNotification *notification,
                                           const gchar *label,
                                           const gchar *action,
                                           const gchar *target_format,
                                           ...);

Adds a button to `notification` that activates `action` when clicked. `action` must be an application-wide action (it must start with "app.").

If `target_format` is given, it is used to collect remaining positional parameters into a GVariant instance, similar to `g_variant_new()`. `action` will be activated with that GVariant as its parameter.

[skip]

#### Parameters

notification | a GNotification |
label | label of the button |
action | an action name |
target_format | a GVariant format string, or `NULL`. | [nullable]
... | positional parameters, as determined by `target_format` |

Since: 2.40

### g_notification_add_button_with_target_value ()

    void
    g_notification_add_button_with_target_value
                                   (GNotification *notification,
                                    const gchar *label,
                                    const gchar *action,
                                    GVariant *target);

Adds a button to `notification` that activates `action` when clicked. `action` must be an application-wide action (it must start with "app.").

If `target` is non-`NULL`, `action` will be activated with `target` as its parameter.

[rename-to g_notification_add_button_with_target]

#### Parameters

notification | a GNotification |
label | label of the button |
action | an action name |
target | a GVariant to use as `action` 's parameter, or `NULL`. | [nullable]

Since: 2.40

## Types and Values

### GNotification

    typedef struct _GNotification GNotification;

This structure type is private and should only be accessed using the public APIs.

Since: 2.40

### enum GNotificationPriority

Priority levels for GNotifications.

#### Members

G_NOTIFICATION_PRIORITY_NORMAL | the default priority, to be used for the majority of notifications (for example email messages, software updates, completed download/sync operations) |
G_NOTIFICATION_PRIORITY_LOW | for notifications that do not require immediate attention - typically used for contextual background information, such as contact birthdays or local weather |
G_NOTIFICATION_PRIORITY_HIGH | for events that require more attention, usually because responses are time-sensitive (for example chat and SMS messages or alarms) |
G_NOTIFICATION_PRIORITY_URGENT | for urgent notifications, or notifications that require a response in a short space of time (for example phone calls or emergency warnings) |

Since: 2.42