Helper class to handle file operations. More...

#include <CCFileUtils.h>

Inheritance diagram for CCFileUtils:

Public Member Functions
virtual long	getClassTypeInfo ()
	Returns an unique ID for this class. More...

virtual	~CCFileUtils ()
	The destructor of CCFileUtils. More...

virtual void	purgeCachedEntries ()
	Purges the file searching cache. More...

local	purgeCachedEntries ()
	Purges the file searching cache. More...

virtual unsigned char *	getFileData (const char pszFileName, const char pszMode, unsigned long *pSize)
	Gets resource file data. More...

local	getFileData ( local pszFileName, local pszMode, local pSize)
	Gets resource file data. More...

virtual unsigned char *	getFileDataFromZip (const char pszZipFilePath, const char pszFileName, unsigned long *pSize)
	Gets resource file data from a zip file. More...

virtual std::string	fullPathForFilename (const char *pszFileName)
	Returns the fullpath for a given filename. More...

virtual void	loadFilenameLookupDictionaryFromFile (const char *filename)
	Loads the filenameLookup dictionary from the contents of a filename. More...

virtual void	setFilenameLookupDictionary (CCDictionary *pFilenameLookupDict)
	Sets the filenameLookup dictionary. More...

var	setFilenameLookupDictionary ( var pFilenameLookupDict)
	Sets the filenameLookup dictionary. More...

virtual const char *	fullPathFromRelativeFile (const char pszFilename, const char pszRelativeFile)
	Gets full path from a file name and the path of the reletive file. More...

local	fullPathFromRelativeFile ( local pszFilename, local pszRelativeFile)
	Gets full path from a file name and the path of the reletive file. More...

virtual void	setSearchResolutionsOrder (const std::vector< std::string > &searchResolutionsOrder)
	Sets the array that contains the search order of the resources. More...

virtual void	addSearchResolutionsOrder (const char *order)
	Append search order of the resources. More...

virtual const std::vector < std::string > &	getSearchResolutionsOrder ()
	Gets the array that contains the search order of the resources. More...

virtual void	setSearchPaths (const std::vector< std::string > &searchPaths)
	Sets the array of search paths. More...

virtual void	addSearchPath (const char *path)
	Adds a path to search paths. More...

var	addSearchPath ( var path)
	Adds a path to search paths. More...

local	addSearchPath ( local path)
	Adds a path to search paths. More...

virtual void	removeSearchPath (const char *path)
	Removes a path from search paths. More...

void	removeAllPaths ()
	Removes all paths. More...

virtual const std::vector < std::string > &	getSearchPaths ()
	Gets the array of search paths. More...

virtual std::string	getWritablePath ()=0
	Gets the writable path. More...

virtual bool	isFileExist (const std::string &strFilePath)=0
	Checks whether a file exists. More...

virtual bool	isAbsolutePath (const std::string &strPath)
	Checks whether the path is an absolute path. More...

var	isAbsolutePath ( var strPath)
	Checks whether the path is an absolute path. More...

virtual void	setPopupNotify (bool bNotify)
	Sets/Gets whether to pop-up a message box when failed to load an image. More...

virtual bool	isPopupNotify ()

Static Public Member Functions
static CCFileUtils *	sharedFileUtils ()
	Gets the instance of CCFileUtils. More...

local	sharedFileUtils ()
	Gets the instance of CCFileUtils. More...

static void	purgeFileUtils ()
	Destroys the instance of CCFileUtils. More...

var	purgeFileUtils ()
	Destroys the instance of CCFileUtils. More...

local	purgeFileUtils ()
	Destroys the instance of CCFileUtils. More...

Protected Member Functions
	CCFileUtils ()
	The default constructor. More...

	CCFileUtils ()
	The default constructor. More...

	CCFileUtils ()
	The default constructor. More...

virtual bool	init ()
	Initializes the instance of CCFileUtils. More...

var	init ()
	Initializes the instance of CCFileUtils. More...

local	init ()
	Initializes the instance of CCFileUtils. More...

virtual std::string	getNewFilename (const char *pszFileName)
	Gets the new filename from the filename lookup dictionary. More...

virtual std::string	getPathForFilename (const std::string &filename, const std::string &resolutionDirectory, const std::string &searchPath)
	Gets full path for filename, resolution directory and search path. More...

virtual std::string	getFullPathForDirectoryAndFilename (const std::string &strDirectory, const std::string &strFilename)
	Gets full path for the directory and the filename. More...

local	getFullPathForDirectoryAndFilename ( local strDirectory, local strFilename)
	Gets full path for the directory and the filename. More...

virtual CCDictionary *	createCCDictionaryWithContentsOfFile (const std::string &filename)
	Creates a dictionary by the contents of a file. More...

local	createCCDictionaryWithContentsOfFile ( local filename)
	Creates a dictionary by the contents of a file. More...

virtual bool	writeToFile (CCDictionary *dict, const std::string &fullPath)
	Write a dictionary to a plist file. More...

var	writeToFile ( var dict, var fullPath)
	Write a dictionary to a plist file. More...

local	writeToFile ( local dict, local fullPath)
	Write a dictionary to a plist file. More...

virtual CCArray *	createCCArrayWithContentsOfFile (const std::string &filename)
	Creates an array by the contents of a file. More...

