![]() |
![]() |
![]() |
Libnotify Reference Manual | |
---|---|---|---|---|
#define NOTIFY_EXPIRES_DEFAULT #define NOTIFY_EXPIRES_NEVER NotifyNotification; enum NotifyUrgency; void (*NotifyActionCallback) (NotifyNotification *, gchar *, gpointer ); #define NOTIFY_ACTION_CALLBACK (func) NotifyNotification* notify_notification_new (const gchar *summary, const gchar *body, const gchar *icon, GtkWidget *attach); NotifyNotification* notify_notification_new_with_status_icon (const gchar *summary, const gchar *body, const gchar *icon, GtkStatusIcon *status_icon); gboolean notify_notification_update (NotifyNotification *notification, const gchar *summary, const gchar *body, const gchar *icon); void notify_notification_attach_to_widget (NotifyNotification *notification, GtkWidget *attach); void notify_notification_attach_to_status_icon (NotifyNotification *notification, GtkStatusIcon *status_icon); void notify_notification_set_geometry_hints (NotifyNotification *notification, GdkScreen *screen, gint x, gint y); gboolean notify_notification_show (NotifyNotification *notification, GError **error); 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_hint_int32 (NotifyNotification *notification, const gchar *key, gint value); void notify_notification_set_hint_double (NotifyNotification *notification, const gchar *key, gdouble value); void notify_notification_set_hint_string (NotifyNotification *notification, const gchar *key, const gchar *value); void notify_notification_set_hint_byte (NotifyNotification *notification, const gchar *key, guchar value); void notify_notification_set_hint_byte_array (NotifyNotification *notification, const gchar *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);
"attach-widget" GtkWidget : Read / Write / Construct "body" gchararray : Read / Write / Construct "icon-name" gchararray : Read / Write / Construct "status-icon" GtkStatusIcon : Read / Write / Construct "summary" gchararray : Read / Write / Construct
"closed" void user_function (NotifyNotification *notification, gpointer user_data) : Run first
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.
#define NOTIFY_EXPIRES_DEFAULT -1
The default expiration time on a notification.
#define NOTIFY_EXPIRES_NEVER 0
The notification never expires. It stays open until closed by the calling API or the user.
typedef struct _NotifyNotification NotifyNotification;
This is an opaque structure representing a notification. This should not be used directly. Use the accessor functions below.
typedef enum { NOTIFY_URGENCY_LOW, NOTIFY_URGENCY_NORMAL, NOTIFY_URGENCY_CRITICAL, } NotifyUrgency;
The urgency level of the notification.
void (*NotifyActionCallback) (NotifyNotification *, gchar *, gpointer );
An action callback function.
Param1 : |
The notification. |
Param2 : |
The action ID. |
Param3 : |
User data. |
#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. |
NotifyNotification* notify_notification_new (const gchar *summary, const gchar *body, const gchar *icon, GtkWidget *attach);
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. |
icon : |
The optional icon theme icon name or filename. |
attach : |
The optional widget to attach to. |
Returns : | The new NotifyNotification. |
NotifyNotification* notify_notification_new_with_status_icon (const gchar *summary, const gchar *body, const gchar *icon, GtkStatusIcon *status_icon);
Creates a new NotifyNotification and attaches to a GtkStatusIcon.
The summary text and status_icon
is required, but all other parameters
are optional.
summary : |
The required summary text. |
body : |
The optional body text. |
icon : |
The optional icon theme icon name or filename. |
status_icon : |
The required GtkStatusIcon. |
Returns : | The new NotifyNotification. |
Since 0.4.1
gboolean notify_notification_update (NotifyNotification *notification, const gchar *summary, const gchar *body, const gchar *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. |
icon : |
The optional icon theme icon name or filename. |
Returns : | TRUE , unless an invalid parameter was passed.
|
void notify_notification_attach_to_widget (NotifyNotification *notification, GtkWidget *attach);
Attaches the notification to a widget. This will set hints on the
notification requesting that the notification point to the widget's
location. If attach
is NULL
, the widget will be unset.
notification : |
The notification. |
attach : |
The widget to attach to, or NULL .
|
void notify_notification_attach_to_status_icon (NotifyNotification *notification, GtkStatusIcon *status_icon);
Attaches the notification to a GtkStatusIcon. This will set hints on the
notification requesting that the notification point to the status icon's
location. If status_icon
is NULL
, the status icon will be unset.
notification : |
The notification. |
status_icon : |
The GtkStatusIcon to attach to, or NULL .
|
Since 0.4.1
void notify_notification_set_geometry_hints (NotifyNotification *notification, GdkScreen *screen, gint x, gint y);
Sets the geometry hints on the notification. This sets the screen the notification should appear on and the X, Y coordinates it should point to, if the particular notification supports X, Y hints.
notification : |
The notification. |
screen : |
The GdkScreen the notification should appear on. |
x : |
The X coordinate to point to. |
y : |
The Y coordinate to point to. |
Since 0.4.1
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 .
|
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
.
notification : |
The notification. |
timeout : |
The timeout in milliseconds. |
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. |
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. |
void notify_notification_set_icon_from_pixbuf (NotifyNotification *notification, GdkPixbuf *icon);
Sets the icon in the notification from a GdkPixbuf.
This will only work when libnotify is compiled against D-BUS 0.60 or higher.
notification : |
The notification. |
icon : |
The icon. |
void notify_notification_set_hint_int32 (NotifyNotification *notification, const gchar *key, gint value);
Sets a hint with a 32-bit integer value.
notification : |
The notification. |
key : |
The hint. |
value : |
The hint's value. |
void notify_notification_set_hint_double (NotifyNotification *notification, const gchar *key, gdouble value);
Sets a hint with a double value.
notification : |
The notification. |
key : |
The hint. |
value : |
The hint's value. |
void notify_notification_set_hint_string (NotifyNotification *notification, const gchar *key, const gchar *value);
Sets a hint with a string value.
notification : |
The notification. |
key : |
The hint. |
value : |
The hint's value. |
void notify_notification_set_hint_byte (NotifyNotification *notification, const gchar *key, guchar value);
Sets a hint with a byte value.
notification : |
The notification. |
key : |
The hint. |
value : |
The hint's value. |
void notify_notification_set_hint_byte_array (NotifyNotification *notification, const gchar *key, const guchar *value, gsize len);
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. |
void notify_notification_clear_hints (NotifyNotification *notification);
Clears all hints from the notification.
notification : |
The notification. |
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.
|
void notify_notification_clear_actions (NotifyNotification *notification);
Clears all actions from the notification.
notification : |
The notification. |
gboolean notify_notification_close (NotifyNotification *notification, GError **error);
Tells the notification server to hide 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 .
|
attach-widget
" property"attach-widget" GtkWidget : Read / Write / Construct
The widget to attach the notification to.
body
" property"body" gchararray : Read / Write / Construct
The message body text.
Default value: NULL
icon-name
" property"icon-name" gchararray : Read / Write / Construct
The icon filename or icon theme-compliant name.
Default value: NULL
status-icon
" property"status-icon" GtkStatusIcon : Read / Write / Construct
The status icon to attach the notification to.
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. |