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:

[legend]

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

FileChooser&	operator= (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::ListModel >	get_files ()
	Lists all the selected files and subfolders in the current folder of chooser as Gio::File. More...

Glib::RefPtr< const Gio::ListModel >	get_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::File >	get_current_folder ()
	Gets the current folder of chooser as Gio::File. More...

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

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

Glib::RefPtr< const Gio::File >	get_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::ListModel >	get_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< FileFilter >	get_filter ()
	Gets the current filter; see set_filter(). More...

Glib::RefPtr< const FileFilter >	get_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::ListModel >	get_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< Action >	property_action ()
	The type of operation that the file selector is performing. More...

Glib::PropertyProxy_ReadOnly< Action >	property_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

Interface &	operator= (Interface &&src) noexcept

	Interface (const Glib::Interface_Class &interface_class)

	Interface (GObject *castitem)

	~Interface () noexcept override

	Interface (const Interface &)=delete

Interface &	operator= (const Interface &)=delete

GObject *	gobj ()

const GObject *	gobj () const

Public Member Functions inherited from Glib::ObjectBase
	ObjectBase (const ObjectBase &)=delete

ObjectBase &	operator= (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 ()

trackable &	operator= (const trackable &src)

trackable &	operator= (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

ObjectBase &	operator= (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::FileChooser >	wrap (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

id	Id for the added choice.
label	User-visible label for the added choice.
options	Ids for the options of the choice, or `nullptr` for a boolean choice.
option_labels	User-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

id	Id for the added choice.
label	User-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

filter A 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

folder A 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

id	The 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

id	The 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

filter A 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

folder A 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

action The 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

id	The ID of the choice to set.
option	The 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_folders true 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

file	The 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

name	The 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

file	The 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

filter A 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_multiple true if multiple files can be selected.

Friends And Related Function Documentation

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

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

Parameters

object	The C instance.
take_copy	False 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.

gtkmm: Gtk::FileChooser Class Reference

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Related Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation