gtk.FileChooser
Prev | The gtk Class Reference | Next

## gtk.FileChooser

gtk.FileChooser — an interface for choosing files used by `gtk.FileChooserWidget` and `gtk.FileChooserDialog` (new in PyGTK 2.4)

## Synopsis

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

## gtk.FileChooser Properties

"action" | Read-Write | The type of operation that the file selector is performing - one of the GTK FileChooser Action Constants. 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" | `def callback(`filechooser`, `user_param1`, `...`)`
"current-folder-changed" | `def callback(`filechooser`, `user_param1`, `...`)`
"file-activated" | `def callback(`filechooser`, `user_param1`, `...`)`
"selection-changed" | `def callback(`filechooser`, `user_param1`, `...`)`
"update-preview" | `def callback(`filechooser`, `user_param1`, `...`)`

## Description

### Note

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).

### Important

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 Control+L.

      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 Alt+Up.

      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 Alt+Down.

      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 Alt+Home.

      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

        def 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`.

### Note

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

        def get_action()

Returns : | the action that is set for the file selector

### Note

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

        def set_local_only(local_only)

`local_only` : | if `True`, only local files can be selected

### Note

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

        def get_local_only()

Returns : | `True` if only local files can be selected.

### Note

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

        def set_select_multiple(select_multiple)

`select_multiple` : | if `True` multiple files can be selected.

### Note

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.

### Note

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

        def get_select_multiple()

Returns : | `True` if multiple files can be selected.

### Note

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

        def set_current_name(name)

`name` : | the filename to use, as a UTF-8 string

### Note

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

        def 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.

### Note

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

        def 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.

### Note

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

        def 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.

### Note

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

        def unselect_filename(filename)

`filename` : | the filename to unselect

### Note

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

        def select_all()

### Note

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

        def unselect_all()

### Note

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

        def get_filenames()

Returns : | a list containing the filenames of all selected files and subfolders in the current folder.

### Note

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

        def set_current_folder(filename)

`filename` : | the full path of the new current folder
Returns : | `True` if the folder could be changed successfully, `False` otherwise.

### Note

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

        def get_current_folder()

Returns : | the full path of the current folder, or `None` if the current path cannot be represented as a local filename.

### Note

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

        def get_uri()

Returns : | The currently selected URI, or `None` if no file is selected.

### Note

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

        def 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.

### Note

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

        def 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.

### Note

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

        def unselect_uri(uri)

`uri` : | the URI of the file to unselect

### Note

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

        def get_uris()

Returns : | a list containing the URIs of all selected files and subfolders in the current folder.

### Note

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

        def set_current_folder_uri(uri)

`uri` : | the URI for the new current folder
Returns : | `True` if the folder could be changed successfully, `False` otherwise.

### Note

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

        def get_current_folder_uri()

Returns : | the URI for the current folder.

### Note

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

        def set_preview_widget(preview_widget)

`preview_widget` : | a widget for displaying a preview.

### Note

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.get_preview_widget

        def get_preview_widget()

Returns : | the current preview widget, or `None`

### Note

This method is available in PyGTK 2.4 and above.

The `get_preview_widget`() method returns the value of the "preview_widget" property i.e. the current preview widget. See the `set_preview_widget()` method for more information.

### gtk.FileChooser.set_preview_widget_active

        def set_preview_widget_active(active)

`active` : | if `True`, display the user-specified preview widget

### Note

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

        def get_preview_widget_active()

Returns : | `True` if the preview widget is active for the current filename.

### Note

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

        def set_use_preview_label(use_label)

`use_label` : | if `True`, display a stock label with the name of the previewed file

### Note

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

        def 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.

### Note

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

        def get_preview_filename()

Returns : | the filename to preview, or `None`.

### Note

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

        def get_preview_uri()

Returns : | the URI for the file to preview, or `None`.

### Note

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.set_extra_widget

        def set_extra_widget(extra_widget)

`extra_widget` : | the widget to display extra options

### Note

This method is available in PyGTK 2.4 and above.

The `set_extra_widget`() method sets the "extra-widget" property to the value of `extra_widget`. `extra_widget` is an application-supplied widget used to display extra options to the user.

### gtk.FileChooser.get_extra_widget

        def get_extra_widget()

Returns : | the current extra widget, or `None`.

### Note

This method is available in PyGTK 2.4 and above.

The `get_extra_widget`() method returns the value of the "extra-widget" property that contains either a widget used to display extra options to the user or `None` if no extra widget is in use. See the `set_extra_widget()` for more information.

### gtk.FileChooser.add_filter

        def add_filter(filter)

`filter` : | a `gtk.FileFilter`

### Note

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

        def remove_filter(filter)

`filter` : | a `gtk.FileFilter`

### Note

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

        def list_filters()

Returns : | a list containing the current set of user selectable filters.

### Note

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

        def set_filter(filter)

`filter` : | a `gtk.FileFilter`

### Note

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

        def get_filter()

Returns : | the current filter, or `None`.

### Note

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

        def add_shortcut_folder(folder)

`folder` : | the filename of the folder to add
Returns : | `True` if the folder could be added successfully.

### Note

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

        def remove_shortcut_folder(folder)

`folder` : | the filename of the folder to remove
Returns : | `True` if `folder` was removed from the list of shortcut folders.

### Note

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

        def list_shortcut_folders()

Returns : | A list of shortcut folder filenames, or `None` if there are no shortcut folders.

### Note

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

        def add_shortcut_folder_uri(uri)

`uri` : | the URI of the folder to add
Returns : | `True` if the folder was added

### Note

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

        def remove_shortcut_folder_uri(uri)

`uri` : | URI of the folder to remove
Returns : | `True` if the folder was removed.

### Note

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

        def list_shortcut_folder_uris()

Returns : | a list of shortcut folder URIs, or `None`

### Note

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

        def set_show_hidden(show_hidden)

`show_hidden` : | if `True` hidden files and folders should be displayed.

### Note

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

        def get_show_hidden()

Returns : | `True` if hidden files and folders are displayed.

### Note

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

        def set_do_overwrite_confirmation(do_overwrite_confirmation)

`do_overwrite_confirmation` : | if `True` ask the user for confirmation before overwriting a file in save mode.

### Note

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

        def get_do_overwrite_confirmation()

Returns : | `True` if hidden files and folders are displayed.

### Note

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

        def get_current_folder_file()

Returns : | The `gio.File`.

### Note

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

        def get_file()

Returns : | A selected `gio.File`.

### Note

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

        def get_preview_file()

Returns : | The `gio.File` for the file to preview, or `None` if no file is selected.

### Note

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

        def 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.

### Note

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

        def set_current_folder_file(file)

`file` : | the `gio.File` for the new folder.
Returns : | `True` if the folder could be changed successfully, `False` otherwise.

### Note

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

        def 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.

### Note

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

        def unselect_file(file)

`file` : | a `gio.File`.

### Note

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

        def 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 GTK FileChooser Confirmation Constants indicating what action GTK+ should take.

### Note

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 GTK FileChooser Confirmation Constants 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

        def 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)

### Note

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

        def 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)

### Note

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

        def 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)

### Note

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

        def 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)

### Note

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

Prev | Up | Next
gtk.Expander | Home | gtk.FileChooserButton