Formatting fixes

2008-05-26  Matthias Clasen  <mclasen@redhat.com>

        * gtk/gtkshow.[hc]: Formatting fixes

        * gtk/gtkmountoperation.c: Add docs


svn path=/trunk/; revision=20169

7 files changed, 149 insertions, 28 deletions

diff --git a/ChangeLog b/ChangeLog
index 70b9743ced..c7b3d698f1 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2008-05-26  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/gtkshow.[hc]: Formatting fixes
+
+	* gtk/gtkmountoperation.c: Add docs
+
 2008-05-25  Cody Russell  <bratsche@gnome.org>
 
 	Bug 507389 – use gslice for gtksettings
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index f14f1378c3..d2a0c7ebe3 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+2008-05-26  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/gtk-sections.txt: 
+	* gtk/gtk-docs.sgml: Add a section for GtkMountOperation
+	
 2008-05-25  Matthias Clasen  <mclasen@redhat.com>
 
 	Bug 465144 - gtkprintjob.h is not included with gtk.h
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 0fd2de55b6..43f22e3b1d 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -234,6 +234,7 @@
 <!ENTITY gtk-builder-convert SYSTEM "gtk-builder-convert.xml">
 <!ENTITY gtk-glossary SYSTEM "xml/glossary.xml">
 <!ENTITY gtk-Testing SYSTEM "xml/gtktesting.xml">
+<!ENTITY gtk-Filesystem SYSTEM "xml/filesystem.xml">
 ]>
 <book id="index">
   <bookinfo>
@@ -350,6 +351,7 @@ that is, GUI components such as #GtkButton or #GtkTextView.
     &gtk-Signals;
     &gtk-Types;
     &gtk-Testing;
+    &gtk-Filesystem;
   </part>
 
   <part id="gtkobjects">
diff --git a/docs/reference/gtk/gtk-sections.txt b/docs/reference/gtk/gtk-sections.txt
index 5950bec4d1..df0f17cc3f 100644
--- a/docs/reference/gtk/gtk-sections.txt
+++ b/docs/reference/gtk/gtk-sections.txt
@@ -6755,3 +6755,21 @@ gtk_test_text_set
 gtk_test_widget_click
 gtk_test_widget_send_key
 </SECTION>
+
+<SECTION>
+<FILE>filesystem</FILE>
+<TITLE>Filesystem utilities</TITLE>
+GtkMountOperation
+gtk_mount_operation_new
+gtk_mount_operation_is_showing
+gtk_mount_operation_set_parent
+gtk_mount_operation_get_parent
+gtk_mount_operation_set_screen
+gtk_mount_operation_get_screen
+gtk_show_uri
+<SUBSECTION Standard>
+GtkMountOperationClass
+<SUBSECTION Private>
+gtk_mount_operation_get_type
+GtkMountOperationPrivate
+</SECTION>
diff --git a/gtk/gtkmountoperation.c b/gtk/gtkmountoperation.c
index 6414c5c743..38fe03c391 100644
--- a/gtk/gtkmountoperation.c
+++ b/gtk/gtkmountoperation.c
@@ -46,6 +46,28 @@
 #include "gtkwindow.h"
 #include "gtkalias.h"
 