var	createCCArrayWithContentsOfFile ( var filename)
	Creates an array by the contents of a file. More...

local	createCCArrayWithContentsOfFile ( local filename)
	Creates an array by the contents of a file. More...

Protected Attributes
CCDictionary *	m_pFilenameLookupDict
	Dictionary used to lookup filenames based on a key. More...

std::vector< std::string >	m_searchResolutionsOrderArray
	The vector contains resolution folders. More...

std::vector< std::string >	m_searchPathArray
	The vector contains search paths. More...

var	m_searchPathArray
	The vector contains search paths. More...

local	m_searchPathArray
	The vector contains search paths. More...

std::string	m_strDefaultResRootPath
	The default root path of resources. More...

var	m_strDefaultResRootPath
	The default root path of resources. More...

local	m_strDefaultResRootPath
	The default root path of resources. More...

std::map< std::string, std::string >	m_fullPathCache
	The full path cache. More...

Static Protected Attributes
static CCFileUtils *	s_sharedFileUtils
	The singleton pointer of CCFileUtils. More...

var	s_sharedFileUtils
	The singleton pointer of CCFileUtils. More...

local	s_sharedFileUtils
	The singleton pointer of CCFileUtils. More...

Friends
class	CCArray
class	CCDictionary

Detailed Description

Helper class to handle file operations.

Constructor & Destructor Documentation

virtual ~CCFileUtils ( )

virtual

The destructor of CCFileUtils.

CCFileUtils ( )

protected

The default constructor.

var CCFileUtils ( )

protected

The default constructor.

local CCFileUtils ( )

protected

The default constructor.

Member Function Documentation

virtual void addSearchPath ( const char * path )

virtual

Adds a path to search paths.

Since: v2.2

Reimplemented in CCFileUtilsWin32.

var addSearchPath ( var path )

virtual

Adds a path to search paths.

Since: v2.2

Reimplemented in CCFileUtilsWin32.

local addSearchPath ( local path )

virtual

Adds a path to search paths.

Since: v2.2

Reimplemented in CCFileUtilsWin32.

virtual void
addSearchResolutionsOrder ( const char * order )

virtual

Append search order of the resources.

See also: setSearchResolutionsOrder(), fullPathForFilename().

Since: v2.1

var addSearchResolutionsOrder ( var order )

virtual

Append search order of the resources.

See also: setSearchResolutionsOrder(), fullPathForFilename().

Since: v2.1

local addSearchResolutionsOrder ( local order )

virtual

Append search order of the resources.

See also: setSearchResolutionsOrder(), fullPathForFilename().

Since: v2.1

virtual CCArray*
createCCArrayWithContentsOfFile ( const std::string & filename )

protectedvirtual

Creates an array by the contents of a file.

Note: This method is used internally.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

var createCCArrayWithContentsOfFile ( var filename )

protectedvirtual

Creates an array by the contents of a file.

Note: This method is used internally.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

local
createCCArrayWithContentsOfFile ( local filename )

protectedvirtual

Creates an array by the contents of a file.

Note: This method is used internally.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

virtual CCDictionary*
createCCDictionaryWithContentsOfFile ( const std::string & filename )

protectedvirtual

Creates a dictionary by the contents of a file.

Note: This method is used internally.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

var
createCCDictionaryWithContentsOfFile ( var filename )

protectedvirtual

Creates a dictionary by the contents of a file.

Note: This method is used internally.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

local
createCCDictionaryWithContentsOfFile ( local filename )

protectedvirtual

Creates a dictionary by the contents of a file.

Note: This method is used internally.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

virtual std::string
fullPathForFilename ( const char * pszFileName )

virtual

Returns the fullpath for a given filename.

First it will try to get a new filename from the "filenameLookup" dictionary. If a new filename can't be found on the dictionary, it will use the original filename. Then it will try to obtain the full path of the filename using the CCFileUtils search rules: resolutions, and search paths. The file search is based on the array element order of search paths and resolution directories.

For instance:

We set two elements("/mnt/sdcard/", "internal_dir/") to search paths vector by setSearchPaths,
and set three elements("resources-ipadhd/", "resources-ipad/", "resources-iphonehd")
to resolutions vector by setSearchResolutionsOrder. The "internal_dir" is relative to "Resources/".

If we have a file named 'sprite.png', the mapping in fileLookup dictionary contains key: sprite.png -> value: sprite.pvr.gz. Firstly, it will replace 'sprite.png' with 'sprite.pvr.gz', then searching the file sprite.pvr.gz as follows:

/mnt/sdcard/resources-ipadhd/sprite.pvr.gz      (if not found, search next)
/mnt/sdcard/resources-ipad/sprite.pvr.gz        (if not found, search next)
/mnt/sdcard/resources-iphonehd/sprite.pvr.gz    (if not found, search next)
/mnt/sdcard/sprite.pvr.gz                       (if not found, search next)
internal_dir/resources-ipadhd/sprite.pvr.gz     (if not found, search next)
internal_dir/resources-ipad/sprite.pvr.gz       (if not found, search next)
internal_dir/resources-iphonehd/sprite.pvr.gz   (if not found, search next)
internal_dir/sprite.pvr.gz                      (if not found, return "sprite.png")

