Add gtk_file_chooser_set_current_name() to set the current entry contents.

Fri Jul 11 14:37:07 2003  Owen Taylor  <otaylor@redhat.com>

        * gtkfilechooser.[ch] gtkfilechooserprivate.h
        gtkfilechooserimpldefault.c: Add
        gtk_file_chooser_set_current_name() to set the current
        entry contents.

        * *.c: Consistently use '-' not '_' in property names and
        signal names.

        * gtkfilechooser.c: Document all exported functions.

8 files changed, 450 insertions, 84 deletions

diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index d6a077cc2d..8daedd8125 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -25,9 +25,10 @@
 
 #define _(str) (str)
 
-static void gtk_file_chooser_base_init (gpointer g_class);
+static void gtk_file_chooser_base_init (gpointer g_iface);
 
-static GtkFilePath *gtk_file_chooser_get_path (GtkFileChooser *chooser);
+static GtkFilePath *gtk_file_chooser_get_path         (GtkFileChooser *chooser);
+static GtkFilePath *gtk_file_chooser_get_preview_path (GtkFileChooser *chooser);
 
 GType
 gtk_file_chooser_get_type (void)
@@ -54,22 +55,22 @@ gtk_file_chooser_get_type (void)
 }
 
 static void
-gtk_file_chooser_base_init (gpointer g_class)
+gtk_file_chooser_base_init (gpointer g_iface)
 {
   static gboolean initialized = FALSE;
   
   if (!initialized)
     {
-      GType iface_type = G_TYPE_FROM_INTERFACE (g_class);
+      GType iface_type = G_TYPE_FROM_INTERFACE (g_iface);
 
-      g_signal_new ("current_folder_changed",
+      g_signal_new ("current-folder-changed",
 		    iface_type,
 		    G_SIGNAL_RUN_LAST,
 		    G_STRUCT_OFFSET (GtkFileChooserIface, current_folder_changed),
 		    NULL, NULL,
 		    g_cclosure_marshal_VOID__VOID,
 		    G_TYPE_NONE, 0);
-      g_signal_new ("selection_changed",
+      g_signal_new ("selection-changed",
 		    iface_type,
 		    G_SIGNAL_RUN_LAST,
 		    G_STRUCT_OFFSET (GtkFileChooserIface, selection_changed),
@@ -77,52 +78,52 @@ gtk_file_chooser_base_init (gpointer g_class)
 		    g_cclosure_marshal_VOID__VOID,
 		    G_TYPE_NONE, 0);
 
-      g_object_interface_install_property (iface_type,
+      g_object_interface_install_property (g_iface,
 					   g_param_spec_enum ("action",
 							      _("Action"),
-							      _("The type of action that the file selector is performing"),
+							      _("The type of operation that the file selector is performing"),
 							      GTK_TYPE_FILE_CHOOSER_ACTION,
 							      GTK_FILE_CHOOSER_ACTION_OPEN,
 							      G_PARAM_READWRITE));
-      g_object_interface_install_property (iface_type,
-					   g_param_spec_object ("file_system",
+      g_object_interface_install_property (g_iface,
+					   g_param_spec_object ("file-system",
 								_("File System"),
 								_("File system object to use"),
 								GTK_TYPE_FILE_SYSTEM,
 								G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
-      g_object_interface_install_property (iface_type,
-					   g_param_spec_boolean ("folder_mode",
+      g_object_interface_install_property (g_iface,
+					   g_param_spec_boolean ("folder-mode",
 								 _("Folder Mode"),
 								 _("Whether to select folders rather than files"),
 								 FALSE,
 								 G_PARAM_READWRITE));
-      g_object_interface_install_property (iface_type,
-					   g_param_spec_boolean ("local_only",
+      g_object_interface_install_property (g_iface,
+					   g_param_spec_boolean ("local-only",
 								 _("Local Only"),
 								 _("Whether the selected file(s) should be limited to local file: URLs"),
 								 TRUE,
 								 G_PARAM_READWRITE));
-      g_object_interface_install_property (iface_type,
-					   g_param_spec_object ("preview_widget",
+      g_object_interface_install_property (g_iface,
+					   g_param_spec_object ("preview-widget",
 								_("Preview widget"),
 								_("Application supplied widget for custom previews."),
 								GTK_TYPE_WIDGET,
 								G_PARAM_READWRITE));
-      g_object_interface_install_property (iface_type,
-					   g_param_spec_boolean ("preview_widget_active",
+      g_object_interface_install_property (g_iface,
+					   g_param_spec_boolean ("preview-widget-active",
 								 _("Preview Widget Active"),
-								 _("Whther the application supplied widget for custom previews should be shown."),
+								 _("Whether the application supplied widget for custom previews should be shown."),
 								 TRUE,
 								 G_PARAM_READWRITE));
-      g_object_interface_install_property (iface_type,
-					   g_param_spec_boolean ("select_multiple",
+      g_object_interface_install_property (g_iface,
+					   g_param_spec_boolean ("select-multiple",
 								 _("Select Multiple"),
 								 _("Whether to allow multiple files to be selected"),
 								 FALSE,
 								 G_PARAM_READWRITE));
       
-      g_object_interface_install_property (iface_type,
-					   g_param_spec_boolean ("show_hidden",
+      g_object_interface_install_property (g_iface,
+					   g_param_spec_boolean ("show-hidden",
 								 _("Show Hidden"),
 								 _("Whether the hidden files and folders should be displayed"),
 								 FALSE,
@@ -131,6 +132,17 @@ gtk_file_chooser_base_init (gpointer g_class)
     }
 }
 
+/**
+ * gtk_file_chooser_set_action:
+ * @chooser: a #GtkFileChooser
+ * @action: the action that the file selector is performing
+ * 
+ * Sets the type of operation that that the chooser is performing; the
+ * user interface is adapted to suit the selected action. For example,
+ * an option to create a new folder might be shown if the action is
+ * %GTK_FILE_CHOOSER_ACTION_SAVE but not if the action is
+ * %GTK_FILE_CHOOSER_ACTION_OPEN.
+ **/
 void
 gtk_file_chooser_set_action (GtkFileChooser       *chooser,
 			     GtkFileChooserAction  action)
@@ -140,6 +152,15 @@ gtk_file_chooser_set_action (GtkFileChooser       *chooser,
   g_object_set (chooser, "action", action, NULL);
 }
 
+/**
+ * gtk_file_chooser_get_action:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Gets the type of operation that the file chooser is performing; see
+ * gtk_file_chooser_set_action().
+ * 
+ * Return value: the action that the file selector is performing
+ **/
 GtkFileChooserAction
 gtk_file_chooser_get_action (GtkFileChooser *chooser)
 {
@@ -170,7 +191,7 @@ gtk_file_chooser_set_folder_mode (GtkFileChooser *chooser,
 {
   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 
-  g_object_set (chooser, "folder_mode", folder_mode, NULL);
+  g_object_set (chooser, "folder-mode", folder_mode, NULL);
 }
 
 /**
@@ -190,7 +211,7 @@ gtk_file_chooser_get_folder_mode (GtkFileChooser *chooser)
   
   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
 
-  g_object_get (chooser, "folder_mode", &folder_mode, NULL);
+  g_object_get (chooser, "folder-mode", &folder_mode, NULL);
 
   return folder_mode;
 }
@@ -216,7 +237,7 @@ gtk_file_chooser_set_local_only (GtkFileChooser *chooser,
 {
   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 
-  g_object_set (chooser, "local_only", local_only, NULL);
+  g_object_set (chooser, "local-only", local_only, NULL);
 }
 
 /**
@@ -235,7 +256,7 @@ gtk_file_chooser_get_local_only (GtkFileChooser *chooser)
   
   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
 
-  g_object_get (chooser, "local_only", &local_only, NULL);
+  g_object_get (chooser, "local-only", &local_only, NULL);
 
   return local_only;
 }
@@ -256,7 +277,7 @@ gtk_file_chooser_set_select_multiple (GtkFileChooser *chooser,
 {
   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 
-  g_object_set (chooser, "select_multiple", select_multiple, NULL);
+  g_object_set (chooser, "select-multiple", select_multiple, NULL);
 }
 
 /**
@@ -275,7 +296,7 @@ gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser)
   
   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
 
-  g_object_get (chooser, "select_multiple", &select_multiple, NULL);
+  g_object_get (chooser, "select-multiple", &select_multiple, NULL);
 
   return select_multiple;
 }
@@ -290,7 +311,7 @@ gtk_file_chooser_get_select_multiple (GtkFileChooser *chooser)
  * 
  * Return value: The currently selected filename, or %NULL
  *  if no file is selected, or the selected file can't
- *  be represented with a local filename.
+ *  be represented with a local filename. Free with g_free().
  **/
 gchar *
 gtk_file_chooser_get_filename (GtkFileChooser *chooser)
@@ -312,6 +333,21 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser)
   return result;
 }
 
+/**
+ * gtk_file_chooser_set_filename:
+ * @chooser: a #GtkFileChooser
+ * @filename: the filename to set as current
+ * 
+ * Sets @filename as the current filename for the the file chooser;
+ * If the file name isn't in the current folder of @chooser, then the
+ * current folder of @chooser will be changed to the folder containing
+ * @filename. This is equivalent to a sequence of
+ * gtk_file_chooser_unselect_all() followed by gtk_file_chooser_select_filename().
+ *
+ * Note that the file must exist, or nothing will be done except
+ * for the directory change. To pre-enter a filename for the user, as in
+ * a save-as dialog, use gtk_file_chooser_set_current_name()
+ **/
 void
 gtk_file_chooser_set_filename (GtkFileChooser *chooser,
 			       const gchar    *filename)
@@ -322,6 +358,15 @@ gtk_file_chooser_set_filename (GtkFileChooser *chooser,
   gtk_file_chooser_select_filename (chooser, filename);
 }
 
+/**
+ * gtk_file_chooser_select_filename:
+ * @chooser: a #GtkFileChooser
+ * @filename: the filename to select
+ * 
+ * Selects a filename. If the file name isn't in the current
+ * folder of @chooser, then the current folder of @chooser will
+ * be changed to the folder containing @filename.
+ **/
 void
 gtk_file_chooser_select_filename (GtkFileChooser *chooser,
 				  const gchar    *filename)
@@ -342,6 +387,15 @@ gtk_file_chooser_select_filename (GtkFileChooser *chooser,
     }
 }
 
+/**
+ * gtk_file_chooser_unselect_filename:
+ * @chooser: a #GtkFileChooser
+ * @filename: the filename to unselect
+ * 
+ * Unselects a currently selected filename. If the filename
+ * is not in the current directory, does not exist, or
+ * is otherwise not currently selected, does nothing.
+ **/
 void
 gtk_file_chooser_unselect_filename (GtkFileChooser *chooser,
 				    const char     *filename)
@@ -362,6 +416,19 @@ gtk_file_chooser_unselect_filename (GtkFileChooser *chooser,
     }
 }
 
+/**
+ * gtk_file_chooser_get_filenames:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Lists all the files and subfolders in the current folder of
+ * @chooser. The returned names are full absolute paths. If files
+ * in the current folder cannot be represented as local filenames
+ * they will be ignored. (See gtk_file_chooser_get_uris())
+ * 
+ * Return value: a #GList containing the filenames of all
+ *   files and subfolders in the current folder. Free the returned list
+ *   with g_lists_free(), and the filenames with g_free().
+ **/
 GSList *
 gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
 {
@@ -387,6 +454,15 @@ gtk_file_chooser_get_filenames (GtkFileChooser *chooser)
   return g_slist_reverse (result);
 }
 
+/**
+ * gtk_file_chooser_set_current_folder:
+ * @chooser: a #GtkFileChooser
+ * @filename: the full path of the new current folder
+ * 
+ * Sets the current folder for @chooser from a local filename.
+ * The user will be shown the full contents of the current folder,
+ * plus user interface elements for navigating to other folders.
+ **/
 void
 gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
 				     const gchar    *filename)
@@ -402,11 +478,22 @@ gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
   path = gtk_file_system_filename_to_path (file_system, filename);
   if (path)
     {
-      _gtk_file_chooser_set_current_folder (chooser, path);
+      _gtk_file_chooser_set_current_folder_path (chooser, path);
       gtk_file_path_free (path);
     }
 }
 
+/**
+ * gtk_file_chooser_get_current_folder:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Gets the current folder of @chooser as a local filename.
+ * See gtk_file_chooser_set_current_folder().
+ * 
+ * Return value: the full path of the current folder, or %NULL
+ *  if the current path cannot be represented as a local filename.
+ *  Free with g_free().
+ **/
 gchar *
 gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
 {
@@ -418,13 +505,47 @@ gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
 
   file_system = _gtk_file_chooser_get_file_system (chooser);
 
-  path = _gtk_file_chooser_get_current_folder (chooser);
+  path = _gtk_file_chooser_get_current_folder_path (chooser);
   filename = gtk_file_system_path_to_filename (file_system, path);
   gtk_file_path_free (path);
 
   return filename;
 }
 
+/**
+ * gtk_file_chooser_set_current_name:
+ * @chooser: a #GtkFileChooser
+ * @name: the filename to use, as a UTF-8 string
+ * 
+ * Sets the current name in the file selector, as if entered
+ * by the user. Note that the name passed in here is a UTF-8
+ * string rather than a filename. This function is meant for
+ * such uses as a suggested name in a "Save As..." dialog.
+ *
+ * If you want to preselect a particular existing file, you
+ * should use gtk_file_chooser_set_filename() instead.
+ **/
+void
+gtk_file_chooser_set_current_name  (GtkFileChooser *chooser,
+				    const gchar    *name)
+{
+  g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
+  g_return_if_fail (name != NULL);
+  
+  GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_name (chooser, name);
+}
+
+/**
+ * gtk_file_chooser_get_uri:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Gets the URI for the currently selected file in
+ * the file selector. If multiple files are selected,
+ * one of the filenames will be returned at random.
+ * 
+ * Return value: The currently selected URI, or %NULL
+ *  if no file is selected. Free with g_free()
+ **/
 gchar *
 gtk_file_chooser_get_uri (GtkFileChooser *chooser)
 {
@@ -445,6 +566,21 @@ gtk_file_chooser_get_uri (GtkFileChooser *chooser)
   return result;
 }
 
+/**
+ * gtk_file_chooser_set_uri:
+ * @chooser: a #GtkFileChooser
+ * @uri: the URI to set as current
+ * 
+ * Sets the file referred to by @uri as the current file for the the
+ * file chooser; If the file name isn't in the current folder of @chooser,
+ * then the current folder of @chooser will be changed to the folder containing
+ * @uri. This is equivalent to a sequence of gtk_file_chooser_unselect_all()
+ * followed by gtk_file_chooser_select_uri().
+ *
+ * Note that the file must exist, or nothing will be done except
+ * for the directory change. To pre-enter a filename for the user, as in
+ * a save-as dialog, use gtk_file_chooser_set_current_name()
+ **/
 void
 gtk_file_chooser_set_uri (GtkFileChooser *chooser,
 			  const char     *uri)
@@ -455,6 +591,15 @@ gtk_file_chooser_set_uri (GtkFileChooser *chooser,
   gtk_file_chooser_select_uri (chooser, uri);
 }
 
+/**
+ * gtk_file_chooser_select_uri:
+ * @chooser: a #GtkFileChooser
+ * @uri: the URI to select
+ * 
+ * Selects the file to by @uri. If the URI doesn't refer to a
+ * file in the current folder of @chooser, then the current folder of
+ * @chooser will be changed to the folder containing @filename.
+ **/
 void
 gtk_file_chooser_select_uri (GtkFileChooser *chooser,
 			     const char     *uri)
@@ -475,6 +620,15 @@ gtk_file_chooser_select_uri (GtkFileChooser *chooser,
     }
 }
 
+/**
+ * gtk_file_chooser_unselect_uri:
+ * @chooser: a #GtkFileChooser
+ * @uri: the URI to unselect
+ * 
+ * Unselects the file referred to by @uri. If the file
+ * is not in the current directory, does not exist, or
+ * is otherwise not currently selected, does nothing.
+ **/
 void
 gtk_file_chooser_unselect_uri (GtkFileChooser *chooser,
 			       const char     *uri)
@@ -512,6 +666,17 @@ gtk_file_chooser_unselect_all (GtkFileChooser *chooser)
   GTK_FILE_CHOOSER_GET_IFACE (chooser)->unselect_all (chooser);
 }
 
+/**
+ * gtk_file_chooser_get_filenames:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Lists all the files and subfolders in the current folder of
+ * @chooser. The returned names are full absolute URIs.
+ * 
+ * Return value: a #GList containing the URIs of all
+ *   files and subfolders in the current folder. Free the returned list
+ *   with g_lists_free(), and the filenames with g_free().
+ **/
 GSList *
 gtk_file_chooser_get_uris (GtkFileChooser *chooser)
 {
@@ -537,6 +702,15 @@ gtk_file_chooser_get_uris (GtkFileChooser *chooser)
   return g_slist_reverse (result);
 }
 
+/**
+ * gtk_file_chooser_set_current_folder_uri:
+ * @chooser: a #GtkFileChooser
+ * @uri: the URI for the new current folder
+ * 
+ * Sets the current folder for @chooser from an URI.
+ * The user will be shown the full contents of the current folder,
+ * plus user interface elements for navigating to other folders.
+ **/
 void
 gtk_file_chooser_set_current_folder_uri (GtkFileChooser *chooser,
 					 const gchar    *uri)
@@ -552,11 +726,21 @@ gtk_file_chooser_set_current_folder_uri (GtkFileChooser *chooser,
   path = gtk_file_system_uri_to_path (file_system, uri);
   if (path)
     {
-      _gtk_file_chooser_set_current_folder (chooser, path);
+      _gtk_file_chooser_set_current_folder_path (chooser, path);
       gtk_file_path_free (path);
     }
 }
 
+/**
+ * gtk_file_chooser_get_current_folder_uri:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Gets the current folder of @chooser as an URI.
+ * See gtk_file_chooser_set_current_folder_uri().
+ * 
+ * Return value: the URI for the current folder.
+ *  Free with g_free().
+ */
 gchar *
 gtk_file_chooser_get_current_folder_uri (GtkFileChooser *chooser)
 {
@@ -568,17 +752,24 @@ gtk_file_chooser_get_current_folder_uri (GtkFileChooser *chooser)
 
   file_system = _gtk_file_chooser_get_file_system (chooser);
 
-  path = _gtk_file_chooser_get_current_folder (chooser);
+  path = _gtk_file_chooser_get_current_folder_path (chooser);
   uri = gtk_file_system_path_to_uri (file_system, path);
   gtk_file_path_free (path);
 
   return uri;
 }
 
-
+/**
+ * _gtk_file_chooser_set_current_folder_path:
+ * @chooser: a #GtkFileChooser
+ * @path: the #GtkFilePath for the new folder
+ * 
+ * Sets the current folder for @chooser from a #GtkFilePath.
+ * Internal function, see _gtk_file_chooser_set_current_folder_uri().
+ **/
 void
-_gtk_file_chooser_set_current_folder (GtkFileChooser    *chooser,
-				      const GtkFilePath *path)
+_gtk_file_chooser_set_current_folder_path (GtkFileChooser    *chooser,
+					   const GtkFilePath *path)
 {
   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
   g_return_if_fail (path != NULL);
@@ -586,14 +777,32 @@ _gtk_file_chooser_set_current_folder (GtkFileChooser    *chooser,
   GTK_FILE_CHOOSER_GET_IFACE (chooser)->set_current_folder (chooser, path);
 }
 
+/**
+ * _gtk_file_chooser_get_current_folder_path:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Gets the current folder of @chooser as #GtkFilePath.
+ * See gtk_file_chooser_get_current_folder_uri().
+ * 
+ * Return value: the #GtkFilePath for the current folder.
+ * Fre with  gtk_file_path_free ().
+ */
 GtkFilePath *
-_gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
+_gtk_file_chooser_get_current_folder_path (GtkFileChooser *chooser)
 {
   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 
   return GTK_FILE_CHOOSER_GET_IFACE (chooser)->get_current_folder (chooser);  
 }
 
+/**
+ * _gtk_file_chooser_select_path:
+ * @chooser: a #GtkFileChooser
+ * @path: the path to select
+ * 
+ * Selects the file referred to by @path. An internal function. See
+ * _gtk_file_chooser_select_uri().
+ **/
 void
 _gtk_file_chooser_select_path (GtkFileChooser    *chooser,
 			       const GtkFilePath *path)
@@ -603,6 +812,14 @@ _gtk_file_chooser_select_path (GtkFileChooser    *chooser,
   GTK_FILE_CHOOSER_GET_IFACE (chooser)->select_path (chooser, path);
 }
 
+/**
+ * _gtk_file_chooser_unselect_path:
+ * @chooser: a #GtkFileChooser
+ * @path: the filename to path
+ * 
+ * Unselects the file referred to by @path. An internal
+ * function. See _gtk_file_chooser_unselect_uri().
+ **/
 void
 _gtk_file_chooser_unselect_path (GtkFileChooser    *chooser,
 				 const GtkFilePath *path)
@@ -612,6 +829,18 @@ _gtk_file_chooser_unselect_path (GtkFileChooser    *chooser,
   GTK_FILE_CHOOSER_GET_IFACE (chooser)->unselect_path (chooser, path);
 }
 
+/**
+ * _gtk_file_chooser_get_paths:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Lists all the files and subfolders in the current folder of
+ * @chooser as #GtkFilePath. An internal function, see
+ * gtk_file_chooser_get_uris().
+ * 
+ * Return value: a #GList containing a #GtkFilePath for each
+ *   files and subfolder in the current folder. Free the returned list
+ *   with g_lists_free(), and the paths with gtk_file_path_free().
+ **/
 GSList *
 _gtk_file_chooser_get_paths (GtkFileChooser *chooser)
 {
@@ -639,6 +868,16 @@ gtk_file_chooser_get_path (GtkFileChooser *chooser)
   return result;
 }
 
+/**
+ * _gtk_file_chooser_get_file_system:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Gets the #GtkFileSystem of @chooser; this is an internal
+ * implementation detail, used for conversion between paths
+ * and filenames and URIs.
+ * 
+ * Return value: the file system for @chooser.
+ **/
 GtkFileSystem *
 _gtk_file_chooser_get_file_system (GtkFileChooser *chooser)
 {
@@ -649,15 +888,42 @@ _gtk_file_chooser_get_file_system (GtkFileChooser *chooser)
 
 /* Preview widget
  */
+/**
+ * gtk_file_chooser_set_preview_widget:
+ * @chooser: a #GtkFileChooser
+ * @preview_widget: widget for displaying preview.
+ *
+ * Sets an application-supplied widget to use to display a custom preview
+ * of the currently selected file. To implement a preview, after setting the
+ * preview widget, you connect to the ::selection-changed
+ * signal, and call gtk_file_chooser_get_preview_filename() or
+ * gtk_file_chooser_get_preview_uri() on each change. If you can
+ * display a preview of the new file, update your widget
+ * and set the preview active using gtk_file_chooser_set_preview_widget_active().
+ * Otherwise, set the preview inactive.
+ *
+ * When there is application-supplied preview widget, or the application-supplied
+ * preview widget is not active, the file chooser may display an internally
+ * generated preview of the current file or it may display no preview at all.
+ **/
 void
 gtk_file_chooser_set_preview_widget (GtkFileChooser *chooser,
 				     GtkWidget      *preview_widget)
 {
   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
 
-  g_object_set (chooser, "preview_widget", preview_widget, NULL);
+  g_object_set (chooser, "preview-widget", preview_widget, NULL);
 }
 
+/**
+ * gtk_file_chooser_get_preview_widget:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Gets the current preview widget; see
+ * gtk_file_chooser_set_preview_widget().
+ * 
+ * Return value: the current preview widget, or %NULL
+ **/
 GtkWidget *
 gtk_file_chooser_get_preview_widget (GtkFileChooser *chooser)
 {
@@ -665,20 +931,43 @@ gtk_file_chooser_get_preview_widget (GtkFileChooser *chooser)
   
   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 
-  g_object_get (chooser, "preview_widget", &preview_widget, NULL);
+  g_object_get (chooser, "preview-widget", &preview_widget, NULL);
 
   return preview_widget;
 }
 
+/**
+ * gtk_file_chooser_set_preview_widget_active:
+ * @chooser: a #GtkFileChooser
+ * @active: whether to display the user-specified preview widget
+ * 
+ * Sets whether the preview widget set by
+ * gtk_file_chooser_set_preview_widget_active() should be shown for the
+ * current filename. When @active is set to false, the file chooser
+ * may display an internally generated preview of the current file
+ * or it may display no preview at all. See
+ * gtk_file_chooser_set_preview_widget() for more details.
+ **/
 void
 gtk_file_chooser_set_preview_widget_active (GtkFileChooser *chooser,
 					    gboolean        active)
 {
   g_return_if_fail (GTK_IS_FILE_CHOOSER (chooser));
   
-  g_object_set (chooser, "preview_widget_active", active, NULL);
+  g_object_set (chooser, "preview-widget-active", active, NULL);
 }
 
+/**
+ * gtk_file_chooser_get_preview_widget_active:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Gets whether the preview widget set by
+ * gtk_file_chooser_set_preview_widget_active() should be shown for the
+ * current filename. See gtk_file_chooser_set_preview_widget_active().
+ * 
+ * Return value: %TRUE if the preview widget is active for the
+ *  current filename.
+ **/
 gboolean
 gtk_file_chooser_get_preview_widget_active (GtkFileChooser *chooser)
 {
@@ -686,23 +975,74 @@ gtk_file_chooser_get_preview_widget_active (GtkFileChooser *chooser)
   
   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), FALSE);
 
-  g_object_get (chooser, "preview_widget_active", &active, NULL);
+  g_object_get (chooser, "preview-widget-active", &active, NULL);
 
   return active;
 }
 
+static GtkFilePath *
+gtk_file_chooser_get_preview_path (GtkFileChooser *chooser)
+{
+  return NULL;
+}
+
+/**
+ * gtk_file_chooser_get_preview_filename:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Gets the filename that should be previewed in a custom preview
+ * widget. See gtk_file_chooser_set_preview_widget().
+ * 
+ * Return value: the filename to display, or %NULL if no file
+ *  is selected, or if the selected file cannot be represented
+ *  as a local filename. Free with g_free()
+ **/
 const char *
 gtk_file_chooser_get_preview_filename (GtkFileChooser *chooser)
 {
+  GtkFileSystem *file_system;
+  GtkFilePath *path;
+  gchar *result = NULL;
+  
   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 
-  return NULL;
+  file_system = _gtk_file_chooser_get_file_system (chooser);
+  path = gtk_file_chooser_get_preview_path (chooser);
+  if (path)
+    {
+      result = gtk_file_system_path_to_filename (file_system, path);
+      gtk_file_path_free (path);
+    }
+
+  return result;
 }
 
+/**
+ * gtk_file_chooser_get_preview_filename:
+ * @chooser: a #GtkFileChooser
+ * 
+ * Gets the URI that should be previewed in a custom preview
+ * widget. See gtk_file_chooser_set_preview_widget().
+ * 
+ * Return value: the URI to display, or %NULL if no file
+ *  is selected.
+ **/
 const char *
 gtk_file_chooser_get_preview_uri (GtkFileChooser *chooser)
 {
+  GtkFileSystem *file_system;
+  GtkFilePath *path;
+  gchar *result = NULL;
+  
   g_return_val_if_fail (GTK_IS_FILE_CHOOSER (chooser), NULL);
 
-  return NULL;
+  file_system = _gtk_file_chooser_get_file_system (chooser);
+  path = gtk_file_chooser_get_path (chooser);
+  if (path)
+    {
+      result = gtk_file_system_path_to_uri (file_system, path);
+      gtk_file_path_free (path);
+    }
+
+  return result;
 }
diff --git a/gtk/gtkfilechooser.h b/gtk/gtkfilechooser.h
index 41ebc06fd5..145cb2c1f1 100644
--- a/gtk/gtkfilechooser.h
+++ b/gtk/gtkfilechooser.h
@@ -56,6 +56,8 @@ gboolean             gtk_file_chooser_get_select_multiple (GtkFileChooser
 
 /* Filename manipulation
  */
+void    gtk_file_chooser_set_current_name  (GtkFileChooser *chooser,
+					    const gchar    *name);
 gchar * gtk_file_chooser_get_filename      (GtkFileChooser *chooser);
 void    gtk_file_chooser_set_filename      (GtkFileChooser *chooser,
 					    const char     *filename);
diff --git a/gtk/gtkfilechooserdefault.c b/gtk/gtkfilechooserdefault.c
index 9931488ef6..c62e446944 100644
--- a/gtk/gtkfilechooserdefault.c
+++ b/gtk/gtkfilechooserdefault.c
@@ -96,6 +96,8 @@ static void     gtk_file_chooser_impl_default_get_property (GObject
 static void           gtk_file_chooser_impl_default_set_current_folder (GtkFileChooser    *chooser,
 									const GtkFilePath *path);
 static GtkFilePath *  gtk_file_chooser_impl_default_get_current_folder (GtkFileChooser    *chooser);
+static void           gtk_file_chooser_impl_default_set_current_name   (GtkFileChooser    *chooser,
+									const gchar       *name);
 static void           gtk_file_chooser_impl_default_select_path        (GtkFileChooser    *chooser,
 									const GtkFilePath *path);
 static void           gtk_file_chooser_impl_default_unselect_path      (GtkFileChooser    *chooser,
@@ -191,6 +193,7 @@ gtk_file_chooser_impl_default_iface_init (GtkFileChooserIface *iface)
   iface->get_file_system = gtk_file_chooser_impl_default_get_file_system;
   iface->set_current_folder = gtk_file_chooser_impl_default_set_current_folder;
   iface->get_current_folder = gtk_file_chooser_impl_default_get_current_folder;
+  iface->set_current_name = gtk_file_chooser_impl_default_set_current_name;
 }
 
 static void
@@ -524,6 +527,15 @@ gtk_file_chooser_impl_default_get_current_folder (GtkFileChooser *chooser)
 }
 
 static void
+gtk_file_chooser_impl_default_set_current_name (GtkFileChooser *chooser,
+						const gchar    *name)
+{
+  GtkFileChooserImplDefault *impl = GTK_FILE_CHOOSER_IMPL_DEFAULT (chooser);
+
+  _gtk_file_chooser_entry_set_file_part (GTK_FILE_CHOOSER_ENTRY (impl->entry), name);
+}
+
+static void
 select_func (GtkFileSystemModel *model,
 	     GtkTreePath        *path,
 	     GtkTreeIter        *iter,
@@ -551,11 +563,11 @@ gtk_file_chooser_impl_default_select_path (GtkFileChooser    *chooser,
 
   if (!parent_path)
     {
-      _gtk_file_chooser_set_current_folder (chooser, path);
+      _gtk_file_chooser_set_current_folder_path (chooser, path);
     }
   else
     {
-      _gtk_file_chooser_set_current_folder (chooser, parent_path);
+      _gtk_file_chooser_set_current_folder_path (chooser, parent_path);
       gtk_file_path_free (parent_path);
       _gtk_file_system_model_path_do (impl->list_model, path,
 				     select_func, impl);
@@ -825,11 +837,11 @@ tree_selection_changed (GtkTreeSelection          *selection,
   gtk_tree_view_set_search_column (GTK_TREE_VIEW (impl->list),
 				   GTK_FILE_SYSTEM_MODEL_DISPLAY_NAME);
 
-  g_signal_emit_by_name (impl, "current_folder_changed", 0);
+  g_signal_emit_by_name (impl, "current-folder-changed", 0);
 
   update_chooser_entry (impl);
 
-  g_signal_emit_by_name (impl, "selection_changed", 0);
+  g_signal_emit_by_name (impl, "selection-changed", 0);
 
 }
 
@@ -839,7 +851,7 @@ list_selection_changed (GtkTreeSelection          *selection,
 {
   update_chooser_entry (impl);
   
-  g_signal_emit_by_name (impl, "selection_changed", 0);
+  g_signal_emit_by_name (impl, "selection-changed", 0);
 }
 
 static void
@@ -896,7 +908,7 @@ entry_activate (GtkEntry                  *entry,
     {
       g_signal_stop_emission_by_name (entry, "activate");
 
-      _gtk_file_chooser_set_current_folder (GTK_FILE_CHOOSER (impl), new_folder);
+      _gtk_file_chooser_set_current_folder_path (GTK_FILE_CHOOSER (impl), new_folder);
       _gtk_file_chooser_entry_set_file_part (chooser_entry, "");
 
       gtk_file_path_free (new_folder);
diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c
index b6ab558f2d..fd40dc1ca5 100644
--- a/gtk/gtkfilechooserdialog.c
+++ b/gtk/gtkfilechooserdialog.c
@@ -131,7 +131,7 @@ gtk_file_chooser_dialog_constructor (GType                  type,
 
   if (priv->file_system)
     priv->widget = g_object_new (GTK_TYPE_FILE_CHOOSER_WIDGET,
-				 "file_system", priv->file_system,
+				 "file-system", priv->file_system,
 				 NULL);
   else
     priv->widget = g_object_new (GTK_TYPE_FILE_CHOOSER_WIDGET, NULL);
diff --git a/gtk/gtkfilechooserprivate.h b/gtk/gtkfilechooserprivate.h
index ddbe16c32a..d3b73f1ec0 100644
--- a/gtk/gtkfilechooserprivate.h
+++ b/gtk/gtkfilechooserprivate.h
@@ -51,6 +51,8 @@ struct _GtkFileChooserIface
   void           (*set_current_folder) (GtkFileChooser    *chooser,
 		 		        const GtkFilePath *path);
   GtkFilePath *  (*get_current_folder) (GtkFileChooser    *chooser);
+  void           (*set_current_name)   (GtkFileChooser    *chooser,
+					const gchar       *name);
   void           (*select_path)        (GtkFileChooser    *chooser,
 		 		        const GtkFilePath *path);
   void           (*unselect_path)      (GtkFileChooser    *chooser,
@@ -68,15 +70,15 @@ struct _GtkFileChooserIface
 				  const gchar     *uri);
 };
 
-GtkFileSystem *_gtk_file_chooser_get_file_system    (GtkFileChooser    *chooser);
-void           _gtk_file_chooser_set_current_folder (GtkFileChooser    *chooser,
-						     const GtkFilePath *path);
-GtkFilePath *  _gtk_file_chooser_get_current_folder (GtkFileChooser    *chooser);
-void           _gtk_file_chooser_select_path        (GtkFileChooser    *chooser,
-						     const GtkFilePath *path);
-void           _gtk_file_chooser_unselect_path      (GtkFileChooser    *chooser,
-						     const GtkFilePath *path);
-GSList *       _gtk_file_chooser_get_paths          (GtkFileChooser    *chooser);
+GtkFileSystem *_gtk_file_chooser_get_file_system         (GtkFileChooser    *chooser);
+void           _gtk_file_chooser_set_current_folder_path (GtkFileChooser    *chooser,
+							  const GtkFilePath *path);
+GtkFilePath *  _gtk_file_chooser_get_current_folder_path (GtkFileChooser    *chooser);
+void           _gtk_file_chooser_select_path             (GtkFileChooser    *chooser,
+							  const GtkFilePath *path);
+void           _gtk_file_chooser_unselect_path           (GtkFileChooser    *chooser,
+							  const GtkFilePath *path);
+GSList *       _gtk_file_chooser_get_paths               (GtkFileChooser    *chooser);
 
 G_END_DECLS
 
diff --git a/gtk/gtkfilechooserutils.c b/gtk/gtkfilechooserutils.c
index 9a09eecb9a..9c0e51ced0 100644
--- a/gtk/gtkfilechooserutils.c
+++ b/gtk/gtkfilechooserutils.c
@@ -27,6 +27,8 @@
 static void           delegate_set_current_folder     (GtkFileChooser    *chooser,
 						       const GtkFilePath *path);
 static GtkFilePath *  delegate_get_current_folder     (GtkFileChooser    *chooser);
+static void           delegate_set_current_name       (GtkFileChooser    *chooser,
+						       const gchar       *name);
 static void           delegate_select_path            (GtkFileChooser    *chooser,
 						       const GtkFilePath *path);
 static void           delegate_unselect_path          (GtkFileChooser    *chooser,
@@ -61,37 +63,37 @@ _gtk_file_chooser_install_properties (GObjectClass *klass)
 							  G_PARAM_READWRITE));
   g_object_class_install_property (klass,
 				   GTK_FILE_CHOOSER_PROP_FILE_SYSTEM,
-				   g_param_spec_override ("file_system",
+				   g_param_spec_override ("file-system",
 							  GTK_TYPE_FILE_SYSTEM,
 							  G_PARAM_WRITABLE | G_PARAM_CONSTRUCT_ONLY));
   g_object_class_install_property (klass,
 				   GTK_FILE_CHOOSER_PROP_FOLDER_MODE,
-				   g_param_spec_override ("folder_mode",
+				   g_param_spec_override ("folder-mode",
 							  G_TYPE_BOOLEAN,
 							  G_PARAM_READWRITE));
   g_object_class_install_property (klass,
 				   GTK_FILE_CHOOSER_PROP_LOCAL_ONLY,
-				   g_param_spec_override ("local_only",
+				   g_param_spec_override ("local-only",
 							  G_TYPE_BOOLEAN,
 							  G_PARAM_READWRITE));
   g_object_class_install_property (klass,
 				   GTK_FILE_CHOOSER_PROP_PREVIEW_WIDGET,
-				   g_param_spec_override ("preview_widget",
+				   g_param_spec_override ("preview-widget",
 							  GTK_TYPE_WIDGET,
 							  G_PARAM_READWRITE));
   g_object_class_install_property (klass,
 				   GTK_FILE_CHOOSER_PROP_PREVIEW_WIDGET_ACTIVE,
-				   g_param_spec_override ("preview_widget_active",
+				   g_param_spec_override ("preview-widget-active",
 							  G_TYPE_BOOLEAN,
 							  G_PARAM_READWRITE));
   g_object_class_install_property (klass,
 				   GTK_FILE_CHOOSER_PROP_SELECT_MULTIPLE,
-				   g_param_spec_override ("select_multiple",
+				   g_param_spec_override ("select-multiple",
 							  G_TYPE_BOOLEAN,
 							  G_PARAM_READWRITE));
   g_object_class_install_property (klass,
 				   GTK_FILE_CHOOSER_PROP_SHOW_HIDDEN,
-				   g_param_spec_override ("show_hidden",
+				   g_param_spec_override ("show-hidden",
 							  G_TYPE_BOOLEAN,
 							  G_PARAM_READWRITE));
 }
@@ -112,6 +114,7 @@ _gtk_file_chooser_delegate_iface_init (GtkFileChooserIface *iface)
 {
   iface->set_current_folder = delegate_set_current_folder;
   iface->get_current_folder = delegate_get_current_folder;
+  iface->set_current_name = delegate_set_current_name;
   iface->select_path = delegate_select_path;
   iface->unselect_path = delegate_unselect_path;
   iface->select_all = delegate_select_all;
@@ -140,9 +143,9 @@ _gtk_file_chooser_set_delegate (GtkFileChooser *receiver,
   
   g_object_set_data (G_OBJECT (receiver), "gtk-file-chooser-delegate", delegate);
 
-  g_signal_connect (delegate, "current_folder_changed",
+  g_signal_connect (delegate, "current-folder-changed",
 		    G_CALLBACK (delegate_current_folder_changed), receiver);
-  g_signal_connect (delegate, "selection_changed",
+  g_signal_connect (delegate, "selection-changed",
 		    G_CALLBACK (delegate_selection_changed), receiver);
 }
 
@@ -194,25 +197,32 @@ static void
 delegate_set_current_folder (GtkFileChooser    *chooser,
 			     const GtkFilePath *path)
 {
-  _gtk_file_chooser_set_current_folder (chooser, path);
+  _gtk_file_chooser_set_current_folder_path (chooser, path);
 }
 
 static GtkFilePath *
 delegate_get_current_folder (GtkFileChooser *chooser)
 {
-  return _gtk_file_chooser_get_current_folder (get_delegate (chooser));
+  return _gtk_file_chooser_get_current_folder_path (get_delegate (chooser));
+}
+
+static void
+delegate_set_current_name (GtkFileChooser *chooser,
+			   const gchar    *name)
+{
+  gtk_file_chooser_set_current_name (get_delegate (chooser), name);
 }
 
 static void
 delegate_selection_changed (GtkFileChooser *chooser,
 			    gpointer        data)
 {
-  g_signal_emit_by_name (data, "selection_changed", 0);
+  g_signal_emit_by_name (data, "selection-changed", 0);
 }
 
 static void
 delegate_current_folder_changed (GtkFileChooser *chooser,
 				 gpointer        data)
 {
-  g_signal_emit_by_name (data, "current_folder_changed", 0);
+  g_signal_emit_by_name (data, "current-folder-changed", 0);
 }
diff --git a/gtk/gtkfilesystem.c b/gtk/gtkfilesystem.c
index 1c50ac2c87..80ee95d7fd 100644
--- a/gtk/gtkfilesystem.c
+++ b/gtk/gtkfilesystem.c
@@ -307,7 +307,7 @@ gtk_file_system_base_init (gpointer g_class)
     {
       GType iface_type = G_TYPE_FROM_INTERFACE (g_class);
 
-      g_signal_new ("roots_changed",
+      g_signal_new ("roots-changed",
 		    iface_type,
 		    G_SIGNAL_RUN_LAST,
 		    G_STRUCT_OFFSET (GtkFileSystemIface, roots_changed),
@@ -553,7 +553,7 @@ gtk_file_folder_base_init (gpointer g_class)
 		    NULL, NULL,
 		    g_cclosure_marshal_VOID__VOID,
 		    G_TYPE_NONE, 0);
-      g_signal_new ("files_added",
+      g_signal_new ("files-added",
 		    iface_type,
 		    G_SIGNAL_RUN_LAST,
 		    G_STRUCT_OFFSET (GtkFileFolderIface, files_added),
@@ -561,7 +561,7 @@ gtk_file_folder_base_init (gpointer g_class)
 		    g_cclosure_marshal_VOID__POINTER,
 		    G_TYPE_NONE, 1,
 		    G_TYPE_POINTER);
-      g_signal_new ("files_changed",
+      g_signal_new ("files-changed",
 		    iface_type,
 		    G_SIGNAL_RUN_LAST,
 		    G_STRUCT_OFFSET (GtkFileFolderIface, files_changed),
@@ -569,7 +569,7 @@ gtk_file_folder_base_init (gpointer g_class)
 		    g_cclosure_marshal_VOID__POINTER,
 		    G_TYPE_NONE, 1,
 		    G_TYPE_POINTER);
-      g_signal_new ("files_removed",
+      g_signal_new ("files-removed",
 		    iface_type,
 		    G_SIGNAL_RUN_LAST,
 		    G_STRUCT_OFFSET (GtkFileFolderIface, files_removed),
diff --git a/gtk/gtkfilesystemmodel.c b/gtk/gtkfilesystemmodel.c
index beff0645c2..ed738481b6 100644
--- a/gtk/gtkfilesystemmodel.c
+++ b/gtk/gtkfilesystemmodel.c
@@ -590,18 +590,18 @@ _gtk_file_system_model_new (GtkFileSystem     *file_system,
 	  
 	  g_signal_connect_object (model->root_folder, "deleted",
 				   G_CALLBACK (root_deleted_callback), model, 0);
-	  g_signal_connect_object (model->root_folder, "files_added",
+	  g_signal_connect_object (model->root_folder, "files-added",
 				   G_CALLBACK (root_files_added_callback), model, 0);
-	  g_signal_connect_object (model->root_folder, "files_changed",
+	  g_signal_connect_object (model->root_folder, "files-changed",
 				   G_CALLBACK (root_files_changed_callback), model, 0);
-	  g_signal_connect_object (model->root_folder, "files_removed",
+	  g_signal_connect_object (model->root_folder, "files-removed",
 				   G_CALLBACK (root_files_removed_callback), model, 0);
 	}
     }
   else
     {
       roots = gtk_file_system_list_roots (file_system);
-      g_signal_connect_object (file_system, "roots_changed",
+      g_signal_connect_object (file_system, "roots-changed",
 			       G_CALLBACK (roots_changed_callback), model, 0);
     }
 
@@ -1200,11 +1200,11 @@ file_model_node_get_children (GtkFileSystemModel *model,
 
 	  g_signal_connect (node->folder, "deleted",
 			    G_CALLBACK (deleted_callback), node);
-	  g_signal_connect (node->folder, "files_added",
+	  g_signal_connect (node->folder, "files-added",
 			    G_CALLBACK (files_added_callback), node);
-	  g_signal_connect (node->folder, "files_changed",
+	  g_signal_connect (node->folder, "files-changed",
 			    G_CALLBACK (files_changed_callback), node);
-	  g_signal_connect (node->folder, "files_removed",
+	  g_signal_connect (node->folder, "files-removed",
 			    G_CALLBACK (files_removed_callback), node);
 
 	  g_object_set_data (G_OBJECT (node->folder), "model-node", node);