[Xfce4-commits] <parole:master> Update the API doc+fix the time in the tray plugin.

Ali Abdallah noreply at xfce.org
Tue Dec 1 14:24:01 CET 2009


Updating branch refs/heads/master
         to dd33007064166e4b910e7e95172ae2bf3650b3b1 (commit)
       from acc3fc53c611bda9c9a8d0c00fcff9ab38896036 (commit)

commit dd33007064166e4b910e7e95172ae2bf3650b3b1
Author: Ali Abdallah <aliov at xfce.org>
Date:   Tue Dec 1 13:23:59 2009 +0100

    Update the API doc+fix the time in the tray plugin.

 docs/plugin-api/Makefile.am                      |    3 +-
 docs/plugin-api/Parole-Plugins-docs.sgml         |    6 +-
 docs/plugin-api/Parole-Plugins-sections.txt      |    3 +-
 docs/plugin-api/parole-plugins-tut.sgml          |  142 +++++++++++
 docs/plugin-api/tmpl/Parole-Plugins-unused.sgml  |  185 ++++++++++++++
 docs/plugin-api/tmpl/parole-filters.sgml         |   19 --
 docs/plugin-api/tmpl/parole-pl-parser.sgml       |    9 +
 docs/plugin-api/tmpl/parole-provider-player.sgml |    4 +-
 docs/plugin-api/tmpl/parole-provider-plugin.sgml |    7 +-
 docs/plugin-api/tmpl/parole-stream.sgml          |    5 +-
 parole/parole-filters.c                          |   68 +++++-
 parole/parole-filters.h                          |   11 -
 parole/parole-pl-parser.c                        |  288 +++++++++++++--------
 parole/parole-pl-parser.h                        |    2 +
 parole/parole-provider-player.c                  |   63 ++++-
 parole/parole-provider-plugin.c                  |    2 +
 parole/parole.h.in                               |    2 +
 plugins/sample/sample-plugin.c                   |    2 +-
 plugins/sample/sample-provider.c                 |    2 -
 plugins/tray/tray-provider.c                     |   22 ++-
 20 files changed, 671 insertions(+), 174 deletions(-)

diff --git a/docs/plugin-api/Makefile.am b/docs/plugin-api/Makefile.am
index 88be230..0ea1d96 100644
--- a/docs/plugin-api/Makefile.am
+++ b/docs/plugin-api/Makefile.am
@@ -55,7 +55,8 @@ HTML_IMAGES=
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
 content_files= 			\
-	version.xml
+	version.xml		\
+	parole-plugins-tut.sgml
 
 # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
 # Only needed if you are using gtkdoc-scangobj to dynamically query widget
diff --git a/docs/plugin-api/Parole-Plugins-docs.sgml b/docs/plugin-api/Parole-Plugins-docs.sgml
index 7fb9374..55baf32 100644
--- a/docs/plugin-api/Parole-Plugins-docs.sgml
+++ b/docs/plugin-api/Parole-Plugins-docs.sgml
@@ -4,6 +4,7 @@
 [
   <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
   <!ENTITY version SYSTEM "version.xml">
+  <!ENTITY plugin-tut SYSTEM "parole-plugins-tut.sgml">
   <!ENTITY date "July 2009">
 ]>
 <book id="index">
@@ -42,8 +43,9 @@
     </para>
   </part>
   
-  <part id="tutorial">
-    <title>Plugin tutorial</title>
+  <part id="parole-plugins-tut">
+  <title>Parole Plugin Tutorial</title>
+    &plugin-tut;
   </part>
   
   <part id="fundamentals">
diff --git a/docs/plugin-api/Parole-Plugins-sections.txt b/docs/plugin-api/Parole-Plugins-sections.txt
index f0e1f1a..dc2e22d 100644
--- a/docs/plugin-api/Parole-Plugins-sections.txt
+++ b/docs/plugin-api/Parole-Plugins-sections.txt
@@ -83,6 +83,7 @@ PAROLE_ENUM_TYPE_PL_FORMAT
 <FILE>parole-pl-parser</FILE>
 ParolePlFormat
 parole_pl_parser_guess_format_from_extension
+parole_pl_parser_guess_format_from_data
 parole_pl_parser_can_parse_data
 parole_pl_parser_parse_from_file_by_extension
 parole_pl_parser_parse_all_from_file
@@ -109,14 +110,12 @@ PAROLE_IMPLEMENT_INTERFACE
 
 <SECTION>
 <FILE>parole-filters</FILE>
-ParoleFileFormat
 parole_get_supported_audio_filter
 parole_get_supported_video_filter
 parole_get_supported_media_filter
 parole_get_supported_files_filter
 parole_get_supported_playlist_filter
 parole_file_filter
-parole_file_guess_format
 </SECTION>
 
 <SECTION>