If the filename contains relative path like "gamescene/uilayer/sprite.png", and the mapping in fileLookup dictionary contains key: gamescene/uilayer/sprite.png -> value: gamescene/uilayer/sprite.pvr.gz. The file search order will be:

 /mnt/sdcard/gamescene/uilayer/resources-ipadhd/sprite.pvr.gz      (if not found, search next)
 /mnt/sdcard/gamescene/uilayer/resources-ipad/sprite.pvr.gz        (if not found, search next)
 /mnt/sdcard/gamescene/uilayer/resources-iphonehd/sprite.pvr.gz    (if not found, search next)
 /mnt/sdcard/gamescene/uilayer/sprite.pvr.gz                       (if not found, search next)
 internal_dir/gamescene/uilayer/resources-ipadhd/sprite.pvr.gz     (if not found, search next)
 internal_dir/gamescene/uilayer/resources-ipad/sprite.pvr.gz       (if not found, search next)
 internal_dir/gamescene/uilayer/resources-iphonehd/sprite.pvr.gz   (if not found, search next)
 internal_dir/gamescene/uilayer/sprite.pvr.gz                      (if not found, return "gamescene/uilayer/sprite.png")

If the new file can't be found on the file system, it will return the parameter pszFileName directly.

This method was added to simplify multiplatform support. Whether you are using cocos2d-js or any cross-compilation toolchain like StellaSDK or Apportable, you might need to load different resources for a given file in the different platforms.

Since: v2.1

Reimplemented in CCFileUtilsWin32.

var fullPathForFilename ( var pszFileName )

virtual

Returns the fullpath for a given filename.

First it will try to get a new filename from the "filenameLookup" dictionary. If a new filename can't be found on the dictionary, it will use the original filename. Then it will try to obtain the full path of the filename using the CCFileUtils search rules: resolutions, and search paths. The file search is based on the array element order of search paths and resolution directories.

For instance:

We set two elements("/mnt/sdcard/", "internal_dir/") to search paths vector by setSearchPaths,
and set three elements("resources-ipadhd/", "resources-ipad/", "resources-iphonehd")
to resolutions vector by setSearchResolutionsOrder. The "internal_dir" is relative to "Resources/".

If we have a file named 'sprite.png', the mapping in fileLookup dictionary contains key: sprite.png -> value: sprite.pvr.gz. Firstly, it will replace 'sprite.png' with 'sprite.pvr.gz', then searching the file sprite.pvr.gz as follows:

/mnt/sdcard/resources-ipadhd/sprite.pvr.gz      (if not found, search next)
/mnt/sdcard/resources-ipad/sprite.pvr.gz        (if not found, search next)
/mnt/sdcard/resources-iphonehd/sprite.pvr.gz    (if not found, search next)
/mnt/sdcard/sprite.pvr.gz                       (if not found, search next)
internal_dir/resources-ipadhd/sprite.pvr.gz     (if not found, search next)
internal_dir/resources-ipad/sprite.pvr.gz       (if not found, search next)
internal_dir/resources-iphonehd/sprite.pvr.gz   (if not found, search next)
internal_dir/sprite.pvr.gz                      (if not found, return "sprite.png")

If the filename contains relative path like "gamescene/uilayer/sprite.png", and the mapping in fileLookup dictionary contains key: gamescene/uilayer/sprite.png -> value: gamescene/uilayer/sprite.pvr.gz. The file search order will be:

 /mnt/sdcard/gamescene/uilayer/resources-ipadhd/sprite.pvr.gz      (if not found, search next)
 /mnt/sdcard/gamescene/uilayer/resources-ipad/sprite.pvr.gz        (if not found, search next)
 /mnt/sdcard/gamescene/uilayer/resources-iphonehd/sprite.pvr.gz    (if not found, search next)
 /mnt/sdcard/gamescene/uilayer/sprite.pvr.gz                       (if not found, search next)
 internal_dir/gamescene/uilayer/resources-ipadhd/sprite.pvr.gz     (if not found, search next)
 internal_dir/gamescene/uilayer/resources-ipad/sprite.pvr.gz       (if not found, search next)
 internal_dir/gamescene/uilayer/resources-iphonehd/sprite.pvr.gz   (if not found, search next)
 internal_dir/gamescene/uilayer/sprite.pvr.gz                      (if not found, return "gamescene/uilayer/sprite.png")

If the new file can't be found on the file system, it will return the parameter pszFileName directly.

This method was added to simplify multiplatform support. Whether you are using cocos2d-js or any cross-compilation toolchain like StellaSDK or Apportable, you might need to load different resources for a given file in the different platforms.

Since: v2.1

Reimplemented in CCFileUtilsWin32.

local fullPathForFilename ( local pszFileName )

virtual

Returns the fullpath for a given filename.

First it will try to get a new filename from the "filenameLookup" dictionary. If a new filename can't be found on the dictionary, it will use the original filename. Then it will try to obtain the full path of the filename using the CCFileUtils search rules: resolutions, and search paths. The file search is based on the array element order of search paths and resolution directories.

For instance:

We set two elements("/mnt/sdcard/", "internal_dir/") to search paths vector by setSearchPaths,
and set three elements("resources-ipadhd/", "resources-ipad/", "resources-iphonehd")
to resolutions vector by setSearchResolutionsOrder. The "internal_dir" is relative to "Resources/".

If we have a file named 'sprite.png', the mapping in fileLookup dictionary contains key: sprite.png -> value: sprite.pvr.gz. Firstly, it will replace 'sprite.png' with 'sprite.pvr.gz', then searching the file sprite.pvr.gz as follows:

/mnt/sdcard/resources-ipadhd/sprite.pvr.gz      (if not found, search next)
/mnt/sdcard/resources-ipad/sprite.pvr.gz        (if not found, search next)
/mnt/sdcard/resources-iphonehd/sprite.pvr.gz    (if not found, search next)
/mnt/sdcard/sprite.pvr.gz                       (if not found, search next)
internal_dir/resources-ipadhd/sprite.pvr.gz     (if not found, search next)
internal_dir/resources-ipad/sprite.pvr.gz       (if not found, search next)
internal_dir/resources-iphonehd/sprite.pvr.gz   (if not found, search next)
internal_dir/sprite.pvr.gz                      (if not found, return "sprite.png")

If the filename contains relative path like "gamescene/uilayer/sprite.png", and the mapping in fileLookup dictionary contains key: gamescene/uilayer/sprite.png -> value: gamescene/uilayer/sprite.pvr.gz. The file search order will be:

 /mnt/sdcard/gamescene/uilayer/resources-ipadhd/sprite.pvr.gz      (if not found, search next)
 /mnt/sdcard/gamescene/uilayer/resources-ipad/sprite.pvr.gz        (if not found, search next)
 /mnt/sdcard/gamescene/uilayer/resources-iphonehd/sprite.pvr.gz    (if not found, search next)
 /mnt/sdcard/gamescene/uilayer/sprite.pvr.gz                       (if not found, search next)
 internal_dir/gamescene/uilayer/resources-ipadhd/sprite.pvr.gz     (if not found, search next)
 internal_dir/gamescene/uilayer/resources-ipad/sprite.pvr.gz       (if not found, search next)
 internal_dir/gamescene/uilayer/resources-iphonehd/sprite.pvr.gz   (if not found, search next)
 internal_dir/gamescene/uilayer/sprite.pvr.gz                      (if not found, return "gamescene/uilayer/sprite.png")

If the new file can't be found on the file system, it will return the parameter pszFileName directly.

This method was added to simplify multiplatform support. Whether you are using cocos2d-js or any cross-compilation toolchain like StellaSDK or Apportable, you might need to load different resources for a given file in the different platforms.

Since: v2.1

Reimplemented in CCFileUtilsWin32.

virtual const char* fullPathFromRelativeFile	(	const char *	pszFilename,
		const char *	pszRelativeFile
	)

virtual

Gets full path from a file name and the path of the reletive file.

Parameters

pszFilename	The file name.
pszRelativeFile	The path of the relative file.

Returns: The full path. e.g. pszFilename: hello.png, pszRelativeFile: /User/path1/path2/hello.plist Return: /User/path1/path2/hello.pvr (If there a a key(hello.png)-value(hello.pvr) in FilenameLookup dictionary. )

var fullPathFromRelativeFile	(	var	pszFilename,
		var	pszRelativeFile
	)

virtual

Gets full path from a file name and the path of the reletive file.

Parameters

pszFilename	The file name.
pszRelativeFile	The path of the relative file.

Returns: The full path. e.g. pszFilename: hello.png, pszRelativeFile: /User/path1/path2/hello.plist Return: /User/path1/path2/hello.pvr (If there a a key(hello.png)-value(hello.pvr) in FilenameLookup dictionary. )

local fullPathFromRelativeFile	(	local	pszFilename,
		local	pszRelativeFile
	)

virtual

Gets full path from a file name and the path of the reletive file.

Parameters

pszFilename	The file name.
pszRelativeFile	The path of the relative file.

Returns: The full path. e.g. pszFilename: hello.png, pszRelativeFile: /User/path1/path2/hello.plist Return: /User/path1/path2/hello.pvr (If there a a key(hello.png)-value(hello.pvr) in FilenameLookup dictionary. )

virtual long getClassTypeInfo ( )

inlinevirtual

Returns an unique ID for this class.

Note: It's only used for JSBindings now.

Returns: The unique ID for this class.

Implements TypeInfo.

virtual unsigned char* getFileData	(	const char *	pszFileName,
		const char *	pszMode,
		unsigned long *	pSize
	)

virtual

Gets resource file data.

Parameters

[in]	pszFileName	The resource file name which contains the path.
[in]	pszMode	The read mode of the file.
[out]	pSize	If the file read operation succeeds, it will be the data size, otherwise 0.

Returns: Upon success, a pointer to the data is returned, otherwise NULL.

Warning: Recall: you are responsible for calling delete[] on any Non-NULL pointer returned.

Reimplemented in CCFileUtilsAndroid, and CCFileUtilsMarmalade.

local getFileData	(	local	pszFileName,
		local	pszMode,
		local	pSize
	)

virtual

Gets resource file data.

Parameters

