FILEFIND Class Reference

Class used to search for files. More...

#include <mi32/filefind.h>

Classes
class	FILTER
	Base FILTER class used in LocatePath() and LocateRelatedFile() to select the correct path if multiple possible. More...
class	MISSINGFILEPROMPTDISABLER
	Class to automatically disable prompt for missing file on creation and enable prompt on destruction. More...
Public Types
enum	ADDPOSN { ADDPOSN_ToFront, ADDPOSN_ToBack }
typedef FastDelegate< void(FILEPATH &)>	DELEGATE_MOUNT
typedef FastDelegate< bool(FILEPATH &, FILEFIND::FILTER , const MISTRING )	DELEGATE_PROMPT )
enum	LOCATIONS { LOCATION_None = 0x0000, LOCATION_Locale = 0x0001, LOCATION_Home = 0x0002, LOCATION_Current = 0x0004, LOCATION_Process = 0x0008, LOCATION_PATH = 0x0010, LOCATION_Installation = 0x0020, LOCATION_Settings_CurInst_CurUser = 0x0100, LOCATION_Settings_CurInst_AllUsers = 0x0200, LOCATION_Settings_AllInst_CurUser = 0x0400, LOCATION_Settings_AllInst_AllUsers = 0x0800, LOCATIONS_Executable = (LOCATION_Installation \| LOCATION_Process \| LOCATION_Current \| LOCATION_PATH), LOCATIONS_Reference = (LOCATION_Installation \| LOCATION_Process \| LOCATION_Current), LOCATIONS_Temporary = 0x1000 }
enum	RELATEDORDER { RELATEDORDER_SourceOriginalMediaTree = ((SUBORDER_Source) \| (SUBORDER_Original << 4) \| (SUBORDER_Media << 8) \| (SUBORDER_Tree << 12)), RELATEDORDER_OriginalSourceMediaTree = ((SUBORDER_Original) \| (SUBORDER_Source << 4) \| (SUBORDER_Media << 8) \| (SUBORDER_Tree << 12)), RELATEDORDER_SourceMediaOriginalTree = ((SUBORDER_Source) \| (SUBORDER_Media << 4) \| (SUBORDER_Original << 8) \| (SUBORDER_Tree << 12)), RELATEDORDER_MediaSourceOriginalTree = ((SUBORDER_Media) \| (SUBORDER_Source << 4) \| (SUBORDER_Original << 8) \| (SUBORDER_Tree << 12)), RELATEDORDER_MediaTreeSourceOriginal = ((SUBORDER_Media) \| (SUBORDER_Tree << 4) \| (SUBORDER_Source << 8) \| (SUBORDER_Original << 12)), RELATEDORDER_NoPrompt = 0x80000000 }
Public Member Functions
	FILEFIND (const FILEFIND &rhs)
	FILEFIND (LOCATIONS locations=LOCATION_None)
	~FILEFIND ()
void	AddEnvVar (const char *EnvTag, ADDPOSN AddPosn=ADDPOSN_ToBack, bool NeedWritable=false)
void	AddLocale (bool IncludeDefault=true, ADDPOSN AddPosn=ADDPOSN_ToBack)
void	AddPath (const FILEPATH &path, ADDPOSN AddPosn=ADDPOSN_ToBack, bool NeedWritable=false)
void	AddString (const MISTRING &mpath, ADDPOSN AddPosn=ADDPOSN_ToBack, bool NeedWritable=false, MIUNICODE Separator=0xFFFF)
bool	CreatePath (const char *name, FILEPATH &path) const
bool	CreatePath (const MISTRING &name, FILEPATH &path) const
const FILEPATHLIST &	GetPathList () const
bool	IsEmpty () const
bool	LocateFile (const MISTRING &relfile, FILEPATH &path) const
bool	LocateFile (const char *name, FILEPATH &path) const
bool	LocateFiles (const MISTRING &pattern, FILEPATHLIST &PathList) const
bool	LocatePath (FILTER &filter, FILEPATH &path) const
FILEFIND &	operator= (const FILEFIND &rhs)
Static Public Member Functions
static void	ClearMissingFileList ()
static ERRVALUE	GetDefaultTempFolder (FILEPATH &Folder, bool bCreateIfMissing)
static bool	LocateExecutableFile (const char *ExecutableFileName, FILEPATH &ExecutableFilePath)
static bool	LocateReferenceFile (const MISTRING &ReferenceFileName, FILEPATH &ReferenceFilePath, LOCATIONS locations=LOCATION_None)
static bool	LocateReferenceFile (const char *ReferenceFileName, FILEPATH &ReferenceFilePath, LOCATIONS locations=LOCATION_None)
static bool	LocateRelatedFile (const FILEPATH &SourcePath, FILEPATH &RelatedPath, RELATEDORDER order, FILTER *pFilter=0)
static bool	LocateSettingsFile (const char *SettingsFileName, FILEPATH &SettingsFilePath, LOCATIONS PreferredLocation, LOCATIONS LegacyLocations=LOCATION_None)
static ERRVALUE	LocateTrueTypeFontFiles (FILEPATHLIST &TrueTypeFiles)
static ERRVALUE	MakeSettingsFilePath (const char *SettingsFileName, FILEPATH &SettingsFilePath, LOCATIONS locations)
static ERRVALUE	MakeTempFile (FILEPATH &TempFilePath, INT64 MinSize, bool LargestPath)
static ERRVALUE	MakeTempFile (FILEPATH &TempFilePath, INT64 MinSize, bool LargestPath, const MISTRING &basename, const char *extn="tmp")
static void	MissingFilePromptDisable ()
static void	MissingFilePromptEnable ()
static void	RegisterMountDelegate (DELEGATE_MOUNT delegate)
static void	RegisterPromptDelegate (DELEGATE_PROMPT delegate)

