Clarify the use of these functions, to avoid the case where a chooser is

2006-06-19  Federico Mena Quintero  <federico@novell.com>

	* gtk/gtkfilechooser.c (gtk_file_chooser_get_current_folder)
	(gtk_file_chooser_get_current_folder_uri): Clarify the use of
	these functions, to avoid the case where a chooser is in
	SELECT_FOLDER mode and people mistakenly use _get_current_folder()
	to get the selection:  they should use _get_filename() instead.

diff --git a/ChangeLog b/ChangeLog
index f557a31b06d92944696ee7450cfb8452bc40075a..62216fecaebf4bdbbb18417641fee45ec9451be9 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2006-06-19  Federico Mena Quintero  <federico@novell.com>
+
+       * gtk/gtkfilechooser.c (gtk_file_chooser_get_current_folder)
+       (gtk_file_chooser_get_current_folder_uri): Clarify the use of
+       these functions, to avoid the case where a chooser is in
+       SELECT_FOLDER mode and people mistakenly use _get_current_folder()
+       to get the selection:  they should use _get_filename() instead.
+
 2006-06-19  Alexander Larsson  <alexl@redhat.com>
 
        * gtk/gtk.symbols:

diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index f557a31b06d92944696ee7450cfb8452bc40075a..62216fecaebf4bdbbb18417641fee45ec9451be9 100644 (file)
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,11 @@
+2006-06-19  Federico Mena Quintero  <federico@novell.com>
+
+       * gtk/gtkfilechooser.c (gtk_file_chooser_get_current_folder)
+       (gtk_file_chooser_get_current_folder_uri): Clarify the use of
+       these functions, to avoid the case where a chooser is in
+       SELECT_FOLDER mode and people mistakenly use _get_current_folder()
+       to get the selection:  they should use _get_filename() instead.
+
 2006-06-19  Alexander Larsson  <alexl@redhat.com>
 
        * gtk/gtk.symbols:

diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index 4ed46e9a85373d81581b4df2abcc5964e18e2f49..a522a9df36a3ce3e793f2e184dd353ea2761d3ee 100644 (file)
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -690,6 +690,14 @@ gtk_file_chooser_set_current_folder (GtkFileChooser *chooser,
  * 
  * Gets the current folder of @chooser as a local filename.
  * See gtk_file_chooser_set_current_folder().
+ *
+ * Note that this is the folder that the file chooser is currently displaying
+ * (e.g. "/home/username/Documents"), which is <emphasis>not the same</emphasis>
+ * as the currently-selected folder if the chooser is in
+ * #GTK_FILE_CHOOSER_SELECT_FOLDER mode
+ * (e.g. "/home/username/Documents/selected-folder/".  To get the
+ * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the
+ * usual way to get the selection.
  * 
  * 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().  This
@@ -1014,6 +1022,14 @@ gtk_file_chooser_set_current_folder_uri (GtkFileChooser *chooser,
  * 
  * Gets the current folder of @chooser as an URI.
  * See gtk_file_chooser_set_current_folder_uri().
+ *
+ * Note that this is the folder that the file chooser is currently displaying
+ * (e.g. "file:///home/username/Documents"), which is <emphasis>not the same</emphasis>
+ * as the currently-selected folder if the chooser is in
+ * #GTK_FILE_CHOOSER_SELECT_FOLDER mode
+ * (e.g. "file:///home/username/Documents/selected-folder/".  To get the
+ * currently-selected folder in that mode, use gtk_file_chooser_get_uri() as the
+ * usual way to get the selection.
  * 
  * Return value: the URI for the current folder.  Free with g_free().  This
  * function will also return %NULL if the file chooser was unable to load the