gtkmm: Gtk::FileChooser Class Reference

File chooser interface used by Gtk::FileChooserWidget and Gtk::FileChooserDialog. More...

#include <gtkmm/filechooser.h>

Inheritance diagram for Gtk::FileChooser:

Public Types

enum  Action {

  Action::OPEN,

  Action::SAVE,

  Action::SELECT_FOLDER

}
 Describes whether a Gtk::FileChooser is being used to open existing files or to save to a possibly new file. More...

 
- Public Types inherited from sigc::trackable
typedef internal::func_destroy_notify func_destroy_notify
 
- Public Types inherited from sigc::notifiable
typedef internal::func_destroy_notify func_destroy_notify
 

Public Member Functions

 FileChooser (FileChooser&& src) noexcept
 
FileChooseroperator= (FileChooser&& src) noexcept
 
 ~FileChooser () noexcept override
 
GtkFileChooser* gobj ()
 Provides access to the underlying C GObject. More...

 
const GtkFileChooser* gobj () const
 Provides access to the underlying C GObject. More...

 
void set_action (Action action)
 Sets the type of operation that the chooser is performing; the user interface is adapted to suit the selected action. More...

 
Action get_action () const
 Gets the type of operation that the file chooser is performing; see set_action(). More...

 
void set_select_multiple (bool select_multiple=true)
 Sets whether multiple files can be selected in the file selector. More...

 
bool get_select_multiple () const
 Gets whether multiple files can be selected in the file selector. More...

 
void set_create_folders (bool create_folders=true)
 Sets whether file chooser will offer to create new folders. More...

 
bool get_create_folders () const
 Gets whether file chooser will offer to create new folders. More...

 
void set_current_name (const Glib::ustring& name)
 Sets the current name in the file selector, as if entered by the user. More...

 
Glib::ustring get_current_name () const
 Gets the current name in the file selector, as entered by the user in the text entry for “Name”. More...

 
bool set_file (const Glib::RefPtr< const Gio::File >& file)
 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. More...

 
Glib::RefPtr< Gio::ListModelget_files ()
 Lists all the selected files and subfolders in the current folder of chooser as Gio::File. More...

 
Glib::RefPtr< const Gio::ListModelget_files () const
 Lists all the selected files and subfolders in the current folder of chooser as Gio::File. More...

 
bool set_current_folder (const Glib::RefPtr< const Gio::File >& file)
 Sets the current folder for chooser from a Gio::File. More...

 
Glib::RefPtr< Gio::Fileget_current_folder ()
 Gets the current folder of chooser as Gio::File. More...

 
Glib::RefPtr< const Gio::Fileget_current_folder () const
 Gets the current folder of chooser as Gio::File. More...

 
Glib::RefPtr< Gio::Fileget_file ()
 Gets the Gio::File for the currently selected file in the file selector. More...

 
Glib::RefPtr< const Gio::Fileget_file () const
 Gets the Gio::File for the currently selected file in the file selector. More...

 
void add_filter (const Glib::RefPtr< FileFilter >& filter)
 Adds filter to the list of filters that the user can select between. More...

 
void remove_filter (const Glib::RefPtr< FileFilter >& filter)
 Removes filter from the list of filters that the user can select between. More...

 
Glib::RefPtr< const Gio::ListModelget_filters () const
 Gets the current set of user-selectable filters, as a list model; see add_filter(), remove_filter(). More...

 
void set_filter (const Glib::RefPtr< FileFilter >& filter)
 Sets the current filter; only the files that pass the filter will be displayed. More...

 
Glib::RefPtr< FileFilterget_filter ()
 Gets the current filter; see set_filter(). More...

 
Glib::RefPtr< const FileFilterget_filter () const
 Gets the current filter; see set_filter(). More...

 
bool add_shortcut_folder (const Glib::RefPtr< Gio::File >& folder)
 Adds a folder to be displayed with the shortcut folders in a file chooser. More...

 
bool remove_shortcut_folder (const Glib::RefPtr< Gio::File >& folder)
 Removes a folder from the shortcut folders in a file chooser. More...

 
Glib::RefPtr< const Gio::ListModelget_shortcut_folders () const
 Queries the list of shortcut folders in the file chooser, as set by add_shortcut_folder(). More...

 
void add_choice (const Glib::ustring& id, const Glib::ustring& label, const std::vector< Glib::ustring >& options, const std::vector< Glib::ustring >& option_labels)
 Adds a 'choice' to the file chooser. More...

 
