VCF::Directory::Finder

VCF::Directory::Finder Class Reference

A Finder object is used to iterate a set of files contained in a Directory object that represents the directory. More...

#include <Directory.h>

Inheritance diagram for VCF::Directory::Finder:

List of all members.


Public Types
enum	DisplayMode { dmNone = 0x0, dmFiles = 0x1, dmDirs = 0x2, dmAny = dmFiles \| dmDirs }
Public Member Functions
virtual	~Finder ()
File *	getCurrentElement () const
	Gets the pointer to the last searched element.
bool	nextElement ()
	Advances the finder to the next element in the search.
void	reset ()
	Resets the search.
bool	hasMoreElements () const
	Are there any more elements in this Finder ? This function doesn't affect the search in any way.
Directory *	getOwningDirectory ()
	Returns the Directory object that created.
void	setDisplayMode (DisplayMode displayMode)
	set flags for DisplayMode enabled It can be set for files ( dmFiles ) or dirs ( dmDirs ) or both ( dmAny ).
DisplayMode	getDisplayMode () const
	Tells the current display mode.
void	setDisplayOrder (DisplayMode displayOrder)
	Set the order used by the Finder for displaying files and directories.
DisplayMode	getDisplayOrder () const
	Tells the order used by the Finder for displaying files and directories.
void	setRecursion (const bool &recurse, const int &recursionLevelMax=-1)
	Sets the Directory::Finder for recursion into subdirectories.
bool	getRecurse () const
	Tells if the Finder is set for recursion into suybdirectories.
int	getRecursionLevelMax () const
	Gets the maximum subdirectory level the Finder is allowed to recurse into, 0 means no recursion.
void	setRecursionLevelMax (const int &recursionLevelMax)
	Sets the maximum subdirectory level up to where the Finder is allowed to recurse into.
int	getRecursionLevel () const
	Gets the current subdirectory level where the Finder is currently recursing into, 0 is the root level of the search.
void	internal_updateToActiveFinder ()
	Not meant for general consumption.
String	getRelativePathToRootSearch () const
	Gets the relative path of the file to the directory where the search started.
void	setRelativePathToRootSearch (const String &val)
void	setSearchFilterFileObject (FileSearchFilter *searchFilterFileObject, const bool &ownFilterFileObject=false)
	sets the search filter used with files by this Finder.
FileSearchFilter *	getSearchFilterFileObject () const
	Returns the search filter used with files by this Finder.
void	setMaskFilterFileAttribs (File::FileAttributes maskFilterFileAttribs)
	Set the file attributes mask used to limit the search for files ( not directories ).
File::FileAttributes	getMaskFilterFileAttribs () const
	Gets the file attributes mask used to limit the search for files ( not directories ).
void	setStatMask (uint32 statMask)
	Sets the mask for the informations we want to extract from a file.
uint32	getStatMask () const
	Gets the mask for the informations we want to extract from a file.
void	ignoreStat (uint32 ignoreMask)
	Sets the mask for the informations we just don't care about.
void	setShowLocalTime (const bool &showLocalTime)
	stets the Finder for showing the local time of any file found.
bool	getShowLocalTime ()
	tells if the Finder is set for showing the local time of any file found, or UTC time instead.
void	setKeepOSSpecificFormat (const bool &keepOSSpecificFormat=true)
	set the finder to always return filenames in the OS specific format
bool	getKeepOSSpecificFormat () const
	tells if we keep currently keep the filenames format OS specific
