Cocos Creator API

1.5.x

Cocos Creator is the game engine for the future.

SpriteFrame

Uses
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

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

Properties

_textureFilenameSetter String private readOnly

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 readOnly

Inherited from Asset:

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

rawUrls String[] readOnly

Inherited from Asset:

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

_rawFiles String[] private

Inherited from Asset:

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

_uuid String private

Inherited from RawAsset:

_name String private

_objFlags Number private

name String

The name of the object.

examples:

obj.name = "New Obj";

isValid Boolean readOnly

Indicates whether the object is not yet destroyed.

examples:

cc.log(obj.isValid);

There are no properties that match your current filter settings. You can change your filter settings in the index section on this page. index

Methods

constructor
(
  • [filename ]
  • [rect ]
  • [rotated ]
  • [offset ]
  • [originalSize ]
)

Constructor of SpriteFrame class.

name type description
filename optional String | Texture2D
rect optional Rect
rotated optional Boolean

Whether the frame is rotated in the texture
offset optional Vec2

The offset of the frame in the texture
originalSize optional Size

The size of the frame in the texture

textureLoaded ( ) boolean

Returns whether the texture have been loaded

returns:

type: boolean

addLoadedEventListener
(
  • callback
  • target
)
deprecated

deprecated: since 3.1, please use EventTarget API instead

Add a event listener for texture loaded event.

name type description
callback Function
target Object

isRotated ( ) Boolean

Returns whether the sprite frame is rotated in the texture.

returns:

type: Boolean

setRotated
(
  • bRotated
)

Set whether the sprite frame is rotated in the texture.

name type description
bRotated Boolean

getRect ( ) Rect

Returns the rect of the sprite frame in the texture.

returns:

type: Rect

setRect
(
  • rect
)

Sets the rect of the sprite frame in the texture.

name type description
rect Rect

getOriginalSize ( ) Size

Returns the original size of the trimmed image.

returns:

type: Size

setOriginalSize
(
  • size
)

Sets the original size of the trimmed image.

name type description
size Size

getTexture ( ) Texture2D

Returns the texture of the frame.

returns:

type: Texture2D

getOffset ( ) Vec2

Returns the offset of the frame in the texture.

returns:

type: Vec2

setOffset
(
  • offsets
)

Sets the offset of the frame in the texture.

name type description
offsets Vec2

clone ( ) SpriteFrame

Clone the sprite frame.

returns:

type: SpriteFrame

setTexture
(
  • textureOrTextureFile
  • [rect =null]
  • [rotated =false]
  • [offset =cc.v2(0,0)]
  • [originalSize =rect.size]
)
Boolean

#en Set SpriteFrame with Texture, rect, rotated, offset and originalSize.
#zh 通过 Texture，rect，rotated，offset 和 originalSize 设置 SpriteFrame

name type description
textureOrTextureFile String | Texture2D
rect optional Rect null
rotated optional Boolean false
offset optional Vec2 cc.v2(0,0)
originalSize optional Size rect.size

returns:

type: Boolean

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

Inherited from Asset:

应 AssetDB 要求提供这个方法

returns:

type: String

createNode
(
  • callback
)

Inherited from Asset:

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.

name type description
callback Function
  • error String

    null or the error info

  • node Object

    the created node or null

_setRawFiles
(
  • rawFiles
)
private

Inherited from Asset:

Set raw file names for this asset.

name type description
rawFiles String[]

_preloadRawFiles
(
  • callback
)
private

Inherited from Asset:

Preload raw files when loading scene.

name type description
callback Function

on
(
  • type
  • callback
  • [target ]
  • [useCapture =false]
)
Function

Inherited from EventTarget:

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

name type description
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).
target optional Object

The target to invoke the callback, can be null
useCapture optional Boolean false

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.

returns:

type: Function

Just returns the incoming callback so you can save the anonymous function easier.

examples:

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

off
(
  • type
  • callback
  • [target ]
  • [useCapture =false]
)

Inherited from EventTarget:

Removes the callback previously registered with the same type, callback, target and or useCapture.

name type description
type String

A string representing the event type being removed.
callback Function

The callback to remove.
target optional Object

The target to invoke the callback, if it's not given, only callback without target will be removed
useCapture optional Boolean false

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 touchEnd eventListener
node.off(cc.Node.EventType.TOUCH_END, touchEnd, node);

targetOff
(
  • target
)

Inherited from EventTarget:

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.

name type description
target Object

The target to be searched for all related listeners

once
(
  • type
  • callback
  • [target ]
  • [useCapture =false]
)

Inherited from EventTarget:

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

name type description
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).
target optional Object

The target to invoke the callback, can be null
useCapture optional Boolean false

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
(
  • event
)

Inherited from EventTarget:

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

name type description
event Event

The Event object that is dispatched into the event flow

emit
(
  • message
  • [detail ]
)

Inherited from EventTarget:

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.

name type description
message String

the message to send
detail optional Any

whatever argument the message needs

destroy ( ) Boolean

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.

returns:

type: Boolean

whether it is the first time the destroy being called

examples:

obj.destroy();

_destruct ( ) private

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

Called before the object being destroyed.

_serialize
(
  • exporting
)
object private

The customized serialization for this object. (Editor Only)

name type description
exporting Boolean

returns:

type: object

the serialized json data object

_deserialize
(
  • data
  • ctx
)
private

Init this object from the custom serialized data.

name type description
data Object

the serialized json data
ctx _Deserializer

There are no methods that match your current filter settings. You can change your filter settings in the index section on this page. index