API Docs for: 1.0.0
Show:

Kiwi.Files.File Class

Defined in: src\file\File.ts:10
Module: Files
Parent Module: Kiwi

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]
)
Kiwi.Files.File

Defined in src\file\File.ts:10

Parameters:

  • game Kiwi.Game

    The game that this file belongs to.

  • dataType Number

    The 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 String

    The location of the file that is to be loaded.

  • [name=''] String optional

    A name for the file. If no name is specified then the files name will be used.

  • [saveToFileStore=true] Boolean optional

    If the file should be saved on the file store or not.

  • [storeAsGlobal=true] Boolean optional

    If this file should be stored as a global file, or if it should be destroyed when this state gets switched out.

Returns:

Methods

addTag

(
  • tag
)
public

Adds a new tag to this file.

Parameters:

  • tag String

    The tag that you would like to add

completeXHRHeadRequest

(
  • outcome
)
private

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 Boolean

    If 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]
)
private

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 optional

    The callback to send this FileInfo object to.

  • [maxLoadAttempts=1] Number optional

    The maximum amount of load attempts. Only set this if it is different from the default.

  • [timeout=this.timeOutDelay] Number optional

    The timeout delay. By default this is the same as the timeout delay property set on this file.

getResponseHeaders

(
  • event
)
private

Process the response headers received.

Parameters:

  • event Any

    The XHR event.

hasTag

(
  • tag
)
Boolean public

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 String

    The tag you are checking to see exists.

Returns:

Boolean:

If the tag does exist on this file or not.

load

(
  • [onCompleteCallback=null]
  • [onProgressCallback=null]
  • [customFileStore=null]
  • [maxLoadAttempts]
  • [timeout]
)
public

Starts the loading process for this file.

Parameters:

  • [onCompleteCallback=null] Any optional

    The callback method to execute when this file has loaded.

  • [onProgressCallback=null] Any optional

    The callback method to execute while this file is loading.

  • [customFileStore=null] Any optional

    A custom filestore that is file should be added to.

  • [maxLoadAttempts] Number optional

    The maximum amount of times to try and load this file.

  • [timeout] Number optional

    The timeout to use when loading the file. Overrides the default timeout if passed otherwise uses the default 2000 milliseconds.

objType

() String public

Defined in src\file\File.ts:95

Returns the type of this object

Returns:

String:

"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
)
public

Removes a tag from this file.

Parameters:

  • tag String

    The 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
)
private

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 Number

    The 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
)
private

Is executed when the tag loader encounters a error that stops it from loading.

Parameters:

  • event Any

tagLoaderOnLoad

(
  • event
)
private

Is executed when the file has successfully loaded.

Parameters:

  • event Any

tagLoaderOnReadyStateChange

(
  • event
)
private

Is executed when the tag loader changes its ready state.

Parameters:

  • event Any

tagLoaderProgressThrough

(
  • event
)
private

Is executed when an audio file can play the whole way through with stopping to load.

Parameters:

  • event Any

xhrHeadOnError

(
  • event
)
private

Is executed when this XHR head request has a error.

Parameters:

  • event Any

    The event containing the reason why this event failed.

xhrHeadOnTimeout

(
  • event
)
private

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

Runs when the XHR loader aborts the load for some reason.

Parameters:

  • event Any

xhrOnError

(
  • event
)
private

Runs when the XHR loader encounters a error.

Parameters:

  • event Any

xhrOnLoad

(
  • event
)
private

Once the file has finished downloading (or pulled from the browser cache) this onload event fires.

Parameters:

  • event Event

    The XHR event.

xhrOnLoadStart

(
  • event
)
private

Is executed when the XHR loader starts to load the file.

Parameters:

  • event Any

xhrOnProgress

(
  • event
)
private

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

Is executed when the XHR loader has changed its ready state.

Parameters:

  • event Any

xhrOnTimeout

(
  • event
)
private

Is executed when the xhr

Parameters:

  • event Any

Properties

_fileStore

Kiwi.Files.FileStore private

The file store that this file is a member of.

_game

Kiwi.Game private

The game that this file belongs to.

_saveToFileStore

Boolean private

Used to determine if this file should be saved to the file store or not.

Default: true

_tags

String private

Any tags that are on this file. This can be used to grab files/objects on the whole game that have these particular tag.

Default: []

_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

ownerState

Kiwi.State public

The state that added the entity - or null if it was added as global

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