virtual void	setAllowSpecialDirs (const bool &allowSpecialDirs)
	enables/disable the visibility of some special directories during the search Under Windows these are indicated with dots ( '.
bool	getAllowSpecialDirs () const
	tells if the search is enabled for retrieving some special directories Under Windows these are indicated with dots ( '.
File &	getFileInfo ()
const File &	getFileInfo () const
DisplayMode	getCurrentDisplayOrder () const
void	setCurrentDisplayOrder (const DisplayMode &mode)
bool	canRecurseDown () const
void	setCurrentElement (File *file)
void	setParentFinder (Finder *finder, const String &relPath, const int &previousRecursionLevel)
void	goDownDir (File *file)
void	goUpDir (File *file)
void	continueSearch (File *file)
Protected Member Functions
	Finder (Directory directoryToSearch, FileSearchFilter filterFileObject=NULL, const bool &ownFilterFileObject=false)
Protected Attributes
File	fileInfos_
Directory *	owningDirectory_
	the directory File owning this finder
FileSearchFilter *	searchFilterFileObject_
bool	ownFilterFileObject_
File::FileAttributes	maskFilterFileAttribs_
uint32	statMask_
File *	currentElement_
	The current element retrieved by the search.
bool	searchHasMoreElements_
	Simply used to know if we have more elements.
DisplayMode	displayMode_
	The display mode requested by the user.
DisplayMode	displayOrder_
	The display order requested by the user.
DisplayMode	displayOrderCurrent_
	The display order currently in use.
bool	allowSpecialDirs_
bool	showLocalTime_
bool	keepOSSpecificFormat_
bool	recurse_
String	relativePathToRootSearch_
	the relative path to where the search started, while in the current subdirectories
Finder *	rootSearchFinder_
	The main finder.
Finder *	activeFinder_
	pointer to the finder currently active in the search
Finder *	childFinder_
	Pointer to finder used to manage the search along the directory tree.
Finder *	parentFinder_
	Pointer to finder used to manage the search along the directory tree.
std::vector< Directory * > *	subdirs_
	memory finders' management.
std::vector< Finder * > *	subfinders_
int	recursionLevel_
	current recursion level
int	recursionLevelMax_
	max allowed recursion level
bool	goSearchAgain_
	for recursion: when we complete the search by dir and we want to search the files or viceversa.
Friends
class	Directory

Detailed Description

A Finder object is used to iterate a set of files contained in a Directory object that represents the directory.

Only Directory objects may create a Finder object.

A Finder is similar to an Enumerator but it doesn't follow the exact same pattern. Specifically it doesn't allow you to go "backwards" - you can only reset the finder, and then progress to the next element. The most import method for iterating the elements in a Finder isntance is the nextElement() function which returns a pointer to an internal File object which is updated for each file element.

All the other methods are used to narrow or speed up the search. Custom filtering can be done the simple way by specifying filter strings, or in a fully flexible way through any class derived from FileSearchFilter.

Member Enumeration Documentation

enum VCF::Directory::Finder::DisplayMode

Enumerator:

dmNone

dmFiles

dmDirs

dmAny

Constructor & Destructor Documentation

virtual VCF::Directory::Finder::~Finder ( ) [virtual]

VCF::Directory::Finder::Finder ( Directory * directoryToSearch,

FileSearchFilter * filterFileObject = NULL,

const bool & ownFilterFileObject = false

) [protected]

Member Function Documentation

bool VCF::Directory::Finder::canRecurseDown ( ) const [inline]

void VCF::Directory::Finder::continueSearch ( File * file )

bool VCF::Directory::Finder::getAllowSpecialDirs ( ) const [inline]

tells if the search is enabled for retrieving some special directories Under Windows these are indicated with dots ( '.
' and '..' ) but they could be others under different OS
Returns:
bool true if visible to the search

DisplayMode VCF::Directory::Finder::getCurrentDisplayOrder ( ) const [inline]

File* VCF::Directory::Finder::getCurrentElement ( ) const

Gets the pointer to the last searched element.

Returns:
the pointer to the last searched element.

DisplayMode VCF::Directory::Finder::getDisplayMode ( ) const [inline]

Tells the current display mode.

Returns:
DisplayMode the current display mode

DisplayMode VCF::Directory::Finder::getDisplayOrder ( ) const [inline]

Tells the order used by the Finder for displaying files and directories.

Returns:
DisplayMode the current display order.

const File& VCF::Directory::Finder::getFileInfo ( ) const [inline]

File& VCF::Directory::Finder::getFileInfo ( ) [inline]

bool VCF::Directory::Finder::getKeepOSSpecificFormat ( ) const [inline]

tells if we keep currently keep the filenames format OS specific

Returns:
bool the current choice

File::FileAttributes VCF::Directory::Finder::getMaskFilterFileAttribs ( ) const [inline]

Gets the file attributes mask used to limit the search for files ( not directories ).

Returns:
the file attributes mask for files

Directory* VCF::Directory::Finder::getOwningDirectory ( ) [inline]

Returns the Directory object that created.
this Finder.
Returns:
Directory the owning directory for this finder.

bool VCF::Directory::Finder::getRecurse ( ) const [inline]

Tells if the Finder is set for recursion into suybdirectories.

Returns:
true if recursion is allowed

int VCF::Directory::Finder::getRecursionLevel ( ) const [inline]

Gets the current subdirectory level where the Finder is currently recursing into, 0 is the root level of the search.

Returns:
the maximum recursion level.

int VCF::Directory::Finder::getRecursionLevelMax ( ) const [inline]

Gets the maximum subdirectory level the Finder is allowed to recurse into, 0 means no recursion.

Returns:
the maximum recursion level.

String VCF::Directory::Finder::getRelativePathToRootSearch ( ) const [inline]

Gets the relative path of the file to the directory where the search started.

Returns:
the relative path to the root of the search.

FileSearchFilter* VCF::Directory::Finder::getSearchFilterFileObject ( ) const [inline]

Returns the search filter used with files by this Finder.

Returns:
FileSearchFilter the search filter object for files used by this Finder

bool VCF::Directory::Finder::getShowLocalTime ( ) [inline]

tells if the Finder is set for showing the local time of any file found, or UTC time instead.

Returns:
true if it shows the local time of files, false if it shows the UTC time of files.

uint32 VCF::Directory::Finder::getStatMask ( ) const [inline]

Gets the mask for the informations we want to extract from a file.

Returns:
the mask

void VCF::Directory::Finder::goDownDir ( File * file )

void VCF::Directory::Finder::goUpDir ( File * file )

bool VCF::Directory::Finder::hasMoreElements ( ) const [inline]

Are there any more elements in this Finder ? This function doesn't affect the search in any way.

Returns:
bool true if the there are more elements yet to search.

void VCF::Directory::Finder::ignoreStat ( uint32 ignoreMask ) [inline]

Sets the mask for the informations we just don't care about.

Parameters:

StatMask the mask of infos we want to ignore

See also:
setStatMask

void VCF::Directory::Finder::internal_updateToActiveFinder ( ) [inline]

Not meant for general consumption.
This is meant for implementors only. Don't call this method, or world wide evils will be unleashed that even Lara Croft will be powerless to stop.

bool VCF::Directory::Finder::nextElement ( )

Advances the finder to the next element in the search.

Returns:
bool true if we found another element fulfilling the conditions set by the user, false otherwise.

void VCF::Directory::Finder::reset ( )

Resets the search.

virtual void VCF::Directory::Finder::setAllowSpecialDirs ( const bool & allowSpecialDirs ) [inline, virtual]

enables/disable the visibility of some special directories during the search Under Windows these are indicated with dots ( '.
' and '..' )
Parameters:

allowSpecialDirs

void VCF::Directory::Finder::setCurrentDisplayOrder ( const DisplayMode & mode ) [inline]

void VCF::Directory::Finder::setCurrentElement ( File * file ) [inline]

void VCF::Directory::Finder::setDisplayMode ( DisplayMode displayMode )

set flags for DisplayMode enabled It can be set for files ( dmFiles ) or dirs ( dmDirs ) or both ( dmAny ).
If it is set for files, the finder will still be able to recurse into subdirectories if specified. Do not modify the display mode during the search unless you know what you are doing.
Parameters:

displayMode the display mode

void VCF::Directory::Finder::setDisplayOrder ( DisplayMode displayOrder )

Set the order used by the Finder for displaying files and directories.
The possible modes are: to display files first ( dmFiles ) and then directories; or vice-versa ( dmDirs ) in two search steps; or to display both of them, unsorted, in only one search step ( dmAny ).
Parameters:

DisplayMode the display order.

void VCF::Directory::Finder::setKeepOSSpecificFormat ( const bool & keepOSSpecificFormat = true ) [inline]

set the finder to always return filenames in the OS specific format

Parameters:

bool true if we keep the format OS specific, false if we keep the native format instead

void VCF::Directory::Finder::setMaskFilterFileAttribs ( File::FileAttributes maskFilterFileAttribs ) [inline]

Set the file attributes mask used to limit the search for files ( not directories ).

Parameters:

maskFilterFileAttribs the file attributes mask for files

void VCF::Directory::Finder::setParentFinder ( Finder * finder,

const String & relPath,

const int & previousRecursionLevel

)

void VCF::Directory::Finder::setRecursion ( const bool & recurse,

const int & recursionLevelMax = -1

)

Sets the Directory::Finder for recursion into subdirectories.

Parameters:

recurse to allow recursion into subdirectories

recursionLevelMax maximum level of subdirectories to recurse into ( default is -1 so no limit is set, 0 implies no recursion )

void VCF::Directory::Finder::setRecursionLevelMax ( const int & recursionLevelMax ) [inline]

Sets the maximum subdirectory level up to where the Finder is allowed to recurse into.

Parameters:

the maximum recursion level. 0 means only current directory. -1 means no limits.

void VCF::Directory::Finder::setRelativePathToRootSearch ( const String & val ) [inline]

void VCF::Directory::Finder::setSearchFilterFileObject ( FileSearchFilter * searchFilterFileObject,

const bool & ownFilterFileObject = false

) [inline]

sets the search filter used with files by this Finder.

Parameters:

the search filter object used to filter the files

void VCF::Directory::Finder::setShowLocalTime ( const bool & showLocalTime ) [inline]

stets the Finder for showing the local time of any file found.
By default it shows the UTC time.
Parameters:

bool true to show the local time of files, false to show the UTC time of files.

void VCF::Directory::Finder::setStatMask ( uint32 statMask ) [inline]

Sets the mask for the informations we want to extract from a file.
This filter is meant to increase the performance, but be careful: this speed up the search significantly, but then if later you'll frequently need of the infos you choosed to exclude, then the performance will end up to be worse.
Parameters:

StatMask the mask

Friends And Related Function Documentation

friend class Directory [friend]

Member Data Documentation

Finder* VCF::Directory::Finder::activeFinder_ [protected]

pointer to the finder currently active in the search

bool VCF::Directory::Finder::allowSpecialDirs_ [protected]

Finder* VCF::Directory::Finder::childFinder_ [protected]

Pointer to finder used to manage the search along the directory tree.

File* VCF::Directory::Finder::currentElement_ [protected]

The current element retrieved by the search.

DisplayMode VCF::Directory::Finder::displayMode_ [protected]

The display mode requested by the user.

DisplayMode VCF::Directory::Finder::displayOrder_ [protected]

The display order requested by the user.

DisplayMode VCF::Directory::Finder::displayOrderCurrent_ [protected]

The display order currently in use.

File VCF::Directory::Finder::fileInfos_ [protected]

bool VCF::Directory::Finder::goSearchAgain_ [protected]

for recursion: when we complete the search by dir and we want to search the files or viceversa.

bool VCF::Directory::Finder::keepOSSpecificFormat_ [protected]

File::FileAttributes VCF::Directory::Finder::maskFilterFileAttribs_ [protected]

bool VCF::Directory::Finder::ownFilterFileObject_ [protected]

Directory* VCF::Directory::Finder::owningDirectory_ [protected]

the directory File owning this finder

Finder* VCF::Directory::Finder::parentFinder_ [protected]

Pointer to finder used to manage the search along the directory tree.

bool VCF::Directory::Finder::recurse_ [protected]

int VCF::Directory::Finder::recursionLevel_ [protected]

current recursion level

int VCF::Directory::Finder::recursionLevelMax_ [protected]

max allowed recursion level

String VCF::Directory::Finder::relativePathToRootSearch_ [protected]

the relative path to where the search started, while in the current subdirectories

Finder* VCF::Directory::Finder::rootSearchFinder_ [protected]

The main finder.
The same finder accessible to the user during all the search loop.

FileSearchFilter* VCF::Directory::Finder::searchFilterFileObject_ [protected]

bool VCF::Directory::Finder::searchHasMoreElements_ [protected]

Simply used to know if we have more elements.

bool VCF::Directory::Finder::showLocalTime_ [protected]

uint32 VCF::Directory::Finder::statMask_ [protected]

std::vector<Directory*>* VCF::Directory::Finder::subdirs_ [protected]

memory finders' management.
This vector is allocated only in the main finder rootSearchFinder_

std::vector<Finder*>* VCF::Directory::Finder::subfinders_ [protected]

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

vcf/FoundationKit/Directory.h

VCF::Directory::Finder Class Reference

Public Types

Public Member Functions

Protected Member Functions