Clarify the usage of this function. (gtk_file_chooser_set_uri): Likewise.

2005-07-21  Federico Mena Quintero  <federico@ximian.com>

	* gtk/gtkfilechooser.c (gtk_file_chooser_set_filename): Clarify
	the usage of this function.
	(gtk_file_chooser_set_uri): Likewise.
	(gtk_file_chooser_set_current_name): Likewise.

	* gtk/gtkfilechooserdefault.c (set_file_system_backend):
	Instrument this function for profiling as well.
	(gtk_file_chooser_default_init): Likewise; just to have a marker
	of where instance initialization begins.

ChangeLog

@@ -1,3 +1,15 @@
+2005-07-21  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/gtkfilechooser.c (gtk_file_chooser_set_filename): Clarify
+	the usage of this function.
+	(gtk_file_chooser_set_uri): Likewise.
+	(gtk_file_chooser_set_current_name): Likewise.
+
+	* gtk/gtkfilechooserdefault.c (set_file_system_backend):
+	Instrument this function for profiling as well.
+	(gtk_file_chooser_default_init): Likewise; just to have a marker
+	of where instance initialization begins.
+
 2005-07-21  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/gtkwidget.c (update_pango_context): Fix a couple of leaks.

ChangeLog.pre-2-10

@@ -1,3 +1,15 @@
+2005-07-21  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/gtkfilechooser.c (gtk_file_chooser_set_filename): Clarify
+	the usage of this function.
+	(gtk_file_chooser_set_uri): Likewise.
+	(gtk_file_chooser_set_current_name): Likewise.
+
+	* gtk/gtkfilechooserdefault.c (set_file_system_backend):
+	Instrument this function for profiling as well.
+	(gtk_file_chooser_default_init): Likewise; just to have a marker
+	of where instance initialization begins.
+
 2005-07-21  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/gtkwidget.c (update_pango_context): Fix a couple of leaks.

ChangeLog.pre-2-8

@@ -1,3 +1,15 @@
+2005-07-21  Federico Mena Quintero  <federico@ximian.com>
+
+	* gtk/gtkfilechooser.c (gtk_file_chooser_set_filename): Clarify
+	the usage of this function.
+	(gtk_file_chooser_set_uri): Likewise.
+	(gtk_file_chooser_set_current_name): Likewise.
+
+	* gtk/gtkfilechooserdefault.c (set_file_system_backend):
+	Instrument this function for profiling as well.
+	(gtk_file_chooser_default_init): Likewise; just to have a marker
+	of where instance initialization begins.
+
 2005-07-21  Owen Taylor  <otaylor@redhat.com>
 
 	* gtk/gtkwidget.c (update_pango_context): Fix a couple of leaks.

gtk/gtkfilechooser.c

@@ -469,15 +469,39 @@ gtk_file_chooser_get_filename (GtkFileChooser *chooser)
  * @chooser: a #GtkFileChooser
  * @filename: the filename to set as current
  * 
- * Sets @filename as the current filename for the file chooser;
+ * Sets @filename as the current filename for the file chooser, by changing
- * If the file name isn't in the current folder of @chooser, then the
+ * to the file's parent folder and actually selecting the file in list.  If
- * current folder of @chooser will be changed to the folder containing
+ * the @chooser is in #GTK_FILE_CHOOSER_ACTION_SAVE mode, the file's base name
- * @filename. This is equivalent to a sequence of
+ * will also appear in the dialog's file name entry.
- * gtk_file_chooser_unselect_all() followed by gtk_file_chooser_select_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. 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
+ * for the directory change.
- * a save-as dialog, use gtk_file_chooser_set_current_name()
+ *
+ * If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog, you
+ * should use this function if you already have a file name to which the user may save; for example,
+ * when the user opens an existing file and then does <guimenuitem>File/Save As...</guimenuitem>
+ * on it.  If you don't have a file name already &mdash; for example, if the user just created
+ * a new file and is saving it for the first time, do not call this function.  Instead, use
+ * something similar to this:
+ *
+ * <programlisting>
+ * if (document_is_new)
+ *   {
+ *     /<!-- -->* the user just created a new document *<!-- -->/
+ *     gtk_file_chooser_set_current_folder (chooser, default_folder_for_saving);
+ *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
+ *   }
+ * else
+ *   {
+ *     /<!-- -->* the user edited an existing document *<!-- -->/ 
+ *     gtk_file_chooser_set_filename (chooser, existing_filename);
+ *   }
+ * </programlisting>
  * 
  * Return value: %TRUE if both the folder could be changed and the file was
  * selected successfully, %FALSE otherwise.