diff --git a/docs/plugin-api/parole-plugins-tut.sgml b/docs/plugin-api/parole-plugins-tut.sgml
new file mode 100644
index 0000000..a33959c
--- /dev/null
+++ b/docs/plugin-api/parole-plugins-tut.sgml
@@ -0,0 +1,142 @@
+
+    <para>
+	This section explains the steps required to write a plugin for Parole using
+	the C language interface.
+    </para>
+    
+    <para>
+	A simple example can be found in the parole plugins dir shipped with the source code, the sample
+	plugin.
+    </para>
+    <para>
+	As a basics, the plugin needs to implement <link linkend="ParoleProviderPlugin"><type>ParoleProviderPlugin</type></link>
+	interface, That is, the player use this interface to get if the plugin is configurable, to ask it to show
+	its properties dialog when needed, to set the <link linkend="ParoleProviderPlayer"><type>ParoleProviderPlayer</type></link>
+	interface used by plugins to access the the Parole player backend.
+    </para>
+    
+
+  <sect1>
+    <title>Plugin structure.</title>
+    sample-plugin.c
+    <programlisting>
+ 
+#include "sample-provider.h"
+    
+/* Avoid a no previous function declaration compiler warning*/
+G_MODULE_EXPORT GType	parole_plugin_initialize (ParoleProviderPlugin *plugin);
+G_MODULE_EXPORT void	parole_plugin_shutdown   (void);
+
+G_MODULE_EXPORT GType
+parole_plugin_initialize (ParoleProviderPlugin *plugin)
+{
+    xfce_textdomain (GETTEXT_PACKAGE, PACKAGE_LOCALE_DIR, "UTF-8");
+    sample_provider_register_type (plugin);
+    return SAMPLE_TYPE_PROVIDER;
+}
+
+G_MODULE_EXPORT void
+parole_plugin_shutdown (void)
+{
+    
+}
+    </programlisting>
+    
+    sample-provider.h
+    <programlisting>
+#ifndef SAMPLE_PROVIDER_H_
+#define SAMPLE_PROVIDER_H_
+
+#include <parole/parole.h>
+
+G_BEGIN_DECLS
+
+typedef struct _SampleProviderClass SampleProviderClass;
+typedef struct _SampleProvider      SampleProvider;
+
+#define SAMPLE_TYPE_PROVIDER             (sample_provider_get_type ())
+#define SAMPLE_PROVIDER(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), SAMPLE_TYPE_PROVIDER, SampleProvider))
+#define SAMPLE_PROVIDER_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST ((klass), SAMPLE_TYPE_PROVIDER, SampleProviderClass))
+#define SAMPLE_IS_PROVIDER(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), SAMPLE_TYPE_PROVIDER))
+#define SAMPLE_IS_PROVIDER_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), SAMPLE_TYPE_PROVIDER))
+#define SAMPLE_PROVIDER_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), SAMPLE_TYPE_PROVIDER, SampleProviderClass))
+
+GType sample_provider_get_type      	(void) G_GNUC_CONST G_GNUC_INTERNAL;
+
+void  sample_provider_register_type	(ParoleProviderPlugin *plugin);
+
+G_END_DECLS
+    </programlisting>
+    
+    sample-provider.c
+    <programlisting>
+
+#include "sample-provider.h"
+
+static void   sample_provider_iface_init 	   (ParoleProviderPluginIface *iface);
+static void   sample_provider_finalize             (GObject 	              *object);
+
+
+struct _SampleProviderClass
+{
+    GObjectClass parent_class;
+};
+
+struct _SampleProvider
+{
+    GObject      parent;
+    ParoleProviderPlayer *player;
+};
+
+PAROLE_DEFINE_TYPE_WITH_CODE (SampleProvider, 
+			      sample_provider, 
+			      G_TYPE_OBJECT,
+			      PAROLE_IMPLEMENT_INTERFACE (PAROLE_TYPE_PROVIDER_PLUGIN, 
+							  sample_provider_iface_init));
+		
+static void  sample_provider_configure (ParoleProviderPlugin *provider, GtkWidget *parent)
+{
+    /*Open the configuration dialog, parent is the window transient for*/
+}
+
+static gboolean sample_provider_is_configurable (ParoleProviderPlugin *plugin)
+{
+    return TRUE; /*Returns FALSE and don't override the iface->configure function*/
+}
+
+static void
+sample_provider_set_player (ParoleProviderPlugin *plugin, ParoleProviderPlayer *player)
+{
+    SampleProvider *provider;
+    provider = SAMPLE_PROVIDER (plugin);
+    
+    provider->player = player;
+}
+
+static void
+sample_provider_iface_init (ParoleProviderPluginIface *iface)
+{
+    iface->get_is_configurable = sample_provider_is_configurable;
+    iface->configure = sample_provider_configure;
+    iface->set_player = sample_provider_set_player;
+}
+
+static void sample_provider_class_init (SampleProviderClass *klass)
+{
+    GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+    
+    gobject_class->finalize = sample_provider_finalize;
+}
+
+static void sample_provider_init (SampleProvider *provider)
+{
+    provider->player = NULL;
+}
+
+static void sample_provider_finalize (GObject *object)
+{
+    G_OBJECT_CLASS (sample_provider_parent_class)->finalize (object);
+}    
+    </programlisting>
+    
+  </sect1>
diff --git a/docs/plugin-api/tmpl/Parole-Plugins-unused.sgml b/docs/plugin-api/tmpl/Parole-Plugins-unused.sgml
index e69de29..abec82b 100644
--- a/docs/plugin-api/tmpl/Parole-Plugins-unused.sgml
+++ b/docs/plugin-api/tmpl/Parole-Plugins-unused.sgml
@@ -0,0 +1,185 @@
+<!-- ##### SECTION ./tmpl/parole-plugins.sgml:Long_Description ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/parole-plugins.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### SECTION ./tmpl/parole-plugins.sgml:Short_Description ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/parole-plugins.sgml:Stability_Level ##### -->
+
+
+
+<!-- ##### SECTION ./tmpl/parole-plugins.sgml:Title ##### -->
+Parole Plugin Tutorial
+
+    <para>
+	This section explains the steps required to write a plugin for Parole using
+	the C language interface.
+    </para>
+    
+    <para>
+	A simple example can be found in the parole plugins dir shipped with the source code, the sample
+	plugin.
+    </para>
+    <para>
+	As a basics, the plugin needs to implement <link linkend="ParoleProviderPlugin"><type>ParoleProviderPlugin</type></link>
+	interface, That is, the player use this interface to get if the plugin is configurable, to ask it to show
+	its properties dialog when needed, to set the <link linkend="ParoleProviderPlayer"><type>ParoleProviderPlayer</type></link>
+	interface used by plugins to access the the Parole player backend.
+    </para>
+    
+  <sect1 id="parole-plugin-strcuted">
+    <title>Plugin structure.</title>
+    sample-plugin.c
+    <programlisting>
+ 
+#include "sample-provider.h"
+    
+/* Avoid a no previous function declaration compiler warning*/
+G_MODULE_EXPORT GType	parole_plugin_initialize (ParoleProviderPlugin *plugin);
+G_MODULE_EXPORT void	parole_plugin_shutdown   (void);
+
+G_MODULE_EXPORT GType
+parole_plugin_initialize (ParoleProviderPlugin *plugin)
+{
+    xfce_textdomain (GETTEXT_PACKAGE, PACKAGE_LOCALE_DIR, "UTF-8");
+    sample_provider_register_type (plugin);
+    return SAMPLE_TYPE_PROVIDER;
+}
+
+G_MODULE_EXPORT void
+parole_plugin_shutdown (void)
+{
+    
+}
+    </programlisting>
+    
+    sample-provider.h
+    <programlisting>
+#ifndef SAMPLE_PROVIDER_H_
+#define SAMPLE_PROVIDER_H_
+
+#include <parole/parole.h>
+
+G_BEGIN_DECLS
+
+typedef struct _SampleProviderClass SampleProviderClass;
+typedef struct _SampleProvider      SampleProvider;
+
+#define SAMPLE_TYPE_PROVIDER             (sample_provider_get_type ())
+#define SAMPLE_PROVIDER(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), SAMPLE_TYPE_PROVIDER, SampleProvider))
+#define SAMPLE_PROVIDER_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST ((klass), SAMPLE_TYPE_PROVIDER, SampleProviderClass))
+#define SAMPLE_IS_PROVIDER(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), SAMPLE_TYPE_PROVIDER))
+#define SAMPLE_IS_PROVIDER_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), SAMPLE_TYPE_PROVIDER))
+#define SAMPLE_PROVIDER_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), SAMPLE_TYPE_PROVIDER, SampleProviderClass))
+
+GType sample_provider_get_type      	(void) G_GNUC_CONST G_GNUC_INTERNAL;
+
+void  sample_provider_register_type	(ParoleProviderPlugin *plugin);
+
+G_END_DECLS
+    </programlisting>
+    
+    sample-provider.c
+    <programlisting>
+
+#include "sample-provider.h"
+
+static void   sample_provider_iface_init 	   (ParoleProviderPluginIface *iface);
+static void   sample_provider_finalize             (GObject 	              *object);
+
+
+struct _SampleProviderClass
+{
+    GObjectClass parent_class;
+};
+
+struct _SampleProvider
+{
+    GObject      parent;
+    ParoleProviderPlayer *player;
+};
+
+PAROLE_DEFINE_TYPE_WITH_CODE (SampleProvider, 
+			      sample_provider, 
+			      G_TYPE_OBJECT,
+			      PAROLE_IMPLEMENT_INTERFACE (PAROLE_TYPE_PROVIDER_PLUGIN, 
+							  sample_provider_iface_init));
+		
+static void  sample_provider_configure (ParoleProviderPlugin *provider, GtkWidget *parent)
+{
+    /*Open the configuration dialog, parent is the window transient for*/
+}
+
+static gboolean sample_provider_is_configurable (ParoleProviderPlugin *plugin)
+{
+    return TRUE; /*Returns FALSE and don't override the iface->configure function*/
+}
+
+static void
+sample_provider_set_player (ParoleProviderPlugin *plugin, ParoleProviderPlayer *player)
+{
+    SampleProvider *provider;
+    provider = SAMPLE_PROVIDER (plugin);
+    
+    provider->player = player;
+}
+
+static void
+sample_provider_iface_init (ParoleProviderPluginIface *iface)
+{
+    iface->get_is_configurable = sample_provider_is_configurable;
+    iface->configure = sample_provider_configure;
+    iface->set_player = sample_provider_set_player;
+}
+
+static void sample_provider_class_init (SampleProviderClass *klass)
+{
+    GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+    
+    gobject_class->finalize = sample_provider_finalize;
+}
+
+static void sample_provider_init (SampleProvider *provider)
+{
+    provider->player = NULL;
+}
+
+static void sample_provider_finalize (GObject *object)
+{
+    G_OBJECT_CLASS (sample_provider_parent_class)->finalize (object);
+}    
+    </programlisting>
+    
+  </sect1>
+    
+  </part>
+
+
+<!-- ##### ENUM ParoleFileFormat ##### -->
+<para>
+
+</para>
+
+ at PAROLE_FILE_UNKNOWN: 
+ at PAROLE_FILE_AUDIO: 
+ at PAROLE_FILE_VIDEO: 
+ at PAROLE_FILE_PLAYLIST: 
+
+<!-- ##### FUNCTION parole_file_guess_format ##### -->
+<para>
+
+</para>
+
+ at file: 
+ at Returns: 
+
diff --git a/docs/plugin-api/tmpl/parole-filters.sgml b/docs/plugin-api/tmpl/parole-filters.sgml
index b4f9d01..19706f0 100644
--- a/docs/plugin-api/tmpl/parole-filters.sgml
+++ b/docs/plugin-api/tmpl/parole-filters.sgml
@@ -17,16 +17,6 @@ Parole Filters
 <!-- ##### SECTION Stability_Level ##### -->
 
 