void add_choice (const Glib::ustring& id, const Glib::ustring& label)
 Adds a boolean 'choice' to the file chooser. More...

 
void remove_choice (const Glib::ustring& id)
 Removes a 'choice' that has been added with add_choice(). More...

 
void set_choice (const Glib::ustring& id, const Glib::ustring& option)
 Selects an option in a 'choice' that has been added with add_choice(). More...

 
Glib::ustring get_choice (const Glib::ustring& id) const
 Gets the currently selected option in the 'choice' with the given ID. More...

 
Glib::PropertyProxy< Actionproperty_action ()
 The type of operation that the file selector is performing. More...

 
Glib::PropertyProxy_ReadOnly< Actionproperty_action () const
 The type of operation that the file selector is performing. More...

 
Glib::PropertyProxy< Glib::RefPtr< FileFilter > > property_filter ()
 The current filter for selecting which files are displayed. More...

 
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< FileFilter > > property_filter () const
 The current filter for selecting which files are displayed. More...

 
Glib::PropertyProxy< bool > property_select_multiple ()
 Whether to allow multiple files to be selected. More...

 
Glib::PropertyProxy_ReadOnly< bool > property_select_multiple () const
 Whether to allow multiple files to be selected. More...

 
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Gio::ListModel > > property_filters () const
 A ListModel containing the filters that have been added with Gtk::FileChooser::add_filter(). More...

 
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Gio::ListModel > > property_shortcut_folders () const
 A ListModel containing the shortcut folders that have been added with Gtk::FileChooser::add_shortcut_folder(). More...

 
Glib::PropertyProxy< bool > property_create_folders ()
 Whether a file chooser not in Gtk::FileChooser::Action::OPEN mode will offer the user to create new folders. More...

 
Glib::PropertyProxy_ReadOnly< bool > property_create_folders () const
 Whether a file chooser not in Gtk::FileChooser::Action::OPEN mode will offer the user to create new folders. More...

 
- Public Member Functions inherited from Glib::Interface
 Interface ()
 
 Interface (Interface &&src) noexcept
 
Interfaceoperator= (Interface &&src) noexcept
 
 Interface (const Glib::Interface_Class &interface_class)
 
 Interface (GObject *castitem)
 
 ~Interface () noexcept override
 
 Interface (const Interface &)=delete
 
Interfaceoperator= (const Interface &)=delete
 
GObject * gobj ()
 
const GObject * gobj () const
 
- Public Member Functions inherited from Glib::ObjectBase
 ObjectBase (const ObjectBase &)=delete
 
ObjectBaseoperator= (const ObjectBase &)=delete
 
void set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
 
void get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
 
void set_property (const Glib::ustring &property_name, const PropertyType &value)
 
void get_property (const Glib::ustring &property_name, PropertyType &value) const
 
PropertyType get_property (const Glib::ustring &property_name) const
 
sigc::connection connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void()> &slot)
 
sigc::connection connect_property_changed (const Glib::ustring &property_name, sigc::slot< void()> &&slot)
 
void freeze_notify ()
 
void thaw_notify ()
 
virtual void reference () const
 
virtual void unreference () const
 
GObject * gobj ()
 
const GObject * gobj () const
 
GObject * gobj_copy () const
 
- Public Member Functions inherited from sigc::trackable
 trackable () noexcept
 
 trackable (const trackable &src) noexcept
 
 trackable (trackable &&src) noexcept
 
 ~trackable ()
 
void add_destroy_notify_callback (notifiable *data, func_destroy_notify func) const
 
void notify_callbacks ()
 
trackableoperator= (const trackable &src)
 
trackableoperator= (trackable &&src) noexcept
 
void remove_destroy_notify_callback (notifiable *data) const
 

Static Public Member Functions

static void add_interface (GType gtype_implementer)
 
static GType get_type ()
 Get the GType for this class, for use with the underlying GObject type system. More...

 

Protected Member Functions

 FileChooser ()
 You should derive from this class to use it. More...

 
- Protected Member Functions inherited from Glib::ObjectBase
 ObjectBase ()
 
 ObjectBase (const char *custom_type_name)
 
 ObjectBase (const std::type_info &custom_type_info)
 
 ObjectBase (ObjectBase &&src) noexcept
 
ObjectBaseoperator= (ObjectBase &&src) noexcept
 
virtual ~ObjectBase () noexcept=0
 
void initialize (GObject *castitem)
 
void initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)
 

Related Functions

(Note that these are not member functions.)

Glib::RefPtr< Gtk::FileChooserwrap (GtkFileChooser* object, bool take_copy=false)
 A Glib::wrap() method for this object. More...

 

Detailed Description

File chooser interface used by Gtk::FileChooserWidget and Gtk::FileChooserDialog.

Gtk::FileChooser is an interface that can be implemented by file selection widgets. In gtkmm, the main objects that implement this interface are FileChooserWidget and FileChooserDialog. 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.

Gtk::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
When the user is finished selecting files in a Gtk::FileChooser, your program can get the selected filenames as Gio::File objects.
Adding Options
You can add extra widgets to a file chooser to provide options that are not present in the default design, by using add_choice(). Each choice has an identifier and a user visible label; additionally, each choice can have multiple options. If a choice has no option, it will be rendered as a check button with the given label; if a choice has options, it will be rendered as a combo box.

Constructor & Destructor Documentation

Gtk::FileChooser::FileChooser ( )
protected

You should derive from this class to use it.

Gtk::FileChooser::FileChooser ( FileChooser&&  src)
noexcept
Gtk::FileChooser::~FileChooser ( )
overridenoexcept

Member Function Documentation

void Gtk::FileChooser::add_choice ( const Glib::ustring id,
const Glib::ustring label,
const std::vector< Glib::ustring > &  options,
const std::vector< Glib::ustring > &  option_labels 
)

Adds a 'choice' to the file chooser.

This is typically implemented as a combobox or, for boolean choices, as a checkbutton. You can select a value using set_choice() before the dialog is shown, and you can obtain the user-selected value in the signal_response() signal handler using get_choice().

Parameters
idId for the added choice.
labelUser-visible label for the added choice.
optionsIds for the options of the choice, or nullptr for a boolean choice.
option_labelsUser-visible labels for the options, must be the same length as options.
void Gtk::FileChooser::add_choice ( const Glib::ustring id,
const Glib::ustring label 
)

Adds a boolean 'choice' to the file chooser.

This is typically implemented as a checkbutton. You can select a value using set_boolean_choice() before the dialog is shown, and you can obtain the user-selected value in the signal_response() signal handler using get_choice().

Compare set_extra_widget().

Since gtkmm 3.22:
Parameters
idId for the added choice.
labelUser-visible label for the added choice.
void Gtk::FileChooser::add_filter ( const Glib::RefPtr< FileFilter >&  filter)

Adds filter to the list of filters that the user can select between.

When a filter is selected, only files that are passed by that filter are displayed.

Note that the chooser takes ownership of the filter if it is floating, so you have to ref and sink it if you want to keep a reference.

Parameters
filterA Gtk::FileFilter.
static void Gtk::FileChooser::add_interface ( GType  gtype_implementer)
static
bool Gtk::FileChooser::add_shortcut_folder ( const Glib::RefPtr< Gio::File > &  folder)

Adds a folder to be displayed with the shortcut folders in a file chooser.

Parameters
folderA Gio::File for the folder to add.
Returns
true if the folder could be added successfully, false otherwise.
Exceptions
Glib::Error
Action Gtk::FileChooser::get_action ( ) const

Gets the type of operation that the file chooser is performing; see set_action().

Returns
The action that the file selector is performing.
Glib::ustring Gtk::FileChooser::get_choice ( const Glib::ustring id) const

Gets the currently selected option in the 'choice' with the given ID.

Parameters
idThe ID of the choice to get.
Returns
The ID of the currently selected option.
bool Gtk::FileChooser::get_create_folders ( ) const

Gets whether file chooser will offer to create new folders.

See set_create_folders().

Returns
true if the Create Folder button should be displayed.
Glib::RefPtr<Gio::File> Gtk::FileChooser::get_current_folder ( )

Gets the current folder of chooser as Gio::File.

Returns
The full path of the current folder, possibly empty if the current path cannot be represented as a local filename. This function may also return an empty string if the file chooser was unable to load the last folder that was requested from it; for example, as would be for calling set_current_folder() on a nonexistent folder.
Glib::RefPtr<const Gio::File> Gtk::FileChooser::get_current_folder ( ) const

Gets the current folder of chooser as Gio::File.

Returns
The full path of the current folder, possibly empty if the current path cannot be represented as a local filename. This function may also return an empty string if the file chooser was unable to load the last folder that was requested from it; for example, as would be for calling set_current_folder() on a nonexistent folder.
Glib::ustring Gtk::FileChooser::get_current_name ( ) const

