/src/wrappers/gtk/library/gtk_file_chooser.e

   1indexing
   2	description: "GtkFileChooser -- File chooser interface used by GtkFileChooserWidget and GtkFileChooserDialog."
   3	copyright: "[
   4					Copyright (C) 2006 eiffel-libraries team, GTK+ team
   5					
   6					This library is free software; you can redistribute it and/or
   7					modify it under the terms of the GNU Lesser General Public License
   8					as published by the Free Software Foundation; either version 2.1 of
   9					the License, or (at your option) any later version.
  10					
  11					This library is distributed in the hope that it will be useful, but
  12					WITHOUT ANY WARRANTY; without even the implied warranty of
  13					MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14					Lesser General Public License for more details.
  15
  16					You should have received a copy of the GNU Lesser General Public
  17					License along with this library; if not, write to the Free Software
  18					Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19					02110-1301 USA
  20				]"
  21	date: "$Date:$"
  22	revision: "$Revision:$"
  23
  24deferred class GTK_FILE_CHOOSER
  25	-- GtkFileChooser is an interface that can be implemented by file
  26	-- selection widgets. In GTK+, the main objects that implement this
  27	-- interface are GtkFileChooserWidget, GtkFileChooserDialog, and
  28	-- GtkFileChooserButton. You do not need to write an object that
  29	-- implements the GtkFileChooser interface unless you are trying to
  30	-- adapt an existing file selector to expose a standard programming
  31	-- interface.
  32
  33	-- GtkFileChooser allows for shortcuts to various places in the
  34	-- filesystem. In the default implementation these are displayed in
  35	-- the left pane. It may be a bit confusing at first taht these
  36	-- shortcuts come from various sources and in various flavours, so
  37	-- lets explain the terminology here:
  38	
  39	-- Bookmarks are created by the user, by dragging folders from the
  40	-- right pane to the left pane, or by using the "Add". Bookmarks
  41	-- can be renamed and deleted by the user.
  42
  43	-- Shortcuts can be provided by the application or by the
  44	-- underlying filesystem abstraction (e.g. both the gnome-vfs and
  45	-- the Windows filesystems provide "Desktop" shortcuts). Shortcuts
  46	-- cannot be modified by the user.
  47
  48	-- Volumes are provided by the underlying filesystem
  49	-- abstraction. They are the "roots" of the filesystem.
  50	
  51	-- File Names and Encodings: When the user is finished selecting
  52	-- files in a GtkFileChooser, your program can get the selected
  53	-- names either as filenames or as URIs. For URIs, the normal
  54	-- escaping rules are applied if the URI contains non-ASCII
  55	-- characters. However, filenames are always returned in the
  56	-- character set specified by the G_FILENAME_ENCODING environment
  57	-- variable. Please see the Glib documentation for more details
  58	-- about this variable.
  59
  60	-- Important: This means that while you can pass the result of
  61	-- gtk_file_chooser_get_filename() to open(2) or fopen(3), you may
  62	-- not be able to directly set it as the text of a GtkLabel widget
  63	-- unless you convert it first to UTF-8, which all GTK+ widgets
  64	-- expect. You should use g_filename_to_utf8() to convert filenames
  65	-- into strings that can be passed to GTK+ widgets.
  66
  67	-- Adding a Preview Widget: You can add a custom preview widget to
  68	-- a file chooser and then get notification about when the preview
  69	-- needs to be updated. To install a preview widget, use
  70	-- gtk_file_chooser_set_preview_widget(). Then, connect to the
  71	-- GtkFileChooser::update-preview signal to get notified when you
  72	-- need to update the contents of the preview.
  73
  74	-- Your callback should use gtk_file_chooser_get_preview_filename()
  75	-- to see what needs previewing. Once you have generated the
  76	-- preview for the corresponding file, you must call
  77	-- gtk_file_chooser_set_preview_widget_active() with a boolean flag
  78	-- that indicates whether your callback could successfully generate
  79	-- a preview.
  80
  81	-- TODO: Eiffellize Example 2. Sample Usage
  82	
  83	-- {
  84	--   GtkImage *preview;
  85
  86	--   ...
  87
  88	--   preview = gtk_image_new ();
  89
  90	--   gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
  91	--   g_signal_connect (my_file_chooser, "update-preview",
  92	-- 		    G_CALLBACK (update_preview_cb), preview);
  93	-- }
  94
  95	-- static void
  96	-- update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
  97	-- {
  98	--   GtkWidget *preview;
  99	--   char *filename;
 100	--   GdkPixbuf *pixbuf;
 101	--   gboolean have_preview;
 102
 103	--   preview = GTK_WIDGET (data);
 104	--   filename = gtk_file_chooser_get_preview_filename (file_chooser);
 105
 106	--   pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
 107	--   have_preview = (pixbuf != NULL);
 108	--   g_free (filename);
 109
 110	--   gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
 111	--   if (pixbuf)
 112	--     gdk_pixbuf_unref (pixbuf);
 113
 114	--   gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
 115	-- }
 116	
 117
 118	-- Adding Extra Widgets
 119
 120	-- You can add extra widgets to a file chooser to provide options that are not present in the default design. For example, you can add a toggle button to give the user the option to open a file in read-only mode. You can use gtk_file_chooser_set_extra_widget() to insert additional widgets in a file chooser.
 121
 122	-- TODO: Eiffelize Example 3. Sample Usage
 123
 124	-- {
 125	--   GtkWidget *toggle;
 126
 127	--   ...
 128
 129	--   toggle = gtk_check_button_new_with_label ("Open file read-only");
 130	--   gtk_widget_show (toggle);
 131	--   gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
 132	-- }
 133	
 134
 135	-- Note
 136
 137	-- If you want to set more than one extra widget in the file chooser, you can a container such as a GtkVBox or a GtkTable and include your widgets in it. Then, set the container as the whole extra widget.
 138	-- Key Bindings
 139
 140	-- Internally, GTK+ implements a file chooser's graphical user interface with the private GtkFileChooserDefaultClass. This widget has several key bindings and their associated signals. This section describes the available key binding signals.
 141
 142	-- TODO: Eiffellize Example 4. GtkFileChooser key binding example
 143
 144	-- The default keys that activate the key-binding signals in GtkFileChooserDefaultClass are as follows:
 145	-- Signal name 	Default key combinations
 146	-- location-popup 	Control-L; /
 147	-- up-folder 	Alt-Up[a] ; Backspace
 148	-- down-folder 	Alt-Down
 149	-- home-folder 	Alt-Home
 150
 151	-- [a] Both the individual Up key and the numeric keypad's Up key are supported.
 152
 153	-- You can change these defaults to something else. For example, to add a Shift modifier to a few of the default bindings, you can include the following fragment in your .gtkrc-2.0 file:
 154
 155	-- binding "my-own-gtkfilechooser-bindings" {
 156	-- 	bind "<Alt><Shift>Up" {
 157	-- 		"up-folder" ()
 158	-- 	}
 159	-- 	bind "<Alt><Shift>Down" {
 160	-- 		"down-folder" ()
 161	-- 	}
 162	-- 	bind "<Alt><Shift>Home" {
 163	-- 		"home-folder" ()
 164	-- 	}
 165	-- }
 166	
 167	-- class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings"
 168	
 169	
 170	-- The "GtkFileChooserDefault::location-popup" signal
 171	
 172	--           void user_function (GtkFileChooserDefault
 173	--           *chooser, const char *path, gpointer user_data);
 174	
 175	
 176	-- This is used to make the file chooser show a "Location" dialog which the user can use to manually type the name of the file he wishes to select. The path argument is a string that gets put in the text entry for the file name. By default this is bound to Control-L with a path string of "" (the empty string); it is also bound to / with a path string of "/" (a slash): this lets you type / and immediately type a path name.
 177	-- chooser : 	the object which received the signal.
 178	-- path : 	default contents for the text entry for the file name
 179	-- user_data : 	user data set when the signal handler was connected.
 180	-- Tip
 181	
 182	-- You can create your own bindings for the location-popup
 183	-- signal with custom path strings, and have a crude form of
 184	-- easily-to-type bookmarks. For example, say you access the
 185	-- path /home/username/misc very frequently. You could then
 186	-- create an Alt-M shortcut by including the following in
 187	-- your .gtkrc-2.0:
 188
 189	-- binding "misc-shortcut" {
 190	-- 	bind "<Alt>M" {
 191	-- 		"location-popup" ("/home/username/misc")
 192	-- 	}
 193	-- }
 194	
 195	-- class "GtkFileChooserDefault" binding "misc-shortcut"
 196	
 197
 198	-- The "GtkFileChooserDefault::up-folder" signal
 199	
 200	--           void user_function (GtkFileChooserDefault
 201	--           *chooser, gpointer user_data);
 202	
 203	
 204	-- This is used to make the file chooser go to the parent of the current folder in the file hierarchy. By default this is bound to Backspace and Alt-Up (the Up key in the numeric keypad also works).
 205	-- chooser : 	the object which received the signal.
 206	-- user_data : 	user data set when the signal handler was connected.
 207	-- The "GtkFileChooserDefault::down-folder" signal
 208	
 209	--           void user_function (GtkFileChooserDefault *chooser,
 210	--                               gpointer user_data);
 211	
 212	
 213	-- This is used to make the file chooser go to a child of the current folder in the file hierarchy. The subfolder that will be used is displayed in the path bar widget of the file chooser. For example, if the path bar is showing "/foo/bar/baz", then this will cause the file chooser to switch to the "baz" subfolder. By default this is bound to Alt-Down (the Down key in the numeric keypad also works).
 214	-- chooser : 	the object which received the signal.
 215	-- user_data : 	user data set when the signal handler was connected.
 216	-- The "GtkFileChooserDefault::home-folder" signal
 217	
 218	--           void user_function (GtkFileChooserDefault *chooser,
 219	--                               gpointer user_data);
 220	
 221	
 222	-- This is used to make the file chooser show the user's home folder in the file list. By default this is bound to Alt-Home (the Home key in the numeric keypad also works).
 223	-- chooser : 	the object which received the signal.
 224	-- user_data : 	user data set when the signal handler was connected.
 225
 226inherit
 227	-- "Prerequisites: GtkFileChooser requires GtkWidget." IMHO this
 228	-- means that GTK_FILE_CHOOSER is a
 229	GTK_WIDGET 
 230		-- Known Implementations: GtkFileChooser is implemented by
 231		-- GtkFileChooserWidget, GtkFileChooserButton and
 232		-- GtkFileChooserDialog.
 233insert
 234	GTK_FILE_CHOOSER_EXTERNALS
 235	GTK_FILE_CHOOSER_CONFIRMATION
 236	GTK_FILE_CHOOSER_ERROR
 237	GTK_FILE_CHOOSER_ACTION
 238		-- Here this renaming is not useful; BTW, it produce incorrect code into GTK_FILE_CHOOSER's heirs
 239		-- 		rename
 240		-- 			gtk_file_chooser_action_open as open_action,
 241		-- 			gtk_file_chooser_action_save as save_action,
 242		-- 			gtk_file_chooser_action_select_folder as select_folder_action,
 243		-- 			gtk_file_chooser_action_create_folder as create_folder_action,
 244		-- 			is_valid_gtk_file_chooser_action	as is_valid_gtk_action
 245		-- 		end
 246
 247feature -- Actions
 248
 249	set_open_action is
 250			-- Set open mode. The file chooser will only let the user
 251			-- pick an existing file.
 252		do
 253			gtk_file_chooser_set_action (handle,gtk_file_chooser_action_open)
 254		end
 255
 256	set_save_action is
 257			-- Set save mode. The file chooser will let the user pick an
 258			-- existing file, or type in a new filename.
 259		do
 260			gtk_file_chooser_set_action (handle,gtk_file_chooser_action_save)
 261		end
 262
 263	set_select_folder_action is
 264			-- Select open mode for selecting folders. The file chooser
 265			-- will let the user pick an existing folder.
 266		do
 267			gtk_file_chooser_set_action (handle,gtk_file_chooser_action_select_folder)
 268		end
 269
 270	set_create_folder_action is
 271			-- Select a mode to create a new folder. The file chooser
 272			-- will let the user name an existing or new folder.
 273		do
 274			gtk_file_chooser_set_action (handle,gtk_file_chooser_action_create_folder)
 275		end
 276
 277	-- GETTERS
 278	is_action_open: BOOLEAN is
 279			-- Set open mode. The file chooser will only let the user
 280			-- pick an existing file.
 281		do
 282			Result := (gtk_file_chooser_get_action(handle)=gtk_file_chooser_action_open)
 283		end
 284
 285	is_action_save: BOOLEAN is
 286			-- Set save mode. The file chooser will let the user pick an
 287			-- existing file, or type in a new filename.
 288		do
 289			Result := (gtk_file_chooser_get_action(handle)=gtk_file_chooser_action_save)
 290		end
 291
 292	is_action_select_folder: BOOLEAN is
 293			-- Select open mode for selecting folders. The file chooser
 294			-- will let the user pick an existing folder.
 295		do
 296			Result := (gtk_file_chooser_get_action(handle)=gtk_file_chooser_action_select_folder)
 297		end
 298
 299	is_action_create_folder: BOOLEAN is
 300			-- Select a mode to create a new folder. The file chooser
 301			-- will let the user name an existing or new folder.
 302		do
 303			Result := (gtk_file_chooser_get_action(handle)=gtk_file_chooser_action_create_folder)
 304		end
 305	
 306feature -- Locality
 307	set_local_only is
 308			-- Makes only local files selectable in the file
 309			-- selector. The selected file are files are guaranteed to be
 310			-- accessible through the operating systems native file file
 311			-- system and therefore the application only needs to worry
 312			-- about the filename functions in GTK_FILE_CHOOSER, like
 313			-- GTK_FILE_CHOOSER.filename, rather than the URI functions
 314			-- like GTK_FILE_CHOOSER.uri
 315		do
 316			gtk_file_chooser_set_local_only (handle,1)
 317		ensure is_local_only
 318		end
 319
 320	unset_local_only is
 321			-- Makes non-local files selectable in the file selector.
 322		do
 323			gtk_file_chooser_set_local_only (handle,0)
 324		ensure not is_local_only
 325		end
 326
 327	is_local_only: BOOLEAN is
 328			-- Are only local files selectable in the file selector?. See `set_local_only'
 329		do
 330			Result:=(gtk_file_chooser_get_local_only (handle)).to_boolean
 331		end
 332	
 333feature -- Multiple selections
 334	allow_multiple_selections is
 335			-- Makes multiple files selectable in the file selector. This
 336			-- is only relevant if `is_open_action' or
 337			-- `is_save_action'. It cannot be set with either of the
 338			-- folder actions (i.e.: if either `is_action_select_folder'
 339			-- or `is_action_create_folder' are True)
 340		require no_folder_actions: not (is_action_select_folder or is_action_create_folder)
 341		do
 342			gtk_file_chooser_set_select_multiple (handle, 1)
 343		ensure are_multiple_selection_allowed
 344		end
 345
 346	forbid_multiple_selections is
 347			-- Makes multiple files not selectable in the file selector.
 348		do
 349			gtk_file_chooser_set_select_multiple (handle, 0)
 350		ensure not are_multiple_selection_allowed
 351		end
 352
 353	are_multiple_selection_allowed: BOOLEAN is
 354			-- Are multiple files can be selected in the file selector?
 355		do
 356			Result := (gtk_file_chooser_get_select_multiple(handle)).to_boolean
 357		end
 358
 359feature -- Hidden files handling
 360	show_hidden is
 361			-- Make hidden files and folders displayed in the file
 362			-- selector.
 363		do
 364			gtk_file_chooser_set_show_hidden (handle,1)
 365		end
 366
 367	hide_hidden is
 368			-- Make hidden files and folders not displayed in the file
 369			-- selector.
 370		do
 371			gtk_file_chooser_set_show_hidden (handle,0)
 372		end
 373
 374	are_hidden_shown: BOOLEAN is
 375			-- Are hidden files and folders displayed in the file
 376			-- selector? See `GTK_FILE_CHOOSER.show_hidden'.
 377		do
 378			Result:=(gtk_file_chooser_get_show_hidden(handle)).to_boolean
 379		end
 380
 381feature -- Overwrite confirmation
 382	set_overwrite_confirmation is
 383			-- Makes a file chooser in GTK_FILE_CHOOSER_ACTION_SAVE mode
 384			-- present a confirmation dialog if the user types a file
 385			-- name that already exists.  Regardless of this setting, the
 386			-- chooser will emit the "confirm-overwrite" signal when
 387			-- appropriate. If all you need is the stock confirmation
 388			-- dialog, set this property. You can override the way
 389			-- confirmation is done by actually handling the
 390			-- "confirm-overwrite" signal; please refer to its
 391			-- documentation for the details.
 392		do
 393			gtk_file_chooser_set_do_overwrite_confirmation (handle, 1)
 394		ensure shall_overwrite_be_confirmed
 395		end
 396
 397	unset_overwrite_confirmation is
 398			-- Makes a file chooser in GTK_FILE_CHOOSER_ACTION_SAVE mode
 399			-- present a confirmation dialog if the user types a file
 400			-- name that already exists.  Regardless of this setting, the
 401			-- chooser will emit the "confirm-overwrite" signal when
 402			-- appropriate. If all you need is the stock confirmation
 403			-- dialog, set this property. You can override the way
 404			-- confirmation is done by actually handling the
 405			-- "confirm-overwrite" signal; please refer to its
 406			-- documentation for the details.
 407		do
 408			gtk_file_chooser_set_do_overwrite_confirmation (handle, 0)
 409		ensure not shall_overwrite_be_confirmed
 410		end
 411	
 412	shall_overwrite_be_confirmed: BOOLEAN is
 413			-- Is a file chooser set to confirm for overwriting when the
 414			-- user types a file name that already exists? Note: this
 415			-- query wraps C's
 416			-- `gtk_file_chooser_get_do_overwrite_confirmation' 
 417		do
 418			Result:=(gtk_file_chooser_get_do_overwrite_confirmation (handle)).to_boolean
 419		end
 420
 421feature -- Name, filenames and uris
 422	filename: STRING is
 423			-- The filename for the currently selected file in the file
 424			-- selector. If multiple files are selected, one of the
 425			-- filenames will be returned at random. If the file chooser
 426			-- is in folder mode, this function returns the selected
 427			-- folder.
 428		local ptr: POINTER
 429		do
 430			ptr := gtk_file_chooser_get_filename(handle)
 431			-- Returns : The currently selected filename, or NULL if no
 432			-- file is selected, or the selected file can't be
 433			-- represented with a local filename. Free with g_free().
 434			if ptr.is_not_null
 435			then create Result.from_external(ptr)
 436			-- else check Result=Void end
 437			end
 438		end
 439
 440	set_current_name (a_name: STRING) is
 441			-- Sets the current name in the file selector, as if entered
 442			-- by the user. Note that the name passed in here is a UTF-8
 443			-- string rather than a filename. This function is meant for
 444			-- such uses as a suggested name in a "Save As..." dialog.
 445			
 446			-- If you want to preselect a particular existing file, you
 447			-- should use `GTK_FILE_CHOOSER.set_filename' or
 448			-- `GTK_FILE_CHOOSER.set_uri' instead. Please see the
 449			-- documentation for those functions for an example of using
 450			-- gtk_file_chooser_set_current_name() as well.
 451			
 452			-- TODO: `a_name' should be UNICODE_STRING: the filename to
 453			-- use, as a UTF-8 string
 454		require a_name /= Void
 455		do
 456			gtk_file_chooser_set_current_name (handle, a_name.to_external)
 457		end
 458
 459	is_last_action_successful: BOOLEAN
 460			-- Returns : 	TRUE if both the folder could be changed and the file was selected successfully, FALSE otherwise.
 461
 462	set_filename (a_filename: STRING) is
 463			-- Sets filename as the current filename for the file
 464			-- chooser, by changing to the file's parent folder and
 465			-- actually selecting the file in list. If the chooser is in
 466			-- GTK_FILE_CHOOSER_ACTION_SAVE mode, the file's base name
 467			-- will also appear in the dialog's file name entry.
 468
 469			-- If the file name isn't in the current folder of chooser,
 470			-- then the current folder of chooser will be changed to the
 471			-- folder containing filename. This is equivalent to a
 472			-- sequence of `unselect_all' followed by `select_filename'.
 473
 474			-- Note that the file must exist, or nothing will be done
 475			-- except for the directory change.
 476
 477			-- If you are implementing a File/Save As... dialog, you
 478			-- should use this function if you already have a file name
 479			-- to which the user may save; for example, when the user
 480			-- opens an existing file and then does File/Save As... on
 481			-- it. If you don't have a file name already -- for example,
 482			-- if the user just created a new file and is saving it for
 483			-- the first time, do not call this function. Instead, use
 484			-- something similar to this: TODO Eiffelize this
 485
 486			-- if (document_is_new) -- { /* the user just created a new
 487			-- document */ gtk_file_chooser_set_current_folder (chooser,
 488			-- default_folder_for_saving);
 489			-- gtk_file_chooser_set_current_name (chooser, "Untitled
 490			-- document"); -- } -- else -- { /* the user edited an
 491			-- existing document */ gtk_file_chooser_set_filename
 492			-- (chooser, existing_filename); -- }
 493
 494			-- `is_last_action_successful' will be True if both the
 495			-- folder could be changed and the file was selected
 496			-- successfully, False otherwise.
 497		require valid_filename: a_filename/=Void
 498		do
 499			is_last_action_successful := (gtk_file_chooser_set_filename (handle, a_filename.to_external)).to_boolean
 500		end
 501
 502	select_filename (a_filename: STRING) is
 503			-- Selects `a_filename'. If the file name isn't in the
 504			-- current folder of chooser, then the current folder of
 505			-- chooser will be changed to the folder containing filename.
 506			
 507			-- `is_last_action_successful' will be True if both the
 508			-- folder could be changed and the file was selected
 509			-- successfully, False otherwise.
 510		require valid_filename: a_filename/=Void
 511		do
 512			is_last_action_successful := (gtk_file_chooser_select_filename (handle, a_filename.to_external)).to_boolean
 513		end
 514
 515	unselect_filename (a_filename: STRING) is
 516			-- Unselects a currently selected filename. If the `a_filename'
 517			-- is not in the current directory, does not exist, or is
 518			-- otherwise not currently selected, does nothing.
 519		require valid_filename: a_filename/=Void
 520		do
 521			gtk_file_chooser_unselect_filename (handle, a_filename.to_external)
 522		end
 523
 524	select_all is
 525			-- Selects all the files in the current folder of a file
 526			-- chooser.
 527		do
 528			gtk_file_chooser_select_all (handle)
 529		end
 530
 531	unselect_all is
 532			-- Unselects all the files in the current folder of a file
 533			-- chooser.
 534		do
 535			gtk_file_chooser_unselect_all (handle)
 536		end
 537
 538	filenames: G_SLIST_STRING is
 539			-- all the selected files and subfolders in the current
 540			-- folder of chooser. The names are full absolute paths. If
 541			-- files in the current folder cannot be represented as local
 542			-- filenames they will be ignored. (See `uris')
 543		do
 544			create Result.from_external_pointer (gtk_file_chooser_get_filenames (handle))
 545			-- TODO: the GSList returned contains the filenames of all
 546			-- selected files and subfolders in the current folder. Free
 547			-- the returned list with g_slist_free(), and the filenames
 548			-- with g_free().
 549		end
 550
 551	set_current_folder (a_folder_name: STRING) is
 552			-- Sets the current folder for chooser from a local
 553			-- filename. The user will be shown the full contents of the
 554			-- current folder, plus user interface elements for
 555			-- navigating to other folders. `a_folder_name' is the full
 556			-- path of the new current folder.
 557
 558			-- `is_last_action_successful' will be True if both the
 559			-- folder could be changed and the file was selected
 560			-- successfully, False otherwise.
 561		require valid_folder_name: a_folder_name/=Void
 562		do
 563			is_last_action_successful := (gtk_file_chooser_set_current_folder(handle,
 564													a_folder_name.to_external)).to_boolean
 565		end
 566
 567	current_folder: STRING is
 568			-- the current folder of chooser as a local filename. See
 569			-- `set_current_folder'. Void if the current path cannot be
 570			-- represented as a local filename
 571		local ptr: POINTER
 572		do
 573			ptr := gtk_file_chooser_get_current_folder (handle)
 574			-- ptr is the (gchar *) the full path of the current folder,
 575			-- or NULL if the current path cannot be represented as a
 576			-- local filename. Free with g_free().
 577			if ptr.is_not_null
 578			then create Result.from_external (ptr)
 579			--else check Result=Void end
 580			end
 581		end
 582
 583	uri: STRING is
 584			-- the URI for the currently selected file in the file
 585			-- selector. If multiple files are selected, one of the
 586			-- filenames will be returned at random. If the file chooser
 587			-- is in folder mode, this function returns the selected
 588			-- folder. Void if no file is selected
 589		local ptr: POINTER
 590		do
 591			ptr := gtk_file_chooser_get_uri (handle)
 592			if ptr.is_not_null
 593			then create Result.from_external (ptr)
 594			--else check Result=Void end
 595			end
 596		end
 597
 598	set_uri (an_uri: STRING) is
 599			-- Sets the file referred to by `an_uri' as the current file
 600			-- for the file chooser, by changing to the URI's parent
 601			-- folder and actually selecting the URI in the list. If the
 602			-- chooser `is_action_save' mode, the URI's base name will
 603			-- also appear in the dialog's file name entry.
 604
 605			-- If `an_uri' isn't in the current folder of chooser, then
 606			-- the current folder of chooser will be changed to the
 607			-- folder containing uri. This is equivalent to a sequence of
 608			-- `unselect_all' followed by `select_uri'.
 609
 610			-- Note that the URI must exist, or nothing will be done
 611			-- except for the directory change. If you are implementing a
 612			-- File/Save As... dialog, you should use this function if
 613			-- you already have a file name to which the user may save;
 614			-- for example, when the user opens an existing file and then
 615			-- does File/Save As... on it. If you don't have a file name
 616			-- already -- for example, if the user just created a new
 617			-- file and is saving it for the first time, do not call this
 618			-- function. Instead, use something similar to this:
 619
 620			-- if (document_is_new) { /* the user just created a new
 621			-- document */ gtk_file_chooser_set_current_folder_uri
 622			-- (chooser, default_folder_for_saving);
 623			-- gtk_file_chooser_set_current_name (chooser, "Untitled
 624			-- document"); } else { /* the user edited an existing
 625			-- document */ gtk_file_chooser_set_uri (chooser,
 626			-- existing_uri); }
 627
 628			-- `is_last_action_successful' will be True if both the
 629			-- folder could be changed and the file was selected
 630			-- successfully, False otherwise.
 631		require valid_uri: an_uri/=Void
 632		do
 633			is_last_action_successful := (gtk_file_chooser_set_uri (handle,an_uri.to_external)).to_boolean
 634		end
 635
 636	select_uri (an_uri: STRING) is
 637			-- Selects the file to by `an_uri'. If `an_uri' doesn't refer
 638			-- to a file in the current folder of chooser, then the
 639			-- current folder of chooser will be changed to the folder
 640			-- containing filename.
 641			
 642			-- `is_last_action_successful' will be True if both the
 643			-- folder could be changed and the file was selected
 644			-- successfully, False otherwise.
 645		require valid_uri: an_uri/=Void
 646		do
 647			is_last_action_successful:=(gtk_file_chooser_select_uri(handle,an_uri.to_external)).to_boolean
 648		end
 649
 650	unselect_uri (an_uri: STRING) is
 651			-- Unselects the file referred to by `an_uri'. If the file is
 652			-- not in the current directory, does not exist, or is
 653			-- otherwise not currently selected, does nothing.
 654		require valid_uri: an_uri/=Void
 655		do
 656			gtk_file_chooser_unselect_uri (handle, an_uri.to_external)
 657		end
 658
 659	uris: G_SLIST_STRING is
 660			-- selected files and subfolders in the current folder of
 661			-- chooser. The names are full absolute URIs.
 662		do
 663			create Result.from_external_pointer (gtk_file_chooser_get_uris (handle))
 664		ensure uri_not_void: Result/=Void
 665		end
 666
 667	set_current_folder_uri (an_uri: STRING) is
 668			-- Sets the current folder for chooser from `an_uri'. The user
 669			-- will be shown the full contents of the current folder, plus
 670			-- user interface elements for navigating to other folders.
 671
 672			-- `is_last_action_successful' will be True if both the
 673			-- folder could be changed and the file was selected
 674			-- successfully, False otherwise.
 675		require valid_uri: an_uri /= Void
 676		do
 677			is_last_action_successful:=(gtk_file_chooser_set_current_folder_uri (handle, an_uri.to_external)).to_boolean
 678		end
 679
 680	get_current_folder_uri: STRING is
 681			-- the current folder of chooser as an
 682			-- URI. `set_current_folder_uri'. Can be Void if the file
 683			-- chooser was unable to load the last folder that was
 684			-- requested from it; for example, as would be for calling
 685			-- `set_current_folder_uri' on a nonexistent folder.
 686		local ptr: POINTER
 687		do
 688			-- TODO: when creating a string shall we use from_external or from_external_copy
 689			ptr := gtk_file_chooser_get_current_folder_uri(handle)
 690			if ptr.is_not_null
 691			then create Result.from_external (ptr) -- TODO: this assumes that STRING calls g_free
 692			end
 693		end
 694
 695feature -- Preview
 696	set_preview_widget (a_widget: GTK_WIDGET) is
 697			-- Sets an application-supplied widget to use to display a
 698			-- custom preview of the currently selected file. To
 699			-- implement a preview, after setting the preview widget, you
 700			-- connect to the `::update-preview' signal, and call
 701			-- `preview_filename' or `preview_uri' on each change. If you
 702			-- can display a preview of the new file, update your widget
 703			-- and set the preview active using
 704			-- `set_preview_widget_active'. Otherwise, set the preview
 705			-- inactive.
 706
 707			-- When there is no application-supplied preview widget, or
 708			-- the application-supplied preview widget is not active, the
 709			-- file chooser may display an internally generated preview
 710			-- of the current file or it may display no preview at all.
 711		require valid_widget: a_widget/=Void
 712		do
 713			gtk_file_chooser_set_preview_widget (handle, a_widget.handle)
 714		end
 715
 716	preview_widget: GTK_WIDGET is
 717			-- the current preview widget; can be Void; see `set_preview_widget'.
 718		local factory: G_OBJECT_FACTORY [GTK_WIDGET]
 719		do
 720			Result := factory.wrapper_or_void (gtk_file_chooser_get_preview_widget(handle))
 721		end
 722
 723	set_preview_widget_active is
 724			-- Show the preview widget set by `set_preview_widget'. See
 725			-- `set_preview_widget' for more details.
 726		do
 727			gtk_file_chooser_set_preview_widget_active (handle,1)
 728		end
 729
 730	set_preview_widget_inactive is
 731			-- Hide the preview widget set by `set_preview_widget'. The
 732			-- file chooser may display an internally generated preview
 733			-- of the current file or it may display no preview at
 734			-- all. See `set_preview_widget' for more details.
 735		do
 736			gtk_file_chooser_set_preview_widget_active (handle,1)
 737		end
 738
 739	is_preview_widget_active: BOOLEAN is
 740			-- Is the preview widget set by `set_preview_widget' shown
 741			-- for the current filename. See `set_preview_widget_active'.
 742		do
 743			Result:=(gtk_file_chooser_get_preview_widget_active(handle)).to_boolean
 744		end
 745
 746	use_preview_label is
 747			-- Makes the file chooser display a stock label with the name
 748			-- of the file that is being previewed; the default is
 749			-- True. Applications that want to draw the whole preview
 750			-- area themselves should set this to False and display the
 751			-- name themselves in their preview widget.
 752
 753			-- See also: `set_preview_widget'
 754		do
 755			gtk_file_chooser_set_use_preview_label (handle,1)
 756		ensure is_preview_label_used
 757		end
 758	
 759	use_no_preview_label is
 760			-- Remove from the file chooser the stock label with the name
 761			-- of the file that is being previewed; applications that want to draw the whole preview
 762			-- area themselves should call this feature and display the
 763			-- name themselves in their preview widget.
 764
 765			-- See also: `set_preview_widget'
 766		do
 767			gtk_file_chooser_set_use_preview_label (handle,0)
 768		ensure not is_preview_label_used
 769		end
 770	
 771	is_preview_label_used: BOOLEAN is
 772			-- Is a stock label drawn with the name of the previewed
 773			-- file? See `use_preview_label'.
 774		do
 775			Result:=gtk_file_chooser_get_use_preview_label(handle).to_boolean
 776		end
 777
 778	preview_filename: STRING is
 779			-- the filename that should be previewed in a custom preview
 780			-- widget. See `set_preview_widget'. Can be Void if no file
 781			-- is selected, or if the selected file cannot be represented
 782			-- as a local filename.
 783		local cstr: POINTER
 784		do
 785			cstr:=gtk_file_chooser_get_preview_filename (handle)
 786			if cstr.is_not_null then
 787				create Result.from_external (cstr)
 788				-- Free with g_free()
 789			end
 790		end
 791
 792	preview_uri: STRING is
 793			-- the URI that should be previewed in a custom preview
 794			-- widget. See `set_preview_widget'. Can be Void if no file
 795			-- is selected.
 796		
 797		local cstr: POINTER
 798		do
 799			cstr:=gtk_file_chooser_get_preview_uri(handle)
 800			if cstr.is_not_null then
 801				create Result.from_external (cstr)
 802				-- TODO: Free with g_free()
 803			end
 804		end
 805
 806feature -- Extra widget
 807	set_extra_widget (a_widget: GTK_WIDGET) is
 808			-- Sets an application-supplied widget to provide extra
 809			-- options to the user.
 810		require valid_widget: a_widget/=Void
 811		do
 812			gtk_file_chooser_set_extra_widget (handle, a_widget.handle)
 813		end
 814
 815	extra_widget: GTK_WIDGET is
 816			-- the current preview widget; see `set_extra_widget'. Can be Void
 817		local widget_ptr: POINTER
 818		do
 819			widget_ptr := gtk_file_chooser_get_extra_widget(handle)
 820			if widget_ptr.is_not_null
 821			then
 822				-- retrieve the Eiffel object stored as a pointer with the key `eiffel_key_label'
 823				not_yet_implemented
 824			end
 825		end
 826
 827feature -- Filters
 828	add_filter (a_filter: GTK_FILE_FILTER) is
 829			-- Adds `a_filter' to the list of filters that the user can
 830			-- select between. When a filter is selected, only files that
 831			-- are passed by that filter are displayed.
 832
 833			-- TODO: Eiffelize this: Note that the chooser takes ownership of the filter, so
 834			-- you have to ref and sink it if you want to keep a
 835			-- reference.
 836		require valid_filter: a_filter /= Void
 837		do
 838			gtk_file_chooser_add_filter (handle, a_filter.handle)
 839		end
 840
 841	remove_filter (a_filter: GTK_FILE_FILTER) is
 842			-- Removes `a_filter' from the list of filters that the user
 843			-- can select between.
 844		require valid_filter: a_filter /= Void
 845		do
 846			gtk_file_chooser_remove_filter  (handle, a_filter.handle)
 847		end
 848
 849	filters: G_SLIST [GTK_FILE_FILTER] is
 850			-- The current set of user-selectable filters; see `add_filter', `remove_filter'.		
 851		do
 852			create {G_OBJECT_SLIST [GTK_FILE_FILTER]} 
 853			Result.from_external_pointer (gtk_file_chooser_list_filters (handle))
 854		end
 855
 856	set_filter  (a_filter: GTK_FILE_FILTER) is
 857			-- Sets the current filter; only the files that pass the
 858			-- filter will be displayed. If the user-selectable list of
 859			-- filters is non-empty, then the filter should be one of the
 860			-- filters in that list. Setting the current filter when the
 861			-- list of filters is empty is useful if you want to restrict
 862			-- the displayed set of files without letting the user change
 863			-- it.
 864		require
 865			valid_filter: a_filter /= Void
 866			-- TODO: The following should implement the manifest
 867			-- precondition "If the user-selectable list of filters is
 868			-- non-empty, then the filter should be one of the filters in
 869			-- that list."
 870			filter_is_in_filters: (not filters.is_empty) implies filters.has (a_filter)
 871		do
 872			gtk_file_chooser_set_filter (handle, a_filter.handle)
 873		end
 874
 875
 876	filter: GTK_FILE_FILTER is
 877			-- The current filter; can be Void
 878		local filter_ptr: POINTER
 879		do
 880			filter_ptr := gtk_file_chooser_get_filter (handle)
 881			if filter_ptr.is_not_null
 882			then create Result.from_external_pointer (filter_ptr)
 883			end
 884		end
 885
 886feature -- Shortcuts folders
 887	add_shortcut_folder (a_folder: STRING) is
 888			-- Adds a folder to be displayed with the shortcut folders in
 889			-- a file chooser. Note that shortcut folders do not get
 890			-- saved, as they are provided by the application. For
 891			-- example, you can use this to add a
 892			-- "/usr/share/mydrawprogram/Clipart" folder to the volume
 893			-- list.
 894
 895			-- `is_last_action_successful' will be True if both the
 896			-- folder could be changed and the file was selected
 897			-- successfully, False otherwise. In that case (TODO)
 898			-- `last_error' will be filled with the cause
 899		require valid_folder: a_folder /= Void
 900		do
 901			-- chooser : 	a GtkFileChooser
 902			-- folder : 	filename of the folder to add
 903			-- error : 	location to store error, or NULL
 904			-- Returns : 	TRUE if the folder could be added successfully, FALSE otherwise. In the latter case, the error will be set as appropriate.
 905
 906			-- TODO: Create G_ERROR
 907			is_last_action_successful := gtk_file_chooser_add_shortcut_folder (handle,
 908																									 a_folder.to_external,
 909																									 default_pointer -- TODO: it will be last_error.handle when G_ERROR exists
 910																									).to_boolean
 911		end
 912
 913	remove_shortcut_folder (a_folder: STRING) is
 914			-- Removes `a_folder' from a file chooser's list of shortcut
 915			-- folders.
 916			
 917			-- `is_last_action_successful' will be True if both the
 918			-- folder could be changed and the file was selected
 919			-- successfully, False otherwise. In that case (TODO)
 920			-- `last_error' will be filled with the cause
 921		require valid_folder: a_folder /= Void
 922		do
 923			is_last_action_successful := gtk_file_chooser_remove_shortcut_folder (handle,
 924																										 a_folder.to_external,
 925																										 default_pointer -- TODO: it will be last_error.handle when G_ERROR exists
 926																										 ).to_boolean
 927		end
 928
 929	shortcut_folders: G_SLIST_STRING is
 930			-- The list of shortcut folders in the file chooser, as set
 931			-- by `add_shortcut_folder'.
 932
 933			-- `is_last_action_successful' will be True if both the
 934			-- folder could be changed and the file was selected
 935			-- successfully, False otherwise. In that case (TODO)
 936			-- `last_error' will be filled with the cause
 937		local folders_ptr: POINTER
 938		do
 939			folders_ptr := gtk_file_chooser_list_shortcut_folders (handle)
 940			if folders_ptr.is_not_null
 941			then create Result.from_external_pointer (folders_ptr)
 942				-- TODO: handle this peculiar memory management: . Free
 943				-- the returned list with g_slist_free(), and the
 944				-- filenames with g_free().
 945			end
 946		end
 947
 948	add_shortcut_folder_uri (an_uri: STRING) is
 949			-- Adds a folder URI to be displayed with the shortcut
 950			-- folders in a file chooser. Note that shortcut folders do
 951			-- not get saved, as they are provided by the
 952			-- application. For example, you can use this to add a
 953			-- "file:///usr/share/mydrawprogram/Clipart" folder to the
 954			-- volume list.
 955			
 956			-- `is_last_action_successful' will be True if both the
 957			-- folder could be changed and the file was selected
 958			-- successfully, False otherwise. In that case (TODO)
 959			-- `last_error' will be filled with the cause
 960		require valid_uri: an_uri /= Void
 961		do
 962			is_last_action_successful := ( gtk_file_chooser_add_shortcut_folder_uri
 963													 (handle, an_uri.to_external,
 964													  default_pointer -- TODO: it will be last_error.handle when G_ERROR exists
 965													  ).to_boolean )
 966		end
 967
 968	remove_shortcut_folder_uri  (an_uri: STRING) is
 969			-- Removes a folder URI from a file chooser's list of
 970			-- shortcut folders.
 971		require valid_uri: an_uri /= Void
 972		do
 973			is_last_action_successful := ( gtk_file_chooser_remove_shortcut_folder_uri
 974													 (handle, an_uri.to_external,
 975													  default_pointer -- TODO: it will be last_error.handle when G_ERROR exists
 976													  ).to_boolean )
 977		end
 978
 979	shortcut_folder_uris: G_SLIST_STRING is
 980			--  The list of shortcut folders in the file chooser, as set by `add_shortcut_folder_uri'.
 981		local a_gslist: POINTER
 982		do
 983			a_gslist := gtk_file_chooser_list_shortcut_folder_uris (handle)
 984			if a_gslist.is_not_null
 985			then create Result.from_external_pointer (a_gslist)
 986				-- TODO: handle this peculiar memory management: Free the
 987				-- returned list with g_slist_free(), and the URIs with
 988				-- g_free().
 989			end
 990		end
 991	
 992-- Property Details
 993-- The "action" property
 994
 995--   "action"               GtkFileChooserAction  : Read / Write
 996
 997-- The type of operation that the file selector is performing.
 998
 999-- Default value: GTK_FILE_CHOOSER_ACTION_OPEN
1000-- The "do-overwrite-confirmation" property
1001
1002--   "do-overwrite-confirmation" gboolean              : Read / Write
1003
1004-- Whether a file chooser in GTK_FILE_CHOOSER_ACTION_SAVE will present an overwrite confirmation dialog if the user selects a file name that already exists.
1005
1006-- Default value: FALSE
1007
1008-- Since 2.8
1009-- The "extra-widget" property
1010
1011--   "extra-widget"         GtkWidget             : Read / Write
1012
1013-- Application supplied widget for extra options.
1014-- The "file-system-backend" property
1015
1016--   "file-system-backend"  gchararray            : Write / Construct Only
1017
1018-- Name of file system backend to use.
1019
1020-- Default value: NULL
1021-- The "filter" property
1022
1023--   "filter"               GtkFileFilter         : Read / Write
1024
1025-- The current filter for selecting which files are displayed.
1026-- The "local-only" property
1027
1028--   "local-only"           gboolean              : Read / Write
1029
1030-- Whether the selected file(s) should be limited to local file: URLs.
1031
1032-- Default value: TRUE
1033-- The "preview-widget" property
1034
1035--   "preview-widget"       GtkWidget             : Read / Write
1036
1037-- Application supplied widget for custom previews.
1038-- The "preview-widget-active" property
1039
1040--   "preview-widget-active" gboolean              : Read / Write
1041
1042-- Whether the application supplied widget for custom previews should be shown.
1043
1044-- Default value: TRUE
1045-- The "select-multiple" property
1046
1047--   "select-multiple"      gboolean              : Read / Write
1048
1049-- Whether to allow multiple files to be selected.
1050
1051-- Default value: FALSE
1052-- The "show-hidden" property
1053
1054--   "show-hidden"          gboolean              : Read / Write
1055
1056-- Whether the hidden files and folders should be displayed.
1057
1058-- Default value: FALSE
1059-- The "use-preview-label" property
1060
1061--   "use-preview-label"    gboolean              : Read / Write
1062
1063-- Whether to display a stock label with the name of the previewed file.
1064
1065-- Default value: TRUE
1066-- Signal Details
1067-- The "confirm-overwrite" signal
1068
1069-- GtkFileChooserConfirmationuser_function                  (GtkFileChooser *filechooser,
1070--                                             gpointer user_data);
1071
1072-- This signal gets emitted whenever it is appropriate to present a confirmation dialog when the user has selected a file name that already exists. The signal only gets emitted when the file chooser is in GTK_FILE_CHOOSER_ACTION_SAVE mode.
1073
1074-- Most applications just need to turn on the do-overwrite-confirmation property (or call the gtk_file_chooser_set_do_overwrite_confirmation() function), and they will automatically get a stock confirmation dialog. Applications which need to customize this behavior should do that, and also connect to the confirm-overwrite signal.
1075
1076-- A signal handler for this signal must return a GtkFileChooserConfirmation value, which indicates the action to take. If the handler determines that the user wants to select a different filename, it should return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN. If it determines that the user is satisfied with his choice of file name, it should return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME. On the other hand, if it determines that the stock confirmation dialog should be used, it should return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM. The following example illustrates this.
1077
1078-- Example 5. Custom confirmation
1079
1080-- static GtkFileChooserConfirmation
1081-- confirm_overwrite_callback (GtkFileChooser *chooser, gpointer data)
1082-- {
1083--   char *uri;
1084
1085--   uri = gtk_file_chooser_get_uri (chooser);
1086
1087--   if (is_uri_read_only (uri))
1088--     {
1089--       if (user_wants_to_replace_read_only_file (uri))
1090--         return GTK_FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME;
1091--       else
1092--         return GTK_FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN;
1093--     } else
1094--       return GTK_FILE_CHOOSER_CONFIRMATION_CONFIRM; /* fall back to the default dialog */
1095-- }
1096
1097-- ...
1098
1099-- chooser = gtk_file_chooser_dialog_new (...);
1100
1101-- gtk_file_chooser_set_do_overwrite_confirmation (GTK_FILE_CHOOSER (dialog), TRUE);
1102-- g_signal_connect (chooser, "confirm-overwrite",
1103--                   G_CALLBACK (confirm_overwrite_callback), NULL);
1104
1105-- if (gtk_dialog_run (chooser) == GTK_RESPONSE_ACCEPT)
1106--         save_to_file (gtk_file_chooser_get_filename (GTK_FILE_CHOOSER (chooser));
1107
1108-- gtk_widget_destroy (chooser);
1109
1110
1111-- filechooser : 	the object which received the signal.
1112-- user_data : 	user data set when the signal handler was connected.
1113-- Returns : 	GtkFileChooserConfirmation value that indicates which action to take after emitting the signal.
1114
1115-- Since 2.8
1116-- The "current-folder-changed" signal
1117
1118-- void        user_function                  (GtkFileChooser *chooser,
1119--                                             gpointer user_data);
1120
1121-- This signal is emitted when the current folder in a GtkFileChooser changes. This can happen due to the user performing some action that changes folders, such as selecting a bookmark or visiting a folder on the file list. It can also happen as a result of calling a function to explicitly change the current folder in a file chooser.
1122
1123-- Normally you do not need to connect to this signal, unless you need to keep track of which folder a file chooser is showing.
1124
1125-- See also: gtk_file_chooser_set_current_folder(), gtk_file_chooser_get_current_folder(), gtk_file_chooser_set_current_folder_uri(), gtk_file_chooser_get_current_folder_uri().
1126
1127-- chooser : 	the object which received the signal.
1128-- user_data : 	user data set when the signal handler was connected.
1129
1130feature -- The "file-activated" signal
1131
1132		-- This signal is emitted when the user "activates" a file in
1133		-- the file chooser. This can happen by double-clicking on a file
1134		-- in the file list, or by pressing Enter.
1135
1136		-- Normally you do not need to connect to this signal. It is
1137		-- used internally by GtkFileChooserDialog to know when to activate
1138		-- the default button in the dialog.
1139
1140	file_activated_signal_name: STRING is "file-activated"
1141		-- void        user_function                  (GtkFileChooser *chooser,
1142		--                                             gpointer user_data);
1143
1144	enable_on_file_activated is
1145			-- Connects "file-activated" signal to `on_file_activated' feature.
1146		do
1147			connect (Current, file_activated_signal_name, $on_file_activated)
1148		end
1149
1150	on_file_activated is
1151		do
1152		end
1153
1154	connect_agent_to_file_activated_signal (a_procedure: PROCEDURE [ANY, TUPLE [GTK_FILE_CHOOSER]]) is
1155			-- chooser : 	the object which received the signal.
1156		require
1157			valid_procedure: a_procedure /= Void
1158		local
1159			file_activated_callback: FILE_ACTIVATED_CALLBACK
1160		do
1161			create file_activated_callback.make
1162			file_activated_callback.connect (Current, a_procedure)
1163		end
1164
1165feature -- The "selection-changed" signal
1166
1167			-- This signal is emitted when there is a change in the set of selected
1168			-- files in a GtkFileChooser. This can happen when the user modifies the
1169			-- selection with the mouse or the keyboard, or when explicitly calling
1170			-- functions to change the selection.
1171
1172			-- Normally you do not need to connect to this signal, as it is easier
1173			-- to wait for the file chooser to finish running, and then to get the list
1174			-- of selected files using the functions mentioned below.
1175
1176			-- See also: gtk_file_chooser_select_filename(),
1177			-- gtk_file_chooser_unselect_filename(), gtk_file_chooser_get_filename(),
1178			-- gtk_file_chooser_get_filenames(), gtk_file_chooser_select_uri(),
1179			-- gtk_file_chooser_unselect_uri(), gtk_file_chooser_get_uri(),
1180			-- gtk_file_chooser_get_uris().
1181
1182	selection_changed_signal_name: STRING is "selection-changed"
1183
1184	enable_on_selection_changed is
1185			-- Connects "selection-changed" signal to `on_selection_changed' feature.
1186		do
1187			connect (Current, selection_changed_signal_name, $on_selection_changed)
1188		end
1189
1190	on_selection_changed is
1191		do
1192		end
1193
1194	connect_agent_to_selection_changed_signal (a_procedure: PROCEDURE [ANY, TUPLE [GTK_FILE_CHOOSER]]) is
1195			-- chooser : 	the object which received the signal.
1196		require
1197			valid_procedure: a_procedure /= Void
1198		local
1199			selection_changed_callback: SELECTION_CHANGED_CALLBACK
1200		do
1201			create selection_changed_callback.make
1202			selection_changed_callback.connect (Current, a_procedure)
1203		end
1204
1205feature -- The "update-preview" signal
1206
1207		-- This signal is emitted when the preview in a file chooser should be
1208		-- regenerated. For example, this can happen when the currently selected
1209		-- file changes. You should use this signal if you want your file chooser
1210		-- to have a preview widget.
1211		
1212		-- Once you have installed a preview widget with
1213		-- gtk_file_chooser_set_preview_widget(), you should update it when this
1214		-- signal is emitted. You can use the functions
1215		-- gtk_file_chooser_get_preview_filename() or
1216		-- gtk_file_chooser_get_preview_uri() to get the name of the file to
1217		-- preview. Your widget may not be able to preview all kinds of files;
1218		-- your callback must call gtk_file_chooser_set_preview_wiget_active()
1219		-- to inform the file chooser about whether the preview was generated
1220		-- successfully or not.
1221		
1222		-- See also: gtk_file_chooser_set_preview_widget(),
1223		-- gtk_file_chooser_set_preview_widget_active(),
1224		-- gtk_file_chooser_set_use_preview_label(),
1225		-- gtk_file_chooser_get_preview_filename(),
1226		-- gtk_file_chooser_get_preview_uri().
1227
1228	update_preview_signal_name: STRING is "update-preview"
1229		-- void user_function (GtkFileChooser *chooser, gpointer user_data);
1230
1231	enable_on_update_preview is
1232			-- Connects "update-preview" signal to `on_update_preview' feature.
1233		do
1234			connect (Current, update_preview_signal_name, $on_update_preview)
1235		end
1236
1237	on_update_preview is
1238		do
1239		end
1240
1241	connect_agent_to_update_preview_signal (a_procedure: PROCEDURE [ANY, TUPLE [GTK_FILE_CHOOSER]]) is
1242			-- chooser: the object which received the signal.
1243		require
1244			valid_procedure: a_procedure /= Void
1245		local
1246			update_preview_callback: UPDATE_PREVIEW_CALLBACK
1247		do
1248			create update_preview_callback.make
1249			update_preview_callback.connect (Current, a_procedure)
1250		end
1251
1252end