SpriteFrame Class

Extends Asset

Module: cc Parent Module: cc

A cc.SpriteFrame has:

• texture: A cc.Texture2D that will be used by the _ccsg.Sprite
  
• rectangle: A rectangle of the texture

Index

Properties

• _textureFilenameSetter String Use this property to set raw texture url during loading
• 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
• rawUrl String Returns the url of this asset's first raw file, if none of rawFile exists, it will returns an empty string.
• rawUrls String[] Returns the url of this asset's raw files, if none of rawFile exists, it will returns an empty array.
• _rawFiles String[] 在 lite 版的 Fireball 里，raw asset 并不仅仅是在 properties 里声明了 rawType 才有， 而是每个 asset 都能指定自己的 raw file url。这些 url 就存在 _rawFiles 字段中。 AssetLibrary 并不会帮你加载这些 url，除非你声明了 rawType。 在 Creator 里，_rawFiles 保留了下来，为了复用 cocos 引擎原有实现，直接用 _rawFiles 来加载 Asset 在 import 之前的源文件。
• _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
• addLoadedEventListener Add a event listener for texture loaded event.
• 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 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.
• 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.
• 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.
• _setRawFiles Set raw file names for this asset.
• _preloadRawFiles Preload raw files when loading scene.
• 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, if only type is passed as parameter, all listeners registered with that type will be removed.
• 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.
• once Register an callback of a specific event type on the EventTarget, the callback will remove itself after the first time it is triggered.
• dispatchEvent Dispatches an event into the event flow. The event target is the EventTarget object upon which the dispatchEvent() method is called.
• emit Send an event to this object directly, this method will not propagate the event to any other objects. The event will be created from the supplied message, you can get the "detail" argument from event.detail.
• destroy Destroy this Object, and release all its own references to other objects.
  Actual object destruction will delayed until before rendering.
  After destroy, this CCObject is not usable any more. You can use cc.isValid(obj) to check whether the object is destroyed before accessing it.
• _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)
• _deserialize Init this object from the custom serialized data.

Details

Properties

_textureFilenameSetter

Use this property to set raw texture url during loading

insetTop

Top border of the sprite

insetBottom

Bottom border of the sprite

insetLeft

Left border of the sprite

insetRight

Right border of the sprite

rawUrl

Returns the url of this asset's first raw file, if none of rawFile exists, it will returns an empty string.

rawUrls

Returns the url of this asset's raw files, if none of rawFile exists, it will returns an empty array.

_rawFiles

在 lite 版的 Fireball 里，raw asset 并不仅仅是在 properties 里声明了 rawType 才有， 而是每个 asset 都能指定自己的 raw file url。这些 url 就存在 _rawFiles 字段中。 AssetLibrary 并不会帮你加载这些 url，除非你声明了 rawType。 在 Creator 里，_rawFiles 保留了下来，为了复用 cocos 引擎原有实现，直接用 _rawFiles 来加载 Asset 在 import 之前的源文件。

_uuid

_name

_objFlags

name

The name of the object.

Examples

obj.name = "New Obj";

isValid

Indicates whether the object is not yet destroyed.

Examples

cc.log(obj.isValid);

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

addLoadedEventListener

Add a event listener for texture loaded event.

Parameters

• callback Function
• target Object

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();

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

_setRawFiles

Set raw file names for this asset.

Parameters

• rawFiles String[]

_preloadRawFiles

Preload raw files when loading scene.

Parameters

• callback Function
  • error Error

on

Register an callback of a specific event type on the EventTarget.

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

  • event Event event
• target Object The target (this object) to invoke the callback, can be null
• useCapture Boolean When set to true, the capture argument prevents callback

                         from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE.
                         When false, callback will NOT be invoked when event's eventPhase attribute value is CAPTURING_PHASE.
                         Either way, callback will be invoked when event's eventPhase attribute value is AT_TARGET.
  

Examples

node.on(cc.Node.EventType.TOUCH_END, function (event) {
    cc.log("this is callback");
}, 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
• useCapture Boolean Specifies whether the callback being removed was registered as a capturing callback or not.

                         If not specified, useCapture defaults to false. If a callback was registered twice,
                         one with capture and one without, each must be removed separately. Removal of a capturing callback
                         does not affect a non-capturing version of the same listener, and vice versa.
  

Examples

// register touchEnd eventListener
var touchEnd = node.on(cc.Node.EventType.TOUCH_END, function (event) {
    cc.log("this is callback");
}, node);
// remove touch end event listener
node.off(cc.Node.EventType.TOUCH_END, touchEnd, node);
// remove all touch end event listeners
node.off(cc.Node.EventType.TOUCH_END);

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

  • event Event event
• target Object The target (this object) to invoke the callback, can be null
• useCapture Boolean When set to true, the capture argument prevents callback

                         from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE.
                         When false, callback will NOT be invoked when event's eventPhase attribute value is CAPTURING_PHASE.
                         Either way, callback will be invoked when event's eventPhase attribute value is AT_TARGET.
  

Examples

node.once(cc.Node.EventType.TOUCH_END, function (event) {
    cc.log("this is callback");
}, node);

dispatchEvent

Dispatches an event into the event flow. The event target is the EventTarget object upon which the dispatchEvent() method is called.

Parameters

• event Event The Event object that is dispatched into the event flow

emit

Send an event to this object directly, this method will not propagate the event to any other objects. The event will be created from the supplied message, you can get the "detail" argument from event.detail.

Parameters

• message String the message to send
• detail Any whatever argument the message needs

destroy

Destroy this Object, and release all its own references to other objects.
Actual object destruction will delayed until before rendering.
After destroy, this CCObject 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