Gets the current name in the file selector, as entered by the user in the text entry for “Name”.

This is meant to be used in save dialogs, to get the currently typed filename when the file itself does not exist yet.

Returns
The raw text from the file chooser’s “Name” entry. Note that this string is not a full pathname or URI; it is whatever the contents of the entry are. Note also that this string is in UTF-8 encoding, which is not necessarily the system’s encoding for filenames.
Glib::RefPtr<Gio::File> Gtk::FileChooser::get_file ( )

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

Returns
A selected Gio::File. You own the returned file; use Glib::object_unref() to release it.
Glib::RefPtr<const Gio::File> Gtk::FileChooser::get_file ( ) const

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

Returns
A selected Gio::File. You own the returned file; use Glib::object_unref() to release it.
Glib::RefPtr<Gio::ListModel> Gtk::FileChooser::get_files ( )

Lists all the selected files and subfolders in the current folder of chooser as Gio::File.

Returns
A list model containing a Gio::File for each selected file and subfolder in the current folder. Free the returned list with Glib::object_unref().
Glib::RefPtr<const Gio::ListModel> Gtk::FileChooser::get_files ( ) const

Lists all the selected files and subfolders in the current folder of chooser as Gio::File.

Returns
A list model containing a Gio::File for each selected file and subfolder in the current folder. Free the returned list with Glib::object_unref().
Glib::RefPtr<FileFilter> Gtk::FileChooser::get_filter ( )

Gets the current filter; see set_filter().

Returns
The current filter, or nullptr.
Glib::RefPtr<const FileFilter> Gtk::FileChooser::get_filter ( ) const

Gets the current filter; see set_filter().

Returns
The current filter, or nullptr.
Glib::RefPtr<const Gio::ListModel> Gtk::FileChooser::get_filters ( ) const

Gets the current set of user-selectable filters, as a list model; see add_filter(), remove_filter().

You should not modify the returned list model. Future changes to chooser may or may not affect the returned model.

Returns
A ListModel containing the current set of user-selectable filters.
bool Gtk::FileChooser::get_select_multiple ( ) const

Gets whether multiple files can be selected in the file selector.

See set_select_multiple().

Returns
true if multiple files can be selected.
Glib::RefPtr<const Gio::ListModel> Gtk::FileChooser::get_shortcut_folders ( ) const

Queries the list of shortcut folders in the file chooser, as set by add_shortcut_folder().

You should not modify the returned list model. Future changes to chooser may or may not affect the returned model.

Returns
A list model of Files.
static GType Gtk::FileChooser::get_type ( )
static

Get the GType for this class, for use with the underlying GObject type system.

GtkFileChooser* Gtk::FileChooser::gobj ( )
inline

Provides access to the underlying C GObject.

const GtkFileChooser* Gtk::FileChooser::gobj ( ) const
inline

Provides access to the underlying C GObject.

FileChooser& Gtk::FileChooser::operator= ( FileChooser&&  src)
noexcept
Glib::PropertyProxy< Action > Gtk::FileChooser::property_action ( )

The type of operation that the file selector is performing.

Default value: Gtk::FileChooser::Action::OPEN

Returns
A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.
Glib::PropertyProxy_ReadOnly< Action > Gtk::FileChooser::property_action ( ) const

The type of operation that the file selector is performing.

Default value: Gtk::FileChooser::Action::OPEN

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
Glib::PropertyProxy< bool > Gtk::FileChooser::property_create_folders ( )

Whether a file chooser not in Gtk::FileChooser::Action::OPEN mode will offer the user to create new folders.

Default value: true

Returns
A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.
Glib::PropertyProxy_ReadOnly< bool > Gtk::FileChooser::property_create_folders ( ) const

Whether a file chooser not in Gtk::FileChooser::Action::OPEN mode will offer the user to create new folders.

Default value: true

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
Glib::PropertyProxy< Glib::RefPtr<FileFilter> > Gtk::FileChooser::property_filter ( )

The current filter for selecting which files are displayed.

Returns
A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.
Glib::PropertyProxy_ReadOnly< Glib::RefPtr<FileFilter> > Gtk::FileChooser::property_filter ( ) const

The current filter for selecting which files are displayed.

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Gio::ListModel> > Gtk::FileChooser::property_filters ( ) const

A ListModel containing the filters that have been added with Gtk::FileChooser::add_filter().

The returned object should not be modified. It may or may not be updated for later changes.

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
Glib::PropertyProxy< bool > Gtk::FileChooser::property_select_multiple ( )