[in]	pszFileName	The resource file name which contains the path.
[in]	pszMode	The read mode of the file.
[out]	pSize	If the file read operation succeeds, it will be the data size, otherwise 0.

Returns: Upon success, a pointer to the data is returned, otherwise NULL.

Warning: Recall: you are responsible for calling delete[] on any Non-NULL pointer returned.

Reimplemented in CCFileUtilsAndroid, and CCFileUtilsMarmalade.

virtual unsigned char* getFileDataFromZip	(	const char *	pszZipFilePath,
		const char *	pszFileName,
		unsigned long *	pSize
	)

virtual

Gets resource file data from a zip file.

Parameters

[in]	pszFileName	The resource file name which contains the relative path of the zip file.
[out]	pSize	If the file read operation succeeds, it will be the data size, otherwise 0.

Returns: Upon success, a pointer to the data is returned, otherwise NULL.

Warning: Recall: you are responsible for calling delete[] on any Non-NULL pointer returned.

local getFileDataFromZip	(	local	pszZipFilePath,
		local	pszFileName,
		local	pSize
	)

virtual

Gets resource file data from a zip file.

Parameters

[in]	pszFileName	The resource file name which contains the relative path of the zip file.
[out]	pSize	If the file read operation succeeds, it will be the data size, otherwise 0.

Returns: Upon success, a pointer to the data is returned, otherwise NULL.

Warning: Recall: you are responsible for calling delete[] on any Non-NULL pointer returned.

virtual std::string getFullPathForDirectoryAndFilename	(	const std::string &	strDirectory,
		const std::string &	strFilename
	)

protectedvirtual

Gets full path for the directory and the filename.

Note: Only iOS and Mac need to override this method since they are using [[NSBundle mainBundle] pathForResource: ofType: inDirectory:] to make a full path. Other platforms will use the default implementation of this method.

Parameters

strDirectory	The directory contains the file we are looking for.
strFilename	The name of the file.

Returns: The full path of the file, if the file can't be found, it will return an empty string.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

var getFullPathForDirectoryAndFilename	(	var	strDirectory,
		var	strFilename
	)

protectedvirtual

Gets full path for the directory and the filename.

Note: Only iOS and Mac need to override this method since they are using [[NSBundle mainBundle] pathForResource: ofType: inDirectory:] to make a full path. Other platforms will use the default implementation of this method.

Parameters

strDirectory	The directory contains the file we are looking for.
strFilename	The name of the file.

Returns: The full path of the file, if the file can't be found, it will return an empty string.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

local getFullPathForDirectoryAndFilename	(	local	strDirectory,
		local	strFilename
	)

protectedvirtual

Gets full path for the directory and the filename.

Note: Only iOS and Mac need to override this method since they are using [[NSBundle mainBundle] pathForResource: ofType: inDirectory:] to make a full path. Other platforms will use the default implementation of this method.

Parameters

strDirectory	The directory contains the file we are looking for.
strFilename	The name of the file.

Returns: The full path of the file, if the file can't be found, it will return an empty string.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

virtual std::string getNewFilename ( const char * pszFileName )

protectedvirtual

Gets the new filename from the filename lookup dictionary.

Parameters

pszFileName The original filename.

Returns: The new filename after searching in the filename lookup dictionary. If the original filename wasn't in the dictionary, it will return the original filename.

var getNewFilename ( var pszFileName )

protectedvirtual

Gets the new filename from the filename lookup dictionary.

Parameters

pszFileName The original filename.

Returns: The new filename after searching in the filename lookup dictionary. If the original filename wasn't in the dictionary, it will return the original filename.

local getNewFilename ( local pszFileName )

protectedvirtual

Gets the new filename from the filename lookup dictionary.

Parameters

pszFileName The original filename.

Returns: The new filename after searching in the filename lookup dictionary. If the original filename wasn't in the dictionary, it will return the original filename.

virtual std::string getPathForFilename	(	const std::string &	filename,
		const std::string &	resolutionDirectory,
		const std::string &	searchPath
	)

protectedvirtual

Gets full path for filename, resolution directory and search path.

Parameters

filename	The file name.
resolutionDirectory	The resolution directory.
searchPath	The search path.

Returns: The full path of the file. It will return an empty string if the full path of the file doesn't exist.

Reimplemented in CCFileUtilsWin32.

var getPathForFilename	(	var	filename,
		var	resolutionDirectory,
		var	searchPath
	)

protectedvirtual

Gets full path for filename, resolution directory and search path.

Parameters

filename	The file name.
resolutionDirectory	The resolution directory.
searchPath	The search path.

Returns: The full path of the file. It will return an empty string if the full path of the file doesn't exist.

Reimplemented in CCFileUtilsWin32.

local getPathForFilename	(	local	filename,
		local	resolutionDirectory,
		local	searchPath
	)

protectedvirtual

Gets full path for filename, resolution directory and search path.

Parameters

filename	The file name.
resolutionDirectory	The resolution directory.
searchPath	The search path.

Returns: The full path of the file. It will return an empty string if the full path of the file doesn't exist.

Reimplemented in CCFileUtilsWin32.

virtual const std::vector
<std::string>& getSearchPaths ( )

virtual

Gets the array of search paths.

Returns: The array of search paths.

See also: fullPathForFilename(const char*).

virtual const std::vector
<std::string>
& getSearchResolutionsOrder ( )

virtual

Gets the array that contains the search order of the resources.

See also: setSearchResolutionsOrder(const std::vector<std::string>&), fullPathForFilename(const char*).

Since: v2.1

virtual std::string getWritablePath ( )

pure virtual

Gets the writable path.

Returns: The path that can be write/read a file in

Implemented in CCFileUtilsAndroid, CCFileUtilsTizen, CCFileUtilsLinux, CCFileUtilsWinRT, CCFileUtilsBlackberry, CCFileUtilsEmscripten, CCFileUtilsWin32, CCFileUtilsMarmalade, CCFileUtilsNaCl, CCFileUtilsIOS, and CCFileUtilsMac.

var getWritablePath ( )

pure virtual

Gets the writable path.

Returns: The path that can be write/read a file in

Implemented in CCFileUtilsAndroid, CCFileUtilsTizen, CCFileUtilsLinux, CCFileUtilsWinRT, CCFileUtilsBlackberry, CCFileUtilsEmscripten, CCFileUtilsWin32, CCFileUtilsMarmalade, CCFileUtilsNaCl, CCFileUtilsIOS, and CCFileUtilsMac.

virtual bool init ( )

protectedvirtual

Initializes the instance of CCFileUtils.

It will set m_searchPathArray and m_searchResolutionsOrderArray to default values.

Note: When you are porting Cocos2d-x to a new platform, you may need to take care of this method. You could assign a default value to m_strDefaultResRootPath in the subclass of CCFileUtils(e.g. CCFileUtilsAndroid). Then invoke the CCFileUtils::init().

Returns: true if successed, otherwise it returns false.

Reimplemented in CCFileUtilsAndroid, CCFileUtilsTizen, CCFileUtilsLinux, CCFileUtilsWinRT, CCFileUtilsBlackberry, CCFileUtilsEmscripten, CCFileUtilsWin32, and CCFileUtilsNaCl.

var init ( )

protectedvirtual

Initializes the instance of CCFileUtils.

It will set m_searchPathArray and m_searchResolutionsOrderArray to default values.

Note: When you are porting Cocos2d-x to a new platform, you may need to take care of this method. You could assign a default value to m_strDefaultResRootPath in the subclass of CCFileUtils(e.g. CCFileUtilsAndroid). Then invoke the CCFileUtils::init().

Returns: true if successed, otherwise it returns false.

Reimplemented in CCFileUtilsAndroid, CCFileUtilsTizen, CCFileUtilsLinux, CCFileUtilsWinRT, CCFileUtilsBlackberry, CCFileUtilsEmscripten, CCFileUtilsWin32, and CCFileUtilsNaCl.

local init ( )

protectedvirtual

Initializes the instance of CCFileUtils.

It will set m_searchPathArray and m_searchResolutionsOrderArray to default values.

Note: When you are porting Cocos2d-x to a new platform, you may need to take care of this method. You could assign a default value to m_strDefaultResRootPath in the subclass of CCFileUtils(e.g. CCFileUtilsAndroid). Then invoke the CCFileUtils::init().

Returns: true if successed, otherwise it returns false.

Reimplemented in CCFileUtilsAndroid, CCFileUtilsTizen, CCFileUtilsLinux, CCFileUtilsWinRT, CCFileUtilsBlackberry, CCFileUtilsEmscripten, CCFileUtilsWin32, and CCFileUtilsNaCl.

virtual bool isAbsolutePath ( const std::string & strPath )

virtual

Checks whether the path is an absolute path.

Note: On Android, if the parameter passed in is relative to "assets/", this method will treat it as an absolute path. Also on Blackberry, path starts with "app/native/Resources/" is treated as an absolute path.

Parameters

strPath The path that needs to be checked.

Returns: true if it's an absolute path, otherwise it will return false.

Reimplemented in CCFileUtilsAndroid, CCFileUtilsWinRT, CCFileUtilsBlackberry, CCFileUtilsEmscripten, CCFileUtilsWin32, CCFileUtilsMarmalade, CCFileUtilsIOS, and CCFileUtilsMac.

var isAbsolutePath ( var strPath )

virtual

Checks whether the path is an absolute path.

Note: On Android, if the parameter passed in is relative to "assets/", this method will treat it as an absolute path. Also on Blackberry, path starts with "app/native/Resources/" is treated as an absolute path.

Parameters

strPath The path that needs to be checked.

Returns: true if it's an absolute path, otherwise it will return false.

Reimplemented in CCFileUtilsAndroid, CCFileUtilsWinRT, CCFileUtilsBlackberry, CCFileUtilsEmscripten, CCFileUtilsWin32, CCFileUtilsMarmalade, CCFileUtilsIOS, and CCFileUtilsMac.

virtual bool isFileExist ( const std::string & strFilePath )

pure virtual

Checks whether a file exists.

Note: If a relative path was passed in, it will be inserted a default root path at the beginning.

Parameters

strFilePath The path of the file, it could be a relative or absolute path.

Returns: true if the file exists, otherwise it will return false.

