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

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:

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.

gtk.FileChooser.set_action

    def set_action(action)

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:

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

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)

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

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)

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.

gtk.FileChooser.get_select_multiple

    def get_select_multiple()

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)

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

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)

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)

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)

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

The select_all() method selects all the files in the current folder of a file chooser.

gtk.FileChooser.unselect_all

    def unselect_all()

The unselect_all() method unselects all the files in the current folder of a file chooser.

gtk.FileChooser.get_filenames

    def get_filenames()

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)

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

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

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)

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)

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)

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

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)

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

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)

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:

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

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)

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

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)

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

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

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

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)

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

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)

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)

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

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)

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

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)

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)

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

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)

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)

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

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)

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

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)

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

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

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

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

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)

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)

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)

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)

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.

The "confirm-overwrite" gtk.FileChooser Signal

    def callback(filechooser, user_param1, ...)

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

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

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

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

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