IdeNotification: Builder SDK Reference

## IdeNotification IdeNotification |

## Functions

IdeNotification * | ide_notification_new ()
void | ide_notification_attach ()
gchar * | ide_notification_dup_id ()
void | ide_notification_set_id ()
gchar * | ide_notification_dup_title ()
void | ide_notification_set_title ()
GIcon * | ide_notification_ref_icon ()
void | ide_notification_set_icon ()
void | ide_notification_set_icon_name ()
gchar * | ide_notification_dup_body ()
void | ide_notification_set_body ()
gboolean | ide_notification_get_has_progress ()
void | ide_notification_set_has_progress ()
gint | ide_notification_get_priority ()
void | ide_notification_set_priority ()
gdouble | ide_notification_get_progress ()
void | ide_notification_set_progress ()
gboolean | ide_notification_get_progress_is_imprecise ()
void | ide_notification_set_progress_is_imprecise ()
gboolean | ide_notification_get_urgent ()
void | ide_notification_set_urgent ()
guint | ide_notification_get_n_buttons ()
gboolean | ide_notification_get_button ()
void | ide_notification_add_button ()
void | ide_notification_add_button_with_target_value ()
gboolean | ide_notification_get_default_action ()
void | ide_notification_set_default_action ()
void | ide_notification_set_default_action_and_target_value ()
gint | ide_notification_compare ()
void | ide_notification_withdraw ()
void | ide_notification_withdraw_in_seconds ()
void | ide_notification_file_progress_callback ()
void | ide_notification_flatpak_progress_callback ()

## Properties

gchar * | body | Read / Write
gboolean | has-progress | Read / Write
GIcon * | icon | Read / Write
gchar * | icon-name | Write
gchar * | id | Read / Write
gint | priority | Read / Write
gdouble | progress | Read / Write
gboolean | progress-is-imprecise | Read / Write
gchar * | title | Read / Write
gboolean | urgent | Read / Write

## Types and Values

#define | IDE_TYPE_NOTIFICATION
struct | IdeNotificationClass
| IdeNotification

## Object Hierarchy

        GObject
        ╰── IdeObject
            ╰── IdeNotification

## Description

## Functions

### ide_notification_new ()

    IdeNotification *
    ide_notification_new (void);

Creates a new IdeNotification.

To "send" the notification, you should attach it to the IdeNotifications object which can be found under the root IdeObject. To simplify this, the `ide_notification_attach()` function is provided to locate the IdeNotifications object using any IdeObject you have access to.

`IdeNotification *notif = `ide_notification_new()`; setup_notification (notify); ide_notification_attach (notif, IDE_OBJECT (some_object));`

Since: 3.32

### ide_notification_attach ()

    void
    ide_notification_attach (IdeNotification *self,
                             IdeObject *object);

This function will locate the IdeNotifications object starting from `object` and attach `self` as a child to that object.

#### Parameters

self | an IdeNotifications |
object | an IdeObject |

Since: 3.32

### ide_notification_dup_id ()

    gchar *
    ide_notification_dup_id (IdeNotification *self);

Copies the id of the notification and returns it to the caller after locking the object. A copy is used to avoid thread-races.

Since: 3.32

### ide_notification_set_id ()

    void
    ide_notification_set_id (IdeNotification *self,
                             const gchar *id);

Sets the “id” property.

#### Parameters

self | an IdeNotification |
id | a string containing the id, or `NULL`. | [nullable]

Since: 3.32

### ide_notification_dup_title ()

    gchar *
    ide_notification_dup_title (IdeNotification *self);

Copies the current title and returns it to the caller after locking the object. A copy is used to avoid thread-races.

Since: 3.32

### ide_notification_set_title ()

    void
    ide_notification_set_title (IdeNotification *self,
                                const gchar *title);

Sets the “title” property.

#### Parameters

self | an IdeNotification |
title | a string containing the title text, or `NULL`. | [nullable]

Since: 3.32

### ide_notification_ref_icon ()

    GIcon *
    ide_notification_ref_icon (IdeNotification *self);

Gets the icon for the notification, and returns a new reference to the GIcon.

#### Returns

a GIcon or `NULL`.

[transfer full][nullable]

Since: 3.32

### ide_notification_set_icon ()

    void
    ide_notification_set_icon (IdeNotification *self,
                               GIcon *icon);

### ide_notification_set_icon_name ()

    void
    ide_notification_set_icon_name (IdeNotification *self,
                                    const gchar *icon_name);

