SUIT_FileDlg Class Reference

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. More...
virtual	~SUIT_FileDlg ()
	Destructor. More...
bool	isOpenDlg () const
	Check if the dialog box is used for opening or saving the file. More...
bool	checkPermissions () const
	Get 'check file permissions' flag. More...
void	setCheckPermissions (const bool)
	Set 'check file permissions' flag. More...
SUIT_FileValidator *	validator () const
	Get file validator. More...
void	setValidator (SUIT_FileValidator *)
	Set file validator. More...
bool	addWidgets (QWidget *, QWidget *, QWidget *)
	Adds the specified widgets to the bottom of the file dialog. More...
QStringList	selectedFiles () const
	Get list of selected files. More...
QString	selectedFile () const
	Get selected file. More...
void	selectFile (const QString &)
	Selects current file. More...

Static Public Member Functions
static QString	getLastVisitedDirectory ()
	Get last visited directory. More...
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. More...
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. More...
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. More...
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. More...
static QString	getExistingDirectory (QWidget *, const QString &, const QString &=QString(), const bool=true, SUIT_FileValidator *=0)
	Show dialog box for the existing directory selection. More...
static QString	getLastVisitedPath ()
	Get last visited path. More...

Protected Slots
void	accept ()
	Called when the user presses "Open"or "Save" button. More...
void	quickDir (const QString &)
	Called when user selects directory from the "Quick Dir" combo box. More...
void	addQuickDir ()
	Called when user presses "Quick Dir Add" button. More...

Protected Member Functions
virtual bool	event (QEvent *)
	Customize events processing. More...
QLineEdit *	lineEdit () const
	Get line edit which is used to enter file name. More...
virtual bool	acceptData ()
	Validate user selection. More...
QString	addExtension (const QString &) const
	Add an extension to the specified file name. More...
bool	processPath (const QString &)
	Processes selection : tries to set specified sirectory or filename as current file dialog selection. More...
void	addFilter (const QString &)
	Add file filter and activates it. More...

Static Protected Member Functions
static bool	hasWildCards (const QString &)
	Check if the string contains wildcard symbols. More...

Private Member Functions
void	polish ()
	Polish the dialog box. More...

Private Attributes
SUIT_FileValidator *	myValidator
	file validator More...
QLabel *	myQuickLab
	quick dir combo box More...
QComboBox *	myQuickCombo
	quick dir combo box More...
QList< QUrl >	myUrls
	quick dir Sidebar Urls More...
QPushButton *	myQuickButton
	quick dir add button More...
bool	myCheckPermissions
	check permissions option More...

Static Private Attributes
static QString	myLastVisitedPath
	last visited path More...

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

void SUIT_FileDlg::accept ( )

protectedslot

Verifies the user choice and closes dialog box, setting the return code to QDialog::Accepted

See Also

acceptData()

References acceptData(), and myLastVisitedPath.

bool SUIT_FileDlg::acceptData ( )

protectedvirtual

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.

Returns

true if user selection (file(s) or directory) is valid

See Also

SUIT_FileValidator class, validator(), setValidator()

References addFilter(), SUIT_FileValidator::canOpen(), SUIT_FileValidator::canReadDir(), SUIT_FileValidator::canSave(), SUIT_FileValidator::canWriteDir(), checkPermissions(), hasWildCards(), isOpenDlg(), lineEdit(), selectedFiles(), and validator().

QString SUIT_FileDlg::addExtension ( const QString &  fileName ) const

protected

The extension is extracted from the active filter.

Parameters

fileName

file name to be processed

Returns

fileName with the extension added

References Qtx::extension(), and IGNORE_NON_MATCHING_EXTENSION.

void SUIT_FileDlg::addFilter ( const QString &  filter )

protected

Parameters

filter

new file filter

void SUIT_FileDlg::addQuickDir ( )

protectedslot

Adds current directory to the quick directories list and to the preferences.

References myQuickCombo, myUrls, SUIT_Session::resourceMgr(), SUIT_Session::session(), QtxResourceMgr::setValue(), and QtxResourceMgr::stringValue().

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

bool SUIT_FileDlg::checkPermissions

(

)

const

Returns

flag value

See Also

setCheckPermissions()

References myCheckPermissions.

bool SUIT_FileDlg::event ( QEvent *  e )

protectedvirtual

Parameters

e

event

Returns

true if the event e was recognized and processed

References polish().

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::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().

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::getLastVisitedPath ( )

static

Returns

last visited path

References myLastVisitedPath.

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().

bool SUIT_FileDlg::hasWildCards ( const QString &  s )

staticprotected

Parameters

s	string to be checked (for example, file name)

Returns

true if string contains "*" or "?" symbols

bool SUIT_FileDlg::isOpenDlg

(

)

const

Returns

true if dialog is used for file opening and false otherwise

QLineEdit * SUIT_FileDlg::lineEdit ( ) const

protected

Returns

line edit widget or0 if it could not be found

void SUIT_FileDlg::polish ( )

private

bool SUIT_FileDlg::processPath ( const QString &  path )

protected

Parameters

path	file or directory path

Returns

true if path is processed correctly and false otherwise

References Qtx::dir(), Qtx::file(), and selectFile().

void SUIT_FileDlg::quickDir ( const QString &  dirPath )

protectedslot

Browses the file dialog to the specified directory (if it is valid).

Parameters

dirPath

selected directory

References SUIT_MessageBox::critical(), and processPath().

QString SUIT_FileDlg::selectedFile

(

)

const

Returns

selected file name or null string if file is not selected

References selectedFiles().

QStringList SUIT_FileDlg::selectedFiles

(

)

const

Returns

selected file names

References addExtension().

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().

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.

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().

SUIT_FileValidator * SUIT_FileDlg::validator

(

)

const

Returns

current file validator

See Also

setValidator()

References myValidator.

Member Data Documentation

bool SUIT_FileDlg::myCheckPermissions

private

QString SUIT_FileDlg::myLastVisitedPath

staticprivate

QPushButton* SUIT_FileDlg::myQuickButton

private

QComboBox* SUIT_FileDlg::myQuickCombo

private

QLabel* SUIT_FileDlg::myQuickLab

private

QList<QUrl> SUIT_FileDlg::myUrls

private

SUIT_FileValidator* SUIT_FileDlg::myValidator

private

---

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

• src/SUIT/SUIT_FileDlg.h
• src/SUIT/SUIT_FileDlg.cxx