An extension of the Qt Open/Save file dialog box. More...

#include <SUIT_FileDlg.h>

Inheritance diagram for SUIT_FileDlg:

Public Member Functions
	SUIT_FileDlg (QWidget *, bool, bool=true, bool=true)
	Constructor.
virtual	~SUIT_FileDlg ()
	Destructor.
bool	isOpenDlg () const
	Check if the dialog box is used for opening or saving the file.
bool	checkPermissions () const
	Get 'check file permissions' flag.
void	setCheckPermissions (const bool)
	Set 'check file permissions' flag.
SUIT_FileValidator *	validator () const
	Get file validator.
void	setValidator (SUIT_FileValidator *)
	Set file validator.
bool	addWidgets (QWidget , QWidget , QWidget *)
	Adds the specified widgets to the bottom of the file dialog.
QStringList	selectedFiles () const
	Get list of selected files.
QString	selectedFile () const
	Get selected file.
void	selectFile (const QString &)
	Selects current file.
Static Public Member Functions
static QString	getLastVisitedDirectory ()
	Get last visited directory.
static QString	getFileName (QWidget , const QString &, const QStringList &, const QString &=QString(), const bool=true, const bool=true, SUIT_FileValidator =0)
	Show dialog box for the file opening/saving.
static QString	getFileName (QWidget , const QString &, const QString &, const QString &=QString(), const bool=true, const bool=true, SUIT_FileValidator =0)
	Show dialog box for the file opening/saving.This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This method can be used to select the file for opening or saving. The behavior is defined by the open parameter. Note, that selection validation depends on the dialog mode used.
static QStringList	getOpenFileNames (QWidget , const QString &, const QStringList &, const QString &=QString(), const bool=true, SUIT_FileValidator =0)
	Show dialog box for the multiple files selection.
static QStringList	getOpenFileNames (QWidget , const QString &, const QString &, const QString &=QString(), const bool=true, SUIT_FileValidator =0)
	Show dialog box for the multiple file opening.This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. If initial parameter is not null string it is used as starting directory or file at which dialog box is opened.
static QString	getExistingDirectory (QWidget , const QString &, const QString &=QString(), const bool=true, SUIT_FileValidator =0)
	Show dialog box for the existing directory selection.
static QString	getLastVisitedPath ()
	Get last visited path.
Protected Slots
void	accept ()
	Called when the user presses "Open"or "Save" button.
void	quickDir (const QString &)
	Called when user selects directory from the "Quick Dir" combo box.
void	addQuickDir ()
	Called when user presses "Quick Dir Add" button.
Protected Member Functions
virtual bool	event (QEvent *)
	Customize events processing.
QLineEdit *	lineEdit () const
	Get line edit which is used to enter file name.
virtual bool	acceptData ()
	Validate user selection.
QString	addExtension (const QString &) const
	Add an extension to the specified file name.
bool	processPath (const QString &)
	Processes selection : tries to set specified sirectory or filename as current file dialog selection.
void	addFilter (const QString &)
	Add file filter and activates it.
Static Protected Member Functions
static bool	hasWildCards (const QString &)
	Check if the string contains wildcard symbols.
Private Member Functions
void	polish ()
	Polish the dialog box.
Private Attributes
SUIT_FileValidator *	myValidator
	file validator
QLabel *	myQuickLab
	quick dir combo box
QComboBox *	myQuickCombo
	quick dir combo box
QList< QUrl >	myUrls
	quick dir Sidebar Urls
QPushButton *	myQuickButton
	quick dir add button
bool	myCheckPermissions
	check permissions option
Static Private Attributes
static QString	myLastVisitedPath
	last visited path

Detailed Description

The class SUIT_FileDlg provides a set of static methods which canbe used for file or directories selection:

getFileName() for single file opening or saving
getOpenFileNames() for mulktiple files opening
getExistingDirectory() for existing directory selection

Examples:

  // select file to dump contents of the view
  QStringList filters;
  filters << "Image files (*.bmp *.gif *.jpg )" << "All files (*)";
  QString fileName = SUIT_FileDlg::getFileName( desktop(), 
                                                QString(), 
                                                filters, 
                                                "Dump view",
                                                false );
  if ( !fileName.isEmpty() ) {
    ... writing image to the file 
  }

  // select list of files to open in the editor windows
  QStringList filters;
  filters << "*.cpp | *.cxx | *.c++" << "*.h | *.hpp | *.hxx";
  QStringList fileNames = SUIT_FileDlg::getOpenFileName( desktop(),
                                                         QString(), 
                                                         filters, 
                                                         QString() );
  if ( !fileNames.isEmpty() ) {
    ... open files
  }

The class SUIT_FileDlg can be subclassed to implement custom file dialog boxes. The class provides a set of methods which can be used in subclasses:

setCheckPermissions() - to enable/disable check of files/directories permissions
setValidator() - to use custom file validator
addWidgets() - to add custom widgets to the lower part of the dialog box
getLastVisitedDirectory() - to get last visited directory
acceptData() - can be used ti customize user selection validation

