FileSearch Class Reference

A class to do a depth-first search for a file in a directory tree efficiently and safely (I hope). The class is fire and forget, letting you get on with other things and take action when you're informed that the search is complete. A FileSearch is single use. More...

#include <filesearch.h>

Inheritance diagram for FileSearch:

Collaboration diagram for FileSearch:

Public Slots
virtual void	start ()
	Begin searching.
const QStringList &	matchingFiles () const
	Return a list of files matched. Note that it is safe to call this while the search is still running, or after it has failed.
int	foundCount () const
	Return the number of files found so far.
const QString &	fileName () const
	Return the name we're searching for.
const QDir &	currentDir () const
	Return a const reference to the QDir we're using to track our progress. This lets the caller get the dirname, absolute dirname, etc.
Public Slots inherited from DeferredTask
virtual void	start ()
	Starts the timer and begins processing. If you override this you must call DeferredTask::start() at the end of your start() implementation. If something goes wrong, emit aborted();.
void	runUntilFinished ()
	Run continuously without returning control to the event loop, until either aborted(bool) or finished() are emitted. Note that EVENTS ARE NOT PROCESSED, including deleteLater() and posted events. It is not recommended that you use this method.
virtual void	cancel ()
	Abort the search and emit aborted(true). This is treated as an abort by the user. If you reimplement this you must call DeferredTask::cancel() at the end of your implementation. Do not emit aborted(bool) yourself from your cancel() implementation, let DeferredTask::cancel() do that.

Signals
void	searchComplete (const QStringList &paths, const QString &filename)
	Emitted when the search has finished. More...
Signals inherited from DeferredTask
void	aborted (bool)
	Emitted if the processing work was aborted before completion. The signal argument is true if processing was aborted by direct or indirect user action, and false if it was aborted for any other reason (such as an internal error).
void	finished ()
	Emitted when processing is complete, from DeferredTask::done(). You can also emit your own custom signal if you want to convey more information, so long as you do so AFTER calling done().
void	progress (int)
	Emitted to inform anybody interested of the approximate level of progress made in the processing task. The argument is a positive integer percentage from 0 to 100 inclusive. Subclasses are not required to emit this signal, but it's a good idea if the user is likely to care about what your class does.

Public Member Functions
	FileSearch (QObject *parent, const QString &fileName, const QString &searchBase=QString::null, int depthLimit=-1, bool caseSensitive=true)
	Construct a new FileSearch object to search for the specified filename. More...
Public Member Functions inherited from DeferredTask
virtual	~DeferredTask ()
	If you override the destructor, call DeferredTask::cleanup() at the end of your dtor.
bool	isFinished () const
	Returns true iff processing has finished. Note that this will return false both while processing, and before start() has been called.
virtual const QString &	lastError () const
	Return a human-readable version of the last error message. Unless overridden, returns the value of m_lastError. Value is undefined until either finished() or aborted(bool) have been emitted.

Protected Slots
virtual void	next ()
Protected Slots inherited from DeferredTask
virtual void	next ()=0
	Do the next small chunk of processing, then return. You must implement this method to do whatever processing work you need to. It will be called repeatedly until it emits either aborted(bool) or finished() to indicate that it's done.

Protected Member Functions
void	pushStack ()
	Push a list of subdirs in the current directory onto m_tree, and put an iterator pointing to the first subdir on top of m_iter.
void	addCurrentDirFiles ()
	Scans the current directory (where QDir is set to) and adds its contents to the list of matched files.
Protected Member Functions inherited from DeferredTask
	DeferredTask (QObject *parent)
	You must provide a new, public, constructor. It should set up the class but not begin processing. You must call DeferredTask::init() from your ctor, preferably early on.
void	init ()
	Do some setup of the DeferredTask. Must be called from all subclass ctors.
void	cleanup ()
	Do some cleanup before deletion. Must be called from all subclass dtors.
void	done ()
	Indicate that processing has finished. You must call this before emitting finished(), since it sets up some state that must happen before any slots connected to finished() are called, and the ordering of slot calls from a signal can not be guaranteed.

Protected Attributes
bool	m_caseSensitive
	Case sensitive flag.
QString	m_searchBase
	Where the search starts from.
QString	m_fileName
	What the filename we're looking for is.
QStringList	m_matchingFiles
	The list of files matched in the search.
QStack< QStringList >	m_tree
	This stack holds a list of directories on the tree, from the base to the level we're currently searching. We use iterators into the values of this stack to keep the search position.
QStack< QStringList::const_iterator >	m_iter
	A matching stack of iterators into the lists in m_tree. We use this stack to iterate directory by directory as we search.
QDir	m_dir
	A QDir set to the current directory, used for listing files and directories.
int	m_depth
	Conveniently keep track of how deeply we've recursed.
int	m_maxdepth
	Maximum depth to search to.
Protected Attributes inherited from DeferredTask
QString	m_lastError
	Human readable, translated version of last error encountered.

Detailed Description

A class to do a depth-first search for a file in a directory tree efficiently and safely (I hope). The class is fire and forget, letting you get on with other things and take action when you're informed that the search is complete. A FileSearch is single use.

Constructor & Destructor Documentation

FileSearch::FileSearch	(	QObject *	parent,
		const QString &	fileName,
		const QString &	searchBase = QString::null,
		int	depthLimit = -1,
		bool	caseSensitive = true
	)

Construct a new FileSearch object to search for the specified filename.

Parameters

parent	Parent object (where it will be displayed)
fileName	should be a basename without path. Once you've created the FileSearch, connect yourself to its searchComplete(int) signal then start() it and return to the event loop.
searchBase	If searchBase is not specified, a search of the user's home directory is done. The caller is expected to ensure that the search base exists.
depthLimit	is -1 for no limit, otherwise number of levels deep to search. The base dir is level 0.
caseSensitive	it will search case INSENSITIVE filenames if false.

Warning

It's useless to set caseSensitive on MS Windows! This will be set to false on windows automatically because Windows are case insensitive already.

Member Function Documentation

void FileSearch::searchComplete ( const QStringList &  paths, const QString &  filename  )

signal

Emitted when the search has finished.

Parameters

paths	is list of paths matched,
filename	is filename searched for. Remember you can simply discard one or both params.

---

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

• /Users/ale/src/Scribus/scribus/filesearch.h
• /Users/ale/src/Scribus/scribus/filesearch.cpp