Struct gtk::FileChooserDialog

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

FileChooserDialog is a dialog box suitable for use with “File/Open” or “File/Save as” commands. This widget works by putting a FileChooserWidget inside a Dialog. It exposes the FileChooser interface, so you can use all of the FileChooser functions on the file chooser dialog as well as those for Dialog.

Note that FileChooserDialog does not have any methods of its own. Instead, you should use the functions that work on a FileChooser.

If you want to integrate well with the platform you should use the FileChooserNative API, which will use a platform-specific dialog if available and fall back to GtkFileChooserDialog otherwise.

Typical usage ## {gtkfilechooser-typical-usage}

In the simplest of cases, you can the following code to use FileChooserDialog to select a file for opening:

GtkWidget *dialog;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;
gint res;

dialog = gtk_file_chooser_dialog_new ("Open File",
                                      parent_window,
                                      action,
                                      _("_Cancel"),
                                      GTK_RESPONSE_CANCEL,
                                      _("_Open"),
                                      GTK_RESPONSE_ACCEPT,
                                      NULL);

res = gtk_dialog_run (GTK_DIALOG (dialog));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;
    GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog);
    filename = gtk_file_chooser_get_filename (chooser);
    open_file (filename);
    g_free (filename);
  }

gtk_widget_destroy (dialog);

To use a dialog for saving, you can use this:

GtkWidget *dialog;
GtkFileChooser *chooser;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE;
gint res;

dialog = gtk_file_chooser_dialog_new ("Save File",
                                      parent_window,
                                      action,
                                      _("_Cancel"),
                                      GTK_RESPONSE_CANCEL,
                                      _("_Save"),
                                      GTK_RESPONSE_ACCEPT,
                                      NULL);
chooser = GTK_FILE_CHOOSER (dialog);

gtk_file_chooser_set_do_overwrite_confirmation (chooser, TRUE);

if (user_edited_a_new_document)
  gtk_file_chooser_set_current_name (chooser,
                                     _("Untitled document"));
else
  gtk_file_chooser_set_filename (chooser,
                                 existing_filename);

res = gtk_dialog_run (GTK_DIALOG (dialog));
if (res == GTK_RESPONSE_ACCEPT)
  {
    char *filename;

    filename = gtk_file_chooser_get_filename (chooser);
    save_to_file (filename);
    g_free (filename);
  }

gtk_widget_destroy (dialog);

Setting up a file chooser dialog ## {gtkfilechooserdialog-setting-up}

There are various cases in which you may need to use a FileChooserDialog:

• To select a file for opening. Use FileChooserAction::Open.

• To save a file for the first time. Use FileChooserAction::Save, and suggest a name such as “Untitled” with FileChooserExt::set_current_name().

• To save a file under a different name. Use FileChooserAction::Save, and set the existing filename with FileChooserExt::set_filename().

• To choose a folder instead of a file. Use FileChooserAction::SelectFolder.

Note that old versions of the file chooser’s documentation suggested using FileChooserExt::set_current_folder() in various situations, with the intention of letting the application suggest a reasonable default folder. This is no longer considered to be a good policy, as now the file chooser is able to make good suggestions on its own. In general, you should only cause the file chooser to show a specific folder when it is appropriate to use FileChooserExt::set_filename(), i.e. when you are doing a Save As command and you already have a file saved somewhere.

Response Codes ## {gtkfilechooserdialog-responses}

FileChooserDialog inherits from Dialog, so buttons that go in its action area have response codes such as ResponseType::Accept and ResponseType::Cancel. For example, you could call gtk_file_chooser_dialog_new() as follows:

GtkWidget *dialog;
GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN;

dialog = gtk_file_chooser_dialog_new ("Open File",
                                      parent_window,
                                      action,
                                      _("_Cancel"),
                                      GTK_RESPONSE_CANCEL,
                                      _("_Open"),
                                      GTK_RESPONSE_ACCEPT,
                                      NULL);

This will create buttons for “Cancel” and “Open” that use stock response identifiers from ResponseType. For most dialog boxes you can use your own custom response codes rather than the ones in ResponseType, but FileChooserDialog assumes that its “accept”-type action, e.g. an “Open” or “Save” button, will have one of the following response codes:

• ResponseType::Accept
• ResponseType::Ok
• ResponseType::Yes
• ResponseType::Apply

This is because FileChooserDialog must intercept responses and switch to folders if appropriate, rather than letting the dialog terminate — the implementation uses these known response codes to know which responses can be blocked if appropriate.

To summarize, make sure you use a [stock response code][gtkfilechooserdialog-responses] when you use FileChooserDialog to ensure proper operation.

Implements

DialogExt, GtkWindowExt, BinExt, ContainerExt, WidgetExt, glib::ObjectExt, BuildableExt, FileChooserExt, DialogExtManual, [GtkWindowExtManual][trait@crate::prelude::GtkWindowExtManual], ContainerExtManual, WidgetExtManual, BuildableExtManual, FileChooserExtManual

Implementations

impl FileChooserDialog

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

pub fn builder() -> FileChooserDialogBuilder

Creates a new builder-pattern struct instance to construct FileChooserDialog objects.

This method returns an instance of FileChooserDialogBuilder which can be used to create FileChooserDialog objects.

impl FileChooserDialog

pub fn new<T: IsA<Window>>(
    title: Option<&str>,
    parent: Option<&T>,
    action: FileChooserAction
) -> FileChooserDialog

Creates a new FileChooserDialog. This function is analogous to gtk_dialog_new_with_buttons().

title

Title of the dialog, or None

parent

Transient parent of the dialog, or None

action

Open or save mode for the dialog

first_button_text

stock ID or text to go in the first button, or None

Returns

a new FileChooserDialog

pub fn with_buttons<T: IsA<Window>>(
    title: Option<&str>,
    parent: Option<&T>,
    action: FileChooserAction,
    buttons: &[(&str, ResponseType)]
) -> FileChooserDialog

Trait Implementations

impl Clone for FileChooserDialog

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 FileChooserDialog

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

Formats the value using the given formatter.

impl Default for FileChooserDialog

fn default() -> Self

Returns the “default value” for a type.

impl Display for FileChooserDialog

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

Formats the value using the given formatter.

impl Hash for FileChooserDialog

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 FileChooserDialog

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 ParentClassIs for FileChooserDialog

type Parent = Dialog

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

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 FileChooserDialog

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 FileChooserDialog

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for FileChooserDialog

impl IsA<Bin> for FileChooserDialog

impl IsA<Buildable> for FileChooserDialog

impl IsA<Container> for FileChooserDialog

impl IsA<Dialog> for FileChooserDialog

impl IsA<FileChooser> for FileChooserDialog

impl IsA<Widget> for FileChooserDialog

impl IsA<Window> for FileChooserDialog