Struct gtk::FileChooser

#[repr(transparent)]
pub struct FileChooser { /* private fields */ }

FileChooser is an interface that can be implemented by file selection widgets. In GTK+, the main objects that implement this interface are FileChooserWidget, FileChooserDialog, and FileChooserButton. You do not need to write an object that implements the FileChooser interface unless you are trying to adapt an existing file selector to expose a standard programming interface.

FileChooser allows for shortcuts to various places in the filesystem. In the default implementation these are displayed in the left pane. It may be a bit confusing at first that these shortcuts come from various sources and in various flavours, so lets explain the terminology here:

• Bookmarks: are created by the user, by dragging folders from the right pane to the left pane, or by using the “Add”. Bookmarks can be renamed and deleted by the user.

• Shortcuts: can be provided by the application. For example, a Paint program may want to add a shortcut for a Clipart folder. Shortcuts cannot be modified by the user.

• Volumes: are provided by the underlying filesystem abstraction. They are the “roots” of the filesystem.

File Names and Encodings

When the user is finished selecting files in a 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 G_FILENAME_ENCODING environment variable. Please see the GLib documentation for more details about this variable.

This means that while you can pass the result of FileChooserExt::filename() to g_open() or g_fopen(), you may not be able to directly set it as the text of a Label widget unless you convert it first to UTF-8, which all GTK+ widgets expect. You should use g_filename_to_utf8() to convert filenames into strings that can be passed to GTK+ widgets.

Adding a Preview Widget

You can add a custom preview widget to a file chooser and then get notification about when the preview needs to be updated. To install a preview widget, use FileChooserExt::set_preview_widget(). Then, connect to the signal::FileChooser::update-preview signal to get notified when you need to update the contents of the preview.

Your callback should use FileChooserExt::preview_filename() to see what needs previewing. Once you have generated the preview for the corresponding file, you must call FileChooserExt::set_preview_widget_active() with a boolean flag that indicates whether your callback could successfully generate a preview.

Example: Using a Preview Widget ## {gtkfilechooser-preview}

⚠️ The following code is in C ⚠️

{
  GtkImage *preview;

  ...

  preview = gtk_image_new ();

  gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
  g_signal_connect (my_file_chooser, "update-preview",
            G_CALLBACK (update_preview_cb), preview);
}

static void
update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
{
  GtkWidget *preview;
  char *filename;
  GdkPixbuf *pixbuf;
  gboolean have_preview;

  preview = GTK_WIDGET (data);
  filename = gtk_file_chooser_get_preview_filename (file_chooser);

  pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
  have_preview = (pixbuf != NULL);
  g_free (filename);

  gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
  if (pixbuf)
    g_object_unref (pixbuf);

  gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
}

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 toggle button to give the user the option to open a file in read-only mode. You can use FileChooserExt::set_extra_widget() to insert additional widgets in a file chooser.

An example for adding extra widgets:

⚠️ The following code is in C ⚠️

  GtkWidget *toggle;

  ...

  toggle = gtk_check_button_new_with_label ("Open file read-only");
  gtk_widget_show (toggle);
  gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
}

If you want to set more than one extra widget in the file chooser, you can a container such as a Box or a Grid and include your widgets in it. Then, set the container as the whole extra widget.

Implements

FileChooserExt, FileChooserExtManual

Implementations

impl FileChooser

pub const NONE: Option<&'static FileChooser> = None

Trait Implementations

impl Clone for FileChooser

fn clone(&self) -> Self

Returns a copy of the value.

const fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FileChooser

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for FileChooser

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for FileChooser

fn hash<H>(&self, state: &mut H)where
    H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)where
    H: Hasher,

Feeds a slice of this type into the given Hasher.

impl Ord for FileChooser

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

const fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

const fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

const fn clamp(self, min: Self, max: Self) -> Selfwhere
    Self: PartialOrd<Self>,

Restrict a value to a certain interval.

impl<OT: ObjectType> PartialEq<OT> for FileChooser

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for FileChooser

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

const fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

const fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

const fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

const fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for FileChooser

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for FileChooser

impl IsA<FileChooser> for FileChooserButton

impl IsA<FileChooser> for FileChooserDialog

impl IsA<FileChooser> for FileChooserNative

impl IsA<FileChooser> for FileChooserWidget