A dialog designed to allow the user to navigate a filesytem and select or create one or more files or folders that match a criteria. More...

Inheritance diagram for FileChooserDialog:

[legend]

Collaboration diagram for FileChooserDialog:

[legend]

Public Types
enum	DisplayMode { e_browser , e_recents , e_favorites }
	Enumerates the display modes available in the file chooser dialog. More...

Public Member Functions
	FileChooserDialog (bool save_dialog=false, QWidget *parent=nullptr)
	Constructs a FileChooserDialog.
	FileChooserDialog (const File &ini_location, bool save_dialog=false, QWidget *parent=nullptr)
	Constructs a FileChooserDialog with a custom INI settings location.
TranslatedString	actionName () const
	Returns the action name displayed on the accept button (e.g., "Open" or "Save").
void	addToRecents (const Buffer< File > &files)
	Adds multiple files to the recents list.
void	addToRecents (const File &file, bool update_display)
	Adds a single file to the recents list.
void	autoHideDialog (PopupInfo info=PopupInfo())
	Hides the dialog using the most appropriate method for the current platform.
void	autoShowDialog (PopupInfo info=PopupInfo())
	Shows the dialog using the most appropriate method for the current platform.
void	browseFile (PopupInfo popup_origin=PopupInfo())
	Opens a native file browse dialog.
const File &	currentDirectory () const
	Returns the current browsing directory.
bool	event (QEvent *e) override
	Handles events for the dialog.
void	finishedSignal ()
	Emitted when the dialog finishes with a selection.
void	finishReadingINI (INIFactory &factory) override
	Called after reading dialog state from INI to finalize initialization.
Buffer< File >	getSelected () const
	Returns the list of files currently selected by the user.
const Buffer< FileRequest > &	getSelectedRequests () const
	Returns the selected file requests, including format information.
bool	isFolderBrowser () const
	Returns whether this dialog is configured to browse for folders only.
bool	isSaveDialog () const
	Returns whether this dialog is configured for saving files.
void	onCanceledSignal ()
	Emitted when the user cancels the dialog.
void	onFileChosenSignal ()
	Emitted when a file has been chosen by the user.
void	prepareForINI (INIFactory &factory) override
	Prepares dialog state for writing to INI.
const Buffer< UUID > &	saveContent () const
	Returns the UUIDs of content to be saved.
void	selectFileNameField ()
	Selects and focuses the file name input field.
void	setActionName (const TranslatedString &action_name)
	Sets the action name displayed on the accept button.
void	setAdditionalFavorites (Buffer< File > favorites)
	Sets additional directories to appear in the favorites list.
void	setAllowAny (bool allow_any)
	Sets whether any file type is allowed regardless of filter.
void	setCanReadCallback (const std::function< bool(const FileFormat &, const File &)> &callback)
	Sets a callback to determine if a file can be read with a given format.
void	setCurrentDirectory (const File &current_directory)
	Sets the current browsing directory.
void	setCurrentExtension (const StringView &extension, bool update_format_to_first_match)
	Sets the current file extension filter.
void	setCurrentFile (const File &file)
	Sets the current file, updating both directory and file name.
void	setCurrentFileName (const StringView &name)
	Sets the current file name in the name field.
void	setFallbackDirectory (const File &file)
	Sets a fallback directory to use when the current directory is invalid.
void	setIconProvider (const std::function< String(const FileRequest &)> &icon_provider)
	Sets a callback to provide custom icons for file requests.
void	setNativeParent (QWidget *native_parent)
	Sets the parent widget for native file dialogs.
void	setOptions (const Buffer< FileFormat > &extensions, bool save_dialog)
	Sets the available file formats and whether this is a save dialog.
void	setRecentPriorityModifiers (sint04 constant_modifier, fltp08 recent_priority_time_modifier)
	Allows adding weight to a file (changing extension listing order) based on how recently a file has been modified.
void	setSaveContent (const Buffer< UUID > &save_content)
	Sets the UUIDs of content to be saved.
void	setShowRecents (bool show_recent)
	Sets whether the recents section is available.
void	showAccessedTime (bool show_accessed_time)
	Sets whether the accessed time column is visible.