@@ -701,8 +725,10 @@ gtk_file_chooser_get_current_folder (GtkFileChooser *chooser)
  * 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
+ * If you want to preselect a particular existing file, you should use
- * should use gtk_file_chooser_set_filename() instead.
+ * gtk_file_chooser_set_filename() or gtk_file_chooser_set_uri() instead.
+ * Please see the documentation for those functions for an example of using
+ * gtk_file_chooser_set_current_name() as well.
  *
  * Since: 2.4
  **/
@@ -757,15 +783,38 @@ gtk_file_chooser_get_uri (GtkFileChooser *chooser)
  * @chooser: a #GtkFileChooser
  * @uri: the URI to set as current
  * 
- * Sets the file referred to by @uri as the current file for the
+ * Sets the file referred to by @uri as the current file for the file chooser,
- * file chooser; If the file name isn't in the current folder of @chooser,
+ * by changing to the URI's parent folder and actually selecting the URI in the
- * then the current folder of @chooser will be changed to the folder containing
+ * list.  If the @chooser is #GTK_FILE_CHOOSER_ACTION_SAVE mode, the URI's base
- * @uri. This is equivalent to a sequence of gtk_file_chooser_unselect_all()
+ * name will also appear in the dialog's file name entry.
- * followed by gtk_file_chooser_select_uri().
  *
- * Note that the file must exist, or nothing will be done except
+ * If the URI isn't in the current folder of @chooser, then the current folder
- * for the directory change. To pre-enter a filename for the user, as in
+ * of @chooser will be changed to the folder containing @uri. This is equivalent
- * a save-as dialog, use gtk_file_chooser_set_current_name()
+ * to a sequence of gtk_file_chooser_unselect_all() followed by
+ * gtk_file_chooser_select_uri().
+ *
+ * Note that the URI must exist, or nothing will be done except
+ * for the directory change.
+ * If you are implementing a <guimenuitem>File/Save As...</guimenuitem> dialog, you
+ * should use this function if you already have a file name to which the user may save; for example,
+ * when the user opens an existing file and then does <guimenuitem>File/Save As...</guimenuitem>
+ * on it.  If you don't have a file name already &mdash; for example, if the user just created
+ * a new file and is saving it for the first time, do not call this function.  Instead, use
+ * something similar to this:
+ *
+ * <programlisting>
+ * if (document_is_new)
+ *   {
+ *     /<!-- -->* the user just created a new document *<!-- -->/
+ *     gtk_file_chooser_set_current_folder_uri (chooser, default_folder_for_saving);
+ *     gtk_file_chooser_set_current_name (chooser, "Untitled document");
+ *   }
+ * else
+ *   {
+ *     /<!-- -->* the user edited an existing document *<!-- -->/ 
+ *     gtk_file_chooser_set_uri (chooser, existing_uri);
+ *   }
+ * </programlisting>
  *
  * Return value: %TRUE if both the folder could be changed and the URI was
  * selected successfully, %FALSE otherwise.

gtk/gtkfilechooserdefault.c

@@ -83,7 +83,7 @@
 
 /* Profiling stuff */
 
-#undef PROFILE_FILE_CHOOSER
+#define PROFILE_FILE_CHOOSER
 #ifdef PROFILE_FILE_CHOOSER
 #include <unistd.h>
 
@@ -726,6 +726,8 @@ gtk_file_chooser_embed_default_iface_init (GtkFileChooserEmbedIface *iface)
 static void
 gtk_file_chooser_default_init (GtkFileChooserDefault *impl)
 {
+  profile_start ("start", NULL);
+
   impl->local_only = TRUE;
   impl->preview_widget_active = TRUE;
   impl->use_preview_label = TRUE;
@@ -740,6 +742,8 @@ gtk_file_chooser_default_init (GtkFileChooserDefault *impl)
   impl->tooltips = gtk_tooltips_new ();
   g_object_ref (impl->tooltips);
   gtk_object_sink (GTK_OBJECT (impl->tooltips));
+
+  profile_end ("end", NULL);
 }
 
 /* Frees the data columns for the specified iter in the shortcuts model*/
@@ -4191,6 +4195,8 @@ static void
 set_file_system_backend (GtkFileChooserDefault *impl,
 			 const char *backend)
 {
+  profile_start ("start for backend", backend ? backend : "default");
+
   if (impl->file_system)
     {
       g_signal_handler_disconnect (impl->file_system, impl->volumes_changed_id);
@@ -4236,6 +4242,8 @@ set_file_system_backend (GtkFileChooserDefault *impl,
 						     G_CALLBACK (bookmarks_changed_cb),
 						     impl);
     }
+
+  profile_end ("end", NULL);
 }
 
 /* This function is basically a do_all function.