GtdNotification: GNOME To Do - Reference Manual

## GtdNotification GtdNotification — a notification with actions |

## Stability Level

Stable, unless otherwise indicated

## Functions

void | (*GtdNotificationActionFunc) ()
GtdNotification * | gtd_notification_new ()
void | gtd_notification_execute_primary_action ()
void | gtd_notification_execute_secondary_action ()
void | gtd_notification_start ()
void | gtd_notification_stop ()
void | gtd_notification_set_primary_action ()
void | gtd_notification_set_secondary_action ()
const gchar * | gtd_notification_get_text ()
void | gtd_notification_set_text ()
gdouble | gtd_notification_get_timeout ()
void | gtd_notification_set_timeout ()

## Properties

gboolean | has-primary-action | Read
gboolean | has-secondary-action | Read
gchar * | secondary-action-name | Read / Write
gchar * | text | Read / Write
gdouble | timeout | Read / Write

## Signals

void | executed | Run First

## Types and Values

#define | GTD_TYPE_NOTIFICATION
| GtdNotification

## Object Hierarchy

        GObject
        ╰── GtdObject
            ╰── GtdNotification

## Description

The GtdNotification represents a notification shown at the top of the window. The action can have a primary action that is called when the notification is gone.

Optionally, the notification may have a secondary action (see `gtd_notification_set_secondary_action()`) shown as a button.

The notification may also have a timeout, which is how long the notification is displayed. By default, the timeout is 7.5 seconds.

Example:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    GtdNotification *notification;

    notification = gtd_notification_new ("Something happened!", 7500);

    gtd_notification_set_primary_action (notification,
                                         called_when_notification_is_closed,
                                         self);

    gtd_notification_set_secondary_action (notification,
                                           "Details",
                                           show_details,
                                           self);
    [...]

    gtd_window_send_notification (window, notification);

## Functions

### GtdNotificationActionFunc ()

    void
    (*GtdNotificationActionFunc) (GtdNotification *notification,
                                  gpointer user_data);

Will be called when the primary or secondary action of `notification` is executed.

#### Parameters

notification | the GtdNotification running the function |
user_data | user data. | [closure]

### gtd_notification_new ()

    GtdNotification *
    gtd_notification_new (const gchar *text,
                          gdouble timeout);

Creates a new notification with `text` and `timeout` . If `timeout` is 0, the notification is indefinitely displayed.

#### Parameters

text | text of the notification. | [nullable]
timeout | time for the notification to stay visible |

#### Returns

a new GtdNotification.

[transfer full]

### gtd_notification_execute_primary_action ()

    void
    gtd_notification_execute_primary_action
                                   (GtdNotification *notification);

Executes the primary action of `notification` if set.

#### Parameters

notification | a GtdNotification |

### gtd_notification_execute_secondary_action ()

    void
    gtd_notification_execute_secondary_action
                                   (GtdNotification *notification);

Executes the secondary action of `notification` if any.

#### Parameters

notification | a GtdNotification |

### gtd_notification_start ()

    void
    gtd_notification_start (GtdNotification *notification);

Starts the timeout of notification. Use `gtd_notification_stop()` to stop it.

#### Parameters

notification | a GtdNotification |

### gtd_notification_stop ()

    void
    gtd_notification_stop (GtdNotification *notification);

Stops the timeout of notification. Use `gtd_notification_start()` to start it.

#### Parameters

notification | a GtdNotification |

### gtd_notification_set_primary_action ()

    void
    gtd_notification_set_primary_action (GtdNotification *notification,
                                         GtdNotificationActionFunc func,
                                         gpointer user_data);

Sets the primary action of `notification` , which is triggered on dismiss or timeout.

#### Parameters

notification | a GtdNotification |
func | the primary action function. | [closure user_data][scope call][nullable]
user_data | data passed to `func` |

### gtd_notification_set_secondary_action ()

    void
    gtd_notification_set_secondary_action (GtdNotification *notification,
                                           const gchar *name,
                                           GtdNotificationActionFunc func,
                                           gpointer user_data);

Sets the secondary action of `notification` , which is triggered only on user explicit input.

#### Parameters

notification | a GtdNotification |
name | the name of the secondary action |
func | the secondary action function. | [closure user_data][scope call][nullable]
user_data | data passed to `func` |

### gtd_notification_get_text ()

    const gchar *
    gtd_notification_get_text (GtdNotification *notification);

Gets the text of `notification` .

#### Parameters

notification | a GtdNotification |

#### Returns

the text of `notification` .

[transfer none]

### gtd_notification_set_text ()

    void
    gtd_notification_set_text (GtdNotification *notification,
                               const gchar *text);

Sets the text of `notification` to `text` .

#### Parameters

notification | a GtdNotification |
text | the user-visible text of `notification` |

### gtd_notification_get_timeout ()

    gdouble
    gtd_notification_get_timeout (GtdNotification *notification);

Retrieves the timeout of `notification` .

#### Returns

the timeout of `notification` .

### gtd_notification_set_timeout ()

    void
    gtd_notification_set_timeout (GtdNotification *notification,
                                  gdouble timeout);

Sets the timeout of `notification` to `timeout` . Set it to `0` to disable the timeout.

#### Parameters

notification | a GtdNotification |
timeout | the time to wait before running `notification` , in miliseconds |

## Types and Values

### GTD_TYPE_NOTIFICATION

    #define GTD_TYPE_NOTIFICATION (gtd_notification_get_type())

### GtdNotification

    typedef struct _GtdNotification GtdNotification;

## Property Details

### The `“has-primary-action”` property

      “has-primary-action”       gboolean

Whether the notification has the primary action, activated on timeout or dismiss.

Flags: Read

Default value: FALSE

### The `“has-secondary-action”` property

      “has-secondary-action”     gboolean

Whether the notification has the secondary action, activated by the user.

Flags: Read

Default value: FALSE

### The `“secondary-action-name”` property

      “secondary-action-name”    gchar *

The text of the secondary action button.

Flags: Read / Write

Default value: ""

### The `“text”` property

      “text”                     gchar *

The main message of the notification.

Flags: Read / Write

Default value: ""

### The `“timeout”` property

      “timeout”                  gdouble

The time the notification is displayed.

Flags: Read / Write

Allowed values: [0,30000]

Default value: 7500

## Signal Details

### The `“executed”` signal

    void
    user_function (GtdNotification *arg0,
                   gpointer         user_data)

The ::executed signal is emmited after the primary or secondary GtdNotification action is executed.

#### Parameters

user_data | user data set when the signal handler was connected. |

Flags: Run First