Synopsis

gtk.FileChooser an interface for choosing files used by gtk.FileChooserWidget and gtk.FileChooserDialog (new in PyGTK 2.4) Synopsis gtk.FileChooser gobject.GInterface set_action action get_action set_local_only local_only get_local_only set_select_multiple select_multiple get_select_multiple set_current_name name get_filename set_filename filename select_filename filename unselect_filename filename select_all unselect_all get_filenames set_current_folder filename get_current_folder get_uri set_uri uri select_uri uri unselect_uri uri get_uris set_current_folder_uri uri get_current_folder_uri set_preview_widget preview_widget get_preview_widget set_preview_widget_active active get_preview_widget_active set_use_preview_label use_label get_use_preview_label get_preview_filename get_preview_uri set_extra_widget extra_widget get_extra_widget add_filter filter remove_filter filter list_filters set_filter filter get_filter add_shortcut_folder folder remove_shortcut_folder folder list_shortcut_folders add_shortcut_folder_uri uri remove_shortcut_folder_uri uri list_shortcut_folder_uris set_show_hidden show_hidden get_show_hidden set_do_overwrite_confirmation do_overwrite_confirmation get_do_overwrite_confirmation get_current_folder_file get_file get_preview_file select_file file set_current_folder_file file set_file file unselect_file file gtk.FileChooser Properties

"action" Read-Write The type of operation that the file selector is performing - one of the . Default value: gtk.FILE_CHOOSER_ACTION_OPEN "do-overwrite-confirmation" Read-Write If True 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. Default value: False. This property is available in GTK+ 2.8 and above "extra-widget" Read-Write An application supplied widget for extra options. "file-system-backend" Write-Construct The name of the file system backend to use. Default value: None "filter" Read-Write The current gtk.FileFilter for selecting which files are displayed. "local-only" Read-Write If True, the selected file(s) should be limited to local file: URLs. Default value: True "preview-widget" Read-Write An application supplied widget for custom previews. "preview-widget-active" Read-Write If True, the application supplied widget for custom previews should be shown. Default value: True "select-multiple" Read-Write If True, allow multiple files to be selected except if gtk.FILE_CHOOSER_ACTION_SAVE is set as the "action" property. Default value: False "show-hidden" Read-Write If True, hidden files and folders should be displayed. Default value: False "use-preview-label" Read-Write If True, display a stock label with the name of the previewed file. Default value: True