Implemented in CCFileUtilsAndroid, CCFileUtilsTizen, CCFileUtilsLinux, CCFileUtilsWinRT, CCFileUtilsBlackberry, CCFileUtilsEmscripten, CCFileUtilsWin32, CCFileUtilsMarmalade, CCFileUtilsNaCl, CCFileUtilsIOS, and CCFileUtilsMac.

var isFileExist ( var strFilePath )

pure virtual

Checks whether a file exists.

Note: If a relative path was passed in, it will be inserted a default root path at the beginning.

Parameters

strFilePath The path of the file, it could be a relative or absolute path.

Returns: true if the file exists, otherwise it will return false.

Implemented in CCFileUtilsAndroid, CCFileUtilsTizen, CCFileUtilsLinux, CCFileUtilsWinRT, CCFileUtilsBlackberry, CCFileUtilsEmscripten, CCFileUtilsWin32, CCFileUtilsMarmalade, CCFileUtilsNaCl, CCFileUtilsIOS, and CCFileUtilsMac.

virtual bool isPopupNotify ( )

virtual

var isPopupNotify ( )

virtual

local isPopupNotify ( )

virtual

virtual void
loadFilenameLookupDictionaryFromFile ( const char * filename )

virtual

Loads the filenameLookup dictionary from the contents of a filename.

Note: The plist file name should follow the format below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>filenames</key>
    <dict>
        <key>sounds/click.wav</key>
        <string>sounds/click.caf</string>
        <key>sounds/endgame.wav</key>
        <string>sounds/endgame.caf</string>
        <key>sounds/gem-0.wav</key>
        <string>sounds/gem-0.caf</string>
    </dict>
    <key>metadata</key>
    <dict>
        <key>version</key>
        <integer>1</integer>
    </dict>
</dict>
</plist>

Parameters

filename The plist file name.

Since: v2.1

var
loadFilenameLookupDictionaryFromFile ( var filename )

virtual

Loads the filenameLookup dictionary from the contents of a filename.

Note: The plist file name should follow the format below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>filenames</key>
    <dict>
        <key>sounds/click.wav</key>
        <string>sounds/click.caf</string>
        <key>sounds/endgame.wav</key>
        <string>sounds/endgame.caf</string>
        <key>sounds/gem-0.wav</key>
        <string>sounds/gem-0.caf</string>
    </dict>
    <key>metadata</key>
    <dict>
        <key>version</key>
        <integer>1</integer>
    </dict>
</dict>
</plist>

Parameters

filename The plist file name.

Since: v2.1

local
loadFilenameLookupDictionaryFromFile ( local filename )

virtual

Loads the filenameLookup dictionary from the contents of a filename.

Note: The plist file name should follow the format below:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>filenames</key>
    <dict>
        <key>sounds/click.wav</key>
        <string>sounds/click.caf</string>
        <key>sounds/endgame.wav</key>
        <string>sounds/endgame.caf</string>
        <key>sounds/gem-0.wav</key>
        <string>sounds/gem-0.caf</string>
    </dict>
    <key>metadata</key>
    <dict>
        <key>version</key>
        <integer>1</integer>
    </dict>
</dict>
</plist>

Parameters

filename The plist file name.

Since: v2.1

virtual void purgeCachedEntries ( )

virtual

Purges the file searching cache.

Note: It should be invoked after the resources were updated. For instance, in the CocosPlayer sample, every time you run application from CocosBuilder, All the resources will be downloaded to the writable folder, before new js app launchs, this method should be invoked to clean the file search cache.

var purgeCachedEntries ( )

virtual

Purges the file searching cache.

Note: It should be invoked after the resources were updated. For instance, in the CocosPlayer sample, every time you run application from CocosBuilder, All the resources will be downloaded to the writable folder, before new js app launchs, this method should be invoked to clean the file search cache.

local purgeCachedEntries ( )

virtual

Purges the file searching cache.

Note: It should be invoked after the resources were updated. For instance, in the CocosPlayer sample, every time you run application from CocosBuilder, All the resources will be downloaded to the writable folder, before new js app launchs, this method should be invoked to clean the file search cache.

static void purgeFileUtils ( )

static

Destroys the instance of CCFileUtils.

var purgeFileUtils ( )

static

Destroys the instance of CCFileUtils.

local purgeFileUtils ( )

static

Destroys the instance of CCFileUtils.

void removeAllPaths ( )

Removes all paths.

Since: v2.2

var removeAllPaths ( )

Removes all paths.

Since: v2.2

virtual void removeSearchPath ( const char * path )

virtual

Removes a path from search paths.

Since: v2.2

Reimplemented in CCFileUtilsWin32.

var removeSearchPath ( var path )

virtual

Removes a path from search paths.

Since: v2.2

Reimplemented in CCFileUtilsWin32.

virtual void
setFilenameLookupDictionary ( CCDictionary * pFilenameLookupDict )

virtual

Sets the filenameLookup dictionary.

Parameters

pFilenameLookupDict The dictionary for replacing filename.

Since: v2.1

var setFilenameLookupDictionary ( var pFilenameLookupDict )

virtual

Sets the filenameLookup dictionary.

Parameters

pFilenameLookupDict The dictionary for replacing filename.

Since: v2.1

virtual void setPopupNotify ( bool bNotify )

virtual

Sets/Gets whether to pop-up a message box when failed to load an image.