Whether to allow multiple files to be selected.

Default value: false

Returns
A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.
Glib::PropertyProxy_ReadOnly< bool > Gtk::FileChooser::property_select_multiple ( ) const

Whether to allow multiple files to be selected.

Default value: false

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
Glib::PropertyProxy_ReadOnly< Glib::RefPtr<Gio::ListModel> > Gtk::FileChooser::property_shortcut_folders ( ) const

A ListModel containing the shortcut folders that have been added with Gtk::FileChooser::add_shortcut_folder().

The returned object should not be modified. It may or may not be updated for later changes.

Returns
A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.
void Gtk::FileChooser::remove_choice ( const Glib::ustring id)

Removes a 'choice' that has been added with add_choice().

Parameters
idThe ID of the choice to remove.
void Gtk::FileChooser::remove_filter ( const Glib::RefPtr< FileFilter >&  filter)

Removes filter from the list of filters that the user can select between.

Parameters
filterA Gtk::FileFilter.
bool Gtk::FileChooser::remove_shortcut_folder ( const Glib::RefPtr< Gio::File > &  folder)

Removes a folder from the shortcut folders in a file chooser.

Parameters
folderA Gio::File for the folder to remove.
Returns
true if the folder could be removed successfully, false otherwise.
Exceptions
Glib::Error
void Gtk::FileChooser::set_action ( Action  action)

Sets the type of operation that the chooser is performing; the user interface is adapted to suit the selected action.

For example, an option to create a new folder might be shown if the action is Gtk::FileChooser::Action::SAVE but not if the action is Gtk::FileChooser::Action::OPEN.

Parameters
actionThe action that the file selector is performing.
void Gtk::FileChooser::set_choice ( const Glib::ustring id,
const Glib::ustring option 
)

Selects an option in a 'choice' that has been added with add_choice().

For a boolean choice, the possible options are "true" and "false".

Parameters
idThe ID of the choice to set.
optionThe ID of the option to select.
void Gtk::FileChooser::set_create_folders ( bool  create_folders = true)

Sets whether file chooser will offer to create new folders.

This is only relevant if the action is not set to be Gtk::FileChooser::Action::OPEN.

Parameters
create_folderstrue if the Create Folder button should be displayed.
bool Gtk::FileChooser::set_current_folder ( const Glib::RefPtr< const Gio::File > &  file)

Sets the current folder for chooser from a Gio::File.

Parameters
fileThe Gio::File for the new folder.
Returns
true if the folder could be changed successfully, false otherwise.
Exceptions
Glib::Error
void Gtk::FileChooser::set_current_name ( const Glib::ustring name)

Sets the current name in the file selector, as if entered by the user.

Note that the name passed in here is a UTF-8 string rather than a filename. This function is meant for such uses as a suggested name in a “Save As...” dialog. You can pass “Untitled.doc” or a similarly suitable suggestion for the name.

If you want to preselect a particular existing file, you should use set_file() instead.

Please see the documentation for those functions for an example of using set_current_name() as well.

Parameters
nameThe filename to use, as a UTF-8 string.
bool Gtk::FileChooser::set_file ( const Glib::RefPtr< const Gio::File > &  file)

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::FileChooser::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.

Note that the file must exist, or nothing will be done except for the directory change.

If you are implementing a save 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 Save As... 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:

[C example ellipted]

Parameters
fileThe Gio::File to set as current.
Returns
Not useful.
Exceptions
Glib::Error
void Gtk::FileChooser::set_filter ( const Glib::RefPtr< FileFilter >&  filter)

Sets the current filter; only the files that pass the filter will be displayed.

If the user-selectable list of filters is non-empty, then the 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.

Parameters
filterA Gtk::FileFilter.
void Gtk::FileChooser::set_select_multiple ( bool  select_multiple = true)

Sets whether multiple files can be selected in the file selector.

This is only relevant if the action is set to be Gtk::FileChooser::Action::OPEN or Gtk::FileChooser::Action::SELECT_FOLDER.

Parameters
select_multipletrue if multiple files can be selected.

Friends And Related Function Documentation

Glib::RefPtr< Gtk::FileChooser > wrap ( GtkFileChooser *  object,
bool  take_copy = false 
)
related

A Glib::wrap() method for this object.

Parameters
objectThe C instance.
take_copyFalse if the result should take ownership of the C instance. True if it should take a new copy or ref.
Returns
A C++ instance that wraps this C instance.