Detailed Description

Class used to search for files.

Member Typedef Documentation

typedef FastDelegate<void(FILEPATH&)> FILEFIND::DELEGATE_MOUNT

Delegate to mount file.

typedef FastDelegate<bool(FILEPATH&, FILEFIND::FILTER*, const MISTRING*) FILEFIND::DELEGATE_PROMPT)

Delegate to prompt user for file.

Returns:: true if path found/located, false if not.

Member Enumeration Documentation

enum FILEFIND::ADDPOSN

Placement of path in the search list.

Enumerator:

ADDPOSN_ToFront
ADDPOSN_ToBack

enum FILEFIND::LOCATIONS

Enumerator:

LOCATION_None
LOCATION_Locale	Active and default locale folders, if any, in that order.
LOCATION_Home	Home folder, if any.
LOCATION_Current	Current working directory.
LOCATION_Process	Folder containing process executable.
LOCATION_PATH	PATH environment variable.
LOCATION_Installation	Installation folder.
LOCATION_Settings_CurInst_CurUser	Settings for current 'installation', current user.
LOCATION_Settings_CurInst_AllUsers	Settings for current 'installation', all users.
LOCATION_Settings_AllInst_CurUser	Settings for all 'installations', current user.
LOCATION_Settings_AllInst_AllUsers	Settings for all 'installations', all users.
LOCATIONS_Executable
LOCATIONS_Reference	Executable file locations.
LOCATIONS_Temporary	Reference file locations. Temporary locations

enum FILEFIND::RELATEDORDER

Searching order for LocateRelatedPath.

Search order consists of up to 4 components. "Source" indicates the folder referred to by the SourcePath. "Original" indicates the original value of RelatedPath. "Media" replaces the media/filesystem component(s) of RelatedPath with those from SourcePath. "Tree" searches all subfolders of the SourcePath.

Enumerator:

RELATEDORDER_SourceOriginalMediaTree
RELATEDORDER_OriginalSourceMediaTree
RELATEDORDER_SourceMediaOriginalTree
RELATEDORDER_MediaSourceOriginalTree
RELATEDORDER_MediaTreeSourceOriginal
RELATEDORDER_NoPrompt	Don't prompt user for file if not found.

Constructor & Destructor Documentation

FILEFIND::FILEFIND ( LOCATIONS locations = LOCATION_None ) [explicit]

Construct with specified locations in standard order.

Specified locations will occur in the list in the following order. 1. Locale 2. Current 3. Process 4. PATH environment 5. Settings_CurInst_CurUser 6. Settings_AllInst_CurUser 7. Settings_CurInst_AllUsers 8. Settings_AllInst_AllUsers 9. Home Note that this order may be different than the search order used in the static Locate... methods.

Parameters:

locations

Locations to add to list

FILEFIND::FILEFIND ( const FILEFIND & rhs )

Copy constructor.

FILEFIND::~FILEFIND ( )

Destructor.

Member Function Documentation

void FILEFIND::AddEnvVar	(	const char *	EnvTag,
		ADDPOSN	AddPosn = `ADDPOSN_ToBack`,
		bool	NeedWritable = `false`
	)

Add environment variable items to the search list, uses system environment separator for multiple paths.

void FILEFIND::AddLocale	(	bool	IncludeDefault = `true`,
		ADDPOSN	AddPosn = `ADDPOSN_ToBack`
	)

Add locale paths to search list.

Regardless of position, the active locale will be searched before the default (English) locale.