See also:: SUIT_FileValidator class.

Constructor & Destructor Documentation

SUIT_FileDlg::SUIT_FileDlg	(	QWidget *	parent,
		bool	open,
		bool	showQuickDir = `true`,
		bool	modal = `true`
	)

Parameters:

parent	parent widget
open	if `true` dialog box is used for file opening, otherwise - for saving
showQuickDir	if `true` the quick directory list widgets will be shown
modal	if `true` the dialog box will be modal

References addQuickDir(), addWidgets(), QtxResourceMgr.booleanValue(), myLastVisitedPath, myQuickButton, myQuickCombo, myQuickLab, myUrls, myValidator, processPath(), quickDir(), SUIT_Session.resourceMgr(), SUIT_Session.session(), and QtxResourceMgr.stringValue().

SUIT_FileDlg::~SUIT_FileDlg ( ) [virtual]

References setValidator().

Member Function Documentation

bool SUIT_FileDlg::isOpenDlg ( ) const

Returns:: true if dialog is used for file opening and false otherwise

bool SUIT_FileDlg::checkPermissions ( ) const

Returns:: flag value

See also:: setCheckPermissions()

References myCheckPermissions.

void SUIT_FileDlg::setCheckPermissions ( const bool checkPerm )

If this flag is set and file validator is not null, the validator will check the file permissions also.

Parameters:

checkPerm new flag value

See also:: checkPermissions()

References myCheckPermissions.

SUIT_FileValidator * SUIT_FileDlg::validator ( ) const

Returns:: current file validator

See also:: setValidator()

References myValidator.

void SUIT_FileDlg::setValidator ( SUIT_FileValidator * v )

Destroys previous validator if the dialog owns it.

Parameters:

v	new file validator

See also:: validator()

References myValidator, and SUIT_FileValidator.parent().

bool SUIT_FileDlg::addWidgets	(	QWidget *	l,
		QWidget *	w,
		QWidget *	b
	)

The first widget (usually label) l is placed underneath the "file name" and the "file types" labels. The widget w is placed underneath the file types combobox. The last widget (usually button) b is placed underneath the Cancel push button.

In general, the widgets can be arbitrary. This method is added to support the functionality provided by the Qt series 3.x.

If you don't want to have one of the widgets added, pass 0 in that widget's position. Every time this function is called, a new row of widgets is added to the bottom of the file dialog.

Parameters:

l	first widget (e.g. text label)
w	second widget (e.g. combo box)
b	third widget (e.g. push button)

Returns:: true if widgets have been added successfully

QStringList SUIT_FileDlg::selectedFiles ( ) const

Returns:: selected file names

References addExtension().

QString SUIT_FileDlg::selectedFile ( ) const

Returns:: selected file name or null string if file is not selected

References selectedFiles().

void SUIT_FileDlg::selectFile ( const QString & f )

This version of selectFile() methods works similar to Qt version 3.x: it selects the given file as current and it changes the current file dialog's directory to the directory of the file

Parameters:

f	- new current file name

References Qtx.dir().

QString SUIT_FileDlg::getLastVisitedDirectory ( ) [static]

Note, that last visited path is memorized only if the dialog box is accepted.

Returns:: last visited directory

References myLastVisitedPath.

QString SUIT_FileDlg::getFileName	(	QWidget *	parent,
		const QString &	initial,
		const QStringList &	filters,
		const QString &	caption = `QString()`,
		const bool	open = `true`,
		const bool	showQuickDir = `true`,
		SUIT_FileValidator *	validator = `0`
	)		`[static]`

This method can be used to select the file for opening or saving. The behavior is defined by the open parameter. Note, that selection validation depends on the dialog mode used.

If initial parameter is not null string it is used as starting directory or file at which dialog box is opened.

The parameter filters defines file filters (wildcards) to be used. If filters list is empty, "All files (*)" is used by default.

The parameter caption is used as dialog box title. If it is is empty, the default title is used.

The parameter showQuickDir specifies if it is necessary to show additional quick directories list controls in the bottom part of the dialog box.

The validation of the user selection is done with help of the file validator (SUIT_FileValidator class). The last parameter validator can be used to pass the custom file validator to the dialog box.

Parameters:

parent	parent widget
initial	initial file (or directory) dialog box to be opened on
filters	file filters list
caption	dialog box title
open	if `true` dialog box is used for file opening, otherwise - for saving
showQuickDir	if `true` the quick directory list widgets will be shown
validator	custom file validator

Returns:: selected file name or null string if dialog box is cancelled

See also:: getOpenFileNames(), getExistingDirectory()

References processPath(), selectedFile(), and setValidator().

QString SUIT_FileDlg::getFileName	(	QWidget *	parent,
		const QString &	initial,
		const QString &	filters,
		const QString &	caption = `QString()`,
		const bool	open = `true`,
		const bool	showQuickDir = `true`,
		SUIT_FileValidator *	validator = `0`
	)		`[static]`

If initial parameter is not null string it is used as starting directory or file at which dialog box is opened.