bool	showFavorites () const
	Returns whether the favorites section is shown.
void	showFileSize (bool show_modified_time)
	Sets whether the file size column is visible.
void	showModifiedTime (bool show_modified_time)
	Sets whether the modified time column is visible.
void	showRecents ()
	Switches the display mode to show recent files.
bool	showRecents () const
	Returns whether the recents section is shown.
QSize	sizeHint () const override
	Returns the recommended size for this dialog.
TranslatedString	windowTitle () const
	Returns the translated window title for this dialog.
Public Member Functions inherited from INIInterface
	INIInterface ()
	Constructs an INIInterface with no default INI file.
	INIInterface (const File &default_ini)
	Constructs an INIInterface with the specified default INI file.
virtual	~INIInterface ()
	Virtual destructor for safe polymorphic cleanup.
virtual bool	readINIOptions ()
	Reads INI options from the default INI file.
virtual bool	readINIOptions (File &ini_file)
	Reads INI options from the specified INI file.
virtual bool	saveINIOptions (bool multithead=false)
	Saves INI options to the default INI file.
virtual bool	saveINIOptions (File &ini_file, bool multithead=false)
	Saves INI options to the specified INI file.
void	setDefaultINIFile (const File &file)
	Sets the default INI file path used for reading and writing options.
virtual void	writeToLog (const StringView &title, LogPtr log, uint01 log_level=2U)
	Writes the current INI options to the specified log with a title.
virtual void	writeToLog (LogPtr log, uint01 log_level=2U)
	Writes the current INI options to the specified log.

Static Public Member Functions
static void	SaveFileContent (File file)
	Saves file content associated with the given file.

Protected Member Functions
void	addItem (ButtonGallery gallery, QCustomTableWidget table, uint04 index, const File &item)
	Adds a file item to both the gallery and table views.
void	autoSelectFavoritesItem ()
	Automatically selects a favorites item based on the current directory.
void	browseFileNative ()
	Opens a native OS file browse dialog.
bool	checkFileAgainstFilter (const File &file, const FileFormat &selected_format) const
	Checks whether a file matches the given format filter.
void	clearRecents ()
	Clears all entries from the recents list.
QWidget *	createBottomPanel ()
	Creates the bottom panel with accept/cancel buttons and file name input.
QWidget *	createfavoritesPanel ()
	Creates the favorites side panel.
QWidget *	createNavigationButtons ()
	Creates the navigation button bar (back, up, favorites, etc.).
QWidget *	createRequestWidget (File item)
	Creates a widget representing a single file request entry.
const Buffer< File > &	currentDirectoryFiles () const
	Returns the cached list of files in the current directory.
FileFormat	currentSelectedFormat () const
	Returns the currently selected file format from the format combo box.
String	extensionsString (const StringView &delimiter=";;") const
	Builds a string of all supported extensions joined by the given delimiter.
const Buffer< File >	favoriteFiles () const
	Returns the list of favorite files and directories.
Buffer< File >	filterFiles (const Buffer< File > &all_files) const
	Filters a list of files according to the current format selection.
void	finishBrowse ()
	Finalizes the browse operation after the user makes a selection.
FileFormat	getFileFormat (const File &file)
	Determines the file format for a given file.
FileFormat	getFileFormat (const StringView &file, const StringView &string) const
	Determines the file format from a file path and a filter string.
FileFormat	getFileFormatFromExtension (const StringView &ext) const
	Determines the file format from a file extension string.
void	hidePopupDialog ()
	Hides the popup dialog if it is currently shown.
void	onFileChosen (File file)
	Called when the user has chosen a file to process the selection.
void	postResolveIcons ()
	Finalizes icon resolution after background icon loading completes.
void	removeFromRecents (File item)
	Removes a file from the recents list.
void	retranslate ()
	Retranslates all user-visible text in the dialog.
void	setAndSortFormats (const Buffer< FileFormat > &formats)
	Assigns and sorts the available file formats by priority.
void	setIsFileChooser (bool is_file_chooser)
	Sets whether this dialog is choosing files (true) or folders (false).
QWidget *	settingsDialog ()
	Creates and returns the settings dialog widget.
