jcarr
/
libnotify
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Provide more documentation.

This commit is contained in:
Christian Hammond 2006-06-06 08:29:32 +00:00
parent 2ef25f78f9
commit 629f6e08ca
6 changed files with 230 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
ChangeLog
View File

@ -1,3 +1,12 @@
Tue Jun 06 01:29:20 PDT 2006 Christian Hammond <chipx86@chipx86.com>
* docs/reference/libnotify-sections.txt:
* docs/reference/tmpl/notification.sgml:
* docs/reference/tmpl/notify.sgml:
* libnotify/notification.c:
* libnotify/notification.h:
- Provide more documentation.
Tue Jun 06 00:27:50 PDT 2006 Christian Hammond <chipx86@chipx86.com>
* docs/reference/tmpl/notification.sgml:

1
docs/reference/libnotify-sections.txt
View File

@ -2,7 +2,6 @@
<FILE>notification</FILE>
NOTIFY_EXPIRES_DEFAULT
NOTIFY_EXPIRES_NEVER
NotifyNotificationPrivate
<TITLE>NotifyNotification</TITLE>
NotifyNotification
NotifyUrgency

47
docs/reference/tmpl/notification.sgml
View File

@ -2,11 +2,16 @@
NotifyNotification
<!-- ##### SECTION Short_Description ##### -->
A passive pop-up notification.
<!-- ##### SECTION Long_Description ##### -->
<para>
#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.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -19,57 +24,57 @@ NotifyNotification
<!-- ##### MACRO NOTIFY_EXPIRES_DEFAULT ##### -->
<para>
The default expiration time on a notification.
</para>
<!-- ##### MACRO NOTIFY_EXPIRES_NEVER ##### -->
<para>
The notification never expires. It stays open until closed by the calling API
or the user.
</para>
<!-- ##### STRUCT NotifyNotificationPrivate ##### -->
<para>
</para>
<!-- ##### STRUCT NotifyNotification ##### -->
<para>
This is an opaque structure representing a notification. This should
not be used directly. Use the accessor functions below.
</para>
@parent:
@priv:
@parent: The parent object.
@priv: Private data.
<!-- ##### ENUM NotifyUrgency ##### -->
<para>
The urgency level of the notification.
</para>
@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.
<!-- ##### USER_FUNCTION NotifyActionCallback ##### -->
<para>
An action callback function.
</para>
@Param1:
@Param2:
@Param3:
@Param1: The notification.
@Param2: The action ID.
@Param3: User data.
<!-- ##### MACRO NOTIFY_ACTION_CALLBACK ##### -->
<para>
A convenience macro for casting a function to a #NotifyActionCallback. This
is much like #G_CALLBACK().
</para>
@func:
@func: The function to cast.
<!-- ##### FUNCTION notify_notification_new ##### -->
@ -171,7 +176,7 @@ NotifyNotification
</para>
@notification:
@l:
@urgency:
<!-- ##### FUNCTION notify_notification_set_icon_from_pixbuf ##### -->

2
docs/reference/tmpl/notify.sgml
View File

@ -2,7 +2,7 @@
notify
<!-- ##### SECTION Short_Description ##### -->
Notification API
<!-- ##### SECTION Long_Description ##### -->
<para>

256
libnotify/notification.c
View File

@ -142,7 +142,12 @@ notify_notification_class_init(NotifyNotificationClass *klass)
object_class->set_property = notify_notification_set_property;
object_class->finalize = notify_notification_finalize;
/* Create signals here: */
/**
* NotifyNotification::closed:
* @notification: The object which received the signal.
*
* Emitted when the notification is closed.
*/
signals[SIGNAL_CLOSED] =
g_signal_new("closed",
G_TYPE_FROM_CLASS(object_class),
@ -151,71 +156,59 @@ notify_notification_class_init(NotifyNotificationClass *klass)
NULL, NULL,
g_cclosure_marshal_VOID__VOID, G_TYPE_NONE, 0);
g_object_class_install_property
(object_class,
PROP_SUMMARY,
g_param_spec_string("summary",
"Summary",
"Summary",
NULL,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT |
G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK |
G_PARAM_STATIC_BLURB));
g_object_class_install_property(object_class, PROP_SUMMARY,
g_param_spec_string("summary", "Summary",
"The summary text",
NULL,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT |
G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK |
G_PARAM_STATIC_BLURB));
g_object_class_install_property
(object_class,
PROP_BODY,
g_param_spec_string("body",
"Message Body",
"Message body",
NULL,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT |
G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK |
G_PARAM_STATIC_BLURB));
g_object_class_install_property(object_class, PROP_BODY,
g_param_spec_string("body", "Message Body",
"The message body text",
NULL,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT |
G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK |
G_PARAM_STATIC_BLURB));
g_object_class_install_property
(object_class,
PROP_ICON_NAME,
g_param_spec_string("icon-name",
"Icon Name",
"Icon name",
NULL,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT |
G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK |
G_PARAM_STATIC_BLURB));
g_object_class_install_property(object_class, PROP_ICON_NAME,
g_param_spec_string("icon-name",
"Icon Name",
"The icon filename or icon theme-compliant name",
NULL,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT |
G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK |
G_PARAM_STATIC_BLURB));
g_object_class_install_property
(object_class,
PROP_ATTACH_WIDGET,
g_param_spec_object("attach-widget",
"Attach Widget",
"Attach Widget",
GTK_TYPE_WIDGET,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT |
G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK |
G_PARAM_STATIC_BLURB));
g_object_class_install_property(object_class, PROP_ATTACH_WIDGET,
g_param_spec_object("attach-widget",
"Attach Widget",
"The widget to attach the notification to",
GTK_TYPE_WIDGET,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT |
G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK |
G_PARAM_STATIC_BLURB));
#ifdef HAVE_STATUS_ICON
g_object_class_install_property
(object_class,
PROP_STATUS_ICON,
g_param_spec_object("status-icon",
"Status Icon",
"Status Icon",
GTK_TYPE_STATUS_ICON,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT |
G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK |
G_PARAM_STATIC_BLURB));
g_object_class_install_property(object_class, PROP_STATUS_ICON,
g_param_spec_object("status-icon",
"Status Icon",
"The status icon to attach the notification to",
GTK_TYPE_STATUS_ICON,
G_PARAM_READWRITE |
G_PARAM_CONSTRUCT |
G_PARAM_STATIC_NAME |
G_PARAM_STATIC_NICK |
G_PARAM_STATIC_BLURB));
#endif /* HAVE_STATUS_ICON */
}
@ -638,6 +631,19 @@ notify_notification_attach_to_status_icon(NotifyNotification *notification,
}
#endif /* HAVE_STATUS_ICON */
/**
* notify_notification_set_geometry_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.
*
* 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.
*
* Since: 0.4.1
*/
void
notify_notification_set_geometry_hints(NotifyNotification *notification,
GdkScreen *screen,
@ -706,6 +712,16 @@ _gslist_to_string_array(GSList *list)
return (gchar **)g_array_free(a, FALSE);
}
/**
* notify_notification_show:
* @notification: The notification.
* @error: The returned error information.
*
* Tells the notification server to display the notification on the screen.
*
* Returns: %TRUE if successful. On error, this will return %FALSE and set
* @error.
*/
gboolean
notify_notification_show(NotifyNotification *notification, GError **error)
{
@ -766,6 +782,15 @@ notify_notification_show(NotifyNotification *notification, GError **error)
return TRUE;
}
/**
* notify_notification_set_timeout:
* @notification: The notification.
* @timeout: The timeout in milliseconds.
*
* 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.
*/
void
notify_notification_set_timeout(NotifyNotification *notification,
gint timeout)
@ -785,6 +810,14 @@ _notify_notification_get_timeout(const NotifyNotification *notification)
return notification->priv->timeout;
}
/**
* notify_notification_set_category:
* @notification: The notification.
* @category: The 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.
*/
void
notify_notification_set_category(NotifyNotification *notification,
const char *category)
@ -795,14 +828,23 @@ notify_notification_set_category(NotifyNotification *notification,
notify_notification_set_hint_string(notification, "category", category);
}
/**
* notify_notification_set_urgency:
* @notification: The notification.
* @urgency: The urgency level.
*
* Sets the urgency level of this notification.
*
* See: #NotifyUrgency
*/
void
notify_notification_set_urgency(NotifyNotification *notification,
NotifyUrgency l)
NotifyUrgency urgency)
{
g_return_if_fail(notification != NULL);
g_return_if_fail(NOTIFY_IS_NOTIFICATION(notification));
notify_notification_set_hint_byte(notification, "urgency", (guchar)l);
notify_notification_set_hint_byte(notification, "urgency", (guchar)urgency);
}
#if CHECK_DBUS_VERSION(0, 60)
@ -863,6 +905,16 @@ _gvalue_array_append_byte_array(GValueArray *array, guchar *bytes, gsize len)
}
#endif /* D-BUS >= 0.60 */
/**
* notify_notification_set_icon_from_pixbuf:
* @notification: The notification.
* @icon: The 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.
*/
void
notify_notification_set_icon_from_pixbuf(NotifyNotification *notification,
GdkPixbuf *icon)
@ -914,6 +966,14 @@ notify_notification_set_icon_from_pixbuf(NotifyNotification *notification,
#endif
}
/**
* notify_notification_set_hint_int32:
* @notification: The notification.
* @key: The hint.
* @value: The hint's value.
*
* Sets a hint with a 32-bit integer value.
*/
void
notify_notification_set_hint_int32(NotifyNotification *notification,
const gchar *key, gint value)
@ -931,6 +991,14 @@ notify_notification_set_hint_int32(NotifyNotification *notification,
g_strdup(key), hint_value);
}
/**
* notify_notification_set_hint_double:
* @notification: The notification.
* @key: The hint.
* @value: The hint's value.
*
* Sets a hint with a double value.
*/
void
notify_notification_set_hint_double(NotifyNotification *notification,
const gchar *key, gdouble value)
@ -948,6 +1016,14 @@ notify_notification_set_hint_double(NotifyNotification *notification,
g_strdup(key), hint_value);
}
/**
* notify_notification_set_hint_byte:
* @notification: The notification.
* @key: The hint.
* @value: The hint's value.
*
* Sets a hint with a byte value.
*/
void
notify_notification_set_hint_byte(NotifyNotification *notification,
const gchar *key, guchar value)
@ -965,6 +1041,16 @@ notify_notification_set_hint_byte(NotifyNotification *notification,
g_hash_table_insert(notification->priv->hints, g_strdup(key), hint_value);
}
/**
* notify_notification_set_hint_byte_array:
* @notification: The notification.
* @key: The hint.
* @value: The hint's value.
* @len: The length of the byte array.
*
* Sets a hint with a byte array value. The length of @value must be passed
* as @len.
*/
void
notify_notification_set_hint_byte_array(NotifyNotification *notification,
const gchar *key,
@ -991,6 +1077,14 @@ notify_notification_set_hint_byte_array(NotifyNotification *notification,
g_strdup(key), hint_value);
}
/**
* notify_notification_set_hint_string:
* @notification: The notification.
* @key: The hint.
* @value: The hint's value.
*
* Sets a hint with a string value.
*/
void
notify_notification_set_hint_string(NotifyNotification *notification,
const gchar *key, const gchar *value)
@ -1014,6 +1108,12 @@ _remove_all(void)
return TRUE;
}
/**
* notify_notification_clear_hints:
* @notification: The notification.
*
* Clears all hints from the notification.
*/
void
notify_notification_clear_hints(NotifyNotification *notification)
{
@ -1024,6 +1124,12 @@ notify_notification_clear_hints(NotifyNotification *notification)
(GHRFunc)_remove_all, NULL);
}
/**
* notify_notification_clear_actions:
* @notification: The notification.
*
* Clears all actions from the notification.
*/
void
notify_notification_clear_actions(NotifyNotification *notification)
{
@ -1043,6 +1149,20 @@ notify_notification_clear_actions(NotifyNotification *notification)
notification->priv->has_nondefault_actions = FALSE;
}
/**
* notify_notification_add_action:
* @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.
*
* 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.
*/
void
notify_notification_add_action(NotifyNotification *notification,
const char *action,
@ -1085,6 +1205,16 @@ _notify_notification_has_nondefault_actions(const NotifyNotification *n)
return n->priv->has_nondefault_actions;
}
/**
* notify_notification_close:
* @notification: The notification.
* @error: The returned error information.
*
* Tells the notification server to hide the notification on the screen.
*
* Returns: %TRUE if successful. On error, this will return %FALSE and set
* @error.
*/
gboolean
notify_notification_close(NotifyNotification *notification,
GError **error)

2
libnotify/notification.h
View File

@ -121,7 +121,7 @@ void notify_notification_set_category(NotifyNotification *notification,
const char *category);
void notify_notification_set_urgency(NotifyNotification *notification,
NotifyUrgency l);
NotifyUrgency urgency);
void notify_notification_set_icon_from_pixbuf(NotifyNotification *notification,
GdkPixbuf *icon);