-<!-- ##### ENUM ParoleFileFormat ##### -->
-<para>
-
-</para>
-
- at PAROLE_FILE_UNKNOWN: 
- at PAROLE_FILE_AUDIO: 
- at PAROLE_FILE_VIDEO: 
- at PAROLE_FILE_PLAYLIST: 
-
 <!-- ##### FUNCTION parole_get_supported_audio_filter ##### -->
 <para>
 
@@ -77,12 +67,3 @@ Parole Filters
 @Returns: 
 
 
-<!-- ##### FUNCTION parole_file_guess_format ##### -->
-<para>
-
-</para>
-
- at file: 
- at Returns: 
-
-
diff --git a/docs/plugin-api/tmpl/parole-pl-parser.sgml b/docs/plugin-api/tmpl/parole-pl-parser.sgml
index 2295761..c9c2708 100644
--- a/docs/plugin-api/tmpl/parole-pl-parser.sgml
+++ b/docs/plugin-api/tmpl/parole-pl-parser.sgml
@@ -37,6 +37,15 @@ Parole Playlist Parser
 @Returns: 
 
 
+<!-- ##### FUNCTION parole_pl_parser_guess_format_from_data ##### -->
+<para>
+
+</para>
+
+ at filename: 
+ at Returns: 
+
+
 <!-- ##### FUNCTION parole_pl_parser_can_parse_data ##### -->
 <para>
 
