docs/manual/appendix-integration.xml: Update GNOME integration section to use gst_ini...

Original commit message from CVS:
* docs/manual/appendix-integration.xml:
Update GNOME integration section to use gst_init_get_option_group()
instead of the old popt stuff (#322911). Also, GNOME applications
should  now use gconf*sink and gconf*src instead of the old gconf
helper lib we had.

diff --git a/ChangeLog b/ChangeLog
index 36b1f70..c0f9104 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2006-01-13  Tim-Philipp Müller  <tim at centricular dot net>
+
+       * docs/manual/appendix-integration.xml:
+         Update GNOME integration section to use gst_init_get_option_group()
+         instead of the old popt stuff (#322911). Also, GNOME applications
+         should  now use gconf*sink and gconf*src instead of the old gconf
+         helper lib we had.
+
 2006-01-13  Stefan Kost  <ensonic@users.sf.net>
 
 

diff --git a/docs/manual/appendix-integration.xml b/docs/manual/appendix-integration.xml
index eae9e7e..020d55b 100644 (file)
--- a/docs/manual/appendix-integration.xml
+++ b/docs/manual/appendix-integration.xml
@@ -68,27 +68,72 @@
           <function>gst_init ()</function> to do the same for GStreamer.
           This would mean that only one of the two can parse command-line
           options. To work around this issue, &GStreamer; can provide a
-          <classname>poptOption</classname> array which can be passed to
-          <function>gnome_program_init ()</function>.
+          GLib <classname>GOptionGroup</classname> which can be passed to
+          <function>gnome_program_init ()</function>. The following
+          example requires Gnome-2.14 or newer (previous libgnome versions
+          do not support command line parsing via GOption yet but use the
+          now deprecated popt)
         </para>
         <programlisting><!-- example-begin gnome.c a -->
 #include &lt;gnome.h&gt;
 #include &lt;gst/gst.h&gt;
 
+static gchar **cmd_filenames = NULL;
+
+static GOptionEntries cmd_options[] = {
+  /* here you can add command line options for your application. Check
+   * the GOption section in the GLib API reference for a more elaborate
+   * example of how to add your own command line options here */
+
+  /* at the end we have a special option that collects all remaining 
+   * command line arguments (like filenames) for us. If you don&apos;
+   * need this, you can safely remove it */
+  { G_OPTION_REMAINING, 0, 0, G_OPTION_ARG_FILENAME_ARRAY, &amp;cmd_filenames,
+    "Special option that collects any remaining arguments for us" },
+
+  /* mark the end of the options array with a NULL option */
+  { NULL, }
+};
+
+/* this should usually be defined in your config.h */
+#define VERSION "0.0.1"
+
 gint
-main (gint   argc,
-      gchar *argv[])
+main (gint argc, gchar **argv)
 {
-  struct poptOption options[] = {
-    {NULL, '\0', POPT_ARG_INCLUDE_TABLE, NULL, 0, "GStreamer", NULL},
-    POPT_TABLEEND
-  };
-
-  /* init GStreamer and GNOME using the GStreamer popt tables */
-  options[0].arg = (void *) gst_init_get_popt_table ();
-  gnome_program_init ("my-application", "0.0.1", LIBGNOMEUI_MODULE, argc, argv,
-                     GNOME_PARAM_POPT_TABLE, options,
-                     NULL);
+  GOptionContext *context;
+  GOptionGroup *gstreamer_group;
+  GnomeProgram *program;
+
+  context = g_option_context_new ("gnome-demo-app");
+
+  /* get command line options from GStreamer and add them to the group */
+  gstreamer_group = gst_init_get_option_group ();
+  g_option_context_add_group (context, gstreamer_group);
+
+  /* add our own options. If you are using gettext for translation of your
+   * strings, use GETTEXT_PACKAGE here instead of NULL */
+  g_option_context_add_main_entries (context, cmd_options, NULL);
+
+  program = gnome_program_init ("gnome-demo-app", VERSION
+                                LIBGNOMEUI_MODULE, argc, argv,
+                                GNOME_PARAM_HUMAN_READABLE_NAME, "Gnome Demo",
+                                GNOME_PARAM_GOPTION_CONTEXT, context,
+                                NULL);
+
+  /* any filenames we got passed on the command line? parse them! */
+  if (cmd_filenames != NULL) {
+    guint i, num;
+
+    num = g_strv_length (cmd_filenames);
+    for (i = 0; i &lt; num; ++i) {
+      /* do something with the filename ... */
+      g_print ("Adding to play queue: %s\n", cmd_filenames[i]);
+    }
+
+    g_strfreev (cmd_filenames);
+    cmd_filenames = NULL;
+  }
 <!-- example-end gnome.c a -->
 [..]<!-- example-begin gnome.c b --><!--
   return 0;
@@ -100,11 +145,13 @@ main (gint   argc,
       <listitem>
         <para>
           GNOME stores the default video and audio sources and sinks in GConf.
-          &GStreamer; provides a small utility library that can be used to
-          get the elements from the registry using functions such as
-          <function>gst_gconf_get_default_video_sink ()</function>. See the
-          header file (<filename>gst/gconf/gconf.h</filename>) for details.
-          All GNOME applications are recommended to use those variables.
+          &GStreamer; provides a number of elements that create audio and
+          video sources and sinks directly based on those GConf settings. 
+          Those elements are: gconfaudiosink, gconfvideosink, gconfaudiosrc
+          and gconfvideosrc. You can create them with
+          <function>gst_element_factory_make ()</function> and use them
+          directly just like you would use any other source or sink element.
+          All GNOME applications are recommended to use those elements.
         </para>
       </listitem>
       <listitem>