gtk.FileChooser Signal Prototypes "confirm-overwrite" callback filechooser user_param1 ... "current-folder-changed" callback filechooser user_param1 ... "file-activated" callback filechooser user_param1 ... "selection-changed" callback filechooser user_param1 ... "update-preview" callback filechooser user_param1 ... Description This interface is available in PyGTK 2.4 and above. gtk.FileChooser is an interface that can be implemented by file selection widgets. In PyGTK, the main objects that implement this interface are gtk.FileChooserWidget and gtk.FileChooserDialog. You do not need to write an object that implements the gtk.FileChooser interface unless you are trying to adapt an existing file selector to expose a standard programming interface. gtk.FileChooser has several elements to its display: a list of shortcut folders on the left that is divided into two lists by a horizontal line: a default list of folders usually including "Home" and "Filesystem" with folders added using the add_shortcut_folder() or add_shortcut_folder_uri() methods. a list of user specified shortcut folders managed using the "Add" and "Remove" buttons at the bottom of the file chooser. the "Add" and "Remove" buttons that allow a user to add or remove a folder to or from the user's shortcut folder list. the current folder path as a series of buttons above the file selection window. The buttons can be clicked to jump to the associated ancestor folder. the file selection window that displays the contents of the current folder in alphabetical order with last modified time. File Names and Encodings When the user is finished selecting files in a gtk.FileChooser, your program can get the selected names either as filenames or as URIs. For URIs, the normal escaping rules are applied if the URI contains non-ASCII characters. However, filenames are always returned in the character set specified by the result of calling the Python sys.getfilesystemencoding() function. On POSIX this is the actual on-disk encoding which might correspond to the locale settings of the process, or not. On Windows the file name encoding is UTF-8. Note that the Microsoft C library does not use UTF-8, but has separate APIs for current system code page and wide characters (UTF-16). This means that while you can pass the result of get_filename() to open() or os.open(), you may not be able to directly set it as the text of a gtk.Label widget unless you convert it first to UTF-8, which all PyGTK widgets expect. If necessary you should use the Python codecs to convert filenames into strings that can be passed to PyGTK widgets. Adding A Preview Widget You can add a custom preview widget to a file chooser and get notification when the preview needs to be updated. To install a preview widget, use the set_preview_widget() method. Then, connect to the "update-preview" signal to be notified when you need to update the contents of the preview. Your callback should use the get_preview_filename() method to see what needs previewing. Once you have generated the preview for the corresponding file, you must call the set_preview_widget_active() method with a boolean flag that indicates whether your callback could successfully generate a preview. An example use of a custom preview is: ... preview = gtk.Image() my_file_chooser.set_preview_widget(preview) my_file_chooser.connect("update-preview", update_preview_cb, preview) ... def update_preview_cb(file_chooser, preview): filename = file_chooser.get_preview_filename() try: pixbuf = gtk.gdk.pixbuf_new_from_file_at_size(filename, 128, 128) preview.set_from_pixbuf(pixbuf) have_preview = True except: have_preview = False file_chooser.set_preview_widget_active(have_preview) return ... Adding Extra Widgets 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 gtk.ToggleButton to give the user the option to open a file in read-only mode. You can use the set_extra_widget() method to insert additional widgets in a file chooser. For example: toggle = gtk.CheckButton("Open file read-only") toggle.show () my_file_chooser.set_extra_widget(toggle) If you want to set more than one extra widget in the file chooser, you can use a container such as a gtk.VBox or a gtk.Table to hold your widgets; then set the container as the whole extra widget. Key Bindings The gtk.FileChooserDialog uses the private GtkFileChooserDefaultClass that has several key bindings and their associated signals. This section describes the available key binding signals. The default keys that activate the key-binding signals in GtkFileChooserDefaultClass are as follows: Signal name Key location-popup Control-L up-folder Alt-Up down-folder Alt-Down home-folder Alt-Home To change these defaults to something else, you could include the following fragment in your .gtkrc-2.0 file: binding "my-own-gtkfilechooser-bindings" { bind "<Alt><Shift>l" { "location-popup" () } bind "<Alt><Shift>Up" { "up-folder" () } bind "<Alt><Shift>Down" { "down-folder" () } bind "<Alt><Shift>Home" { "home-folder-folder" () } } class "GtkFileChooserDefault" binding "my-own-gtkfilechooser-bindings" The "GtkFileChooserDefault::location-popup" signal 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. By default this is bound to ControlL. def location_popup_cb(filechooser, user_data): where filechooser is the gtk.FileChooser that received the signal, user_data is user data set when the signal handler was connected. The "GtkFileChooserDefault::up-folder" signal 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 AltUp. def up_folder_cb(filechooser, user_data): where filechooser is the object that received the signal and user_data is the user data set when the signal handler was connected. The "GtkFileChooserDefault::down-folder" signal 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 AltDown . def down_folder_cb(filechooser, user_data): where filechooser is the object that received the signal and user_data is the user data set when the signal handler was connected. The "GtkFileChooserDefault::home-folder" signal is used to make the file chooser show the user's home folder in the file list. By default this is bound to AltHome . def home_folder_cb(filechooser, user_data): where filechooser is the object that received the signal and user_data is the user data set when the signal handler was connected. Methods gtk.FileChooser.set_action set_action action action : the file selection action - one of: gtk.FILE_CHOOSER_ACTION_OPEN, gtk.FILE_CHOOSER_ACTION_SAVE, gtk.FILE_CHOOSER_ACTION_SELECT_FOLDER or gtk.FILE_CHOOSER_ACTION_CREATE_FOLDER. This method is available in PyGTK 2.4 and above. The set_action() method sets the "action" property to the value of action. The type of operation that that the chooser is performing is set by action causing the user interface to be changed to suit the selected action. The value of action must be one of: gtk.FILE_CHOOSER_ACTION_OPEN Indicates open mode. The file chooser will only let the user pick an existing file. gtk.FILE_CHOOSER_ACTION_SAVE Indicates save mode. The file chooser will let the user pick an existing file, or type in a new filename. gtk.FILE_CHOOSER_ACTION_SELECT_FOLDER Indicates an open mode for selecting folders. The file chooser will let the user pick an existing folder. gtk.FILE_CHOOSER_ACTION_CREATE_FOLDER Indicates a mode for creating a new folder. The file chooser will let the user name an existing or new folder 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. gtk.FileChooser.get_action get_action Returns : the action that is set for the file selector This method is available in PyGTK 2.4 and above. The get_action() method returns the value of the "action" property that indicates the type of operation that the file chooser is set to perform. See the set_action() method for more information. gtk.FileChooser.set_local_only set_local_only local_only local_only : if True, only local files can be selected This method is available in PyGTK 2.4 and above. The set_local_only() method sets the "local-only" property to the value of local_only. If local_only is True (the default), only local files can be selected in the file selector and the selected files are guaranteed to be accessible through the operating system's native file system. Therefore, the application only needs to use the filename methods in gtk.FileChooser. For example, the application can use the get_filename() method instead of the URI method get_uri(). gtk.FileChooser.get_local_only get_local_only Returns : True if only local files can be selected. This method is available in PyGTK 2.4 and above. The get_local_only() method returns the value of the "local-only" property that indicates whether only local files can be selected in the file selector. See the set_local_only() method for more information. gtk.FileChooser.set_select_multiple set_select_multiple select_multiple select_multiple : if True multiple files can be selected. This method is available in PyGTK 2.4 and above. The set_select_multiple() method sets the "select_multiple" property to the value of select_multiple. If select_multiple is True, multiple files can be selected in the file selector. The "select-multiple" property cannot be set True when the file chooser action is gtk.FILE_CHOOSER_ACTION_SAVE or gtk.FILE_CHOOSER_ACTION_CREATE_FOLDER. gtk.FileChooser.get_select_multiple get_select_multiple Returns : True if multiple files can be selected. This method is available in PyGTK 2.4 and above. The get_select_multiple() method returns the value of the "select_multiple" property that indicates whether multiple files can be selected in the file selector. See the set_select_multiple() method for more information. gtk.FileChooser.set_current_name set_current_name name name : the filename to use, as a UTF-8 string This method is available in PyGTK 2.4 and above. The set_current_name() method sets the current name in the file selector to the value of name, as if entered by the user. Note that the name passed in here is a UTF-8 string rather than a filename. This method 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 the set_filename() method instead. gtk.FileChooser.get_filename get_filename Returns : The currently selected filename, or None if no file is selected, or the selected file can't be represented with a local filename. This method is available in PyGTK 2.4 and above. The get_filename() method returns the filename of the currently selected file in the file selector. If multiple files are selected, one of the filenames will be returned at random. If the file chooser is in folder mode, this function returns the selected folder. gtk.FileChooser.set_filename set_filename filename filename : the filename to set as current Returns : True if both the folder could be changed and the file was selected successfully, False otherwise. This method is available in PyGTK 2.4 and above. The set_filename() method sets filename as the current filename for the the file chooser. If the file name isn't in the current folder of the chooser, then the current folder of the chooser will be changed to the folder containing filename. This is equivalent to a sequence of unselect_all() followed by 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 the set_current_name() method. gtk.FileChooser.select_filename select_filename filename filename : the filename to select Returns : True if both the folder could be changed and the file was selected successfully, False otherwise. This method is available in PyGTK 2.4 and above. The select_filename() method selects the filename specified by filename. If filename isn't in the current folder of the chooser, then the current folder of the chooser will be changed to the folder containing filename. gtk.FileChooser.unselect_filename unselect_filename filename filename : the filename to unselect This method is available in PyGTK 2.4 and above. The unselect_filename() method unselects the currently selected filename specified by filename. If filename is not in the current directory, does not exist, or is otherwise not currently selected, this method does nothing. gtk.FileChooser.select_all select_all This method is available in PyGTK 2.4 and above. The select_all() method selects all the files in the current folder of a file chooser. gtk.FileChooser.unselect_all unselect_all This method is available in PyGTK 2.4 and above. The unselect_all() method unselects all the files in the current folder of a file chooser. gtk.FileChooser.get_filenames get_filenames Returns : a list containing the filenames of all selected files and subfolders in the current folder. This method is available in PyGTK 2.4 and above. The get_filenames() method returns a list containing all the selected files and subfolders in the current folder of the 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 the get_uris() method for more information) gtk.FileChooser.set_current_folder set_current_folder filename filename : the full path of the new current folder Returns : True if the folder could be changed successfully, False otherwise. This method is available in PyGTK 2.4 and above. The set_current_folder() method sets the current folder for the chooser to the local filename specified by filename. The user will be shown the full contents of the current folder, plus user interface elements for navigating to other folders. gtk.FileChooser.get_current_folder get_current_folder Returns : the full path of the current folder, or None if the current path cannot be represented as a local filename. This method is available in PyGTK 2.4 and above. The get_current_folder() method returns the current folder of the chooser as a local filename. See the set_current_folder() method for more information. gtk.FileChooser.get_uri get_uri Returns : The currently selected URI, or None if no file is selected. This method is available in PyGTK 2.4 and above. The get_uri() method returns 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. If the file chooser is in folder mode, this function returns the selected folder. gtk.FileChooser.set_uri set_uri uri uri : the URI to set as the current file Returns : True if both the folder could be changed and the URI was successfully selected. This method is available in PyGTK 2.4 and above. The set_uri() method sets the file referred to by uri as the current file for the file chooser; If the file name isn't in the current folder of the chooser, then the current folder of the chooser will be changed to the folder containing uri. This is equivalent to the sequence of unselect_all() followed by 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 the set_current_name() method. gtk.FileChooser.select_uri select_uri uri uri : the URI of the file to select Returns : True if both the folder could be changed and the URI was successfully selected. This method is available in PyGTK 2.4 and above. The select_uri() method selects the file referred to by uri. If the URI doesn't refer to a file in the current folder of the chooser, then the current folder of the chooser will be changed to the folder containing the file referenced by uri. gtk.FileChooser.unselect_uri unselect_uri uri uri : the URI of the file to unselect This method is available in PyGTK 2.4 and above. The unselect_uri() method 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, this method does nothing. gtk.FileChooser.get_uris get_uris Returns : a list containing the URIs of all selected files and subfolders in the current folder. This method is available in PyGTK 2.4 and above. The get_uris() method returns a list containing all the selected files and subfolders in the current folder of the chooser. The returned names are full absolute URIs. gtk.FileChooser.set_current_folder_uri set_current_folder_uri uri uri : the URI for the new current folder Returns : True if the folder could be changed successfully, False otherwise. This method is available in PyGTK 2.4 and above. The set_current_folder_uri() method sets the current folder for the chooser to the folder referenced by uri. The user will be shown the full contents of the current folder, plus user interface elements for navigating to other folders. gtk.FileChooser.get_current_folder_uri get_current_folder_uri Returns : the URI for the current folder. This method is available in PyGTK 2.4 and above. The get_current_folder_uri() method returns the URI reference of the current folder of the chooser. See the set_current_folder_uri() method for more information. gtk.FileChooser.set_preview_widget set_preview_widget preview_widget preview_widget : a widget for displaying a preview. This method is available in PyGTK 2.4 and above. The set_preview_widget() method sets the "preview-widget" property to the value of preview_widget. The preview_widget is used to preview the currently selected file. To implement a custom preview: set the preview widget connect a callback to the "selection-changed" signal of the file chooser in the callback, call the get_preview_filename() method or the get_preview_uri() method to retrieve the selected file name or URI if you can, display a preview of the selected file and set the preview active using the set_preview_widget_active() method otherwise, set the preview inactive When there is no 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. gtk.FileChooser.set_preview_widget_active set_preview_widget_active active active : if True, display the user-specified preview widget This method is available in PyGTK 2.4 and above. The set_preview_widget_active() method sets the "preview_widget_active" property to the value of active. If active is True, the preview widget set by the set_preview_widget() method should be shown for the current filename. When active is False, the file chooser may display an internally generated preview of the current file or it may display no preview at all. See the set_preview_widget() for more details. gtk.FileChooser.get_preview_widget_active get_preview_widget_active Returns : True if the preview widget is active for the current filename. This method is available in PyGTK 2.4 and above. The get_preview_widget_active() method returns the value of the "preview-widget-active" property that indicates whether the preview widget set by the set_preview_widget() method should be shown for the current filename. See the set_preview_widget_active() method for more details. gtk.FileChooser.set_use_preview_label set_use_preview_label use_label use_label : if True, display a stock label with the name of the previewed file This method is available in PyGTK 2.4 and above. The set_use_preview_label() method sets the "use-preview-label" property to the value of use_label. If use_label is True (the default), the file chooser should display a stock label with the name of the file that is being previewed. Applications that want to draw the whole preview area themselves should set this to False and display the name themselves in their preview widget. See the set_preview_widget() method for more information. gtk.FileChooser.get_use_preview_label get_use_preview_label Returns : True if the file chooser is set to display a label with the name of the previewed file; False otherwise. This method is available in PyGTK 2.4 and above. The get_use_preview_label() method returns the value of the "use-preview-label" property that indicates whether a stock label should be drawn with the name of the previewed file. See the set_use_preview_label() for more information. gtk.FileChooser.get_preview_filename get_preview_filename Returns : the filename to preview, or None. This method is available in PyGTK 2.4 and above. The get_preview_filename() method returns the filename that should be previewed in a custom preview widget or None if no file is selected, or if the selected file cannot be represented as a local filename. See the set_preview_widget() method for more details. gtk.FileChooser.get_preview_uri get_preview_uri Returns : the URI for the file to preview, or None. This method is available in PyGTK 2.4 and above. The get_preview_uri() method returns the URI of the file that should be previewed in a custom preview widget or None if no file is selected. See the set_preview_widget() method fr more details. gtk.FileChooser.add_filter add_filter filter filter : a gtk.FileFilter This method is available in PyGTK 2.4 and above. The add_filter() method adds the gtk.FileFilter specified by filter to the list of filters that the user can select from. When a filter is selected, only files that are passed by that filter are displayed. gtk.FileChooser.remove_filter remove_filter filter filter : a gtk.FileFilter This method is available in PyGTK 2.4 and above. The remove_filter() method removes the gtk.FileFilter specified by filter from the list of filters that the user can select from. gtk.FileChooser.list_filters list_filters Returns : a list containing the current set of user selectable filters. This method is available in PyGTK 2.4 and above. The list_filters() method returns the current set of user-selectable filters. See the add_filter() and remove_filter() method for more details. gtk.FileChooser.set_filter set_filter filter filter : a gtk.FileFilter This method is available in PyGTK 2.4 and above. The set_filter() method sets the "filter" property to the value of filter and also sets the current filter to filter. Only the files that pass filter will be displayed. If the user-selectable list of filters is non-empty, then filter should be one of the filters in that list. Setting the current filter when the list of filters is empty is useful if you want to restrict the displayed set of files without letting the user change it. gtk.FileChooser.get_filter get_filter Returns : the current filter, or None. This method is available in PyGTK 2.4 and above. The get_filter() method returns the value of the "filter" property which is the current filter. See the set_filter() method for more information. gtk.FileChooser.add_shortcut_folder add_shortcut_folder folder folder : the filename of the folder to add Returns : True if the folder could be added successfully. This method is available in PyGTK 2.4 and above. The add_shortcut_folder() adds the folder specified by folder the list of shortcut folders in a file chooser. Shortcut folders are displayed at the upper left in the gtk.FileChooser. By double-clicking on a shortcut the user can open that folder directly. Note that shortcut folders do not get saved, as they are provided by the application. For example, you can use this to add a "/usr/share/mydrawprogram/Clipart" folder to the volume list. The GError exception is raised if an error occurred while adding the folder. gtk.FileChooser.remove_shortcut_folder remove_shortcut_folder folder folder : the filename of the folder to remove Returns : True if folder was removed from the list of shortcut folders. This method is available in PyGTK 2.4 and above. The remove_shortcut_folder() method removes the folder specified by folder from a file chooser's list of shortcut folders. remove_shortcut_folder() returns True if successful. See the add_shortcut_folder() method for more information. The GError exception is raised if an error occurred while removing the folder. gtk.FileChooser.list_shortcut_folders list_shortcut_folders Returns : A list of shortcut folder filenames, or None if there are no shortcut folders. This method is available in PyGTK 2.4 and above. The list_shortcut_folders() method returns the list of shortcut folders in the file chooser, as set by the add_shortcut_folder() method or None if there are no shortcut folders. It is not possible to get a list of the user-specified shortcut folders. gtk.FileChooser.add_shortcut_folder_uri add_shortcut_folder_uri uri uri : the URI of the folder to add Returns : True if the folder was added This method is available in PyGTK 2.4 and above. The add_shortcut_folder_uri() method adds a folder with the URI specified by uri to the list of shortcut folders in a file chooser. Note that shortcut folders do not get saved, as they are provided by the application. For example, you can use this to add a "file:///usr/share/mydrawprogram/Clipart" folder to the volume list. See the add_shortcut_folder() method for more details. The GError exception is raised if an error occurred while adding the folder. gtk.FileChooser.remove_shortcut_folder_uri remove_shortcut_folder_uri uri uri : URI of the folder to remove Returns : True if the folder was removed. This method is available in PyGTK 2.4 and above. The remove_shortcut_folder_uri() method removes the folder with the URI specified by uri from the file chooser's list of shortcut folders. The GError exception is raised if an error occurred while removing the folder. gtk.FileChooser.list_shortcut_folder_uris list_shortcut_folder_uris Returns : a list of shortcut folder URIs, or None This method is available in PyGTK 2.4 and above. The list_shortcut_folder_uris() method returns a list of the shortcut folders in the file chooser, as set by the add_shortcut_folder_uri() method. It is not possible to get a list of the user-specified folder URIs. gtk.FileChooser.set_show_hidden set_show_hidden show_hidden show_hidden : if True hidden files and folders should be displayed. This method is available in PyGTK 2.6 and above. The set_show_hidden() method sets the "show-hidden" property to the value of show_hidden. If show_hidden is True, hidden files and folders should be displayed in the file selector. gtk.FileChooser.get_show_hidden get_show_hidden Returns : True if hidden files and folders are displayed. This method is available in PyGTK 2.6 and above. The get_show_hidden() method returns the value of the "show-hidden" property that indicates whether hidden files and folders should be displayed in the file selector. See the set_show_hidden() method for more information. gtk.FileChooser.set_do_overwrite_confirmation set_do_overwrite_confirmation do_overwrite_confirmation do_overwrite_confirmation : if True ask the user for confirmation before overwriting a file in save mode. This method is available in PyGTK 2.8 and above. The set_do_overwrite_confirmation() method sets the "do-overwrite-confirmation" property to the value of do_overwrite_confirmation. If do_overwrite_confirmation is True and the "action" property is set to gtk.FILE_CHOOSER_ACTION_SAVE, the file chooser will present a confirmation dialog if the user attempts to overwrite an existing file. The default value is False. If all you need is the stock confirmation dialog, set the "do-overwrite-confirmation" property to True. You can override the way confirmation is done by actually handling the "confirm-overwrite" signal; please refer to its documentation for details. gtk.FileChooser.get_do_overwrite_confirmation get_do_overwrite_confirmation Returns : True if hidden files and folders are displayed. This method is available in PyGTK 2.8 and above. The get_do_overwrite_confirmation() method returns the value of the "do-overwrite-confirmation" property that indicates whether a user is asked for confirmation before overwriting an existing file. See the set_do_overwrite_confirmation() method for more information. gtk.FileChooser.get_current_folder_file get_current_folder_file Returns : The gio.File. This method is available in PyGTK 2.14 and above. The get_current_folder_file() method returns the current folder of chooser as gio.File. See gtk.FileChooser.get_current_folder_uri(). gtk.FileChooser.get_file get_file Returns : A selected gio.File. This method is available in PyGTK 2.14 and above. The get_file() method returns the gio.File for the currently selected file in the file selector. If multiple files are selected, one of the files will be returned at random. If the file chooser is in folder mode, this function returns the selected folder. gtk.FileChooser.get_preview_file get_preview_file Returns : The gio.File for the file to preview, or None if no file is selected. This method is available in PyGTK 2.14 and above. The get_preview_file() method returns the gio.File that should be previewed in a custom preview Internal function, see gtk.FileChooser.get_preview_uri(). gtk.FileChooser.select_file select_file file file : the file to select. Returns : True if both the folder could be changed and the path was selected successfully, False otherwise. This method is available in PyGTK 2.14 and above. The select_file() method selects the file referred to by file. An internal function. See gtk.FileChooser.select_uri(). gtk.FileChooser.set_current_folder_file set_current_folder_file file file : the gio.File for the new folder. Returns : True if the folder could be changed successfully, False otherwise. This method is available in PyGTK 2.14 and above. The set_current_folder_file() method sets the current folder for chooser from a gio.File. Internal function, see gtk.FileChooser.set_current_folder_uri(). gtk.FileChooser.set_file set_file file file : the gio.File to set as current. Returns : True if both the folder could be changed and the file selected successfully, False otherwise. This method is available in PyGTK 2.14 and above. The set_file() method Sets file as the current filename for the file chooser, by changing to the file's parent folder and actually selecting the file in list. If the chooser is in gtk.FILE_CHOOSER_ACTION_SAVE mode, the file's base name will also appear in the dialog's file name entry. 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.FileChooser.unselect_all() followed by gtk.FileChooser.select_filename(). Note that the file must exist, or nothing will be done except for the directory change. If you are implementing a File/Save As... 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 File/Save As... on it. If you don't have a file name already — 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: if (document_is_new): # the user just created a new document chooser.set_current_folder_file(default_file_for_saving) chooser.set_current_name("Untitled document") else: # the user edited an existing document chooser.set_file(existing_file) gtk.FileChooser.unselect_file unselect_file file file : a gio.File. This method is available in PyGTK 2.14 and above. The unselect_file() method unselects the file referred to by file. If the file is not in the current directory, does not exist, or is otherwise not currently selected, does nothing. Signals The "confirm-overwrite" gtk.FileChooser Signal callback filechooser user_param1 ... filechooser : the filechooser widget that received the signal user_param1 : the first user parameter (if any) specified with the connect() method ... : additional user parameters (if any) Returns : one of the indicating what action GTK+ should take. This signal is available in PyGTK 2.8 and above. The "confirm-overwrite" signal is emitted when it is appropriate to present a confirmation dialog when the user has selected a file name that already exists. The signal is only emitted when the file chooser "action" property is set to gtk.FILE_CHOOSER_ACTION_SAVE. Most applications just need to turn on the "do-overwrite-confirmation" property (or call the set_do_overwrite_confirmation() method), to automatically get a stock confirmation dialog. Applications that need to customize this behavior should do that, and also connect to the "confirm-overwrite" signal. A signal handler for this signal must return one of the that 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 gtkfile_CHOOSER_CONFIRMATION_CONFIRM. The following psuedo-code example illustrates this. def confirm_overwrite_callback(chooser): uri = chooser.get_uri() if is_uri_read_only(uri): if user_wants_to_replace_read_only_file (uri): return gtk.FILE_CHOOSER_CONFIRMATION_ACCEPT_FILENAME else return gtk.FILE_CHOOSER_CONFIRMATION_SELECT_AGAIN else # fall back to the default dialog return gtk.FILE_CHOOSER_CONFIRMATION_CONFIRM ... chooser = gtk.FileChooserDialog(...) chooser.set_do_overwrite_confirmation(True) chooser.connect("confirm-overwrite", confirm_overwrite_callback) if chooser.run() == gtk.RESPONSE_ACCEPT: save_to_file(chooser.get_filename() chooser.destroy() The "current-folder-changed" gtk.FileChooser Signal callback filechooser user_param1 ... filechooser : the filechooser widget that received the signal user_param1 : the first user parameter (if any) specified with the connect() method ... : additional user parameters (if any) This signal is available in PyGTK 2.4 and above. The "current-folder-changed" signal is emitted when the current folder displayed in filechooser is changed. Normally you do not need to connect to this signal, unless you need to keep track of which folder a file chooser is showing. The "file-activated" gtk.FileChooser Signal callback filechooser user_param1 ... filechooser : the filechooser widget that received the signal user_param1 : the first user parameter (if any) specified with the connect() method ... : additional user parameters (if any) This signal is available in PyGTK 2.4 and above. The "file-activated" signal is emitted when the user double-clicks on a file (not a folder) or presses Enter. Normally you do not need to connect to this signal. It is used internally by gtk.FileChooserDialog to know when to activate the default button in the dialog. The "selection-changed" gtk.FileChooser Signal callback filechooser user_param1 ... filechooser : the filechooser widget that received the signal user_param1 : the first user parameter (if any) specified with the connect() method ... : additional user parameters (if any) This signal is available in PyGTK 2.4 and above. The "selection-changed" signal is emitted when the file selection in filechooser is changed either by clicking on a filename or by changing the current folder. Normally you do not need to connect to this signal, as it is easier to wait for the file chooser to finish running, and then to get the list of selected files using the functions mentioned below. The "update-preview" gtk.FileChooser Signal callback filechooser user_param1 ... filechooser : the filechooser widget that received the signal user_param1 : the first user parameter (if any) specified with the connect() method ... : additional user parameters (if any) This signal is available in PyGTK 2.4 and above. The "update-preview" signal is emitted when the preview when a file chooser should be regenerated. For example, this can happen when the currently selected file changes. You should use this signal if you want your file chooser to have a preview widget. Once you have installed a preview widget with the set_preview_widget() method, you should update it when this signal is emitted. You can use the methods get_preview_filename() or get_preview_uri() to get the name of the file to preview. Your widget may not be able to preview all kinds of files so your callback must call the set_preview_widget_active() to inform the file chooser if the preview was generated successfully or not. Please see the example code in the section called Adding a Preview Widget. Also see the set_preview_widget(), set_preview_widget_active(), set_use_preview_label(), get_preview_filename() and get_preview_uri() methods for more information