Kiwi.Files.File Class
Handles the loading of an external data file via a tag loader OR xhr + arraybuffer, and optionally saves to the file store. Also can contain information about the file (like file size, last modified, e.t.c.) either after it has been loaded OR if you use the 'getFileDetails' method and the properties will then be set.
Constructor
Kiwi.Files.File
-
game
-
dataType
-
path
-
[name='']
-
[saveToFileStore=true]
-
[storeAsGlobal=true]
Parameters:
-
game
Kiwi.GameThe game that this file belongs to.
-
dataType
NumberThe type of file that is being loaded. For this you can use the STATIC properties that are located on this class for quick code completion.
-
path
StringThe location of the file that is to be loaded.
-
[name='']
String optionalA name for the file. If no name is specified then the files name will be used.
-
[saveToFileStore=true]
Boolean optionalIf the file should be saved on the file store or not.
-
[storeAsGlobal=true]
Boolean optionalIf this file should be stored as a global file, or if it should be destroyed when this state gets switched out.
Returns:
Item Index
Methods
- addTag
- completeXHRHeadRequest
- createBlob
- getFileDetails
- getResponseHeaders
- hasTag
- load
- objType
- parseComplete
- processFile
- removeTag
- revoke
- sendXHRHeadRequest
- start
- stop
- tagLoader
- tagLoaderIOSLoad
- tagLoaderOnError
- tagLoaderOnLoad
- tagLoaderOnReadyStateChange
- tagLoaderProgressThrough
- xhrHeadOnError
- xhrHeadOnTimeout
- xhrLoader
- xhrOnAbort
- xhrOnError
- xhrOnLoad
- xhrOnLoadStart
- xhrOnProgress
- xhrOnReadyStateChange
- xhrOnTimeout
Properties
- _fileStore
- _game
- _saveToFileStore
- _tags
- _useTagLoader
- _xhr
- attemptCounter
- AUDIO static
- BINARY_DATA static
- buffer
- bytesLoaded
- bytesTotal
- data
- data
- dataType
- duration
- error
- ETag
- fileExtension
- fileName
- filePath
- fileSize
- fileType
- fileURL
- hasError
- hasTimedOut
- IMAGE static
- isAudio
- isData
- isTexture
- JSON static
- key
- lastModified
- lastProgress
- maxHeadLoadAttempts
- maxLoadAttempts
- onCompleteCallback
- onProgressCallback
- ownerState
- percentLoaded
- readyState
- SPRITE_SHEET static
- status
- statusText
- success
- TEXT_DATA static
- TEXTUREATLAS static
- timedOut
- timeFinished
- timeOutDelay
- timeStarted
- XML static
Methods
addTag
-
tag
Adds a new tag to this file.
Parameters:
-
tag
StringThe tag that you would like to add
completeXHRHeadRequest
-
outcome
Used to finialise the XHR Head Request (used with get File Details). When passed an outcome this method will see if it can 'try again' otherwise it will just finish the attempt.
Parameters:
-
outcome
BooleanIf the outcome was a success or not.
createBlob
()
private
Creates a new Binary Large Object for the data that was loaded through the XHR.
getFileDetails
-
[callback=null]
-
[maxLoadAttempts=1]
-
[timeout=this.timeOutDelay]
Attempts to make the file send a XHR HEAD request to get information about the file that is going to be downloaded. This is particularly useful when you are wanting to check how large a file is before loading all of the content.
Parameters:
-
[callback=null]
Any optionalThe callback to send this FileInfo object to.
-
[maxLoadAttempts=1]
Number optionalThe maximum amount of load attempts. Only set this if it is different from the default.
-
[timeout=this.timeOutDelay]
Number optionalThe timeout delay. By default this is the same as the timeout delay property set on this file.
getResponseHeaders
-
event
Process the response headers received.
Parameters:
-
event
AnyThe XHR event.
hasTag
-
tag
Checks to see if a tag that is passed exists on this file and returns a boolean that is used as a indication of the results. True means that the tag exists on this file.
Parameters:
-
tag
StringThe tag you are checking to see exists.
Returns:
If the tag does exist on this file or not.
load
-
[onCompleteCallback=null]
-
[onProgressCallback=null]
-
[customFileStore=null]
-
[maxLoadAttempts]
-
[timeout]
Starts the loading process for this file.
Parameters:
-
[onCompleteCallback=null]
Any optionalThe callback method to execute when this file has loaded.
-
[onProgressCallback=null]
Any optionalThe callback method to execute while this file is loading.
-
[customFileStore=null]
Any optionalA custom filestore that is file should be added to.
-
[maxLoadAttempts]
Number optionalThe maximum amount of times to try and load this file.
-
[timeout]
Number optionalThe timeout to use when loading the file. Overrides the default timeout if passed otherwise uses the default 2000 milliseconds.
objType
()
String
public
Returns the type of this object
Returns:
"File"
parseComplete
()
private
Executed when this file has completed loading (this could be due to it failing or succeeding).
processFile
()
private
Handles the processing of the files information when it was loaded via the xhr + arraybuffer method. Is only executed when the loading was a success
removeTag
-
tag
Removes a tag from this file.
Parameters:
-
tag
StringThe tag that is to be removed.
revoke
()
private
Revokes the object url that was added to the window when creating the image. Also tells the File that the loading is now complete.
sendXHRHeadRequest
-
timeout
Sends a XHR request for the HEAD information of this file. Useful as it can will contain the information about the file before loading the actual file.
Parameters:
-
timeout
NumberThe timeout delay.
start
()
private
Is executed when this file starts loading. Gets the time and initalised properties that are used across both loading methods.
stop
()
private
Is executed when this file stops loading. Used across all loading methods.
tagLoader
()
private
Handles the loading of the file when using the tag loader method. Only supports the IMAGES and AUDIO files.
tagLoaderIOSLoad
()
private
Is executed when iOS (or another device) is being used and the audio is 'locked'. 'Fakes' the loading and tells the rest of the game to carry on.
tagLoaderOnError
-
event
Is executed when the tag loader encounters a error that stops it from loading.
Parameters:
-
event
Any
tagLoaderOnLoad
-
event
Is executed when the file has successfully loaded.
Parameters:
-
event
Any
tagLoaderOnReadyStateChange
-
event
Is executed when the tag loader changes its ready state.
Parameters:
-
event
Any
tagLoaderProgressThrough
-
event
Is executed when an audio file can play the whole way through with stopping to load.
Parameters:
-
event
Any
xhrHeadOnError
-
event
Is executed when this XHR head request has a error.
Parameters:
-
event
AnyThe event containing the reason why this event failed.
xhrHeadOnTimeout
-
event
Is executed when the XHR head request timed out.
Parameters:
-
event
Any
xhrLoader
()
private
Sets up a XHR loader based on the properties of this file.
xhrOnAbort
-
event
Runs when the XHR loader aborts the load for some reason.
Parameters:
-
event
Any
xhrOnError
-
event
Runs when the XHR loader encounters a error.
Parameters:
-
event
Any
xhrOnLoad
-
event
Once the file has finished downloading (or pulled from the browser cache) this onload event fires.
Parameters:
-
event
EventThe XHR event.
xhrOnLoadStart
-
event
Is executed when the XHR loader starts to load the file.
Parameters:
-
event
Any
xhrOnProgress
-
event
Is execute whilst loading of the file is occuring. Updates the number of bytes that have been loaded and percentage loaded.
Parameters:
-
event
Any
xhrOnReadyStateChange
-
event
Is executed when the XHR loader has changed its ready state.
Parameters:
-
event
Any
xhrOnTimeout
-
event
Is executed when the xhr
Parameters:
-
event
Any
Properties
_saveToFileStore
Boolean
private
Used to determine if this file should be saved to the file store or not.
Default: true
_useTagLoader
Boolean
private
If when loading the file in we have loaded the file in using a tag loader (older browsers) or we are using the an XHR loader + array buffer. By default we use the tag loader and only used the second method if the browser supports it.
Default: true
_xhr
XMLHttpRequest
private
The XMLHttpRequest object. This only has a value if the xhr method of load is being used, otherwise this is null.
attemptCounter
Number
public
The number of attempts at loading there have currently been at loading the file. This is only used with XHR methods of loading.
AUDIO
Number
public
final
static
A STATIC property that has the number associated with the AUDIO Datatype.
Default: 3
BINARY_DATA
Number
public
final
static
A STATIC property that has the number associated with the BINARY_DATA Datatype.
Default: 6
buffer
Any
public
The response that is given by the XHR loader when loading is complete.
bytesLoaded
Number
public
The number of bytes that have currently been loaded. This can used to create progress bars but only has a value when using the XHR method of loading.
Default: 0
bytesTotal
Number
public
The total number of bytes that the file consists off. Only has a value when using the XHR method of loading.
Default: 0
data
Any
public
A dictionary, stores any information relating to this file. Is useful when loading images that are to be used as a spritesheet or texture atlas.
data
Any
The particular piece of data that the developer wanted loaded. This is in a format that is based upon the datatype passed.
dataType
String
public
Holds the type of data that is being loaded. This should be used with the STATIC properties that hold the various datatypes that can be loaded.
duration
Number
public
The duration or how long it took to load the file. In milliseconds.
Default: 0
error
Any
public
Holds the error (if there was one) when loading the file.
ETag
String
public
The Entity Tag that is assigned to the file. O Only has a value when either using the XHR loader OR when requesting the file details.
fileExtension
String
public
The extension of the file that is being loaded. This is based upon what the file path that the developer (you) specify.
fileName
String
public
The name of the file being loaded.
filePath
String
public
The location of where the file is placed without the file itself (So without the files name). Example: If the file you are load is located at 'images/awesomeImage.png' then the filepath will be 'images/'
fileSize
Number
public
The size of the file that was/is being loaded. Only has a value when the file was loaded by the XHR method OR you request the file information before hand using 'getFileDetails'.
Default: 0
fileType
String
public
The type of file that is being loaded. Is only ever given a value when used with the XHR method of loading OR if you use 'getFileDetails' before hand. The value is based off of the 'Content-Type' of the XHR's response header returns.
fileURL
String
public
The full filepath including the file itself.
hasError
Boolean
public
If the loading of the file failed or encountered an error.
Default: false
hasTimedOut
Boolean
public
If this file has timeout when it was loading.
Default: false
IMAGE
Number
public
final
static
A STATIC property that has the number associated with the IMAGE Datatype.
Default: 0
isAudio
Boolean
public
An indication of if this file is a piece of audio. This is READ ONLY.
isData
Boolean
public
An indication of if this file is data. This is READ ONLY.
isTexture
Boolean
public
An indication of if this file is texture. This is READ ONLY.
JSON
Number
public
final
static
A STATIC property that has the number associated with the JSON Datatype.
Default: 4
key
String
public
The 'key' is the user defined name and the users way of accessing this file once loaded.
lastModified
String
public
The last date/time that this file was last modified. Only has a value when using the XHR method of loading OR when requesting the file details.
Default: ''
lastProgress
Number
public
The time at which progress in loading the file was last occurred.
maxHeadLoadAttempts
Number
public
The maximum number of load attempts when requesting the file details that will be preformed.
Default: 1
maxLoadAttempts
Number
public
The maximum attempts at loading the file that there is allowed. Only used with XHR methods of loading.
Default: 2
onCompleteCallback
Any
public
A method that is to be executed when this file has finished loading.
Default: null
onProgressCallback
Any
public
A method that is to be executed while this file is loading.
Default: null
percentLoaded
Number
public
The amount of percent loaded the file is. This is out of 100.
readyState
Number
public
The ready state of the XHR loader whilst loading.
Default: 0
SPRITE_SHEET
Number
public
final
static
A STATIC property that has the number associated with the SPRITE_SHEET Datatype.
Default: 1
status
Number
public
The status of this file that is being loaded. Only used/has a value when the file was/is being loaded by the XHR method.
Default: 0
statusText
String
public
The status piece of text that the XHR returns.
Default: ''
success
Boolean
public
If the loading was a success or not.
TEXT_DATA
Number
public
final
static
A STATIC property that has the number associated with the TEXT_DATA Datatype.
Default: 7
TEXTUREATLAS
Number
public
final
static
A STATIC property that has the number associated with the TEXTURE_ATLAS Datatype.
Default: 2
timedOut
Number
public
If the file timed out or not.
Default: 0
timeFinished
Number
public
The time at which the load finished. Only has a value if loading the file was successful and when the XHR method of loading is in use.
Default: 0
timeOutDelay
Number
public
The default number of milliseconds that the XHR should wait before timing out. Set this to NULL if you want it to not timeout.
Default: 2000
timeStarted
Number
public
The time at which the loading started. Only has a value when the XHR method of loading is in use.
Default: 0
XML
Number
public
final
static
A STATIC property that has the number associated with the XML Datatype.
Default: 5