diff --git a/docs/plugin-api/tmpl/parole-provider-player.sgml b/docs/plugin-api/tmpl/parole-provider-player.sgml
index 37badd1..c038e96 100644
--- a/docs/plugin-api/tmpl/parole-provider-player.sgml
+++ b/docs/plugin-api/tmpl/parole-provider-player.sgml
@@ -6,7 +6,9 @@ The interface of the player.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The player interface that the plugins should use in order to, issue playback 
+command to the Parole GStreamer backend or to get information about the current
+playback status.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/plugin-api/tmpl/parole-provider-plugin.sgml b/docs/plugin-api/tmpl/parole-provider-plugin.sgml
index e06000a..0f1a36c 100644
--- a/docs/plugin-api/tmpl/parole-provider-plugin.sgml
+++ b/docs/plugin-api/tmpl/parole-provider-plugin.sgml
@@ -6,12 +6,15 @@ The interface of the plugin type registration.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The methods of this interface should be overridden by the plugin, the Parole player
+calls these methods to determine if the plugin is configurable, to ask the plugin to
+open its configuration dialog or to set the #ParoleProviderPlayer that the plugin
+can use to get access to various functionalities of the player.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#ParoleProviderPlayer.
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->
diff --git a/docs/plugin-api/tmpl/parole-stream.sgml b/docs/plugin-api/tmpl/parole-stream.sgml
index eea567a..b043df7 100644
--- a/docs/plugin-api/tmpl/parole-stream.sgml
+++ b/docs/plugin-api/tmpl/parole-stream.sgml
@@ -6,12 +6,15 @@ Currently playing stream.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+This object contains all the information describing the current processed stream
+by Parole, this object is used with the callback function the #ParoleProviderPlayerIface::state-changed
+signal of the player, the plugin shouldn't take reference and all the properties are read-only for the plugins.s
 
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#ParoleProviderPlayer
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->
diff --git a/parole/parole-filters.c b/parole/parole-filters.c
index cbfab27..e03b9f5 100644
--- a/parole/parole-filters.c
+++ b/parole/parole-filters.c
@@ -43,8 +43,16 @@ static char *playlist_mime_types[] = {
     "application/xspf+xml",
 };
 
-/*
- * Supported Audio formats.
+/**
+ * parole_get_supported_audio_filter:
+ * 
+ * 
+ * Get a #GtkFileFilter according to the supported
+ * Parole audio mime types.
+ * 
+ * Returns: A #GtkFileFilter for supported audio formats.
+ * 
+ * Since: 0.2
  */
 GtkFileFilter 		*parole_get_supported_audio_filter	(void)
 {
@@ -61,8 +69,16 @@ GtkFileFilter 		*parole_get_supported_audio_filter	(void)
     return filter;
 }
 
-/*
- * Supported Video formats.
+/**
+ * parole_get_supported_video_filter:
+ * 
+ * 
+ * Get a #GtkFileFilter according to the supported
+ * Parole video mime types.
+ * 
+ * Returns: A #GtkFileFilter for supported video formats.
+ * 
+ * Since: 0.2
  */
 GtkFileFilter 		*parole_get_supported_video_filter	(void)
 {
@@ -79,8 +95,15 @@ GtkFileFilter 		*parole_get_supported_video_filter	(void)
     return filter;
 }
 
-/*
- * Supported Audio And Video.
+/**
+ * parole_get_supported_media_filter:
+ * 
+ * Get a #GtkFileFilter according to the supported
+ * Parole media mime types, including audio and vide.
+ * 
+ * Returns: A #GtkFileFilter for supported media formats.
+ * 
+ * Since: 0.2
  */
 GtkFileFilter 		*parole_get_supported_media_filter	(void)
 {
@@ -100,6 +123,17 @@ GtkFileFilter 		*parole_get_supported_media_filter	(void)
     return filter;
 }
 
+/**
+ * parole_get_supported_files_filter:
+ * 
+ * 
+ * Get a #GtkFileFilter according to the supported
+ * Parole files mime types, including audio/video/play list formats.
+ * 
+ * Returns: A #GtkFileFilter for supported files formats.
+ * 
+ * Since: 0.2
+ */
 GtkFileFilter *parole_get_supported_files_filter (void)
 {
     GtkFileFilter *filter;
@@ -116,6 +150,17 @@ GtkFileFilter *parole_get_supported_files_filter (void)
     
 }
 
+/**
+ * parole_get_supported_playlist_filter:
+ * 
+ * 
+ * Get a #GtkFileFilter according to the supported
+ * Parole play-list mime types.
+ * 
+ * Returns: A #GtkFileFilter for supported playlist formats.
+ * 
+ * Since: 0.2
+ */
 GtkFileFilter 	*parole_get_supported_playlist_filter	(void)
 {
     GtkFileFilter *filter;
@@ -131,6 +176,17 @@ GtkFileFilter 	*parole_get_supported_playlist_filter	(void)
     return filter;
 }
 