Parameters:

IncludeDefault

Include default (enu) locale

void FILEFIND::AddPath	(	const FILEPATH &	path,
		ADDPOSN	AddPosn = `ADDPOSN_ToBack`,
		bool	NeedWritable = `false`
	)

Add a path to the search list.

void FILEFIND::AddString	(	const MISTRING &	mpath,
		ADDPOSN	AddPosn = `ADDPOSN_ToBack`,
		bool	NeedWritable = `false`,
		MIUNICODE	Separator = `0xFFFF`
	)

Add multiple separated strings to the search list.

static void FILEFIND::ClearMissingFileList ( ) [static]

Clear "missing file" list so next use of LocateRelatedFile may prompt user.

bool FILEFIND::CreatePath	(	const char *	name,
		FILEPATH &	path
	)			const

Create file path using the search list.

The first writable location in the list NOT already containing a file of the specified name will be used to generate the file path.

Returns:: 'True' if the file was created, 'false' if not

Parameters:

path

FILEPATH set to made file

bool FILEFIND::CreatePath	(	const MISTRING &	name,
		FILEPATH &	path
	)			const

Create file path using the search list.

The first writable location in the list NOT already containing a file of the specified name will be used to generate the file path.

Returns:: 'True' if the file was created, 'false' if not

Parameters:

path

FILEPATH set to made file

static ERRVALUE FILEFIND::GetDefaultTempFolder	(	FILEPATH &	Folder,
		bool	bCreateIfMissing
	)			`[static]`

Get the default temporay folder location.

This is currently only useful on Macintosh, where we put a "TNT Temporary Files" folder in the install folder along with the start icons. This function will return a path to that folder and optionally create it if missing.

const FILEPATHLIST& FILEFIND::GetPathList ( ) const [inline]

Get list of paths to search.

bool FILEFIND::IsEmpty ( ) const

Does the search list have any entries.

Returns:: 'True' if no entries in the list

static bool FILEFIND::LocateExecutableFile	(	const char *	ExecutableFileName,
		FILEPATH &	ExecutableFilePath
	)			`[static]`

Locate an executable file.

Searches LOCATIONS_Executable folders in the following order: 1. Current working directory. 2. Process executable path. 3. PATH environment variable.

Returns:: 'True' if file located

Parameters:

	ExecutableFileName	Name of file to search for
	ExecutableFilePath	Executable file RETURNED

bool FILEFIND::LocateFile	(	const MISTRING &	relfile,
		FILEPATH &	path
	)			const

Locate file using search list and a possible relative path.

Returns:: 'True' if the path was found, 'false' if not

Parameters:

	relfile	Relative path to locate
	path	Set to path if found

bool FILEFIND::LocateFile	(	const char *	name,
		FILEPATH &	path
	)			const

Locate file using search list.

Returns:: 'True' if the path was found, 'false' if not

Parameters:

	name	Name of file to locate
	path	Set to path if found

bool FILEFIND::LocateFiles	(	const MISTRING &	pattern,
		FILEPATHLIST &	PathList
	)			const

Locate files using search list and pattern.

Returns:: 'True' if the path was found, 'false' if not

Parameters:

PathList

List of files found

bool FILEFIND::LocatePath	(	FILTER &	filter,
		FILEPATH &	path
	)			const

Locate path using filter.

Returns:: 'True' if the path was found, 'false' if not

Parameters:

path

Set to path if found

static bool FILEFIND::LocateReferenceFile	(	const MISTRING &	ReferenceFileName,
		FILEPATH &	ReferenceFilePath,
		LOCATIONS	locations = `LOCATION_None`
	)			`[static]`

Locate a reference file using MISTRING name.

Searches folders in the following order: 1. locale/??? (Current locale) folder if LOCATION_Locale specified and not using 'enu' locale. 2. locale/enu (English) folder if LOCATION_Locale specified. 3. Current working directory. 4. Process executable path. 5. Product installation folder 6. Home path if LOCATION_Home specified.

Returns:: 'True' if file located

Parameters:

	ReferenceFileName	Name of file to search for
	ReferenceFilePath	Reference file RETURNED
	locations	Locations to search in addition to LOCATIONS_Reference

static bool FILEFIND::LocateReferenceFile	(	const char *	ReferenceFileName,
		FILEPATH &	ReferenceFilePath,
		LOCATIONS	locations = `LOCATION_None`
	)			`[static]`

Locate a reference file using char* name.

Searches folders in the following order: 1. locale/??? (Current locale) folder if LOCATION_Locale specified and not using 'enu' locale. 2. locale/enu (English) folder if LOCATION_Locale specified. 3. Current working directory. 4. Process executable path. 5. Product installation folder 6. Home path if LOCATION_Home specified.