### ide_notification_dup_body ()

    gchar *
    ide_notification_dup_body (IdeNotification *self);

Copies the current body and returns it to the caller after locking the object. A copy is used to avoid thread-races.

Since: 3.32

### ide_notification_set_body ()

    void
    ide_notification_set_body (IdeNotification *self,
                               const gchar *body);

Sets the “body” property.

#### Parameters

self | an IdeNotification |
body | a string containing the body text, or `NULL`. | [nullable]

Since: 3.32

### ide_notification_get_has_progress ()

    gboolean
    ide_notification_get_has_progress (IdeNotification *self);

Gets if the notification supports progress updates.

#### Parameters

self | a IdeNotification |

#### Returns

`TRUE` if progress updates are supported.

Since: 3.32

### ide_notification_set_has_progress ()

    void
    ide_notification_set_has_progress (IdeNotification *self,
                                       gboolean has_progress);

Set to `TRUE` if the notification supports progress updates.

#### Parameters

self | a IdeNotification |
has_progress | if `notification` supports progress |

Since: 3.32

### ide_notification_get_priority ()

    gint
    ide_notification_get_priority (IdeNotification *self);

### ide_notification_set_priority ()

    void
    ide_notification_set_priority (IdeNotification *self,
                                   gint priority);

### ide_notification_get_progress ()

    gdouble
    ide_notification_get_progress (IdeNotification *self);

Gets the progress for the notification.

#### Parameters

self | a IdeNotification |

#### Returns

a value between 0.0 and 1.0

Since: 3.32

### ide_notification_set_progress ()

    void
    ide_notification_set_progress (IdeNotification *self,
                                   gdouble progress);

Sets the progress for the notification.

#### Parameters

self | a IdeNotification |
progress | a value between 0.0 and 1.0 |

Since: 3.32

### ide_notification_get_progress_is_imprecise ()

    gboolean
    ide_notification_get_progress_is_imprecise
                                   (IdeNotification *self);

### ide_notification_set_progress_is_imprecise ()

    void
    ide_notification_set_progress_is_imprecise
                                   (IdeNotification *self,
                                    gboolean progress_is_imprecise);

### ide_notification_get_urgent ()

    gboolean
    ide_notification_get_urgent (IdeNotification *self);

### ide_notification_set_urgent ()

    void
    ide_notification_set_urgent (IdeNotification *self,
                                 gboolean urgent);

### ide_notification_get_n_buttons ()

    guint
    ide_notification_get_n_buttons (IdeNotification *self);

### ide_notification_get_button ()

    gboolean
    ide_notification_get_button (IdeNotification *self,
                                 guint button,
                                 gchar **label,
                                 GIcon **icon,
                                 gchar **action,
                                 GVariant **target);

Gets the button indexed by `button` , and stores information about the button into the various out parameters `label` , `icon` , `action` , and `target` .

Caller should check for the number of buttons using `ide_notification_get_n_buttons()` to determine the numerical range of indexes to provide for `button` .

To avoid racing with threads modifying notifications, the caller can hold a recursive lock across the function calls using `ide_object_lock()` and `ide_object_unlock()`.

#### Parameters

self | an IdeNotification |
label | a location for the button label. | [out][optional]
icon | a location for the button icon. | [out][optional]
action | a location for the button action name. | [out][optional]
target | a location for the button action target. | [out][optional]

#### Returns

`TRUE` if `button` was found; otherwise `FALSE`

Since: 3.32

### ide_notification_add_button ()

    void
    ide_notification_add_button (IdeNotification *self,
                                 const gchar *label,
                                 GIcon *icon,
                                 const gchar *detailed_action);

Adds a new button that may be displayed with the notification.

See also: `ide_notification_add_button_with_target_value()`.

#### Parameters

self | an IdeNotification |
label | the label for the button |
icon | an optional icon for the button. | [nullable]
detailed_action | a detailed action name (See GAction) |

Since: 3.32

### ide_notification_add_button_with_target_value ()

    void
    ide_notification_add_button_with_target_value
                                   (IdeNotification *self,
                                    const gchar *label,
                                    GIcon *icon,
                                    const gchar *action,
                                    GVariant *target);

Adds a new button, used the parsed GVariant format for the action target.

#### Parameters

self | an IdeNotification |
label | the label for the button |
icon | an optional icon for the button. | [nullable]
action | an action name (See GAction) |
target | an optional GVariant for the action target. | [nullable]

