SpriteFrame Class

Extends Asset, EventTarget(mixin)

Module: cc

A cc.SpriteFrame has:

• texture: A cc.Texture2D that will be used by render components
  
• rectangle: A rectangle of the texture

Examples

// load a cc.SpriteFrame with image path (Recommend)
var self = this;
var url = "test assets/PurpleMonster";
cc.loader.loadRes(url, cc.SpriteFrame, function (err, spriteFrame) {
 var node = new cc.Node("New Sprite");
 var sprite = node.addComponent(cc.Sprite);
 sprite.spriteFrame = spriteFrame;
 node.parent = self.node
});

Index

Properties

• insetTop Number Top border of the sprite
• insetBottom Number Bottom border of the sprite
• insetLeft Number Left border of the sprite
• insetRight Number Right border of the sprite
• loaded Boolean Whether the asset is loaded or not
• url String Points to the true url of this asset's native object, only valid when asset is loaded and asyncLoadAsset is not enabled.
• nativeUrl String Returns the url of this asset's native object, if none it will returns an empty string.
• _native String Serializable url for native asset.
• _nativeAsset Object The underlying native asset of this asset if one is available.
• _uuid String
• _name String
• _objFlags Number
• name String The name of the object.
• isValid Boolean Indicates whether the object is not yet destroyed.

Methods

• constructor Constructor of SpriteFrame class.
• textureLoaded Returns whether the texture have been loaded
• isRotated Returns whether the sprite frame is rotated in the texture.
• setRotated Set whether the sprite frame is rotated in the texture.
• getRect Returns the rect of the sprite frame in the texture.
• setRect Sets the rect of the sprite frame in the texture.
• getOriginalSize Returns the original size of the trimmed image.
• setOriginalSize Sets the original size of the trimmed image.
• getTexture Returns the texture of the frame.
• getOffset Returns the offset of the frame in the texture.
• setOffset Sets the offset of the frame in the texture.
• clone Clone the sprite frame.
• setTexture Set SpriteFrame with Texture, rect, rotated, offset and originalSize.
• ensureLoadTexture associated by user's custom Components in the scene, will not preload automatically.
• clearTexture If you do not need to use the SpriteFrame temporarily, you can call this method so that its texture could be garbage collected.
• toString Returns the asset's url.
• serialize 应 AssetDB 要求提供这个方法
• createNode Create a new node using this asset in the scene....
• _setRawAsset Set native file name for this asset.
• hasEventListener Checks whether the EventTarget object has any callback registered for a specific type of event.
• on Register an callback of a specific event type on the EventTarget.
• off Removes the listeners previously registered with the same type, callback, target and or useCapture,...
• targetOff Removes all callbacks previously registered with the same target (passed as parameter).
• once Register an callback of a specific event type on the EventTarget,...
• emit Trigger an event directly with the event name and necessary arguments.
• dispatchEvent Send an event with the event object.
• destroy Actual object destruction will delayed until before rendering.
• _destruct Clear all references in the instance.
• _onPreDestroy Called before the object being destroyed.
• _serialize The customized serialization for this object.
• _deserialize Init this object from the custom serialized data.

Details

Properties

insetTop

Top border of the sprite

insetBottom

Bottom border of the sprite

insetLeft

Left border of the sprite

insetRight

Right border of the sprite

loaded

Whether the asset is loaded or not

url

Points to the true url of this asset's native object, only valid when asset is loaded and asyncLoadAsset is not enabled. Url equals nativeUrl on web(web-mobile, web-desktop) or native(iOS, Android etc) platform. The difference between nativeUrl and url is that url may points to temporary path or cached path on mini game platform which has cache mechanism (WeChat etc). If you want to make use of the native file on those platforms, you should use url instead of nativeUrl.

nativeUrl

Returns the url of this asset's native object, if none it will returns an empty string.

_native

Serializable url for native asset.

_nativeAsset

The underlying native asset of this asset if one is available. This property can be used to access additional details or functionality releated to the asset. This property will be initialized by the loader if _native is available.

_uuid

_name

_objFlags

name

The name of the object.

Examples

obj.name = "New Obj";

isValid

Indicates whether the object is not yet destroyed. (It will not be available after being destroyed)
When an object's destroy is called, it is actually destroyed after the end of this frame. So isValid will return false from the next frame, while isValid in the current frame will still be true. If you want to determine whether the current frame has called destroy, use cc.isValid(obj, true), but this is often caused by a particular logical requirements, which is not normally required.

Examples

var node = new cc.Node();
cc.log(node.isValid);    // true
node.destroy();
cc.log(node.isValid);    // true, still valid in this frame
// after a frame...
cc.log(node.isValid);    // false, destroyed in the end of last frame

Methods

constructor

Constructor of SpriteFrame class.

Parameters

• filename String | Texture2D
• rect Rect
• rotated Boolean Whether the frame is rotated in the texture
• offset Vec2 The offset of the frame in the texture
• originalSize Size The size of the frame in the texture

textureLoaded

Returns whether the texture have been loaded

isRotated

Returns whether the sprite frame is rotated in the texture.

setRotated

Set whether the sprite frame is rotated in the texture.

Parameters

• bRotated Boolean

getRect

Returns the rect of the sprite frame in the texture.

setRect

Sets the rect of the sprite frame in the texture.

Parameters

• rect Rect

getOriginalSize

Returns the original size of the trimmed image.

setOriginalSize

Sets the original size of the trimmed image.