+/**
+ * parole_file_filter:
+ * @filter: a #GtkFileFilter.
+ * @file: a #ParoleFile
+ * 
+ * Tests whether a file should be displayed according to filter
+ * 
+ * Returns: TRUE if the file should be displayed.
+ * 
+ * Since: 0.2
+ */
 gboolean parole_file_filter (GtkFileFilter *filter, ParoleFile *file)
 {
     GtkFileFilterInfo filter_info;
diff --git a/parole/parole-filters.h b/parole/parole-filters.h
index f23f18f..e7f8e6a 100644
--- a/parole/parole-filters.h
+++ b/parole/parole-filters.h
@@ -31,15 +31,6 @@
 
 G_BEGIN_DECLS
 
-typedef enum
-{
-    PAROLE_FILE_UNKNOWN,
-    PAROLE_FILE_AUDIO,
-    PAROLE_FILE_VIDEO,
-    PAROLE_FILE_PLAYLIST
-    
-} ParoleFileFormat;
-
 GtkFileFilter 		*parole_get_supported_audio_filter	(void);
 
 GtkFileFilter 		*parole_get_supported_video_filter	(void);
@@ -53,8 +44,6 @@ GtkFileFilter 		*parole_get_supported_playlist_filter	(void);
 gboolean		 parole_file_filter			(GtkFileFilter *filter,
 								 ParoleFile *file);
 
-ParoleFileFormat	 parole_file_guess_format		(ParoleFile *file);
-
 G_END_DECLS
 
 #endif /* PAROLE_FILTERS_H */
diff --git a/parole/parole-pl-parser.c b/parole/parole-pl-parser.c
index 905b8a3..1e1d2da 100644
--- a/parole/parole-pl-parser.c
+++ b/parole/parole-pl-parser.c
@@ -230,60 +230,6 @@ parole_asx_xml_end (GMarkupParseContext *context, const gchar *element_name,
     }
 }
 
-ParolePlFormat
-parole_pl_parser_guess_format_from_extension (const gchar *filename)
-{
-    if ( g_str_has_suffix (filename, ".m3u") || g_str_has_suffix (filename, ".M3U") )
-	return PAROLE_PL_FORMAT_M3U;
-	
-    if ( g_str_has_suffix (filename, ".pls") || g_str_has_suffix (filename, ".PLS") )
-	return PAROLE_PL_FORMAT_PLS;
-	
-    if ( g_str_has_suffix (filename, ".xspf") || g_str_has_suffix (filename, ".XSPF") )
-	return PAROLE_PL_FORMAT_XSPF;
-	
-    if ( g_str_has_suffix (filename, ".asx") || g_str_has_suffix (filename, ".ASX") )
-	return PAROLE_PL_FORMAT_ASX;
-	
-    if ( g_str_has_suffix (filename, ".wax") || g_str_has_suffix (filename, ".WAX") )
-	return PAROLE_PL_FORMAT_XSPF;
-	
-    return PAROLE_PL_FORMAT_UNKNOWN;
-}
-
-static ParolePlFormat
-parole_pl_parser_guess_format_from_data (const gchar *filename)
-{
-    GFile *file;
-    gchar *contents = NULL;
-    gsize size;
-    
-    ParolePlFormat format = PAROLE_PL_FORMAT_UNKNOWN;
-    
-    file = g_file_new_for_path (filename);
-
-    if ( !g_file_load_contents (file, NULL, &contents, &size, NULL, NULL ) )
-    {
-	g_debug ("Unable to load content of file=%s", filename);
-	goto out;
-    }
-
-    if ( strstr (contents, "<ASX VERSION") )
-	format = PAROLE_PL_FORMAT_ASX;
-    else if ( strstr (contents, "<trackList>") || strstr (contents, "<tracklist>") )
-	format = PAROLE_PL_FORMAT_XSPF;
-    else if ( strstr (contents, "NumberOfEntries") )
-	format = PAROLE_PL_FORMAT_PLS;
-    else 
-	/* try to load the file as M3U*/
-	format = PAROLE_PL_FORMAT_M3U;
-
-    g_free (contents);
-out:
-    g_object_unref (file);
-    return format;
-}
-
 static GSList *
 parole_pl_parser_parse_asx (const gchar *filename)
 {
@@ -534,62 +480,6 @@ parole_pl_parser_parse (ParolePlFormat format, const gchar *filename)
     return list;
 }
 
-gboolean parole_pl_parser_can_parse_data (const guchar *data, gint len)
-{
-    gchar *mime_type = NULL;
-    gboolean result_uncertain;
-    gboolean result = FALSE;
-
-    mime_type = g_content_type_guess (NULL, data, len,  &result_uncertain);
-    
-    if ( mime_type && result_uncertain == FALSE )
-    {
-	GtkFileFilter *filter = g_object_ref_sink (parole_get_supported_playlist_filter ());
-	GtkFileFilterInfo filter_info;
-	g_debug ("Mime_type=%s", mime_type);
-	filter_info.mime_type = mime_type;
-    
-	filter_info.contains = GTK_FILE_FILTER_MIME_TYPE;
-    
-	result = gtk_file_filter_filter (filter, &filter_info);
-	g_object_unref (filter);
-	g_free (mime_type);
-    }
-    
-    return result;
-}
-
-GSList *parole_pl_parser_parse_from_file_by_extension (const gchar *filename)
-{
-    ParolePlFormat format = PAROLE_PL_FORMAT_UNKNOWN;
-    GSList *list = NULL;
-    
-    if ( (format = parole_pl_parser_guess_format_from_extension (filename)) == PAROLE_PL_FORMAT_UNKNOWN &&
-	 (format = parole_pl_parser_guess_format_from_data (filename)) == PAROLE_PL_FORMAT_UNKNOWN ) 
-    {
-	g_debug ("Unable to guess playlist format : %s", filename);
-	goto out;
-    }
-
-    PAROLE_DEBUG_ENUM_FULL (format, PAROLE_ENUM_TYPE_PL_FORMAT, "playlist %s ", filename);
-    list = parole_pl_parser_parse (format, filename);
-	
-out:
-    return list;
-}
-
-GSList *parole_pl_parser_parse_all_from_file (const gchar *filename)
-{
-    GSList *list = NULL;
-    
-    list = parole_pl_parser_parse_asx (filename);
-    list = g_slist_concat (list, parole_pl_parser_parse_m3u (filename));
-    list = g_slist_concat (list, parole_pl_parser_parse_pls (filename));
-    list = g_slist_concat (list, parole_pl_parser_parse_xspf (filename));
-    
-    return list;
-}
-
 static gboolean
 parole_pl_parser_save_m3u (FILE *f, GSList *files)
 {
@@ -685,6 +575,95 @@ parole_pl_parser_save_xspf (FILE *f, GSList *files)
     return TRUE;
 }
 