void	setup ()
	Performs initial setup of all dialog widgets and layout.
void	SetupForBrowser ()
	Sets up the dialog UI for filesystem browsing mode.
void	SetupForFavorites ()
	Sets up the dialog UI for favorites mode.
void	updateBrowserWidgets ()
	Refreshes the file browser widgets with current directory content.
void	updateGallery (Button *b)
	Updates the gallery display when a button is selected.
void	updateTableIconSize (QCustomTableWidget *table)
	Updates the icon size in the given table to match the current settings.

Protected Attributes
bool	m_allow_any
	Whether any file type is accepted regardless of filter.
bool	m_needs_to_update = false
	Flag indicating that the file list needs refreshing.
Buffer< FileRequest >	m_selected_files
	The currently selected file requests.
Protected Attributes inherited from INIInterface
File	m_default_ini
	The default file path used for reading and writing INI options.

Private Member Functions
virtual void	getINI (INIFactory &factory) override
	Reads or writes dialog settings from/to an INI factory.

Detailed Description

A dialog designed to allow the user to navigate a filesytem and select or create one or more files or folders that match a criteria.

Supports browsing the filesystem using a native dialog or in touch mode a touch-friendly dialog. Also supports favorites and recents when available.

See also: File, ModelFactory, IOFactory

Definition at line 80 of file FileChooserDialog.h.

Member Enumeration Documentation

◆ DisplayMode

enum FileChooserDialog::DisplayMode

Enumerates the display modes available in the file chooser dialog.

Enumerator
e_browser	Browse the filesystem directly.
e_recents	Show recently accessed files.
e_favorites	Show favorited files and directories.

Definition at line 90 of file FileChooserDialog.h.

Constructor & Destructor Documentation

◆ FileChooserDialog() [1/2]

FileChooserDialog::FileChooserDialog	(	bool	save_dialog = false,
		QWidget *	parent = nullptr )

Constructs a FileChooserDialog.

Parameters

[in]	save_dialog	Whether this dialog is for saving (true) or opening (false).
[in]	parent	The parent widget.

Referenced by FileChooserDialog().

◆ FileChooserDialog() [2/2]

FileChooserDialog::FileChooserDialog	(	const File &	ini_location,
		bool	save_dialog = false,
		QWidget *	parent = nullptr )

Constructs a FileChooserDialog with a custom INI settings location.

Parameters

[in]	ini_location	The file path to load/save dialog settings.
[in]	save_dialog	Whether this dialog is for saving (true) or opening (false).
[in]	parent	The parent widget.

References FileChooserDialog().

Member Function Documentation

◆ actionName()

TranslatedString FileChooserDialog::actionName ( ) const

Returns the action name displayed on the accept button (e.g., "Open" or "Save").

Returns: The translated action name.

◆ addToRecents() [1/2]

void FileChooserDialog::addToRecents ( const Buffer< File > & files )

Adds multiple files to the recents list.

Parameters

[in] files The files to add to recents.

◆ addToRecents() [2/2]

void FileChooserDialog::addToRecents	(	const File &	file,
		bool	update_display )

Adds a single file to the recents list.

Parameters

[in]	file	The file to add to recents.
[in]	update_display	Whether to refresh the display immediately.

◆ autoHideDialog()

void FileChooserDialog::autoHideDialog ( PopupInfo info = PopupInfo() )

Hides the dialog using the most appropriate method for the current platform.

Parameters

[in] info Popup configuration info.

◆ autoShowDialog()

void FileChooserDialog::autoShowDialog ( PopupInfo info = PopupInfo() )

Shows the dialog using the most appropriate method for the current platform.

Parameters

[in] info Popup configuration info.

◆ browseFile()

void FileChooserDialog::browseFile ( PopupInfo popup_origin = PopupInfo() )

Opens a native file browse dialog.

Parameters

[in] popup_origin Optional popup origin info for positioning.

◆ currentDirectory()

const File & FileChooserDialog::currentDirectory ( ) const

inline

Returns the current browsing directory.

Returns: A reference to the current directory.

Definition at line 296 of file FileChooserDialog.h.

◆ event()

bool FileChooserDialog::event ( QEvent * e )

override

Handles events for the dialog.

Parameters

[in] e The event to process.

Returns: True if the event was handled.

◆ finishReadingINI()

void FileChooserDialog::finishReadingINI ( INIFactory & factory )

overridevirtual

Called after reading dialog state from INI to finalize initialization.

Parameters

[in] factory The INI factory that was read from.

Reimplemented from INIInterface.

◆ getSelected()

Buffer< File > FileChooserDialog::getSelected ( ) const

Returns the list of files currently selected by the user.

Returns: A buffer of selected File objects.

◆ getSelectedRequests()

const Buffer< FileRequest > & FileChooserDialog::getSelectedRequests ( ) const

Returns the selected file requests, including format information.

Returns: A reference to the buffer of selected FileRequest objects.

◆ isFolderBrowser()

bool FileChooserDialog::isFolderBrowser ( ) const

Returns whether this dialog is configured to browse for folders only.

Returns: True if this is a folder browser.

◆ isSaveDialog()

bool FileChooserDialog::isSaveDialog ( ) const

inline

Returns whether this dialog is configured for saving files.

Returns: True if this is a save dialog.

Definition at line 150 of file FileChooserDialog.h.

◆ prepareForINI()

void FileChooserDialog::prepareForINI ( INIFactory & factory )

overridevirtual

Prepares dialog state for writing to INI.

Parameters

[in] factory The INI factory to write to.

Reimplemented from INIInterface.

◆ saveContent()

const Buffer< UUID > & FileChooserDialog::saveContent ( ) const

inline

Returns the UUIDs of content to be saved.

Returns: A reference to the buffer of save content UUIDs.

Definition at line 170 of file FileChooserDialog.h.

◆ SaveFileContent()

void FileChooserDialog::SaveFileContent ( File file )

static

Saves file content associated with the given file.

Parameters

[in] file The file whose content should be saved.

◆ setActionName()

void FileChooserDialog::setActionName ( const TranslatedString & action_name )

Sets the action name displayed on the accept button.

Parameters

[in] action_name The translated action name to display.

◆ setAdditionalFavorites()

void FileChooserDialog::setAdditionalFavorites ( Buffer< File > favorites )

Sets additional directories to appear in the favorites list.

Parameters

[in] favorites The buffer of favorite directories to add.

◆ setAllowAny()

void FileChooserDialog::setAllowAny ( bool allow_any )

inline

Sets whether any file type is allowed regardless of filter.

Parameters

[in] allow_any True to allow any file type.

Definition at line 145 of file FileChooserDialog.h.

References m_allow_any.

◆ setCanReadCallback()

void FileChooserDialog::setCanReadCallback ( const std::function< bool(const FileFormat &, const File &)> & callback )

Sets a callback to determine if a file can be read with a given format.

Parameters

[in] callback A function returning true if the file is readable with the format.

◆ setCurrentDirectory()

void FileChooserDialog::setCurrentDirectory ( const File & current_directory )

Sets the current browsing directory.

Parameters

[in] current_directory The directory to navigate to.

◆ setCurrentExtension()

void FileChooserDialog::setCurrentExtension	(	const StringView &	extension,
		bool	update_format_to_first_match )

Sets the current file extension filter.

Parameters

[in]	extension	The extension to set.
[in]	update_format_to_first_match	Whether to update the format combo to the first matching format.

◆ setCurrentFile()

void FileChooserDialog::setCurrentFile ( const File & file )

Sets the current file, updating both directory and file name.

Parameters

[in] file The file to set as current.

◆ setCurrentFileName()

void FileChooserDialog::setCurrentFileName ( const StringView & name )

Sets the current file name in the name field.

Parameters

[in] name The file name to display.

◆ setFallbackDirectory()

void FileChooserDialog::setFallbackDirectory ( const File & file )

Sets a fallback directory to use when the current directory is invalid.

Parameters

[in] file The fallback directory path.

◆ setIconProvider()

void FileChooserDialog::setIconProvider ( const std::function< String(const FileRequest &)> & icon_provider )

Sets a callback to provide custom icons for file requests.

Parameters