Parameters

• size Size

getTexture

Returns the texture of the frame.

getOffset

Returns the offset of the frame in the texture.

setOffset

Sets the offset of the frame in the texture.

Parameters

• offsets Vec2

clone

Clone the sprite frame.

setTexture

Set SpriteFrame with Texture, rect, rotated, offset and originalSize.

Parameters

• textureOrTextureFile String | Texture2D
• rect Rect
• rotated Boolean
• offset Vec2
• originalSize Size

ensureLoadTexture

If a loading scene (or prefab) is marked as asyncLoadAssets, all the textures of the SpriteFrame which associated by user's custom Components in the scene, will not preload automatically. These textures will be load when Sprite component is going to render the SpriteFrames. You can call this method if you want to load the texture early.

Examples

if (spriteFrame.textureLoaded()) {
    this._onSpriteFrameLoaded();
}
else {
    spriteFrame.once('load', this._onSpriteFrameLoaded, this);
    spriteFrame.ensureLoadTexture();
}

clearTexture

If you do not need to use the SpriteFrame temporarily, you can call this method so that its texture could be garbage collected. Then when you need to render the SpriteFrame, you should call ensureLoadTexture manually to reload texture.

Examples

spriteFrame.clearTexture();
// when you need the SpriteFrame again...
spriteFrame.once('load', onSpriteFrameLoaded);
spriteFrame.ensureLoadTexture();

toString

Returns the asset's url.

The Asset object overrides the toString() method of the Object object. For Asset objects, the toString() method returns a string representation of the object. JavaScript calls the toString() method automatically when an asset is to be represented as a text value or when a texture is referred to in a string concatenation.

serialize

应 AssetDB 要求提供这个方法

createNode

Create a new node using this asset in the scene.
If this type of asset dont have its corresponding node type, this method should be null.

Parameters

• callback Function
  • error String null or the error info
  • node Object the created node or null

_setRawAsset

Set native file name for this asset.

Parameters

• filename String
• inLibrary Boolean

hasEventListener

Checks whether the EventTarget object has any callback registered for a specific type of event.

Parameters

• type String The type of event.

on

Register an callback of a specific event type on the EventTarget. This type of event should be triggered via emit.

Parameters

• type String A string representing the event type to listen for.
• callback Function The callback that will be invoked when the event is dispatched.

                         The callback is ignored if it is a duplicate (the callbacks are unique).
  

  • arg1 Any arg1
  • arg2 Any arg2
  • arg3 Any arg3
  • arg4 Any arg4
  • arg5 Any arg5
• target Object The target (this object) to invoke the callback, can be null

Examples

eventTarget.on('fire', function () {
    cc.log("fire in the hole");
}, node);

off

Removes the listeners previously registered with the same type, callback, target and or useCapture, if only type is passed as parameter, all listeners registered with that type will be removed.

Parameters

• type String A string representing the event type being removed.
• callback Function The callback to remove.
• target Object The target (this object) to invoke the callback, if it's not given, only callback without target will be removed

Examples

// register fire eventListener
var callback = eventTarget.on('fire', function () {
    cc.log("fire in the hole");
}, target);
// remove fire event listener
eventTarget.off('fire', callback, target);
// remove all fire event listeners
eventTarget.off('fire');

targetOff

Removes all callbacks previously registered with the same target (passed as parameter). This is not for removing all listeners in the current event target, and this is not for removing all listeners the target parameter have registered. It's only for removing all listeners (callback and target couple) registered on the current event target by the target parameter.

Parameters

• target Object The target to be searched for all related listeners

once

Register an callback of a specific event type on the EventTarget, the callback will remove itself after the first time it is triggered.

Parameters

• type String A string representing the event type to listen for.
• callback Function The callback that will be invoked when the event is dispatched.

                         The callback is ignored if it is a duplicate (the callbacks are unique).
  

  • arg1 Any arg1
  • arg2 Any arg2
  • arg3 Any arg3
  • arg4 Any arg4
  • arg5 Any arg5
• target Object The target (this object) to invoke the callback, can be null

Examples

eventTarget.once('fire', function () {
    cc.log("this is the callback and will be invoked only once");
}, node);

emit

Trigger an event directly with the event name and necessary arguments.

Parameters

• type String event type
• arg1 Any First argument
• arg2 Any Second argument
• arg3 Any Third argument
• arg4 Any Fourth argument
• arg5 Any Fifth argument

Examples

eventTarget.emit('fire', event);
eventTarget.emit('fire', message, emitter);

dispatchEvent

Send an event with the event object.

Parameters

• event Event

destroy

Destroy this Object, and release all its own references to other objects.
Actual object destruction will delayed until before rendering. From the next frame, this object is not usable any more. You can use cc.isValid(obj) to check whether the object is destroyed before accessing it.

Examples

obj.destroy();

_destruct

Clear all references in the instance.

NOTE: this method will not clear the getter or setter functions which defined in the instance of CCObject. You can override the _destruct method if you need, for example: _destruct: function () { for (var key in this) { if (this.hasOwnProperty(key)) { switch (typeof this[key]) { case 'string': this[key] = ''; break; case 'object': case 'function': this[key] = null; break; } } }

_onPreDestroy

Called before the object being destroyed.

_serialize

The customized serialization for this object. (Editor Only)

Parameters

• exporting Boolean

_deserialize

Init this object from the custom serialized data.

Parameters

• data Object the serialized json data
• ctx _Deserializer