var setPopupNotify ( var bNotify )

virtual

Sets/Gets whether to pop-up a message box when failed to load an image.

local setPopupNotify ( local bNotify )

virtual

Sets/Gets whether to pop-up a message box when failed to load an image.

virtual void setSearchPaths ( const std::vector< std::string > & searchPaths )

virtual

Sets the array of search paths.

You can use this array to modify the search path of the resources. If you want to use "themes" or search resources in the "cache", you can do it easily by adding new entries in this array.

Note: This method could access relative path and absolute path. If the relative path was passed to the vector, CCFileUtils will add the default resource directory before the relative path. For instance: On Android, the default resource root path is "assets/". If "/mnt/sdcard/" and "resources-large" were set to the search paths vector, "resources-large" will be converted to "assets/resources-large" since it was a relative path.

Parameters

searchPaths The array contains search paths.

See also: fullPathForFilename(const char*)

Since: v2.1

virtual void
setSearchResolutionsOrder ( const std::vector< std::string > & searchResolutionsOrder )

virtual

Sets the array that contains the search order of the resources.

Parameters

searchResolutionsOrder The source array that contains the search order of the resources.

See also: getSearchResolutionsOrder(void), fullPathForFilename(const char*).

Since: v2.1

static CCFileUtils* sharedFileUtils ( )

static

Gets the instance of CCFileUtils.

var getInstance ( )

static

Gets the instance of CCFileUtils.

local sharedFileUtils ( )

static

Gets the instance of CCFileUtils.

virtual bool writeToFile	(	CCDictionary *	dict,
		const std::string &	fullPath
	)

protectedvirtual

Write a dictionary to a plist file.

Note: This method is used internally.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

var writeToFile	(	var	dict,
		var	fullPath
	)

protectedvirtual

Write a dictionary to a plist file.

Note: This method is used internally.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

local writeToFile	(	local	dict,
		local	fullPath
	)

protectedvirtual

Write a dictionary to a plist file.

Note: This method is used internally.

Reimplemented in CCFileUtilsIOS, and CCFileUtilsMac.

Friends And Related Function Documentation

friend class CCArray

friend

var CCArray

friend

local CCArray

friend

friend class CCDictionary

friend

var CCDictionary

friend

local CCDictionary

friend

Member Data Documentation

std::map<std::string,
std::string> m_fullPathCache

protected

The full path cache.

When a file is found, it will be added into this cache. This variable is used for improving the performance of file search.

var m_fullPathCache

protected

The full path cache.

When a file is found, it will be added into this cache. This variable is used for improving the performance of file search.

local m_fullPathCache

protected

The full path cache.

When a file is found, it will be added into this cache. This variable is used for improving the performance of file search.

CCDictionary* m_pFilenameLookupDict

protected

Dictionary used to lookup filenames based on a key.

It is used internally by the following methods:

std::string fullPathForFilename(const char*);

Since: v2.1

std::vector<std::string>
m_searchPathArray

protected

The vector contains search paths.

The lower index of the element in this vector, the higher priority for this search path.

var m_searchPathArray

protected

The vector contains search paths.

The lower index of the element in this vector, the higher priority for this search path.

local m_searchPathArray

protected

The vector contains search paths.

The lower index of the element in this vector, the higher priority for this search path.

std::vector<std::string>
m_searchResolutionsOrderArray

protected

The vector contains resolution folders.

The lower index of the element in this vector, the higher priority for this resolution directory.

var m_searchResolutionsOrderArray

protected

The vector contains resolution folders.

The lower index of the element in this vector, the higher priority for this resolution directory.

local m_searchResolutionsOrderArray

protected

The vector contains resolution folders.

The lower index of the element in this vector, the higher priority for this resolution directory.

std::string m_strDefaultResRootPath

protected

The default root path of resources.

If the default root path of resources needs to be changed, do it in the init method of CCFileUtils's subclass. For instance: On Android, the default root path of resources will be assigned with "assets/" in CCFileUtilsAndroid::init(). Similarly on Blackberry, we assign "app/native/Resources/" to this variable in CCFileUtilsBlackberry::init().

var m_strDefaultResRootPath

protected

The default root path of resources.

If the default root path of resources needs to be changed, do it in the init method of CCFileUtils's subclass. For instance: On Android, the default root path of resources will be assigned with "assets/" in CCFileUtilsAndroid::init(). Similarly on Blackberry, we assign "app/native/Resources/" to this variable in CCFileUtilsBlackberry::init().

local m_strDefaultResRootPath

protected

The default root path of resources.

If the default root path of resources needs to be changed, do it in the init method of CCFileUtils's subclass. For instance: On Android, the default root path of resources will be assigned with "assets/" in CCFileUtilsAndroid::init(). Similarly on Blackberry, we assign "app/native/Resources/" to this variable in CCFileUtilsBlackberry::init().

CCFileUtils* s_sharedFileUtils

staticprotected

The singleton pointer of CCFileUtils.

var s_sharedFileUtils

staticprotected

The singleton pointer of CCFileUtils.

local s_sharedFileUtils

staticprotected

The singleton pointer of CCFileUtils.

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

/Users/guanghui/cocos2d-x/cocos2dx/platform/CCFileUtils.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation