totem-pl-parser r40 - in trunk: . docs/reference plparse

[pwithnall svn gnome org]

Author: pwithnall
Date: Thu Jan 17 22:00:21 2008
New Revision: 40
URL: http://svn.gnome.org/viewvc/totem-pl-parser?rev=40&view=rev

Log:
2008-01-17  Philip Withnall  <pwithnall svn gnome org>

	* docs/reference/totem-pl-parser-docs.sgml:
	* docs/reference/totem-pl-parser-sections.txt:
	* plparse/totem-pl-parser.c:
	* plparse/totem-pl-parser.h: Clean up the documentation order,
	add some documentation for the TotemPlParser object, and add 
some
	example code. (Closes: #507995)



Modified:
   trunk/ChangeLog
   trunk/docs/reference/totem-pl-parser-docs.sgml
   trunk/docs/reference/totem-pl-parser-sections.txt
   trunk/plparse/totem-pl-parser.c
   trunk/plparse/totem-pl-parser.h

Modified: trunk/docs/reference/totem-pl-parser-docs.sgml
==============================================================================
--- trunk/docs/reference/totem-pl-parser-docs.sgml	(original)
+++ trunk/docs/reference/totem-pl-parser-docs.sgml	Thu Jan 17 22:00:21 2008
@@ -2,6 +2,7 @@
 <!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">
+<!ENTITY slash "/">
 ]>
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
   <bookinfo>

Modified: trunk/docs/reference/totem-pl-parser-sections.txt
==============================================================================
--- trunk/docs/reference/totem-pl-parser-sections.txt	(original)
+++ trunk/docs/reference/totem-pl-parser-sections.txt	Thu Jan 17 22:00:21 2008
@@ -1,6 +1,21 @@
 <SECTION>
 <FILE>totem-pl-parser</FILE>
+TotemPlParser
+TotemPlParserClass
 TotemPlParserResult
+TotemPlParserType
+TotemPlParserError
+TotemPlParserIterFunc
+totem_pl_parser_new
+totem_pl_parser_parse
+totem_pl_parser_parse_with_base
+totem_pl_parser_write
+totem_pl_parser_write_with_title
+totem_pl_parser_parse_duration
+totem_pl_parser_parse_date
+totem_pl_parser_resolve_url
+totem_pl_parser_add_ignored_scheme
+totem_pl_parser_add_ignored_mimetype
 TOTEM_PL_PARSER_FIELD_URL
 TOTEM_PL_PARSER_FIELD_GENRE
 TOTEM_PL_PARSER_FIELD_TITLE
@@ -24,19 +39,6 @@
 TOTEM_PL_PARSER_FIELD_CONTACT
 TOTEM_PL_PARSER_FIELD_IMAGE_URL
 TOTEM_PL_PARSER_FIELD_IS_PLAYLIST
-TotemPlParserType
-TotemPlParserError
-TotemPlParserIterFunc
-totem_pl_parser_parse_duration
-totem_pl_parser_parse_date
-totem_pl_parser_resolve_url
-totem_pl_parser_write
-totem_pl_parser_write_with_title
-totem_pl_parser_add_ignored_scheme
-totem_pl_parser_add_ignored_mimetype
-totem_pl_parser_parse
-totem_pl_parser_parse_with_base
-totem_pl_parser_new
 <SUBSECTION Standard>
 TOTEM_PL_PARSER
 TOTEM_IS_PL_PARSER
@@ -47,12 +49,10 @@
 totem_pl_parser_error_quark
 TOTEM_PL_PARSER_ERROR
 <SUBSECTION Private>
-TotemPlParser
-TotemPlParserClass
 TotemPlParserPrivate
 entry_parsed
-playlist_started
 playlist_ended
+playlist_started
 </SECTION>
 
 <SECTION>

Modified: trunk/plparse/totem-pl-parser.c
==============================================================================
--- trunk/plparse/totem-pl-parser.c	(original)
+++ trunk/plparse/totem-pl-parser.c	Thu Jan 17 22:00:21 2008
@@ -28,6 +28,69 @@
  *
  * #TotemPlParser is a general-purpose playlist parser and writer, with
  * support for several different types of playlist.
+ *
+ * <example>
+ *  <title>Reading a Playlist</title>
+ *  <programlisting>
+ * TotemPlParser *pl = totem_pl_parser_new ();
+ * g_object_set (pl, "recurse", FALSE, "disable-unsafe", TRUE, NULL);
+ * g_signal_connect (G_OBJECT (pl), "playlist-started", G_CALLBACK (playlist_started), NULL);
+ * g_signal_connect (G_OBJECT (pl), "entry-parsed", G_CALLBACK (entry_parsed), NULL);
+ *
+ * if (totem_pl_parser_parse (pl, "http://example.com/playlist.pls";, FALSE) != TOTEM_PL_PARSER_RESULT_SUCCESS)
+ * 	g_error ("Playlist parsing failed.");
+ *
+ * g_object_unref (pl);
+ *  </programlisting>
+ * </example>
+ *
+ * <example>
+ *  <title>Getting Metadata from Entries</title>
+ *  <programlisting>
+ * static void
+ * entry_parsed (TotemPlParser *parser, const gchar *uri, GHashTable *metadata, gpointer user_data)
+ * {
+ * 	gchar *title = g_hash_table_lookup (metadata, TOTEM_PL_PARSER_FIELD_TITLE);
+ * 	if (title != NULL)
+ * 		g_message ("Entry title: %s", title);
+ * 	else
+ * 		g_message ("Entry (URI: %s) has no title.", uri);
+ * }
+ *  </programlisting>
+ * </example>
+ *
+ * <example>
+ *  <title>Writing a Playlist</title>
+ *  <programlisting>
+ * void
+ * parser_func (GtkTreeModel *model, GtkTreeIter *iter, gchar **uri, gchar **title, gboolean *custom_title, gpointer user_data)
+ * {
+ * 	gtk_tree_model_get (model, iter,
+ * 		0, uri,
+ * 		1, title,
+ * 		2, custom_title,
+ * 		-1);
+ * }
+ *
+ * {
+ * 	TotemPlParser *pl;
+ * 	GtkTreeModel *tree_model;
+ *
+ * 	pl = totem_pl_parser_new ();
+ *
+ * 	&slash;* Your tree model can be as simple or as complex as you like;
+ * 	 * parser_func() will just have to return the entry title, URI and custom title flag from it. *&slash;
+ * 	tree_model = gtk_list_store_new (3, G_TYPE_STRING, G_TYPE_STRING, G_TYPE_BOOLEAN);
+ * 	populate_model (tree_model);
+ *
+ * 	if (totem_pl_parser_write (pl, tree_model, parser_func, "/tmp/playlist.pls", TOTEM_PL_PARSER_PLS, NULL, NULL) != TRUE)
+ * 		g_error ("Playlist writing failed.");
+ *
+ * 	g_object_unref (tree_model);
+ * 	g_object_unref (pl);
+ * }
+ *  </programlisting>
+ * </example>
  **/
 
 #include "config.h"

Modified: trunk/plparse/totem-pl-parser.h
==============================================================================
--- trunk/plparse/totem-pl-parser.h	(original)
+++ trunk/plparse/totem-pl-parser.h	Thu Jan 17 22:00:21 2008
@@ -58,6 +58,11 @@
 typedef struct TotemPlParserClass      TotemPlParserClass;
 typedef struct TotemPlParserPrivate    TotemPlParserPrivate;
 
+/**
+ * TotemPlParser:
+ *
+ * All the fields in the #TotemPlParser structure are private and should never be accessed directly.
+ **/
 struct TotemPlParser {
 	GObject parent;
 	TotemPlParserPrivate *priv;
@@ -206,6 +211,18 @@
  **/
 #define TOTEM_PL_PARSER_FIELD_IS_PLAYLIST	"is-playlist"
 
+/**
+ * TotemPlParserClass:
+ * @parent_class: the parent class
+ * @entry_parsed: the generic signal handler for the #TotemPlParser::entry-parsed signal,
+ * which can be overridden by inheriting classes
+ * @playlist_started: the generic signal handler for the #TotemPlParser::playlist-started signal,
+ * which can be overridden by inheriting classes
+ * @playlist_ended: the generic signal handler for the #TotemPlParser::playlist-ended signal,
+ * which can be overridden by inheriting classes
+ *
+ * The class structure for the #TotemPlParser type.
+ **/
 struct TotemPlParserClass {
 	GObjectClass parent_class;