+/**
+ * SECTION:filesystem
+ * @short_description: Functions for working with GIO
+ *
+ * The functions and objects described here make working with GTK+ and
+ * GIO more convenient. #GtkMountOperation is needed when mounting volumes
+ * and gtk_show_uri() is a convenient way to launch applications for URIs.
+ * Another object that is worth mentioning in this context is 
+ * #GdkAppLaunchContext, which provides visual feedback when lauching
+ * applications.
+ */
+
+/** 
+ * GtkMountOperation:
+ *
+ * #GtkMountOperation is an implementation of #GMountOperation that 
+ * can be used with GIO functions for mounting volumes such as
+ * g_file_mount_enclosing_volume() or g_file_mount_mountable().
+ *
+ * When necessary, #GtkMountOperation shows dialogs to ask for passwords.
+ */
+
 /* GObject, GtkObject methods
  */
 static void   gtk_mount_operation_set_property (GObject          *object,
@@ -160,10 +182,10 @@ gtk_mount_operation_class_init (GtkMountOperationClass *klass)
 
 
 static void
-gtk_mount_operation_set_property (GObject         *object,
-                                  guint            prop_id,
-                                  const GValue    *value,
-                                  GParamSpec      *pspec)
+gtk_mount_operation_set_property (GObject      *object,
+                                  guint         prop_id,
+                                  const GValue *value,
+                                  GParamSpec   *pspec)
 {
   GtkMountOperation *operation;
   gpointer tmp;
@@ -190,10 +212,10 @@ gtk_mount_operation_set_property (GObject         *object,
 }
 
 static void
-gtk_mount_operation_get_property (GObject         *object,
-                                  guint            prop_id,
-                                  GValue          *value,
-                                  GParamSpec      *pspec)
+gtk_mount_operation_get_property (GObject    *object,
+                                  guint       prop_id,
+                                  GValue     *value,
+                                  GParamSpec *pspec)
 {
   GtkMountOperationPrivate *priv;
   GtkMountOperation *operation;
@@ -688,6 +710,16 @@ gtk_mount_operation_ask_question (GMountOperation *op,
   g_object_ref (op);
 }
 
+/**
+ * gtk_mount_operation_new:
+ * @parent: transient parent of the window, or %NULL
+ *
+ * Creates a new #GtkMountOperation
+ *
+ * Returns: a new #GtkMountOperation
+ *
+ * Since: 2.14
+ */
 GMountOperation *
 gtk_mount_operation_new (GtkWindow *parent)
 {
@@ -699,6 +731,17 @@ gtk_mount_operation_new (GtkWindow *parent)
   return mount_operation;
 }
 
+/**
+ * gtk_mount_operation_is_showing:
+ * @op: a #GtkMountOperation
+ *
+ * Returns whether the #GtkMountOperation is currently displaying
+ * a window.
+ *
+ * Returns: %TRUE if @op is currently displaying a window
+ *
+ * Since: 2.14
+ */
 gboolean
 gtk_mount_operation_is_showing (GtkMountOperation *op)
 {
@@ -707,6 +750,14 @@ gtk_mount_operation_is_showing (GtkMountOperation *op)
   return op->priv->dialog != NULL;
 }
 
+/**
+ * gtk_mount_operation_set_parent:
+ * @op: a #GtkMountOperation
+ * @parent: transient parent of the window, or %NULL
+ *
+ * Sets the transient parent for windows shown by the
+ * #GtkMountOperation.
+ */
 void
 gtk_mount_operation_set_parent (GtkMountOperation *op,
                                 GtkWindow         *parent)
@@ -744,6 +795,16 @@ gtk_mount_operation_set_parent (GtkMountOperation *op,
   g_object_notify (G_OBJECT (op), "parent");
 }
 
+/**
+ * gtk_mount_operation_get_parent:
+ * @op: a #GtkMountOperation
+ *
+ * Gets the transient parent used by the #GtkMountOperation
+ *
+ * Returns: the transient parent for windows shown by @op
+ *
+ * Since: 2.14
+ */
 GtkWindow *
 gtk_mount_operation_get_parent (GtkMountOperation *op)
 {
@@ -752,6 +813,15 @@ gtk_mount_operation_get_parent (GtkMountOperation *op)
   return op->priv->parent_window;
 }
 
+/**
+ * gtk_mount_operation_set_screen:
+ * @op: a #GtkMountOperation
+ * @screen: a #GdkScreen
+ *
+ * Sets the screen to show windows of the #GtkMountOperation on.
+ *
+ * Since: 2.14
+ */
 void
 gtk_mount_operation_set_screen (GtkMountOperation *op,
                                 GdkScreen         *screen)
@@ -777,6 +847,17 @@ gtk_mount_operation_set_screen (GtkMountOperation *op,
   g_object_notify (G_OBJECT (op), "screen");
 }
 
+/**
+ * gtk_mount_operation_get_screen:
+ * @op: a #GtkMountOperation
+ *
+ * Gets the screen on which windows of the #GtkMountOperation 
+ * will be shown.
+ *
+ * Returns: the screen on which windows of @op are shown
+ *
+ * Since: 2.14
+ */
 GdkScreen *
 gtk_mount_operation_get_screen (GtkMountOperation *op)
 {
diff --git a/gtk/gtkshow.c b/gtk/gtkshow.c
index 8c916181ab..949f67b6e6 100644
--- a/gtk/gtkshow.c
+++ b/gtk/gtkshow.c
@@ -29,33 +29,40 @@
 
 #include "gtkshow.h"
 
+#include "gtkalias.h"
+
 
 /**
  * gtk_show_uri:
- * @screen: screen to show the uri on or NULL for the default screen
+ * @screen: screen to show the uri on or %NULL for the default screen
  * @uri: the uri to show
  * @timestamp: a timestamp to prevent focus stealing. 
  * @error: a #GError that is returned in case of errors
  *
- * This is a convenience function for launching the default application to show 
- * the uri. The uri can amongst others (depending on support in gio/gvfs) take 
- * the following forms:
- * "file:///home/gnome/pict.jpg",
- * "http://www.gnome.org",
- * "mailto:me@gnome.org",
- * "ghelp:eog".
- * Ideally the timestamp is taken from the event triggering gtk_show_uri. 
- * If timestamp is not known you can take %GDK_CURRENT_TIME
+ * This is a convenience function for launching the default application 
+ * to show the uri. The uri must be of a form understood by GIO. Typical
+ * examples are 
+ * <simplelist>
+ *   <member><filename>file:///home/gnome/pict.jpg</filename></member>
+ *   <member><filename>http://www.gnome.org</filename></member>
+ *   <member><filename>mailto:me&commat;gnome.org</filename></member>
+ * </simplelist>
+ * Ideally the timestamp is taken from the event triggering 
+ * the gtk_show_uri() call. If timestamp is not known you can take 
+ * %GDK_CURRENT_TIME.
+ *
+ * This function can be used as a replacement for gnome_vfs_url_show() 
+ * and gnome_url_show().
  *
  * Returns: %TRUE on success, %FALSE on error.
  *
  * Since: 2.14
  */
 gboolean
-gtk_show_uri (GdkScreen *screen, 
-              const char* uri, 
-              guint32 timestamp, 
-              GError **error)
+gtk_show_uri (GdkScreen    *screen, 
+              const gchar  *uri, 
+              guint32       timestamp, 
+              GError      **error)
 {
   GdkAppLaunchContext *context;
   gboolean ret;
@@ -63,9 +70,7 @@ gtk_show_uri (GdkScreen *screen,
   g_return_val_if_fail (uri != NULL, FALSE);
 
   context = gdk_app_launch_context_new ();
-
   gdk_app_launch_context_set_screen (context, screen);
-  
   gdk_app_launch_context_set_timestamp (context, timestamp);
 
   ret = g_app_info_launch_default_for_uri (uri, (GAppLaunchContext*)context, error);
@@ -73,3 +78,7 @@ gtk_show_uri (GdkScreen *screen,
 
   return ret;
 }
+
+
+#define __GTK_SHOW_C__
+#include "gtkaliasdef.c"
diff --git a/gtk/gtkshow.h b/gtk/gtkshow.h
index 68699c1ff5..9a3faf015a 100644
--- a/gtk/gtkshow.h
+++ b/gtk/gtkshow.h
@@ -27,10 +27,10 @@
 
 G_BEGIN_DECLS
 
-gboolean gtk_show_uri  (GdkScreen *screen, 
-                        const char* uri, 
-                        guint32 timestamp, 
-                        GError **error);
+gboolean gtk_show_uri  (GdkScreen   *screen, 
+                        const gchar *uri, 
+                        guint32      timestamp, 
+                        GError     **error);
 
 G_END_DECLS