Helper class to handle file operations
Class CCFileUtils
Examples0
Public static methods3
staticcocos2d::CCFileUtils*get()
No description provided
staticvoidpurgeFileUtils()
Destroys the instance of CCFileUtils.
Public member functions29
virtuallonggetClassTypeInfo()
Returns an unique ID for this class.
The unique ID for this class.
ℹ It's only used for JSBindings now.
virtualvoidpurgeCachedEntries()
Purges the file searching cache.
ℹ 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.
virtualuchar*getFileData(charconst*pszFileName,charconst*pszMode,unsigned long*pSize)
Gets resource file data
pszFileName
The resource file name which contains the path.
pszMode
The read mode of the file.
pSize
If the file read operation succeeds, it will be the data size, otherwise 0.
Upon success, a pointer to the data is returned, otherwise NULL.
⚠️ Recall: you are responsible for calling delete[] on any Non-NULL pointer returned.
virtualuchar*getFileDataFromZip(charconst*pszZipFilePath,charconst*pszFileName,unsigned long*pSize)
Gets resource file data from a zip file.
pszFileName
The resource file name which contains the relative path of the zip file.
pSize
If the file read operation succeeds, it will be the data size, otherwise 0.
Upon success, a pointer to the data is returned, otherwise NULL.
⚠️ Recall: you are responsible for calling delete[] on any Non-NULL pointer returned.
virtualgd::stringfullPathForFilename(charconst*pszFileName,)
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.
ℹ Robtop Addition: added a bool parameter
virtualvoidremoveFullPath(charconst*path)
No description provided
virtualvoidloadFilenameLookupDictionaryFromFile(charconst*filename)
Loads the filenameLookup dictionary from the contents of a filename.
filename
The plist file name.
ℹ 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>virtualvoidsetFilenameLookupDictionary(cocos2d::CCDictionary*pFilenameLookupDict)
Sets the filenameLookup dictionary.
pFilenameLookupDict
The dictionary for replacing filename.
virtualcharconst*fullPathFromRelativeFile(charconst*pszFilename,charconst*pszRelativeFile)
Gets full path from a file name and the path of the reletive file.
pszFilename
The file name.
pszRelativeFile
The path of the relative file.
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. )
virtualvoidsetSearchResolutionsOrder()
Sets the array that contains the search order of the resources.
searchResolutionsOrder
The source array that contains the search order of the resources.
virtualvoidaddSearchResolutionsOrder(charconst*order)
Append search order of the resources.
virtualstd::vector<gd::string>const&getSearchResolutionsOrder()
Gets the array that contains the search order of the resources.
virtualvoidsetSearchPaths()
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.
searchPaths
The array contains search paths.
ℹ 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.
voidaddTexturePack()
Add a texture pack. Texture packs are prioritized over other search paths, so if a texture pack has a replacement for a file, it will be used over others. Contrary to addSearchPath, this function adds the pack to the front of the list. If the pack has already been added, it’s moved to the front of the list (equivalent to removing and re-adding the pack)
pack
Pack to add
ℹ Geode addition
voidremoveTexturePack()
Remove texture pack by ID
id
ID of the texture pack
ℹ Geode addition
voidaddPriorityPath(charconst*path)
Add a search path to the front of the list
path
Path to add
ℹ Geode addition
voidupdatePaths()
Update search path order; texture packs are added first, then other
paths
ℹ Geode addition
virtualvoidaddSearchPath(charconst*path)
Adds a path to search paths.
virtualvoidremoveSearchPath(charconst*path)
Removes a path from search paths.
voidremoveAllPaths()
Removes all paths.
virtualstd::vector<gd::string>const&getSearchPaths()
Gets the array of search paths.
The array of search paths.
virtualgd::stringgetWritablePath()
Gets the writable path.
The path that can be write/read a file in
virtualgd::stringgetWritablePath2()
No description provided
virtualboolisFileExist(gd::stringconst&strFilePath)
Checks whether a file exists.
strFilePath
The path of the file, it could be a relative or absolute path.
true if the file exists, otherwise it will return false.
ℹ If a relative path was passed in, it will be inserted a default root path at the beginning.
virtualboolisAbsolutePath(gd::stringconst&strPath)
Checks whether the path is an absolute path.
strPath
The path that needs to be checked.
true if it's an absolute path, otherwise it will return false.
ℹ 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.
virtualvoidsetPopupNotify(boolbNotify)
Sets/Gets whether to pop-up a message box when failed to load an image.
virtualboolisPopupNotify()
No description provided
gd::stringgetAndroidPath()const
No description provided
voidsetAndroidPath()
No description provided
Fields0
Protected member functions9
virtualboolinit()
Initializes the instance of CCFileUtils. It will set m_searchPathArray and m_searchResolutionsOrderArray to default values.
true if successed, otherwise it returns false.
ℹ 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().
virtualgd::stringgetNewFilename(charconst*pszFileName)
Gets the new filename from the filename lookup dictionary.
pszFileName
The original filename.
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.
virtualboolshouldUseHD()
No description provided
virtualgd::stringaddSuffix(,)
No description provided
virtualgd::stringgetPathForFilename(gd::stringconst&filename,gd::stringconst&resolutionDirectory,gd::stringconst&searchPath)
Gets full path for filename, resolution directory and search path.
filename
The file name.
resolutionDirectory
The resolution directory.
searchPath
The search path.
The full path of the file. It will return an empty string if the full path of the file doesn't exist.
virtualgd::stringgetFullPathForDirectoryAndFilename(gd::stringconst&strDirectory,gd::stringconst&strFilename)
Gets full path for the directory and the filename.
strDirectory
The directory contains the file we are looking for.
strFilename
The name of the file.
The full path of the file, if the file can't be found, it will return an empty string.
ℹ 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.
virtualcocos2d::CCDictionary*createCCDictionaryWithContentsOfFile(gd::stringconst&filename)
Creates a dictionary by the contents of a file.
ℹ This method is used internally.
virtualboolwriteToFile(,gd::stringconst&fullPath)
Write a dictionary to a plist file.
ℹ This method is used internally.
virtualcocos2d::CCArray*createCCArrayWithContentsOfFile(gd::stringconst&filename)
Creates an array by the contents of a file.
ℹ This method is used internally.
Protected fields5
cocos2d::CCDictionary*m_pFilenameLookupDict;
Dictionary used to lookup filenames based on a key. It is used internally by the following methods:
gd::string fullPathForFilename(const char*);
;
The vector contains resolution folders. The lower index of the element in this vector, the higher priority for this resolution directory.
;
The vector contains search paths. The lower index of the element in this vector, the higher priority for this search path.
gd::stringm_strDefaultResRootPath;
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().
;
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.