Since: 3.32

### ide_notification_get_default_action ()

    gboolean
    ide_notification_get_default_action (IdeNotification *self,
                                         gchar **action,
                                         GVariant **target);

### ide_notification_set_default_action ()

    void
    ide_notification_set_default_action (IdeNotification *self,
                                         const gchar *detailed_action);

### ide_notification_set_default_action_and_target_value ()

    void
    ide_notification_set_default_action_and_target_value
                                   (IdeNotification *self,
                                    const gchar *action,
                                    GVariant *target);

### ide_notification_compare ()

    gint
    ide_notification_compare (IdeNotification *a,
                              IdeNotification *b);

### ide_notification_withdraw ()

    void
    ide_notification_withdraw (IdeNotification *self);

Withdraws the notification by removing it from the IdeObject parent it belongs to.

#### Parameters

self | a IdeNotification |

Since: 3.32

### ide_notification_withdraw_in_seconds ()

    void
    ide_notification_withdraw_in_seconds (IdeNotification *self,
                                          gint seconds);

Withdraws `self` from it's IdeObject parent after `seconds` have passed.

#### Parameters

self | a IdeNotification |
seconds | number of seconds to withdraw after, or less than zero for a sensible default. |

Since: 3.32

### ide_notification_file_progress_callback ()

    void
    ide_notification_file_progress_callback
                                   (goffset current_num_bytes,
                                    goffset total_num_bytes,
                                    gpointer user_data);

This function is a GFileProgressCallback helper that will update the “fraction” property. `user_data` must be an IdeNotification.

Remember to make sure to unref the IdeNotification instance with `g_object_unref()` during the GDestroyNotify.

Since: 3.32

### ide_notification_flatpak_progress_callback ()

    void
    ide_notification_flatpak_progress_callback
                                   (const char *status,
                                    guint notification,
                                    gboolean estimating,
                                    gpointer user_data);

## Types and Values

### IDE_TYPE_NOTIFICATION

    #define IDE_TYPE_NOTIFICATION (ide_notification_get_type())

### struct IdeNotificationClass

    struct IdeNotificationClass {
      IdeObjectClass parent_class;

      /*< private */
      gpointer _reserved[16];
    };

### IdeNotification

    typedef struct _IdeNotification IdeNotification;

## Property Details

### The `“body”` property

      “body”                     gchar *

The "body" property is the main body of text for the notification. Not all notifications need this, but more complex notifications might.

Flags: Read / Write

Default value: NULL

Since: 3.32

### The `“has-progress”` property

      “has-progress”             gboolean

The "has-progress" property denotes the notification will receive updates to the “progress” property.

Flags: Read / Write

Default value: FALSE

Since: 3.32

### The `“icon”` property

      “icon”                     GIcon *

The "icon" property is an optional icon that may be shown next to the notification title and body under certain senarios.

Flags: Read / Write

Since: 3.32

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

      “icon-name”                gchar *

The "icon-name" property is a helper to make setting “icon” more convenient.

Flags: Write

Default value: NULL

Since: 3.32

### The `“id”` property

      “id”                       gchar *

The "id" property is an optional identifier that can be used to locate the notification later.

Flags: Read / Write

Default value: NULL

Since: 3.32

### The `“priority”` property

      “priority”                 gint

The "priority" property is used to sort the notification in order of importance when displaying to the user.

You may also use the “urgent” property to raise the importance of a message to the user.

Flags: Read / Write

Default value: 0

Since: 3.32

### The `“progress”` property

      “progress”                 gdouble

The "progress" property is a value between 0.0 and 1.0 describing the progress of the operation for which the notification represents.

This property is ignored if “has-progress” is unset.

Flags: Read / Write

Allowed values: [0,1]

Default value: 0

Since: 3.32

### The `“progress-is-imprecise”` property

      “progress-is-imprecise”    gboolean

The "progress-is-imprecise" property indicates that the notification has progress, but it is imprecise.

The UI may show a bouncing progress bar if set.

Flags: Read / Write

Default value: FALSE

Since: 3.32

### The `“title”` property

      “title”                    gchar *

The "title" property is the main text to show the user. It may be displayed more prominently such as in the titlebar.

Flags: Read / Write

Default value: NULL

Since: 3.32

### The `“urgent”` property

      “urgent”                   gboolean

If the notification is urgent. These notifications will be displayed with higher priority than those without the urgent property set.

Flags: Read / Write

Default value: FALSE

Since: 3.32