Returns:: 'True' if file located

Parameters:

	ReferenceFileName	Name of file to search for
	ReferenceFilePath	Reference file RETURNED
	locations	Locations to search in addition to LOCATIONS_Reference

static bool FILEFIND::LocateRelatedFile	(	const FILEPATH &	SourcePath,
		FILEPATH &	RelatedPath,
		RELATEDORDER	order,
		FILTER *	pFilter = `0`
	)			`[static]`

Locate related file from another file.

Returns:: 'true' if file located, false if not

Parameters:

	SourcePath	Path to source file or starting folder
	RelatedPath	Related file to search for passed/returned
	order	Folder search order
	pFilter	Optional filter

static bool FILEFIND::LocateSettingsFile	(	const char *	SettingsFileName,
		FILEPATH &	SettingsFilePath,
		LOCATIONS	PreferredLocation,
		LOCATIONS	LegacyLocations = `LOCATION_None`
	)			`[static]`

Locate a 'settings' file using char* name.

Searches specified locations in the following order: 1. Settings_CurInst_CurUser (if specified or no other listed locations specified) 2. Settings_CurInst_AllUsers 3. Settings_AllInst_CurUser 4. Settings_AllInst_AllUsers 5. Current. 6. Process. In most cases only a single 'preferred' location should be specified. If the file is not found in the preferred location and any 'legacy' locations are specified, they will be searched, and if the file is found there, it will be copied to the preferred location.

Returns:: 'True' if file located

Parameters:

	SettingsFileName	Name of file to search for
	SettingsFilePath	Settings file RETURNED
	PreferredLocation	Preferred location(s) to search
	LegacyLocations	Legacy locations to search

static ERRVALUE FILEFIND::LocateTrueTypeFontFiles ( FILEPATHLIST & TrueTypeFiles ) [static]

Locate the available truetype font files on the current platform.

Parameters:

TrueTypeFiles

Locations of the truetype files on the platform RETURNED

static ERRVALUE FILEFIND::MakeSettingsFilePath	(	const char *	SettingsFileName,
		FILEPATH &	SettingsFilePath,
		LOCATIONS	locations
	)			`[static]`

Make 'settings' file path in first available location specified.

The first writable location NOT already containing a file of the specified name will be used to generate the file path. One or more of the following locations must be specified, which are tried in the following order: 1. Settings_CurInst_CurUser 2. Settings_CurInst_AllUsers 3. Settings_AllInst_CurUser 4. Settings_AllInst_AllUsers 5. Current 6. Process In most cases only a single specific location should be specified Does not actually create the file itself.

Parameters:

	SettingsFileName	Name of file
	SettingsFilePath	New reference file location RETURNED
	locations	Locations to search, must be one or more listed above

static ERRVALUE FILEFIND::MakeTempFile	(	FILEPATH &	TempFilePath,
		INT64	MinSize,
		bool	LargestPath
	)			`[static]`

Make a temporary file using default 'temp' base name.

An empty unopened file will be created using the returned path.

Parameters:

	TempFilePath	Path of created temp file
	MinSize	Minimum file size for the temp file
	LargestPath	Select largest path to create temp file in

static ERRVALUE FILEFIND::MakeTempFile	(	FILEPATH &	TempFilePath,
		INT64	MinSize,
		bool	LargestPath,
		const MISTRING &	basename,
		const char *	extn = `"tmp"`
	)			`[static]`

Make a temporary file.

An empty unopened file will be created using the returned path.

Parameters:

	TempFilePath	Path of created temp file
	MinSize	Minimum file size for the temp file
	LargestPath	Select largest path to create temp file in
	basename	Basename for the temp file
	extn	Default extension to use (no dot)

static void FILEFIND::MissingFilePromptDisable ( ) [static]

Disable prompt for missing file.

Increments count, match with MissingFilePromptEnable().

static void FILEFIND::MissingFilePromptEnable ( ) [static]

Enable prompt for missing file.

Decrements count.

FILEFIND& FILEFIND::operator= ( const FILEFIND & rhs )

Assignment.

static void FILEFIND::RegisterMountDelegate ( DELEGATE_MOUNT delegate ) [static]

Register delegate to call to request mount of file in LocateRelatedFile().

Parameters:

delegate

Delegate to call

static void FILEFIND::RegisterPromptDelegate ( DELEGATE_PROMPT delegate ) [static]

Register delegate to call when file can't be located in LocateRelatedFile().

Parameters:

delegate

Delegate to call

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

mi32/filefind.h

FILEFIND Class Reference

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation