CCFileUtils Class Reference

Inherits from	NSObject
Declared in	CCFileUtils.h

Overview

Helper class to handle file operations

Tasks

Other Methods

bundle
NSBundle used by CCFileUtils. By default it uses [NSBundle mainBundle].
property
fileManager
NSFileManager used by CCFileUtils. By default it uses its own instance.
property
enableiPhoneResourcesOniPad
Whether of not the fallback suffixes is enabled. When enabled it will try to search for the following suffixes in the following order until one is found: * On iPad HD : iPad HD, iPad, iPhone HD, Resources without resolution * On iPad : iPad, iPhone HD, Resources without resolution * On iPhone HD: iPhone HD, Resources without resolution * On Mac HD : Mac HD, Mac, Resources without resolution * On Mac : Mac, Resources without resolution
property
directoriesDict
Dictionary that contians the search directories for the different devices. Default values: – iPhone: “resources-iphone” – iPhone HD: “resources-hd” – iPhone5 : “resources-wide” – iPhone5 HD: “resources-widehd” – iPad: “resources-ipad” – iPad HD: “resources-ipadhd” – Mac: “resources-mac” – Mac HD: “resources-machd”
property

suffixesDict

Dictionary that contians the suffix for the different devices. Default values:

- iPhone: ""
- iPhone HD: "-hd"
- iPhone5 : "-wide"
- iPhone5 HD: "-widehd"
- iPad: "-ipad"
- iPad HD: "-ipadhd"
- Mac: ""
- Mac HD: "-machd"

property

searchResolutionsOrder
Array that contains the search order of the resources based for the device. By default it will try to load resources in the following order until one is found: – On iPad HD: iPad HD resources, iPad resources, resources not associated with any device – On iPad: iPad resources, resources not associated with any device – On iPhone 5 HD: iPhone 5 HD resources, iPhone HD resouces, iPhone 5 resources, iPhone resources, resources not associated with any device – On iPhone HD: iPhone HD resources, iPhone resouces, resources not associated with any device – On iPhone: iPhone resources, resources not associated with any device
property
searchPath
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.
property

searchMode

It determines how the “resolution resources” are to be searched. Possible values:

- kCCFileUtilsSearchSuffix: It will search for resources by appending suffixes like "-hd", "-ipad", etc...
- kCCFileUtilsSearchDirectory: It will search the resoureces in subdirectories like "resources-hd", "resources-ipad", etc...

property

filenameLookup
Dictionary used to lookup filenames based on a key. It is used internally by the following methods:
property
– setiPhoneRetinaDisplaySuffix:
The iPhone RetinaDisplay suffixes to load resources. By default it is “-hd” and “” in that order. Only valid on iOS. Not valid for OS X.
– setiPadSuffix:
The iPad suffixes to load resources. By default it is “-ipad”, “-hd”, “”, in that order. Only valid on iOS. Not valid for OS X.
– setiPadRetinaDisplaySuffix:
Sets the iPad Retina Display suffixes to load resources. By default it is “-ipadhd”, “-ipad”, “-hd”, “”, in that order. Only valid on iOS. Not valid for OS X.
+ sharedFileUtils
returns the shared file utils instance
– purgeCachedEntries
Purge cached entries. Will be called automatically by the Director when a memory warning is received
– buildSearchResolutionsOrder
Calling this method will populate the searchResolutionsOrder property depending on the current device.
– fullPathFromRelativePath:
Returns the fullpath of an filename.
– fullPathFromRelativePath:resolutionType:
Returns the fullpath of an filename. It will try to get the correct file for the current screen resolution. Useful for loading images and other assets that are related for the screen resolution.
– fullPathFromRelativePathIgnoringResolutions:
Returns the fullpath of an filename without taking into account the screen resolution suffixes or directories.
– fullPathForFilename:
Returns the fullpath for a given filename.
– fullPathForFilename:resolutionType:
Returns the fullpath for a given filename.
– fullPathForFilenameIgnoringResolutions:
Returns the fullpath for a given filename, without taking into account device resolution.
– loadFilenameLookupDictionaryFromFile:
– removeSuffixFromFile:
removes the suffix from a path * On iPhone RetinaDisplay it will remove the -hd suffix * On iPad it will remove the -ipad suffix * On iPad RetinaDisplay it will remove the -ipadhd suffix
– standarizePath:
– iPhoneRetinaDisplayFileExistsAtPath:
Returns whether or not a given path exists with the iPhone RetinaDisplay suffix. Only available on iOS. Not supported on OS X.
– iPadFileExistsAtPath:
Returns whether or not a given filename exists with the iPad suffix. Only available on iOS. Not supported on OS X.
– iPadRetinaDisplayFileExistsAtPath:
Returns whether or not a given filename exists with the iPad RetinaDisplay suffix. Only available on iOS. Not supported on OS X.
– setEnableFallbackSuffixes:
@deprecated