+/**
+ * parole_pl_parser_guess_format_from_extension:
+ * @filename: a filename.
+ * 
+ * Guess a playlist format from the filename extension.
+ * 
+ * Returns: PAROLE_PL_FORMAT_UNKNOWN if unable to get the playlist format, and a valid  
+ *          playlist format otherwise.
+ * 
+ * Since: 0.2
+ */
+ParolePlFormat
+parole_pl_parser_guess_format_from_extension (const gchar *filename)
+{
+    if ( g_str_has_suffix (filename, ".m3u") || g_str_has_suffix (filename, ".M3U") )
+	return PAROLE_PL_FORMAT_M3U;
+	
+    if ( g_str_has_suffix (filename, ".pls") || g_str_has_suffix (filename, ".PLS") )
+	return PAROLE_PL_FORMAT_PLS;
+	
+    if ( g_str_has_suffix (filename, ".xspf") || g_str_has_suffix (filename, ".XSPF") )
+	return PAROLE_PL_FORMAT_XSPF;
+	
+    if ( g_str_has_suffix (filename, ".asx") || g_str_has_suffix (filename, ".ASX") )
+	return PAROLE_PL_FORMAT_ASX;
+	
+    if ( g_str_has_suffix (filename, ".wax") || g_str_has_suffix (filename, ".WAX") )
+	return PAROLE_PL_FORMAT_XSPF;
+	
+    return PAROLE_PL_FORMAT_UNKNOWN;
+}
+
+/**
+ * parole_pl_parser_guess_format_from_data:
+ * @filename: a filename.
+ * 
+ * Guess a playlist format from its data.
+ * 
+ * Returns: PAROLE_PL_FORMAT_UNKNOWN if unable to get the playlist format, and a valid  
+ *          playlist format otherwise.
+ * 
+ * Since: 0.2
+ */
+ParolePlFormat
+parole_pl_parser_guess_format_from_data (const gchar *filename)
+{
+    GFile *file;
+    gchar *contents = NULL;
+    gsize size;
+    
+    ParolePlFormat format = PAROLE_PL_FORMAT_UNKNOWN;
+    
+    file = g_file_new_for_path (filename);
+
+    if ( !g_file_load_contents (file, NULL, &contents, &size, NULL, NULL ) )
+    {
+	g_debug ("Unable to load content of file=%s", filename);
+	goto out;
+    }
+
+    if ( strstr (contents, "<ASX VERSION") )
+	format = PAROLE_PL_FORMAT_ASX;
+    else if ( strstr (contents, "<trackList>") || strstr (contents, "<tracklist>") )
+	format = PAROLE_PL_FORMAT_XSPF;
+    else if ( strstr (contents, "NumberOfEntries") )
+	format = PAROLE_PL_FORMAT_PLS;
+    else 
+	/* try to load the file as M3U*/
+	format = PAROLE_PL_FORMAT_M3U;
+
+    g_free (contents);
+out:
+    g_object_unref (file);
+    return format;
+}
+
+/**
+ * parole_pl_parser_save_from_files:
+ * @files: a #GSList list of #ParoleFile files.
+ * @filename: a filename to save.
+ * @format: a #ParolePlFormat format of the playlist.
+ * 
+ * Saves a #GSList containing a list of #ParoleFile files to filename.
+ * 
+ * 
+ * Returns: TRUE if the playlist was saved, FALSE otherwise.
+ * 
+ * Since: 0.2
+ **/
 gboolean parole_pl_parser_save_from_files (GSList *files, const gchar *filename, ParolePlFormat format)
 {
     FILE *f;
@@ -716,3 +695,92 @@ gboolean parole_pl_parser_save_from_files (GSList *files, const gchar *filename,
     
     return ret_val;
 }
+
+/**
+ * parole_pl_parser_parse_from_file_by_extension:
+ * @filename: a filename.
+ * 
+ * 
+ * Returns: a #GSList containts a list of #Parolefile parsed from the playlist, 
+ *          or NULL if no files were parsed.
+ * 
+ * Since: 0.2
+ */
+GSList *parole_pl_parser_parse_from_file_by_extension (const gchar *filename)
+{
+    ParolePlFormat format = PAROLE_PL_FORMAT_UNKNOWN;
+    GSList *list = NULL;
+    
+    if ( (format = parole_pl_parser_guess_format_from_extension (filename)) == PAROLE_PL_FORMAT_UNKNOWN &&
+	 (format = parole_pl_parser_guess_format_from_data (filename)) == PAROLE_PL_FORMAT_UNKNOWN ) 
+    {
+	g_debug ("Unable to guess playlist format : %s", filename);
+	goto out;
+    }
+
+    PAROLE_DEBUG_ENUM_FULL (format, PAROLE_ENUM_TYPE_PL_FORMAT, "playlist %s ", filename);
+    list = parole_pl_parser_parse (format, filename);
+	
+out:
+    return list;
+}
+
+/**
+ * parole_pl_parser_parse_all_from_file:
+ * @filename: a filename
+ * 
+ * This function tries to parse a playlist without guessing the playlist format.
+ * 
+ * 
+ * Returns: a #GSList containts a list of #Parolefile parsed from the playlist, 
+ *          or NULL if no files were parsed.
+ * 
+ * Since: 0.2
+ */
+GSList *parole_pl_parser_parse_all_from_file (const gchar *filename)
+{
+    GSList *list = NULL;
+    
+    list = parole_pl_parser_parse_asx (filename);
+    list = g_slist_concat (list, parole_pl_parser_parse_m3u (filename));
+    list = g_slist_concat (list, parole_pl_parser_parse_pls (filename));
+    list = g_slist_concat (list, parole_pl_parser_parse_xspf (filename));
+    
+    return list;
+}
+
+/**
+ * parole_pl_parser_can_parse_data:
+ * @data: data.
+ * @len: length of data.
+ * 
+ * Get if the Parole parser can parse from the passed data.
+ * 
+ * Returns: TRUE if it can parse from the data, FALSE otherwise.
+ * 
+ * Since: 0.2
+ */
+gboolean parole_pl_parser_can_parse_data (const guchar *data, gint len)
+{
+    gchar *mime_type = NULL;
+    gboolean result_uncertain;
+    gboolean result = FALSE;
+
+    mime_type = g_content_type_guess (NULL, data, len,  &result_uncertain);
+    
+    if ( mime_type && result_uncertain == FALSE )
+    {
+	GtkFileFilter *filter = g_object_ref_sink (parole_get_supported_playlist_filter ());
+	GtkFileFilterInfo filter_info;
+	g_debug ("Mime_type=%s", mime_type);
+	filter_info.mime_type = mime_type;
+    
+	filter_info.contains = GTK_FILE_FILTER_MIME_TYPE;
+    
+	result = gtk_file_filter_filter (filter, &filter_info);
+	g_object_unref (filter);
+	g_free (mime_type);
+    }
+    
+    return result;
+}
diff --git a/parole/parole-pl-parser.h b/parole/parole-pl-parser.h
index 9cb4fd0..33dbaeb 100644
--- a/parole/parole-pl-parser.h
+++ b/parole/parole-pl-parser.h
@@ -41,6 +41,8 @@ typedef enum
 
 ParolePlFormat		 parole_pl_parser_guess_format_from_extension   	(const gchar *filename);
 
+ParolePlFormat		 parole_pl_parser_guess_format_from_data	   	(const gchar *filename);
+
 gboolean		 parole_pl_parser_can_parse_data			(const guchar *data, gint len);
 
 GSList 			*parole_pl_parser_parse_from_file_by_extension     	(const gchar *filename);
diff --git a/parole/parole-provider-player.c b/parole/parole-provider-player.c
index 490e81b..7a85914 100644
--- a/parole/parole-provider-player.c
+++ b/parole/parole-provider-player.c
@@ -70,6 +70,8 @@ static void parole_provider_player_base_init (gpointer klass)
 	 * @stream: a #ParoleStream.
 	 * @state: the new state.
 	 * 
+	 * Issued when the Parole state changed.
+	 * 
 	 * Since: 0.2 
 	 **/
         g_signal_new ("state-changed",
@@ -86,6 +88,8 @@ static void parole_provider_player_base_init (gpointer klass)
 	 * @player: the object which received the signal.
 	 * @stream: a #ParoleStream.
 	 * 
+	 * Indicated that the stream tags were found and ready to be read.
+	 * 
 	 * Since: 0.2 
 	 **/
 	g_signal_new ("tag-message",
@@ -106,10 +110,13 @@ static void parole_provider_player_class_init (gpointer klass)
 
 /**
  * parole_provider_player_get_main_window:
- * @player: a 
+ * @player: a #ParoleProviderPlayer 
  * 
+ * Ask the Player to get the Parole main window.
  * 
- * Returns: 
+ * Returns: #GtkWidget window.
+ * 
+ * Since: 0.2
  **/
 GtkWidget *parole_provider_player_get_main_window (ParoleProviderPlayer *player)
 {
@@ -126,10 +133,16 @@ GtkWidget *parole_provider_player_get_main_window (ParoleProviderPlayer *player)
 
 /**
  * parole_provider_player_pack:
- * @player:
- * @widget:
- * @title:
- * @container:
+ * @player: a #ParoleProviderPlayer
+ * @widget: a #GtkWidget.
+ * @title: title
+ * @container: a #ParolePluginContainer.
+ * 
+ * Ask the player to pack a widget in the playlist notebook if PAROLE_PLUGIN_CONTAINER_PLAYLIST 
+ * is specified or in the main window notebook if PAROLE_PLUGIN_CONTAINER_MAIN_VIEW is specified.
+ * 
+ * This function can be called once, the Player is responsible on removing the widget in
+ * case the plugin was unloaded.
  * 
  **/ 
 void parole_provider_player_pack (ParoleProviderPlayer *player, GtkWidget *widget, 
@@ -145,10 +158,11 @@ void parole_provider_player_pack (ParoleProviderPlayer *player, GtkWidget *widge
 		
 /**
  * parole_provider_player_get_state:
- * @player:
+ * @player: a #ParoleProviderPlayer
  * 
+ * Get the current state of the player.
  * 
- * Returns:
+ * Returns: a #ParoleState.
  * 
  * 
  * Since: 0.2
@@ -172,9 +186,13 @@ ParoleState parole_provider_player_get_state (ParoleProviderPlayer *player)
  * @player: a #ParoleProviderPlayer
  * @uri: uri
  * 
+ * Issue a play command on the backend for the given uri, note this function
+ * can be called only of the Parole current state is PAROLE_STATE_STOPPED.
  * 
- * Returns:
+ * Returning TRUE doesn't mean that the funtion succeeded to change the state of the player, 
+ * the state change is indicated asynchronously by #ParoleProviderPlayerIface::state-changed signal.
  * 
+ * Returns: TRUE if the command is processed, FALSE otherwise.
  * 
  * Since: 0.2
  **/
@@ -196,8 +214,13 @@ gboolean parole_provider_player_play_uri (ParoleProviderPlayer *player, const gc
  * parole_provider_player_pause:
  * @player: a #ParoleProviderPlayer
  * 
+ * Issue a pause command to the backend, this function can be called when the state of the player
+ * is PAROLE_STATE_PLAYING.
+ * 
+ * Returning TRUE doesn't mean that the funtion succeeded to change the state of the player, 
+ * the state change is indicated asynchronously by #ParoleProviderPlayerIface::state-changed signal.
  * 
- * Returns:
+ * Returns: TRUE if the command is processed, FALSE otherwise.
  * 
  * 
  * Since: 0.2
@@ -222,7 +245,13 @@ gboolean parole_provider_player_pause (ParoleProviderPlayer *player)
  * @player: a #ParoleProviderPlayer
  * 
  * 
- * Returns:
+ * Issue a resume command to the player, this function can be called when
+ * the current state of the player is PAROLE_STATE_PAUSED.
+ * 
+ * Returning TRUE doesn't mean that the funtion succeeded to change the state of the player, 
+ * the state change is indicated asynchronously by #ParoleProviderPlayerIface::state-changed signal.
+ * 
+ * Returns: TRUE if the command is processed, FALSE otherwise.
  * 
  * 
  * Since: 0.2
@@ -246,9 +275,12 @@ gboolean parole_provider_player_resume (ParoleProviderPlayer *player)
  * parole_provider_player_stop:
  * @player: a #ParoleProviderPlayer
  * 
+ * Issue a stop command to the player.
  * 
- * Returns:
+ * Returning TRUE doesn't mean that the funtion succeeded to change the state of the player, 
+ * the state change is indicated asynchronously by #ParoleProviderPlayerIface::state-changed signal.
  * 
+ * Returns: TRUE if the command is processed, FALSE otherwise.
  * 
  * Since: 0.2
  **/
@@ -270,9 +302,12 @@ gboolean parole_provider_player_stop (ParoleProviderPlayer *player)
 /**
  * parole_provider_player_seek:
  * @player: a #ParoleProviderPlayer
+ * @pos: position to seek.
+ * 
  * 
+ * Issue a seek command.
  * 
- * Returns:
+ * Returns: TRUE if the seek command succeeded, FALSE otherwise.
  * 
  * 
  * Since: 0.2
@@ -296,7 +331,7 @@ gboolean parole_provider_player_seek (ParoleProviderPlayer *player, gdouble pos)
  * parole_provider_player_open_media_chooser:
  * @player: a #ParoleProviderPlayer
  * 
- * 
+ * Ask Parole to open its media chooser dialog.
  * 
  * Since: 0.2
  **/
diff --git a/parole/parole-provider-plugin.c b/parole/parole-provider-plugin.c
index 09d8291..4c01645 100644
--- a/parole/parole-provider-plugin.c
+++ b/parole/parole-provider-plugin.c
@@ -101,6 +101,8 @@ void parole_provider_plugin_configure (ParoleProviderPlugin *provider, GtkWidget
  * @provider: a #ParoleProviderPlugin
  * @player: a #ParoleProviderPlayer
  * 
+ * The player calls this method on the iface_init funtion implemented by the plugin
+ * to set the #ParoleProviderPlayer, don't take any reference of the Player.
  * 
  * Since: 0.2
  **/
diff --git a/parole/parole.h.in b/parole/parole.h.in
index a4f5a8c..df169dc 100644
--- a/parole/parole.h.in
+++ b/parole/parole.h.in
@@ -33,6 +33,8 @@
 #include <parole/parole-filters.h>
 #include <parole/parole-debug.h>
 
+#include <libxfce4util/libxfce4util.h>
+
 #define PAROLE_MAJOR_VERSION		@PAROLE_VERSION_MAJOR@
 #define PAROLE_MINOR_VERSION		@PAROLE_VERSION_MINOR@
 #define PAROLE_MICRO_VERSION		@PAROLE_VERSION_MICRO@
diff --git a/plugins/sample/sample-plugin.c b/plugins/sample/sample-plugin.c
index 5e19a2e..4d23875 100644
--- a/plugins/sample/sample-plugin.c
+++ b/plugins/sample/sample-plugin.c
@@ -22,7 +22,7 @@
 #include <config.h>
 #endif
 
-#include <libxfce4util/libxfce4util.h>
+#include <parole/parole.h>
 
 #include "sample-provider.h"
 
diff --git a/plugins/sample/sample-provider.c b/plugins/sample/sample-provider.c
index 320d440..783e4fd 100644
--- a/plugins/sample/sample-provider.c
+++ b/plugins/sample/sample-provider.c
@@ -22,8 +22,6 @@
 #include <config.h>
 #endif
 
-#include <glib/gi18n.h>
-
 #include "sample-provider.h"
 
 static void   sample_provider_iface_init 	   (ParoleProviderPluginIface *iface);
diff --git a/plugins/tray/tray-provider.c b/plugins/tray/tray-provider.c
index 92634ac..5d5883f 100644
--- a/plugins/tray/tray-provider.c
+++ b/plugins/tray/tray-provider.c
@@ -200,7 +200,11 @@ notify_playing (TrayProvider *tray, const ParoleStream *stream)
     gboolean live, has_audio, has_video;
     gchar *title;
     gchar *message;
-    gdouble duration;
+    gint64 duration;
+    gint  hours;
+    gint  minutes;
+    gint  seconds;
+    gchar timestring[128];
     ParoleMediaType media_type;
     
     if ( !tray->notify || !tray->enabled)
@@ -239,8 +243,22 @@ notify_playing (TrayProvider *tray, const ParoleStream *stream)
 	g_free (title);
 	return;
     }
+        
+    minutes =  duration / 60;
+    seconds = duration % 60;
+    hours = minutes / 60;
+    minutes = minutes % 60;
+
+    if ( hours == 0 )
+    {
+	g_snprintf (timestring, 128, "%02i:%02i", minutes, seconds);
+    }
+    else
+    {
+	g_snprintf (timestring, 128, "%i:%02i:%02i", hours, minutes, seconds);
+    }
     
-    message = g_strdup_printf ("%s %s %s %4.2f", _("<b>Playing:</b>"), title, _("<b>Duration:</b>"), duration);
+    message = g_strdup_printf ("%s %s %s %s", _("<b>Playing:</b>"), title, _("<b>Duration:</b>"), timestring);
     
     tray->n = notify_notification_new (title, message, NULL, NULL);
     g_free (title);



More information about the Xfce4-commits mailing list