[maemo-commits] [maemo-commits] r14505 - in projects/haf/trunk/hildon-notify: . debian doc src
From: subversion at stage.maemo.org subversion at stage.maemo.orgDate: Thu Oct 18 17:52:55 EEST 2007
- Previous message: [maemo-commits] r14504 - in projects/haf/trunk/dbus-glib/debian: . patches
- Next message: [maemo-commits] r14507 - projects/haf/tags
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
Author: lucasr Date: 2007-10-18 17:52:52 +0300 (Thu, 18 Oct 2007) New Revision: 14505 Added: projects/haf/trunk/hildon-notify/doc/ projects/haf/trunk/hildon-notify/doc/Makefile.am projects/haf/trunk/hildon-notify/doc/gtk-doc.make projects/haf/trunk/hildon-notify/doc/hildon-notify-docs.sgml Modified: projects/haf/trunk/hildon-notify/ChangeLog projects/haf/trunk/hildon-notify/Makefile.am projects/haf/trunk/hildon-notify/configure.ac projects/haf/trunk/hildon-notify/debian/control projects/haf/trunk/hildon-notify/src/hildon-notification.c projects/haf/trunk/hildon-notify/src/hildon-notification.h Log: 2007-10-18 Lucas Rocha <lucas.rocha at nokia.com> * src/hildon-notification.[ch]: added API documentation. * configure.ac, Makefile.am, doc/*: added build infra for gtk-doc. Modified: projects/haf/trunk/hildon-notify/ChangeLog =================================================================== --- projects/haf/trunk/hildon-notify/ChangeLog 2007-10-18 13:03:11 UTC (rev 14504) +++ projects/haf/trunk/hildon-notify/ChangeLog 2007-10-18 14:52:52 UTC (rev 14505) @@ -1,3 +1,8 @@ +2007-10-18 Lucas Rocha <lucas.rocha at nokia.com> + + * src/hildon-notification.[ch]: added API documentation. + * configure.ac, Makefile.am, doc/*: added build infra for gtk-doc. + 2007-07-09 Lucas Rocha <lucas.rocha at nokia.com> * tests/test-led-pattern.c: added new test program for led patterns. Modified: projects/haf/trunk/hildon-notify/Makefile.am =================================================================== --- projects/haf/trunk/hildon-notify/Makefile.am 2007-10-18 13:03:11 UTC (rev 14504) +++ projects/haf/trunk/hildon-notify/Makefile.am 2007-10-18 14:52:52 UTC (rev 14505) @@ -1 +1 @@ -SUBDIRS = src +SUBDIRS = src doc Modified: projects/haf/trunk/hildon-notify/configure.ac =================================================================== --- projects/haf/trunk/hildon-notify/configure.ac 2007-10-18 13:03:11 UTC (rev 14504) +++ projects/haf/trunk/hildon-notify/configure.ac 2007-10-18 14:52:52 UTC (rev 14505) @@ -18,6 +18,8 @@ AC_HEADER_STDBOOL +GTK_DOC_CHECK([1.3]) + #++++++++++++++++++ # Misc build flags #++++++++++++++++++ @@ -42,6 +44,7 @@ Makefile src/Makefile src/hildon-notify.pc +doc/Makefile ]) AC_OUTPUT Modified: projects/haf/trunk/hildon-notify/debian/control =================================================================== --- projects/haf/trunk/hildon-notify/debian/control 2007-10-18 13:03:11 UTC (rev 14504) +++ projects/haf/trunk/hildon-notify/debian/control 2007-10-18 14:52:52 UTC (rev 14505) @@ -1,7 +1,7 @@ Source: hildon-notify Priority: optional Maintainer: Lucas Rocha <lucas.rocha at nokia.com> -Build-Depends: debhelper (>= 4.0.0), libnotify-dev, pkg-config +Build-Depends: debhelper (>= 4.0.0), libnotify-dev, pkg-config, gtk-doc-tools Standards-Version: 3.6.1 Package: libhildonnotify-dev Added: projects/haf/trunk/hildon-notify/doc/Makefile.am =================================================================== --- projects/haf/trunk/hildon-notify/doc/Makefile.am 2007-10-18 13:03:11 UTC (rev 14504) +++ projects/haf/trunk/hildon-notify/doc/Makefile.am 2007-10-18 14:52:52 UTC (rev 14505) @@ -0,0 +1,46 @@ +MAINTAINERCLEANFILES = Makefile.in \ + hildon-notify-sections.txt \ + hildon-notify-undocumented.txt \ + version.xml \ + tmpl/*.sgml + +DOC_MODULE = hildon-notify + +DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.sgml + +SCAN_OPTIONS = + +SCANOBJ_OPTIONS =--type-init-func="gtk_type_init(0)" + +DOC_SOURCE_DIR = $(top_srcdir)/src +DOC_BUILD_DIR = $(top_builddir)/src + + +HFILE_GLOB = $(top_srcdir)/src/*.h + +CFILE_GLOB = $(top_srcdir)/src/*.c + +INCLUDES = $(GLIB_CFLAGS) $(LIBNOTIFY_CFLAGS) + +MKDB_OPTIONS = --sgml-mode --output-format=xml + +content_files = version.xml +# visual_index.xml + +GTKDOC_CFLAGS = $(LIBNOTIFY_CFLAGS) \ + $(GLIB_CFLAGS) + +GTKDOC_LIBS = $(LIBNOTIFY_LIBS) \ + $(GLIB_LIBS) \ + $(top_srcdir)/src/libhildonnotify.la + +HTML_IMAGES = + +version.xml: ../configure.ac + @echo $(VERSION) > version.xml + +html: html-build.stamp + +FIXXREF_OPTIONS = + +include $(top_srcdir)/doc/gtk-doc.make Added: projects/haf/trunk/hildon-notify/doc/gtk-doc.make =================================================================== --- projects/haf/trunk/hildon-notify/doc/gtk-doc.make 2007-10-18 13:03:11 UTC (rev 14504) +++ projects/haf/trunk/hildon-notify/doc/gtk-doc.make 2007-10-18 14:52:52 UTC (rev 14505) @@ -0,0 +1,155 @@ +# -*- mode: makefile -*- + +#################################### +# Everything below here is generic # +#################################### + +if GTK_DOC_USE_LIBTOOL +GTKDOC_CC = $(LIBTOOL) --mode=compile $(CC) $(INCLUDES) $(AM_CFLAGS) $(CFLAGS) +GTKDOC_LD = $(LIBTOOL) --mode=link $(CC) $(AM_CFLAGS) $(CFLAGS) $(LDFLAGS) +else +GTKDOC_CC = $(CC) $(INCLUDES) $(AM_CFLAGS) $(CFLAGS) +GTKDOC_LD = $(CC) $(AM_CFLAGS) $(CFLAGS) $(LDFLAGS) +endif + +# We set GPATH here; this gives us semantics for GNU make +# which are more like other make's VPATH, when it comes to +# whether a source that is a target of one rule is then +# searched for in VPATH/GPATH. +# +GPATH = $(srcdir) + +TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) + +EXTRA_DIST = \ + $(content_files) \ + $(HTML_IMAGES) \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE)-sections.txt \ + $(DOC_MODULE)-overrides.txt + +DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \ + $(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp + +SCANOBJ_FILES = \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).interfaces \ + $(DOC_MODULE).prerequisites \ + $(DOC_MODULE).signals + +CLEANFILES = $(SCANOBJ_FILES) $(DOC_MODULE)-unused.txt $(DOC_STAMPS) + +if ENABLE_GTK_DOC +all-local: html-build.stamp +else +all-local: +endif + +docs: html-build.stamp + +#### scan #### + +scan-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB) + @echo 'gtk-doc: Scanning header files' + @-chmod -R u+w $(srcdir) + cd $(srcdir) && \ + gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES) + if grep -l '^..*$$' $(srcdir)/$(DOC_MODULE).types > /dev/null 2>&1 ; then \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) --output-dir=$(srcdir) ; \ + else \ + cd $(srcdir) ; \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ + fi + touch scan-build.stamp + +$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp + @true + +#### templates #### + +tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt + @echo 'gtk-doc: Rebuilding template files' + @-chmod -R u+w $(srcdir) + cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS) + touch tmpl-build.stamp + +tmpl.stamp: tmpl-build.stamp + @true + +#### xml #### + +sgml-build.stamp: tmpl.stamp $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files) + @echo 'gtk-doc: Building XML' + @-chmod -R u+w $(srcdir) + cd $(srcdir) && \ + gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $(MKDB_OPTIONS) + touch sgml-build.stamp + +sgml.stamp: sgml-build.stamp + @true + +#### html #### + +html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) + @echo 'gtk-doc: Building HTML' + @-chmod -R u+w $(srcdir) + rm -rf $(srcdir)/html + mkdir $(srcdir)/html + cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html ) + @echo 'gtk-doc: Fixing cross-references' + cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) + touch html-build.stamp + +############## + +clean-local: + rm -f *~ *.bak + rm -rf .libs + +maintainer-clean-local: clean + cd $(srcdir) && rm -rf xml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt + +install-data-local: + installfiles=`echo $(srcdir)/html/*`; \ + if test "$$installfiles" = '$(srcdir)/html/*'; \ + then echo '-- Nothing to install' ; \ + else \ + $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR); \ + for i in $$installfiles; do \ + echo '-- Installing '$$i ; \ + $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \ + done; \ + echo '-- Installing $(srcdir)/html/index.sgml' ; \ + $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR) || :; \ + fi + +uninstall-local: + rm -f $(DESTDIR)$(TARGET_DIR)/* + +# +# Require gtk-doc when making dist +# +if ENABLE_GTK_DOC +dist-check-gtkdoc: +else +dist-check-gtkdoc: + @echo "*** gtk-doc must be installed and enabled in order to make dist" + @false +endif + +dist-hook: dist-check-gtkdoc dist-hook-local + mkdir $(distdir)/tmpl + mkdir $(distdir)/xml + mkdir $(distdir)/html + -cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl + -cp $(srcdir)/xml/*.xml $(distdir)/xml + cp $(srcdir)/html/* $(distdir)/html + if test -f $(srcdir)/$(DOC_MODULE).types; then \ + cp $(srcdir)/$(DOC_MODULE).types $(distdir)/$(DOC_MODULE).types; \ + fi + +.PHONY : dist-hook-local docs Added: projects/haf/trunk/hildon-notify/doc/hildon-notify-docs.sgml =================================================================== --- projects/haf/trunk/hildon-notify/doc/hildon-notify-docs.sgml 2007-10-18 13:03:11 UTC (rev 14504) +++ projects/haf/trunk/hildon-notify/doc/hildon-notify-docs.sgml 2007-10-18 14:52:52 UTC (rev 14505) @@ -0,0 +1,40 @@ +<?xml version="1.0"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" +[ + <!ENTITY version SYSTEM "version.xml"> +]> + +<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude"> + <bookinfo> + <title>libhildonnotify &version; Reference Manual</title> + <releaseinfo>For Hildon Desktop 2.0</releaseinfo> + </bookinfo> + + <chapter id="overview"> + <title>Overview</title> + <para> + libhildonnotify is a wrapper around libnotify which has as its major + addition the support for D-Bus action callbacks. Also some utility functions for + setting sound, persistency and category are provided to make it simpler to + use main features of the Hildon Desktop notification backend. + </para> + <para> + The plan is that libhildonnotify becomes unnecessary when its major features are + incorporated in libnotify accordingly. + </para> + </chapter> + + <chapter id="notifications"> + <title>Notifications</title> + <xi:include href="xml/hildon-notification.xml"/> + </chapter> + + <index id="symbols"> + <title>Index</title> + </index> + <index role="hierarchy" id="hierarchy"> + <title>Object Hierarchy</title> + <xi:include href="xml/tree_index.sgml"/> + </index> +</book> Modified: projects/haf/trunk/hildon-notify/src/hildon-notification.c =================================================================== --- projects/haf/trunk/hildon-notify/src/hildon-notification.c 2007-10-18 13:03:11 UTC (rev 14504) +++ projects/haf/trunk/hildon-notify/src/hildon-notification.c 2007-10-18 14:52:52 UTC (rev 14505) @@ -22,6 +22,15 @@ * */ +/** + * SECTION:hildon-notification + * @short_description: A wrapper around libnotify's @NotifyNotification which adds support + * for D-Bus action callbacks and other utility functions. + * + * HildonNotification is a wrapper class around @NotifyNotification (from libnotify) which + * has as its major addition the support for D-Bus action callbacks. Also some utility + * functions for setting sound, persistency and category are provided. + */ #include <gtk/gtk.h> #include <glib.h> #include <glib-object.h> @@ -41,6 +50,16 @@ { } +/** + * hildon_notification_new: + * @summary: a short notification summary + * @body: a more detailed notification description + * @icon: a name or file path to the notification icon + * @category: the notification category, or NULL + * @returns: A newly allocated HildonNotification instance + * + * Creates a new instance of @HildonNotification + **/ HildonNotification * hildon_notification_new (const gchar *summary, const gchar *body, @@ -70,6 +89,14 @@ return HILDON_NOTIFICATION (n); } +/** + * hildon_notification_set_persistent: + * @n: an instance of @HildonNotification + * @persistent: TRUE is the notification should be persistent; FALSE otherwise + * + * Sets whether the notification should remain available even if Hildon Desktop + * restarts + **/ void hildon_notification_set_persistent (HildonNotification *n, gboolean persistent) { @@ -77,6 +104,15 @@ "persistent", (guchar) persistent); } +/** + * hildon_notification_set_sound: + * @n: an instance of @HildonNotification + * @sound_file: path for sound file that should be played when the notification is + * sent + * + * Sets the sound file that should be played when the notification is sent to the + * notification backend + **/ void hildon_notification_set_sound (HildonNotification *n, const gchar *sound_file) { @@ -180,6 +216,24 @@ g_free (hint); } +/** + * hildon_notification_add_dbus_action: + * @n: an instance of @HildonNotification + * @action_id: a unique string ID to be used to identify the action in the notification backend + * @action_label: label that should be shown in notification UI to activate the respective action + * @dbus_destination: the D-Bus service that should be used in the callback + * @dbus_path: the D-Bus path that should be used in the callback + * @dbus_interface: the D-Bus object interface that should be used in the callback + * @dbus_method: the D-Bus method that should be used in the callback + * @param_type: a @GType for the first param for the D-Bus call, or -1. Currently only + * G_TYPE_STRING, G_TYPE_INT, and G_TYPE_DOUBLE are supported + * @...: the value of the first parameter, then additional parameters, ending with -1 + * + * Defines a new notification action with a D-Bus callback. If such action is activated in the + * notification backend, the specified D-Bus call will be made. In Hildon Desktop 2.0, the only + * action id value supported in the UI is "default" which is activated when the user selects one + * of the notification items in appllication switcher menu. + **/ void hildon_notification_add_dbus_action (HildonNotification *n, const gchar *action_id, @@ -215,15 +269,28 @@ va_end (args); } -/* lucasr: still not sure about this one. */ -#if 0 -GList * -hildon_notification_get_notifications () -{ - return NULL; -} -#endif - +/** + * hildon_notification_helper_show: + * @id: notification id to be used, or -1 + * @summary: a short notification summary + * @body: a more detailed notification description + * @icon: a name or file path to the notification icon + * @category: the notification category, or NULL + * @timeout: the notification timeout in miliseconds. After this timeout the notification will + * be automatically closed + * @persistent: TRUE is the notification should be persistent; FALSE otherwise + * @dbus_destination: the D-Bus service that should be used in the callback + * @dbus_path: the D-Bus path that should be used in the callback + * @dbus_interface: the D-Bus object interface that should be used in the callback + * @dbus_method: the D-Bus method that should be used in the callback + * @param_type: a @GType for the first param for the D-Bus call, or -1. Currently only + * G_TYPE_STRING, G_TYPE_INT, and G_TYPE_DOUBLE are supported + * @...: the value of the first parameter, then additional parameters, ending with -1 + * @returns: the notification id returned from the notification backend + * + * Helper function which creates a notification with basic parameters (summary, body, icon, + * category, timeout and persistent), sets a default D-Bus action. and sends it. + **/ guint hildon_notification_helper_show (guint id, const gchar *summary, Modified: projects/haf/trunk/hildon-notify/src/hildon-notification.h =================================================================== --- projects/haf/trunk/hildon-notify/src/hildon-notification.h 2007-10-18 13:03:11 UTC (rev 14504) +++ projects/haf/trunk/hildon-notify/src/hildon-notification.h 2007-10-18 14:52:52 UTC (rev 14505) @@ -32,7 +32,6 @@ typedef struct _HildonNotification HildonNotification; typedef struct _HildonNotificationClass HildonNotificationClass; -typedef struct _HildonNotificationPrivate HildonNotificationPrivate; #define HILDON_TYPE_NOTIFICATION (hildon_notification_get_type ()) #define HILDON_NOTIFICATION(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), HILDON_TYPE_NOTIFICATION, HildonNotification)) @@ -44,8 +43,6 @@ struct _HildonNotification { NotifyNotification notification; - - HildonNotificationPrivate *priv; }; struct _HildonNotificationClass @@ -76,8 +73,6 @@ GType param_type, ...); -GList *hildon_notification_get_notifications (void); - guint hildon_notification_helper_show (guint id, const gchar *summary, const gchar *body,
- Previous message: [maemo-commits] r14504 - in projects/haf/trunk/dbus-glib/debian: . patches
- Next message: [maemo-commits] r14507 - projects/haf/tags
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]