manpagez: man pages & more
html files: pygtk
Home | html | info | man
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-WriteThe 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-WriteIf 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-WriteAn application supplied widget for extra options.
"file-system-backend"Write-ConstructThe name of the file system backend to use. Default value: None
"filter"Read-WriteThe current gtk.FileFilter for selecting which files are displayed.
"local-only"Read-WriteIf True, the selected file(s) should be limited to local file: URLs. Default value: True
"preview-widget"Read-WriteAn application supplied widget for custom previews.
"preview-widget-active"Read-WriteIf True, the application supplied widget for custom previews should be shown. Default value: True
"select-multiple"Read-WriteIf 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-WriteIf True, hidden files and folders should be displayed. Default value: False
"use-preview-label"Read-WriteIf 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 nameKey
location-popupControl-L
up-folderAlt-Up
down-folderAlt-Down
home-folderAlt-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

© manpagez.com 2000-2017
Individual documents may contain additional copyright information.