Scribus Developer Documentation - API
logo-pen

Scribus Developer Documentation - API

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:

Inheritance graph
[legend]
Collaboration diagram for FileSearch:

Collaboration graph
[legend]

List of all members.

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.

Signals

void searchComplete (const QStringList &, const QString &)
 Emitted when the search has finished.

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

Protected Slots

virtual void next ()
 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 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.


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.

Definition at line 24 of file filesearch.h.


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.

Definition at line 23 of file filesearch.cpp.

References DeferredTask::init(), m_caseSensitive, m_dir, and m_searchBase.

FileSearch::~FileSearch (  ) 

Definition at line 42 of file filesearch.cpp.

References DeferredTask::cleanup().


Member Function Documentation

void FileSearch::start (  )  [virtual, slot]

Begin searching.

Reimplemented from DeferredTask.

Definition at line 67 of file filesearch.cpp.

References addCurrentDirFiles(), pushStack(), and DeferredTask::start().

Referenced by PicSearchOptions::SearchPic().

const QStringList & FileSearch::matchingFiles (  )  const [slot]

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.

Definition at line 47 of file filesearch.cpp.

References m_matchingFiles.

int FileSearch::foundCount (  )  const [slot]

Return the number of files found so far.

Definition at line 52 of file filesearch.cpp.

References m_matchingFiles.

const QString & FileSearch::fileName (  )  const [slot]

Return the name we're searching for.

Definition at line 57 of file filesearch.cpp.

References m_fileName.

const QDir & FileSearch::currentDir (  )  const [slot]

Return a const reference to the QDir we're using to track our progress. This lets the caller get the dirname, absolute dirname, etc.

Definition at line 62 of file filesearch.cpp.

References m_dir.

void FileSearch::searchComplete ( const QStringList &  ,
const QString &   
) [signal]

Emitted when the search has finished.

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

Referenced by next().

void FileSearch::next (  )  [protected, virtual, slot]

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.

Implements DeferredTask.

Definition at line 76 of file filesearch.cpp.

References addCurrentDirFiles(), DeferredTask::done(), m_depth, m_dir, m_fileName, m_iter, m_matchingFiles, m_maxdepth, m_tree, pushStack(), and searchComplete().

void FileSearch::pushStack (  )  [protected]

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.

Definition at line 130 of file filesearch.cpp.

References m_dir, m_iter, and m_tree.

Referenced by next(), and start().

void FileSearch::addCurrentDirFiles (  )  [protected]

Scans the current directory (where QDir is set to) and adds its contents to the list of matched files.

Definition at line 136 of file filesearch.cpp.

References m_caseSensitive, m_dir, m_fileName, and m_matchingFiles.

Referenced by next(), and start().


Member Data Documentation

bool FileSearch::m_caseSensitive [protected]

Case sensitive flag.

Definition at line 89 of file filesearch.h.

Referenced by addCurrentDirFiles(), and FileSearch().

QString FileSearch::m_searchBase [protected]

Where the search starts from.

Definition at line 92 of file filesearch.h.

Referenced by FileSearch().

QString FileSearch::m_fileName [protected]

What the filename we're looking for is.

Definition at line 95 of file filesearch.h.

Referenced by addCurrentDirFiles(), fileName(), and next().

QStringList FileSearch::m_matchingFiles [protected]

The list of files matched in the search.

Definition at line 98 of file filesearch.h.

Referenced by addCurrentDirFiles(), foundCount(), matchingFiles(), and next().

QStack<QStringList> FileSearch::m_tree [protected]

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.

Definition at line 104 of file filesearch.h.

Referenced by next(), and pushStack().

QStack<QStringList::const_iterator> FileSearch::m_iter [protected]

A matching stack of iterators into the lists in m_tree. We use this stack to iterate directory by directory as we search.

Definition at line 109 of file filesearch.h.

Referenced by next(), and pushStack().

QDir FileSearch::m_dir [protected]

A QDir set to the current directory, used for listing files and directories.

Definition at line 113 of file filesearch.h.

Referenced by addCurrentDirFiles(), currentDir(), FileSearch(), next(), and pushStack().

int FileSearch::m_depth [protected]

Conveniently keep track of how deeply we've recursed.

Definition at line 116 of file filesearch.h.

Referenced by next().

int FileSearch::m_maxdepth [protected]

Maximum depth to search to.

Definition at line 119 of file filesearch.h.

Referenced by next().


The documentation for this class was generated from the following files:
Created with personalized Doxygen. This is documentation for GPL software Scribus - Open Source Desktop Publishing.