[in] icon_provider A function returning an icon ID for a given FileRequest.

◆ setNativeParent()

void FileChooserDialog::setNativeParent ( QWidget * native_parent )

Sets the parent widget for native file dialogs.

Parameters

[in] native_parent The parent widget for native dialogs.

◆ setOptions()

void FileChooserDialog::setOptions	(	const Buffer< FileFormat > &	extensions,
		bool	save_dialog )

Sets the available file formats and whether this is a save dialog.

Parameters

[in]	extensions	The file formats to offer as filter options.
[in]	save_dialog	Whether this dialog is for saving.

◆ setRecentPriorityModifiers()

void FileChooserDialog::setRecentPriorityModifiers	(	sint04	constant_modifier,
		fltp08	recent_priority_time_modifier )

Allows adding weight to a file (changing extension listing order) based on how recently a file has been modified.

Parameters

constant_modifier	This is a constant value added if the file has been saved/opened by this dialog
recent_priority_time_modifier	to modify priority based on time with [value] / (hours since modified)

◆ setSaveContent()

void FileChooserDialog::setSaveContent ( const Buffer< UUID > & save_content )

inline

Sets the UUIDs of content to be saved.

Parameters

[in] save_content The buffer of UUIDs representing content to save.

Definition at line 165 of file FileChooserDialog.h.

◆ setShowRecents()

void FileChooserDialog::setShowRecents ( bool show_recent )

Sets whether the recents section is available.

Parameters

[in] show_recent Whether to show the recents section.

◆ showAccessedTime()

void FileChooserDialog::showAccessedTime ( bool show_accessed_time )

Sets whether the accessed time column is visible.

Parameters

[in] show_accessed_time Whether to show accessed time.

◆ showFavorites()

bool FileChooserDialog::showFavorites ( ) const

Returns whether the favorites section is shown.

Returns: True if favorites are shown.

◆ showFileSize()

void FileChooserDialog::showFileSize ( bool show_modified_time )

Sets whether the file size column is visible.

Parameters

[in] show_modified_time Whether to show file size.

◆ showModifiedTime()

void FileChooserDialog::showModifiedTime ( bool show_modified_time )

Sets whether the modified time column is visible.

Parameters

[in] show_modified_time Whether to show modified time.

◆ showRecents()

bool FileChooserDialog::showRecents ( ) const

inline

Returns whether the recents section is shown.

Returns: True if recents are shown.

Definition at line 222 of file FileChooserDialog.h.

◆ sizeHint()

QSize FileChooserDialog::sizeHint ( ) const

override

Returns the recommended size for this dialog.

Returns: The preferred size hint.

◆ windowTitle()

TranslatedString FileChooserDialog::windowTitle ( ) const

Returns the translated window title for this dialog.

Returns: The window title.

The documentation for this class was generated from the following file:

Widgets/Headers/FileChooserDialog.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Member Enumeration Documentation

◆ DisplayMode

Constructor & Destructor Documentation

◆ FileChooserDialog() [1/2]

◆ FileChooserDialog() [2/2]

Member Function Documentation

◆ actionName()

◆ addToRecents() [1/2]

◆ addToRecents() [2/2]

◆ autoHideDialog()

◆ autoShowDialog()

◆ browseFile()

◆ currentDirectory()

◆ event()

◆ finishReadingINI()

◆ getSelected()

◆ getSelectedRequests()

◆ isFolderBrowser()

◆ isSaveDialog()

◆ prepareForINI()

◆ saveContent()

◆ SaveFileContent()

◆ setActionName()

◆ setAdditionalFavorites()

◆ setAllowAny()

◆ setCanReadCallback()

◆ setCurrentDirectory()

◆ setCurrentExtension()

◆ setCurrentFile()

◆ setCurrentFileName()

◆ setFallbackDirectory()

◆ setIconProvider()

◆ setNativeParent()

◆ setOptions()

◆ setRecentPriorityModifiers()

◆ setSaveContent()

◆ setShowRecents()

◆ showAccessedTime()

◆ showFavorites()

◆ showFileSize()

◆ showModifiedTime()

◆ showRecents()

◆ sizeHint()

◆ windowTitle()