The parameter filters defines file filters (wildcards) to be used. This is the list of wildcards, separated by the ";;" symbols. If filters list is empty, "All files (*)" is used by default.

The parameter caption is used as dialog box title. If it is is empty, the default title is used.

The parameter showQuickDir specifies if it is necessary to show additional quick directories list controls in the bottom part of the dialog box.

The validation of the user selection is done with help of the file validator (SUIT_FileValidator class). The last parameter validator can be used to pass the custom file validator to the dialog box.

Parameters:

parent	parent widget
initial	initial file (or directory) dialog box to be opened on
filters	file filters separated by ";;"
caption	dialog box title
open	if `true` dialog box is used for file opening, otherwise - for saving
showQuickDir	if `true` the quick directory list widgets will be shown
validator	custom file validator

Returns:: selected file name or null string if dialog box is cancelled

See also:: getOpenFileNames(), getExistingDirectory()

References getFileName(), and validator().

QStringList SUIT_FileDlg::getOpenFileNames	(	QWidget *	parent,
		const QString &	initial,
		const QStringList &	filters,
		const QString &	caption = `QString()`,
		const bool	showQuickDir = `true`,
		SUIT_FileValidator *	validator = `0`
	)		`[static]`

If initial parameter is not null string it is used as starting directory or file at which dialog box is opened.

The parameter filters defines file filters (wildcards) to be used. If filters list is empty, "All files (*)" is used by default.

The parameter caption is used as dialog box title. If it is is empty, the default title is used.

The parameter showQuickDir specifies if it is necessary to show additional quick directories list controls in the bottom part of the dialog box.

The validation of the user selection is done with help of the file validator (SUIT_FileValidator class). The last parameter validator can be used to pass the custom file validator to the dialog box.

Parameters:

parent	parent widget
initial	initial file (or directory) dialog box to be opened on
filters	file filters list
caption	dialog box title
showQuickDir	if `true` the quick directory list widgets will be shown
validator	custom file validator

Returns:: selected file names or empty list if dialog box is cancelled

See also:: getFileName(), getExistingDirectory()

References processPath(), selectedFiles(), and setValidator().

QStringList SUIT_FileDlg::getOpenFileNames	(	QWidget *	parent,
		const QString &	initial,
		const QString &	filters,
		const QString &	caption = `QString()`,
		const bool	showQuickDir = `true`,
		SUIT_FileValidator *	validator = `0`
	)		`[static]`

The parameter filters defines file filters (wildcards) to be used. This is the list of wildcards, separated by the ";;" symbols. If filters list is empty, "All files (*)" is used by default.

The parameter caption is used as dialog box title. If it is is empty, the default title is used.

The parameter showQuickDir specifies if it is necessary to show additional quick directories list controls in the bottom part of the dialog box.

The validation of the user selection is done with help of the file validator (SUIT_FileValidator class). The last parameter validator can be used to pass the custom file validator to the dialog box.

Parameters:

parent	parent widget
initial	initial file (or directory) dialog box to be opened on
filters	file filters separated by ";;"
caption	dialog box title
showQuickDir	if `true` the quick directory list widgets will be shown
validator	custom file validator

Returns:: selected file names or empty list if dialog box is cancelled

See also:: getFileName(), getExistingDirectory()

References getOpenFileNames(), and validator().

QString SUIT_FileDlg::getExistingDirectory	(	QWidget *	parent,
		const QString &	initial,
		const QString &	caption = `QString()`,
		const bool	showQuickDir = `true`,
		SUIT_FileValidator *	validator = `0`
	)		`[static]`

If initial parameter is not null string it is used as starting directory at which dialog box is opened.

The parameter caption is used as dialog box title. If it is is empty, the default title is used.

The parameter showQuickDir specifies if it is necessary to show additional quick directories list controls in the bottom part of the dialog box.

The validation of the user selection is done with help of the file validator (SUIT_FileValidator class). The last parameter validator can be used to pass the custom file validator to the dialog box.

Parameters:

parent	parent widget
initial	initial directory dialog box to be opened on
caption	dialog box title
showQuickDir	if `true` the quick directory list widgets will be shown
validator	custom file validator

Returns:: selected directory name or null string if dialog box is cancelled

See also:: getFileName(), getOpenFileNames()

References processPath(), selectedFile(), and setValidator().

QString SUIT_FileDlg::getLastVisitedPath ( ) [static]

Returns:: last visited path

References myLastVisitedPath.

bool SUIT_FileDlg::event ( QEvent * e ) [protected, virtual]

Parameters:

e event

Returns:: true if the event e was recognized and processed

References polish().

QLineEdit * SUIT_FileDlg::lineEdit ( ) const [protected]

Returns:: line edit widget or0 if it could not be found

bool SUIT_FileDlg::acceptData ( ) [protected, virtual]

The validation is done by calling the corresponding methods of the validator. If the validator is not set, this method always returns true.

This method can be re-implemented in the subclasses to customize the file dialog behavior. Another solution could be implementing own file validator class.