Helper class to handle file operations. More...

#include <CCFileUtils.h>

Inheritance diagram for FileUtils:

Public Member Functions
virtual	~FileUtils ()
	The destructor of FileUtils. More...

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

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

virtual std::string	getStringFromFile (const std::string &filename)
	Gets string from a file. More...

virtual Data	getDataFromFile (const std::string &filename)
	Creates binary data from a file. More...

local	getDataFromFile ( local filename)
	Creates binary data from a file. More...

virtual CC_DEPRECATED_ATTRIBUTE unsigned char *	getFileData (const std::string &filename, const char mode, ssize_t size)
	Gets resource file data. More...

var	getFileData ( var filename, var mode, var size)
	Gets resource file data. More...

local	getFileData ( local filename, local mode, local size)
	Gets resource file data. More...

virtual unsigned char *	getFileDataFromZip (const std::string &zipFilePath, const std::string &filename, ssize_t *size)
	Gets resource file data from a zip file. More...

var	getFileDataFromZip ( var zipFilePath, var filename, var size)
	Gets resource file data from a zip file. More...

local	getFileDataFromZip ( local zipFilePath, local filename, local size)
	Gets resource file data from a zip file. More...

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

local	fullPathForFilename ( local filename)
	Returns the fullpath for a given filename. More...

virtual void	loadFilenameLookupDictionaryFromFile (const std::string &filename)
	Loads the filenameLookup dictionary from the contents of a filename. More...

virtual void	setFilenameLookupDictionary (const ValueMap &filenameLookupDict)
	Sets the filenameLookup dictionary. More...

virtual std::string	fullPathFromRelativeFile (const std::string &filename, const std::string &relativeFile)
	Gets full path from a file name and the path of the reletive file. More...

local	fullPathFromRelativeFile ( local filename, local relativeFile)
	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 std::string &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...

var	setSearchPaths ( var searchPaths)
	Sets the array of search paths. More...

void	addSearchPath (const std::string &path)
	Add search path. More...

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

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

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

local	isFileExist ( local filePath)
	Checks whether a file exists. More...

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

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

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

virtual bool	isPopupNotify ()
virtual ValueMap	getValueMapFromFile (const std::string &filename)
	Converts the contents of a file to a ValueMap. More...

local	getValueMapFromFile ( local filename)
	Converts the contents of a file to a ValueMap. More...

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

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

virtual ValueVector	getValueVectorFromFile (const std::string &filename)
	Converts the contents of a file to a ValueVector. More...

const std::unordered_map < std::string, std::string > &	getFullPathCache () const
	Returns the full path cache. More...

Static Public Member Functions
static FileUtils *	getInstance ()
	Gets the instance of FileUtils. More...

local	getInstance ()
	Gets the instance of FileUtils. More...

static void	destroyInstance ()
	Destroys the instance of FileUtils. More...

static CC_DEPRECATED_ATTRIBUTE FileUtils *	sharedFileUtils ()
local	sharedFileUtils ()
static CC_DEPRECATED_ATTRIBUTE void	purgeFileUtils ()
local	purgeFileUtils ()

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

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

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

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

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

var	getNewFilename ( var filename)
	Gets the new filename from the filename lookup dictionary. More...

local	getNewFilename ( local filename)
	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 &directory, const std::string &filename)
	Gets full path for the directory and the filename. More...

Protected Attributes
ValueMap	_filenameLookupDict
	Dictionary used to lookup filenames based on a key. More...

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

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

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

std::unordered_map < std::string, std::string >	_fullPathCache
	The full path cache. More...

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

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

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

Detailed Description

Helper class to handle file operations.

Constructor & Destructor Documentation

virtual ~FileUtils ( )

virtual

The destructor of FileUtils.

FileUtils ( )

protected

The default constructor.

var FileUtils ( )

protected

The default constructor.

local FileUtils ( )

protected

The default constructor.

Member Function Documentation

void addSearchPath ( const std::string & path)

Add search path.

Since: v2.1

var addSearchPath ( var path)

Add search path.

Since: v2.1

local addSearchPath ( local path)

Add search path.

Since: v2.1

virtual void
addSearchResolutionsOrder ( const std::string & 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

static void destroyInstance ( )

static

Destroys the instance of FileUtils.

var destroyInstance ( )

static

Destroys the instance of FileUtils.

local destroyInstance ( )

static

Destroys the instance of FileUtils.

virtual std::string
fullPathForFilename ( const std::string & filename)

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 FileUtils 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 filename 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

var fullPathForFilename ( var filename)

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 FileUtils 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 filename 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

local fullPathForFilename ( local filename)

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 FileUtils 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 filename 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

virtual std::string fullPathFromRelativeFile	(	const std::string &	filename,
		const std::string &	relativeFile
	)

virtual

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

Parameters

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

Returns: The full path. e.g. filename: 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	filename,
		var	relativeFile
	)

virtual

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

Parameters

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

Returns: The full path. e.g. filename: 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	filename,
		local	relativeFile
	)

virtual

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

Parameters

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

Returns: The full path. e.g. filename: 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 Data getDataFromFile ( const std::string & filename)

virtual

Creates binary data from a file.

Returns: A data object.

Reimplemented in FileUtilsWin32, and FileUtilsAndroid.

var getDataFromFile ( var filename)

virtual

Creates binary data from a file.

Returns: A data object.

Reimplemented in FileUtilsWin32, and FileUtilsAndroid.

local getDataFromFile ( local filename)

virtual

Creates binary data from a file.

Returns: A data object.

Reimplemented in FileUtilsWin32, and FileUtilsAndroid.

virtual CC_DEPRECATED_ATTRIBUTE unsigned char* getFileData	(	const std::string &	filename,
		const char *	mode,
		ssize_t *	size
	)

virtual

Gets resource file data.

Parameters

[in]	filename	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 free() on any Non-NULL pointer returned.

Reimplemented in FileUtilsWin32, and FileUtilsAndroid.

var getFileData	(	var	filename,
		var	mode,
		var	size
	)

virtual

Gets resource file data.

Parameters

[in]	filename	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 free() on any Non-NULL pointer returned.

Reimplemented in FileUtilsWin32, and FileUtilsAndroid.

local getFileData	(	local	filename,
		local	mode,
		local	size
	)

virtual

Gets resource file data.

Parameters

[in]	filename	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 free() on any Non-NULL pointer returned.

Reimplemented in FileUtilsWin32, and FileUtilsAndroid.

virtual unsigned char* getFileDataFromZip	(	const std::string &	zipFilePath,
		const std::string &	filename,
		ssize_t *	size
	)

virtual

Gets resource file data from a zip file.

Parameters

[in]	filename	The resource file name which contains the relative path of the zip file.
[out]	size	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 nullptr.

Warning: Recall: you are responsible for calling free() on any Non-nullptr pointer returned.

var getFileDataFromZip	(	var	zipFilePath,
		var	filename,
		var	size
	)

virtual

Gets resource file data from a zip file.

Parameters

[in]	filename	The resource file name which contains the relative path of the zip file.
[out]	size	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 nullptr.

Warning: Recall: you are responsible for calling free() on any Non-nullptr pointer returned.

local getFileDataFromZip	(	local	zipFilePath,
		local	filename,
		local	size
	)

virtual

Gets resource file data from a zip file.

Parameters

[in]	filename	The resource file name which contains the relative path of the zip file.
[out]	size	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 nullptr.

Warning: Recall: you are responsible for calling free() on any Non-nullptr pointer returned.

const std::unordered_map
<std::string, std::string>
& getFullPathCache ( ) const

inline

Returns the full path cache.

var getFullPathCache ( )

inline

Returns the full path cache.

local getFullPathCache ( )

inline

Returns the full path cache.

virtual std::string getFullPathForDirectoryAndFilename	(	const std::string &	directory,
		const std::string &	filename
	)

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 FileUtilsWin32, and FileUtilsApple.

var getFullPathForDirectoryAndFilename	(	var	directory,
		var	filename
	)

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 FileUtilsWin32, and FileUtilsApple.

local getFullPathForDirectoryAndFilename	(	local	directory,
		local	filename
	)

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 FileUtilsWin32, and FileUtilsApple.

static FileUtils* getInstance ( )

static

Gets the instance of FileUtils.

var getInstance ( )

static

Gets the instance of FileUtils.

local getInstance ( )

static

Gets the instance of FileUtils.

virtual std::string getNewFilename ( const std::string & filename)

protectedvirtual

Gets the new filename from the filename lookup dictionary.

It is possible to have a override names.

Parameters

filename 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 filename)

protectedvirtual

Gets the new filename from the filename lookup dictionary.

It is possible to have a override names.

Parameters

filename 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 filename)

protectedvirtual

Gets the new filename from the filename lookup dictionary.

It is possible to have a override names.

Parameters

filename 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 FileUtilsWin32.

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 FileUtilsWin32.

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 FileUtilsWin32.

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

virtual

Gets the array of search paths.

Returns: The array of search paths.

See Also: fullPathForFilename(const char*).

var 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

var 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
getStringFromFile ( const std::string & filename)

virtual

Gets string from a file.

Reimplemented in FileUtilsWin32, and FileUtilsAndroid.

var getStringFromFile ( var filename)

virtual

Gets string from a file.

Reimplemented in FileUtilsWin32, and FileUtilsAndroid.

local getStringFromFile ( local filename)

virtual

Gets string from a file.

Reimplemented in FileUtilsWin32, and FileUtilsAndroid.

virtual ValueMap
getValueMapFromFile ( const std::string & filename)

virtual

Converts the contents of a file to a ValueMap.

Note: This method is used internally.

Reimplemented in FileUtilsApple.

var getValueMapFromFile ( var filename)

virtual

Converts the contents of a file to a ValueMap.

Note: This method is used internally.

Reimplemented in FileUtilsApple.

local getValueMapFromFile ( local filename)

virtual

Converts the contents of a file to a ValueMap.

Note: This method is used internally.

Reimplemented in FileUtilsApple.

virtual ValueVector
getValueVectorFromFile ( const std::string & filename)

virtual

Converts the contents of a file to a ValueVector.

Note: This method is used internally.

Reimplemented in FileUtilsApple.

var getValueVectorFromFile ( var filename)

virtual

Converts the contents of a file to a ValueVector.

Note: This method is used internally.

Reimplemented in FileUtilsApple.

local getValueVectorFromFile ( local filename)

virtual

Converts the contents of a file to a ValueVector.

Note: This method is used internally.

Reimplemented in FileUtilsApple.

virtual std::string getWritablePath ( ) const

pure virtual

Gets the writable path.

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

Implemented in FileUtilsAndroid, FileUtilsLinux, FileUtilsWin32, and FileUtilsApple.

var getWritablePath ( )

pure virtual

Gets the writable path.

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

Implemented in FileUtilsAndroid, FileUtilsLinux, FileUtilsWin32, and FileUtilsApple.

local getWritablePath ( )

pure virtual

Gets the writable path.

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

Implemented in FileUtilsAndroid, FileUtilsLinux, FileUtilsWin32, and FileUtilsApple.

virtual bool init ( )

protectedvirtual

Initializes the instance of FileUtils.

It will set _searchPathArray and _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 _defaultResRootPath in the subclass of FileUtils(e.g. FileUtilsAndroid). Then invoke the FileUtils::init().

Returns: true if successed, otherwise it returns false.

Reimplemented in FileUtilsAndroid, FileUtilsLinux, and FileUtilsWin32.

var init ( )

protectedvirtual

Initializes the instance of FileUtils.

It will set _searchPathArray and _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 _defaultResRootPath in the subclass of FileUtils(e.g. FileUtilsAndroid). Then invoke the FileUtils::init().

Returns: true if successed, otherwise it returns false.

Reimplemented in FileUtilsAndroid, FileUtilsLinux, and FileUtilsWin32.

local init ( )

protectedvirtual

Initializes the instance of FileUtils.

It will set _searchPathArray and _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 _defaultResRootPath in the subclass of FileUtils(e.g. FileUtilsAndroid). Then invoke the FileUtils::init().

Returns: true if successed, otherwise it returns false.

Reimplemented in FileUtilsAndroid, FileUtilsLinux, and FileUtilsWin32.

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

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 FileUtilsAndroid, and FileUtilsWin32.

var isAbsolutePath ( var path)

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 FileUtilsAndroid, and FileUtilsWin32.

local isAbsolutePath ( local path)

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 FileUtilsAndroid, and FileUtilsWin32.

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

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 FileUtilsAndroid, FileUtilsLinux, FileUtilsWin32, and FileUtilsApple.

var isFileExist ( var filePath)

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 FileUtilsAndroid, FileUtilsLinux, FileUtilsWin32, and FileUtilsApple.

local isFileExist ( local filePath)

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 FileUtilsAndroid, FileUtilsLinux, FileUtilsWin32, and FileUtilsApple.

virtual bool isPopupNotify ( )

virtual

var isPopupNotify ( )

virtual

local isPopupNotify ( )

virtual

virtual void
loadFilenameLookupDictionaryFromFile ( const std::string & 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 loadFilenameLookup ( 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 loadFilenameLookup ( 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 CC_DEPRECATED_ATTRIBUTE
void purgeFileUtils ( )

inlinestatic

Deprecated:: Use destroyInstance() instead

var purgeFileUtils ( )

inlinestatic

Deprecated:: Use destroyInstance() instead

local purgeFileUtils ( )

inlinestatic

Deprecated:: Use destroyInstance() instead

virtual void
setFilenameLookupDictionary ( const ValueMap & filenameLookupDict)

virtual

Sets the filenameLookup dictionary.

Parameters

pFilenameLookupDict The dictionary for replacing filename.

Since: v2.1

var setFilenameLookupDictionary ( var filenameLookupDict)

virtual

Sets the filenameLookup dictionary.

Parameters

pFilenameLookupDict The dictionary for replacing filename.

Since: v2.1

local setFilenameLookupDictionary ( local filenameLookupDict)

virtual

Sets the filenameLookup dictionary.

Parameters

pFilenameLookupDict The dictionary for replacing filename.

Since: v2.1

virtual void setPopupNotify ( bool notify)

virtual

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

var setPopupNotify ( var notify)

virtual

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

local setPopupNotify ( local notify)

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, FileUtils 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 In js:var setSearchPaths(var jsval);

var setSearchPaths ( var 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, FileUtils 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 In js:var setSearchPaths(var jsval);

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 In js:var setSearchResolutionsOrder(var jsval)

var setSearchResolutionsOrder ( var 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 In js:var setSearchResolutionsOrder(var jsval)

static CC_DEPRECATED_ATTRIBUTE
FileUtils* sharedFileUtils ( )

inlinestatic

Deprecated:: Use getInstance() instead

var sharedFileUtils ( )

inlinestatic

Deprecated:: Use getInstance() instead

local sharedFileUtils ( )

inlinestatic

Deprecated:: Use getInstance() instead

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

virtual

Write a ValueMap to a plist file.

Note: This method is used internally.

Reimplemented in FileUtilsApple.

var writeToFile	(	var	dict,
		var	fullPath
	)

virtual

Write a ValueMap to a plist file.

Note: This method is used internally.

Reimplemented in FileUtilsApple.

local writeToFile	(	local	dict,
		local	fullPath
	)

virtual

Write a ValueMap to a plist file.

Note: This method is used internally.

Reimplemented in FileUtilsApple.

Member Data Documentation

std::string _defaultResRootPath

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 FileUtils's subclass. For instance: On Android, the default root path of resources will be assigned with "assets/" in FileUtilsAndroid::init(). Similarly on Blackberry, we assign "app/native/Resources/" to this variable in FileUtilsBlackberry::init().

var _defaultResRootPath

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 FileUtils's subclass. For instance: On Android, the default root path of resources will be assigned with "assets/" in FileUtilsAndroid::init(). Similarly on Blackberry, we assign "app/native/Resources/" to this variable in FileUtilsBlackberry::init().

local _defaultResRootPath

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 FileUtils's subclass. For instance: On Android, the default root path of resources will be assigned with "assets/" in FileUtilsAndroid::init(). Similarly on Blackberry, we assign "app/native/Resources/" to this variable in FileUtilsBlackberry::init().

ValueMap _filenameLookupDict

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::unordered_map<std::string,
std::string> _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 _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 _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.

std::vector<std::string>
_searchPathArray

protected

The vector contains search paths.

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

var _searchPathArray

protected

The vector contains search paths.

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

local _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>
_searchResolutionsOrderArray

protected

The vector contains resolution folders.

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

var _searchResolutionsOrderArray

protected

The vector contains resolution folders.

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

local _searchResolutionsOrderArray

protected

The vector contains resolution folders.

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

FileUtils* s_sharedFileUtils

staticprotected

The singleton pointer of FileUtils.

var s_sharedFileUtils

staticprotected

The singleton pointer of FileUtils.

local s_sharedFileUtils

staticprotected

The singleton pointer of FileUtils.

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

/Users/cocos2d/MyWork/cocos2d-x-develop/cocos/2d/platform/CCFileUtils.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation