[Galago-commits] r2824 - in trunk/libnotify: . docs/reference
docs/reference/tmpl libnotify
galago-commits at freedesktop.org
galago-commits at freedesktop.org
Tue Jun 6 01:29:36 PDT 2006
Author: chipx86
Date: 2006-06-06 01:29:32 -0700 (Tue, 06 Jun 2006)
New Revision: 2824
Modified:
trunk/libnotify/ChangeLog
trunk/libnotify/docs/reference/libnotify-sections.txt
trunk/libnotify/docs/reference/tmpl/notification.sgml
trunk/libnotify/docs/reference/tmpl/notify.sgml
trunk/libnotify/libnotify/notification.c
trunk/libnotify/libnotify/notification.h
Log:
Provide more documentation.
Modified: trunk/libnotify/ChangeLog
===================================================================
--- trunk/libnotify/ChangeLog 2006-06-06 07:28:21 UTC (rev 2823)
+++ trunk/libnotify/ChangeLog 2006-06-06 08:29:32 UTC (rev 2824)
@@ -1,3 +1,12 @@
+Tue Jun 06 01:29:20 PDT 2006 Christian Hammond <chipx86 at 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 at chipx86.com>
* docs/reference/tmpl/notification.sgml:
Modified: trunk/libnotify/docs/reference/libnotify-sections.txt
===================================================================
--- trunk/libnotify/docs/reference/libnotify-sections.txt 2006-06-06 07:28:21 UTC (rev 2823)
+++ trunk/libnotify/docs/reference/libnotify-sections.txt 2006-06-06 08:29:32 UTC (rev 2824)
@@ -2,7 +2,6 @@
<FILE>notification</FILE>
NOTIFY_EXPIRES_DEFAULT
NOTIFY_EXPIRES_NEVER
-NotifyNotificationPrivate
<TITLE>NotifyNotification</TITLE>
NotifyNotification
NotifyUrgency
Modified: trunk/libnotify/docs/reference/tmpl/notification.sgml
===================================================================
--- trunk/libnotify/docs/reference/tmpl/notification.sgml 2006-06-06 07:28:21 UTC (rev 2823)
+++ trunk/libnotify/docs/reference/tmpl/notification.sgml 2006-06-06 08:29:32 UTC (rev 2824)
@@ -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 @@
<!-- ##### 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>
- at parent:
- at priv:
+ at parent: The parent object.
+ at 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>
- at Param1:
- at Param2:
- at Param3:
+ at Param1: The notification.
+ at Param2: The action ID.
+ at 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>
- at func:
+ at func: The function to cast.
<!-- ##### FUNCTION notify_notification_new ##### -->
@@ -171,7 +176,7 @@
</para>
@notification:
- at l:
+ at urgency:
<!-- ##### FUNCTION notify_notification_set_icon_from_pixbuf ##### -->
Modified: trunk/libnotify/docs/reference/tmpl/notify.sgml
===================================================================
--- trunk/libnotify/docs/reference/tmpl/notify.sgml 2006-06-06 07:28:21 UTC (rev 2823)
+++ trunk/libnotify/docs/reference/tmpl/notify.sgml 2006-06-06 08:29:32 UTC (rev 2824)
@@ -2,8 +2,8 @@
notify
<!-- ##### SECTION Short_Description ##### -->
+Notification API
-
<!-- ##### SECTION Long_Description ##### -->
<para>
Modified: trunk/libnotify/libnotify/notification.c
===================================================================
--- trunk/libnotify/libnotify/notification.c 2006-06-06 07:28:21 UTC (rev 2823)
+++ trunk/libnotify/libnotify/notification.c 2006-06-06 08:29:32 UTC (rev 2824)
@@ -142,7 +142,12 @@
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 @@
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 @@
}
#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 @@
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 @@
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 @@
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_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 @@
}
#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 @@
#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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
(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 @@
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 @@
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)
Modified: trunk/libnotify/libnotify/notification.h
===================================================================
--- trunk/libnotify/libnotify/notification.h 2006-06-06 07:28:21 UTC (rev 2823)
+++ trunk/libnotify/libnotify/notification.h 2006-06-06 08:29:32 UTC (rev 2824)
@@ -121,7 +121,7 @@
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);
More information about the galago-commits
mailing list