Deprecated Methods

+ fullPathFromRelativePath:
+ fullPathFromRelativePath:resolutionType:
+ removeSuffixFromFile:
+ iPhoneRetinaDisplayFileExistsAtPath:
+ iPadFileExistsAtPath:
+ iPadRetinaDisplayFileExistsAtPath:
+ setRetinaDisplaySuffix:

Properties

bundle

NSBundle used by CCFileUtils. By default it uses [NSBundle mainBundle].

@property (nonatomic, readwrite, retain) NSBundle *bundle

Availability

Declared In

CCFileUtils.h

directoriesDict

Dictionary that contians the search directories for the different devices. Default values: – iPhone: “resources-iphone” – iPhone HD: “resources-hd” – iPhone5 : “resources-wide” – iPhone5 HD: “resources-widehd” – iPad: “resources-ipad” – iPad HD: “resources-ipadhd” – Mac: “resources-mac” – Mac HD: “resources-machd”

@property (nonatomic, copy) NSMutableDictionary *directoriesDict

Availability

Discussion

If “search in directories” is enabled (disabled by default), it will try to get the resources from the directories according to the order of “searchResolutionsOrder” array.

Declared In

CCFileUtils.h

enableiPhoneResourcesOniPad

Whether of not the fallback suffixes is enabled. When enabled it will try to search for the following suffixes in the following order until one is found: * On iPad HD : iPad HD, iPad, iPhone HD, Resources without resolution * On iPad : iPad, iPhone HD, Resources without resolution * On iPhone HD: iPhone HD, Resources without resolution * On Mac HD : Mac HD, Mac, Resources without resolution * On Mac : Mac, Resources without resolution

@property (nonatomic, readwrite, getter=isEnablediPhoneResourcesOniPad) BOOL enableiPhoneResourcesOniPad

Discussion

By default this functionality is off;

Declared In

CCFileUtils.h

fileManager

NSFileManager used by CCFileUtils. By default it uses its own instance.

@property (nonatomic, readwrite, retain) NSFileManager *fileManager

Availability

Declared In

CCFileUtils.h

filenameLookup

Dictionary used to lookup filenames based on a key. It is used internally by the following methods:

@property (nonatomic, readwrite, copy) NSMutableDictionary *filenameLookup

Availability

Discussion

–(NSString) fullPathForFilename:(NSString)key resolutionType:(ccResolutionType*)resolutionType;
–(NSString) fullPathForFilenameIgnoringResolutions:(NSString)key;

Declared In

CCFileUtils.h

searchMode

It determines how the “resolution resources” are to be searched. Possible values:

- kCCFileUtilsSearchSuffix: It will search for resources by appending suffixes like "-hd", "-ipad", etc...
- kCCFileUtilsSearchDirectory: It will search the resoureces in subdirectories like "resources-hd", "resources-ipad", etc...

@property (nonatomic, readwrite) int searchMode

Availability

Discussion

Default: kCCFileUtilsSearchSuffix

Declared In

CCFileUtils.h

searchPath

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.

@property (nonatomic, copy) NSArray *searchPath

Availability

Discussion

By default it is an array with only the “” (empty string) element.

Declared In

CCFileUtils.h

searchResolutionsOrder

Array that contains the search order of the resources based for the device. By default it will try to load resources in the following order until one is found: – On iPad HD: iPad HD resources, iPad resources, resources not associated with any device – On iPad: iPad resources, resources not associated with any device – On iPhone 5 HD: iPhone 5 HD resources, iPhone HD resouces, iPhone 5 resources, iPhone resources, resources not associated with any device – On iPhone HD: iPhone HD resources, iPhone resouces, resources not associated with any device – On iPhone: iPhone resources, resources not associated with any device

@property (nonatomic, copy) NSArray *searchResolutionsOrder

Availability

Discussion

On Mac HD: Mac HD resources, Mac resources, resources not associated with any device
On Mac: Mac resources, resources not associated with any device

If the property “enableiPhoneResourcesOniPad” is enabled, it will also search for iPhone resources if you are in an iPad.

Declared In

CCFileUtils.h

suffixesDict

Dictionary that contians the suffix for the different devices. Default values:

- iPhone: ""
- iPhone HD: "-hd"
- iPhone5 : "-wide"
- iPhone5 HD: "-widehd"
- iPad: "-ipad"
- iPad HD: "-ipadhd"
- Mac: ""
- Mac HD: "-machd"

@property (nonatomic, copy) NSMutableDictionary *suffixesDict

Availability

Discussion

If “search with suffixes” is enabled (enabled by default), it will try to get the resources by appending the suffixes according to the order of “searchResolutionsOrder” array.

Declared In

CCFileUtils.h

Class Methods

fullPathFromRelativePath:

fullPathFromRelativePath:resolutionType:

iPadFileExistsAtPath:

iPadRetinaDisplayFileExistsAtPath:

iPhoneRetinaDisplayFileExistsAtPath:

removeSuffixFromFile:

setRetinaDisplaySuffix:

sharedFileUtils

returns the shared file utils instance

+ (CCFileUtils *)sharedFileUtils

Declared In

CCFileUtils.h

Instance Methods

buildSearchResolutionsOrder

Calling this method will populate the searchResolutionsOrder property depending on the current device.

- (void)buildSearchResolutionsOrder

Availability

Declared In

CCFileUtils.h

fullPathForFilename:

Returns the fullpath for a given filename.

- (NSString *)fullPathForFilename:(NSString *)filename

Availability

Discussion

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 obtain the full path of the filename using the CCFileUtils search rules: resolutions, and search paths

If in iPad mode, and an iPad file is found, it will return that path. If in iPhoneRetinaDisplay mode, and a RetinaDisplay file is found, it will return that path. But if it is not found, it will try load an iPhone Non-RetinaDisplay file.

If the filename can’t be found on the file system, it will return nil.

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 differerent resources for a given file in the different platforms.

Examples:

In iPad mode: “image.png” –> “image.pvr” –> “/full/path/image-ipad.pvr” (in case the -ipad file exists)
In Android: “image.png” –> “image.png” –> “/full/path/image.png”

Declared In

CCFileUtils.h

fullPathForFilename:resolutionType:

Returns the fullpath for a given filename.

- (NSString *)fullPathForFilename:(NSString *)filename resolutionType:(ccResolutionType *)resolutionType

Availability

Discussion

If the filename can’t be found on the file system, it will return nil.

Examples:

In iPad mode: “image.png” –> “image.pvr” –> “/full/path/image-ipad.pvr” (in case the -ipad file exists)
In Android: “image.png” –> “image.png” –> “/full/path/image.png”

Declared In

CCFileUtils.h

fullPathForFilenameIgnoringResolutions:

Returns the fullpath for a given filename, without taking into account device resolution.

- (NSString *)fullPathForFilenameIgnoringResolutions:(NSString *)key

Availability

Discussion

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.

Once it gets the filename, it will try to get the fullpath for the filename, using the “searchPath”, but it won’t use any resolution search rules. If the file can’t be found, it will return nil.

Useful for loading music files, shaders, “data” and other files that are not related to the screen resolution of the device.

Examples:

On iOS: “sound.wav” –> “sound.caf” –> “/full/path/sound.caf” (in case the key dictionary says that “sound.wav” should be converted to “sound.caf”)
On Android: “sound.wav” –> “sound.wav” –> “/full/path/sound.caf” (in case the key dictionary says that “sound.wav” should be converted to “sound.caf”)

Declared In

CCFileUtils.h

fullPathFromRelativePath:

Returns the fullpath of an filename.

- (NSString *)fullPathFromRelativePath:(NSString *)relPath

Discussion

If in iPhoneRetinaDisplay mode, and a RetinaDisplay file is found, it will return that path. If in iPad mode, and an iPad file is found, it will return that path.

If the filename can’t be found, it will return “relPath” instead of nil.

Examples:

In iPad mode: “image.png” –> “/full/path/image-ipad.png” (in case the -ipad file exists)
In iPhone RetinaDisplay mode: “image.png” –> “/full/path/image-hd.png” (in case the -hd file exists)
In iPad RetinaDisplay mode: “image.png” –> “/full/path/image-ipadhd.png” (in case the -ipadhd file exists)

Declared In

CCFileUtils.h

fullPathFromRelativePath:resolutionType:

Returns the fullpath of an filename. It will try to get the correct file for the current screen resolution. Useful for loading images and other assets that are related for the screen resolution.

- (NSString *)fullPathFromRelativePath:(NSString *)relPath resolutionType:(ccResolutionType *)resolutionType

Discussion

If the filename can’t be found, it will return “relPath” instead of nil.

Examples:

In iPad mode: “image.png” –> “/full/path/image-ipad.png” (in case the -ipad file exists)
In iPhone RetinaDisplay mode: “image.png” –> “/full/path/image-hd.png” (in case the -hd file exists)
In iPad RetinaDisplay mode: “image.png” –> “/full/path/image-ipadhd.png” (in case the -ipadhd file exists)

Declared In

CCFileUtils.h

fullPathFromRelativePathIgnoringResolutions:

Returns the fullpath of an filename without taking into account the screen resolution suffixes or directories.

- (NSString *)fullPathFromRelativePathIgnoringResolutions:(NSString *)relPath

Availability

Discussion

It will use the “searchPath” though. If the file can’t be found, it will return nil.

Useful for loading music files, shaders, “data” and other files that are not related to the screen resolution of the device.

Declared In

CCFileUtils.h

iPadFileExistsAtPath:

Returns whether or not a given filename exists with the iPad suffix. Only available on iOS. Not supported on OS X.

Availability

Declared In

CCFileUtils.h