存档

‘cocos2d-js’ 分类的存档

【cocos2d-js官方文档】二十五、Cocos2d-JS v3.0中的单例对象

2014年12月22日 没有评论

为何将单例模式移除

在Cocos2d-JS v3.0之前,所有API几乎都是从Cocos2d-x中移植过来的,这是Cocos2d生态圈统一性的重要一环。可惜的是,这种统一性也在很大程度上限制了Cocos2d-html5的发展,有一些在C++中非常有意义的涉及搬到Html5平台后却使得Cocos2d-html5变得臃肿。所以在3.0版中,我们决定将一些API改造成更适合JavaScript开发人员的API。这篇文档中将要展示的是单例类的改造。拿cc.SpriteFrameCache为例:

// 在2.2.2版中,如果我们想通过cc.SpriteFrameCache来创建帧图像,再通过帧图像来创建Sprite
cc.SpriteFrameCache.getInstance().addSpriteFrames(s_boxs_plist);
var boxFrame = cc.SpriteFrameCache.getInstance().getSpriteFrame("box_normal_00.png");
var sprite = cc.Sprite.createWithSpriteFrame(boxFrame);

首先,这样的代码很长并且较难阅读。其次,不论cc.SpriteFrameCache的单例对象是否被创建,获取它都将产生函数调用。如果开发者们不够注意,使用它加载很多帧图像并且创建很多精灵又不缓存cc.SpriteFrameCache的单例对象,那么在javascript上必然造成一定程度的性能损失。最后,也是最重要的是,单例设计模式是为了保护类的单例对象,防止用户重复创建其对象。不过作为javascript开发者我们都知道,这没什么意义:

// 我们可以很容易得获取`cc.SpriteFrameCache`的实际单例对象
cc.s_sharedSpriteFrameCache.addSpriteFrames(s_boxs_plist);
// 如果我们想,我们也可以创建另一个精灵帧缓存对象
var myCache = new cc.SpriteFrameCache();

因此,我们决定Cocos2d-JS v3.0的首要任务就是提供一套更精简更符合JavaScript代码风格的API,这也是重构单例类的好机会。

重构列表

v3.0中部分被重构的单例类如下 :

// In engine core
cc.Configuration.getInstance()              --> cc.configuration
cc.ShaderCache.getInstance()                --> cc.shaderCache
cc.TextureCache.getInstance()               --> cc.textureCache
cc.AnimationCache.getInstance()             --> cc.animationCache
cc.SpriteFrameCache.getInstance()           --> cc.spriteFrameCache
cc.Screen.getInstance()                     --> cc.screen
cc.TIFFReader.getInstance()                 --> cc.tiffReader
cc.IMEDispatcher.getInstance()              --> cc.imeDispatcher

// In extension
ccs.GUIReader.getInstance()                 --> ccs.guiReader
ccs.SceneReader.getInstance()               --> ccs.sceneReader
ccs.DataReaderHelper                        --> ccs.dataReaderHelper
ccs.SpriteFrameCacheHelper.getInstance()    --> ccs.spriteFrameCacheHelper
ccs.ArmatureDataManager.getInstance()       --> ccs.armatureDataManager
ccs.ActionManager.getInstance()             --> ccs.actionManager
ccs.TriggerMng.getInstance()                --> ccs.triggerManager
ccs.ObjectFactory.getInstance()             --> ccs.objectFactory

这些单例类在3.0中变成了纯对象,类似下面的实现:

cc.screen = {
    init: function () {
        //...
    },

    fullScreen: function() {
        //...
    },

    requestFullScreen: function (element, onFullScreenChange) {
        //...
    },

    exitFullScreen: function () {
        //...
    },

    autoFullScreen: function (element, onFullScreenChange) {
        //...
    }
};

另一方面,当我们需要继承和扩展时,作为类本身对于结构可能是很有裨益的,所以并不是所有的单例类都适合被重构为对象。但是我们又希望提供给开发者统一的API风格,所以我们保留了部分类的类实现并且直接提供了它的单例对象,以下这些类在3.0版中是这样实现的:

cc.AudioEngine.getInstance()        --> cc.audioEngine
cc.Director.getInstance()           --> cc.director
cc.EGLView.getInstance()            --> cc.view
cc.SAXParser.getInstance()          --> cc.saxParser
cc.PlistParser.getInstance()        --> cc.plistParser

请留意所有单例对象都是以首字母小写来命名的,这是为了区分一个变量名代表的是类还是对象。

另外,cc.EGLView是最早在Cocos2d-iPhone中被定义的,所以它的名字来源于iOS中的OpenGL ES视图的名字。但是在Cocos2d-JS中,它仅仅是游戏的视图,可以是WebGL或OpenGL视图但同时也可能是Canvas视图,所以我们决定将它重命名为cc.view

结果

重构之后,文档最初的例子在v3.0中将如下面代码所示:

cc.spriteFrameCache.addSpriteFrames(s_boxs_plist);
var boxFrame = cc.spriteFrameCache.getSpriteFrame("box_normal_00.png");
var sprite = cc.Sprite.createWithSpriteFrame(boxFrame);

我们衷心希望这种新的API风格可以让JavaScript开发者们开发起来更加得心应手。

分类: cocos2d, cocos2d-js 标签:

【cocos2d-js官方文档】二十四、如何在android平台上使用js直接调用Java方法

2014年12月20日 没有评论

在cocos2d-js 3.0beta中加入了一个新特性,在android平台上我们可以通过反射直接在js中调用java的静态方法。它的使用方法很简单:

var o = jsb.reflection.callStaticMethod(className, methodName, methodSignature, parameters...)

callStaticMethod方法中,我们通过传入Java的类名,方法名,方法签名,参数就可以直接调用Java的静态方法,并且可以获得Java方法的返回值。下面介绍的类名和方法签名可能会有一点奇怪,但是Java的规范就是如此的。

类名

参数中的类名必须是包含Java包路径的完整类名,例如我们在org.cocos2dx.javascript这个包下面写了一个Test类:

package org.cocos2dx.javascript;

public class Test {

    public static void hello(String msg){
        System.out.println(msg);
    }

    public static int sum(int a, int b){
        return a + b;
    }

    public static int sum(int a){
        return a + 2;
    }

}

那么这个Test类的完整类名应该是org/cocos2dx/javascript/Test,注意这里必须是斜线/,而不是在Java代码中我们习惯的点.

方法名

方法名很简单,就是方法本来的名字,例如sum方法的名字就是sum

方法签名

方法签名稍微有一点复杂,最简单的方法签名是()V,它表示一个没有参数没有返回值的方法。其他一些例子:

  • (I)V表示参数为一个int,没有返回值的方法
  • (I)I表示参数为一个int,返回值为int的方法
  • (IF)Z表示参数为一个int和一个float,返回值为boolean的方法

现在有一些理解了吧,括号内的符号表示参数类型,括号后面的符号表示返回值类型。因为Java是允许函数重载的,可以有多个方法名相同但是参数返回值不同的方法,方法签名正是用来帮助区分这些相同名字的方法的。

目前Cocos2d-js中支持的Java类型签名有下面4种:

Java类型 签名
int I
float F
boolean Z
String Ljava/lang/String;

参数

参数可以是0个或任意多个,直接使用js中的number,bool和string就可以。

使用示例

我们将会调用上面的Test类中的静态方法:

//调用hello方法
jsb.reflection.callStaticMethod("org/cocos2dx/javascript/Test", "hello", "(Ljava/lang/String;)V", "this is a message from js");

//调用第一个sum方法
var result = jsb.reflection.callStaticMethod("org/cocos2dx/javascript/Test", "sum", "(II)I", 3, 7);
cc.log(result); //10

//调用第二个sum方法
var result = jsb.reflection.callStaticMethod("org/cocos2dx/javascript/Test", "sum", "(I)I", 3);
cc.log(result); //5

在你的控制台会有正确的输出的,这很简单吧。

注意

另外有一点需要注意的就是,在android应用中,cocos的渲染和js的逻辑是在gl线程中进行的,而android本身的UI更新是在app的ui线程进行的,所以如果我们在js中调用的Java方法有任何刷新UI的操作,都需要在ui线程进行。

例如,在下面的例子中我们会调用一个Java方法,它弹出一个android的Alert对话框。

//给我们熟悉的AppActivity类稍微加点东西
public class AppActivity extends Cocos2dxActivity {

    private static AppActivity app = null;
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        app = this;
    }

    public static void showAlertDialog(final String title,final String message) {

        //这里一定要使用runOnUiThread
        app.runOnUiThread(new Runnable() {
            @Override
            public void run() {
                AlertDialog alertDialog = new AlertDialog.Builder(app).create();
                alertDialog.setTitle(title);
                alertDialog.setMessage(message);
                alertDialog.setIcon(R.drawable.icon);
                alertDialog.show();
            }
        });
    }
}

然后我们在js中调用

jsb.reflection.callStaticMethod("org/cocos2dx/javascript/AppActivity", "showAlertDialog", "(Ljava/lang/String;Ljava/lang/String;)V", "title", "hahahahha");

这样调用你就可以看到一个android原生的Alert对话框了。

再加点料

现在我们可以从js调用Java了,那么能不能反过来?当然可以! 在你的项目中包含Cocos2dxJavascriptJavaBridge,这个类有一个evalString方法可以执行js代码,它位于frameworks/js-bindings/bindings/manual/platform/android/java/src/org/cocos2dx/lib文件夹下。我们将会给刚才的Alert对话框增加一个按钮,并在它的响应中执行js。和上面的情况相反,这次执行js代码必须在gl线程中进行。

alertDialog.setButton("OK", new DialogInterface.OnClickListener() {
    public void onClick(DialogInterface dialog, int which) {
        //一定要在GL线程中执行
        app.runOnGLThread(new Runnable() {
            @Override
            public void run() {
                Cocos2dxJavascriptJavaBridge.evalString("cc.log(/"Javascript Java bridge!/")");
            }
        });
    }
});

这样在点击OK按钮后,你应该可以在控制台看到正确的输出。evalString可以执行任何js代码,并且它可以访问到你在js代码中的对象。

分类: cocos2d, cocos2d-js 标签:

【cocos2d-js官方文档】二十三、如何在IOS平台上使用js直接调用OC方法

2014年12月20日 没有评论

在Cocos2d-JS v3.0 RC2中,与Android上js调用Java一样,Cocos2d-JS也提供了在iOS和Mac上js直接调用Objective-C的方法,示例代码如下:

    var ojb = jsb.reflection.callStaticMethod(className, methodNmae, arg1, arg2, .....);

jsb.reflection.callStaticMethod方法中,我们通过传入OC的类名,方法名,参数就可以直接调用OC的静态方法,并且可以获得OC方法的返回值。

  • 参数中的类名,只需要传入OC中的类名即可,与Java不同,类名并不需要路径。比如你在工程底下新建一个类NativeOcClass,只要你将他引入工程,那么他的类名就是NativeOcClass,你并不需要传入它的路径。
    import <Foundation/Foundation.h>
    @interface NativeOcClass : NSObject
    +(BOOL)callNativeUIWithTitle:(NSString *) title andContent:(NSString *)content;
    @end

方法

  • js到OC的反射仅支持OC中类的静态方法。
  • 方法名比较要需要注意,我们需要传入完整的方法名,特别是当某个方法带有参数的时候,你需要将他的:也带上。根据上面的例子。此时的方法名字是callNativeUIWithTitle:andContent:,不要漏掉了他们之间的:
  • 如果是没有参数的函数,那么他就不需要:,如下代码,他的方法名是callNativeWithReturnString,由于没有参数,他不需要:,跟OC的method写法一致。
    +(NSString *)callNativeWithReturnString;

使用示例

  • 下面的示例代码将调用上面NativeOcClass的方法,在js层我们只需要这样调用:
    var ret = jsb.reflection.callStaticMethod("NativeOcClass", 
                                               "callNativeUIWithTitle:andContent:", 
                                               "cocos2d-js", 
                                               "Yes! you call a Native UI from Reflection");
  • 这里是这个方法在OC的实现,可以看到是弹出一个native的对话框。并把titlecontent设置成你传入的参数,并返回一个boolean类型的返回值。
    +(BOOL)callNativeUIWithTitle:(NSString *) title andContent:(NSString *)content{
        UIAlertView *alertView = [[UIAlertView alloc] initWithTitle:title message:content delegate:self cancelButtonTitle:@"Cancel" otherButtonTitles:@"OK", nil];
        [alertView show];
        return true;
    }
  • 此时,你就可以在ret中接受到从OC传回的返回值(true)了。

注意

在OC的实现中,如果方法的参数需要使用float、int、bool的,请使用如下类型进行转换:

  • float,int 请使用NSNumber类型
  • bool请使用BOOL类型。
  • 例如下面代码,我们传入2个浮点数,然后计算他们的合并返回,我们使用NSNumber而不是int、float去作为参数类型。
+(float) addTwoNumber:(NSNumber *)num1 and:(NSNumber *)num2{
    float result = [num1 floatValue]+[num2 floatValue];
    return result;
}
  • 目前参数和返回值支持 int, float, bool, string,其余的类型暂时不支持。

转载自:http://www.cocos2dx.net/post/254

分类: cocos2d, cocos2d-js 标签:

【cocos2d-js官方文档】二十二、project.json

2014年12月18日 没有评论

概述

项目相关配置,由原来的cocos2d.js中转移到project.json中,该文件需要与index.html同级,一般建议放在根目录下。

由原来的cocos2d.js改为project.json的好处如下:

  • 原来的cocos2d.js中参杂了一些逻辑代码,无法很好体现其就是作为项目的配置文件。

  • 用json格式作为配置文件会更友好。也可以使得cocos-consolecocos-utils,甚至是用户自定义脚本工具能够使用同一个配置文件。

字段说明

debugMode

相当于原来的COCOS2D_DEBUG,其中:

0表示关闭调试模式,1表示log,2表示warn,3表示error,5表示logForWebPage,6表示warnForWebPage,7表示errorForWebPage。

renderMode

跟原来配置相同,表示渲染模式。0为默认,1为canvas,2为webgl。

showFPS

跟原来配置相同,表示是否开启帧率显示。默认为false。

frameRate

跟原来配置相同,表示设置帧率。默认为60。

engineDir

跟原来配置相同,用于指定引擎目录。区别在于,在v2版本中,指向的是**/cocos2d-html5/cocos2d,但在v3版本中,只要指向**/cocos2d-html5就行了。
默认为"frameworks/cocos2d-html5"。

jsList

相当于原来的appFiles,用于罗列用于js列表。

id

相当于原来的tag,用于指定canvas的id。

modules

用于指定加载模块。

在v2版本中,只能通过loadExtensionbox2dchipmunkpluginx等开关来指定是否使用某个模块。

在v3版本中则使用modules字段,灵活进行配置,这也能较好的支持今后引擎进行模块裁剪。配置如下:

"modules" : ["extensions", "pluginx", "box2d", "chipmunk"]

如果想知道引擎中具体提供了哪些模块,可以参见moduleConfig.json文件中的module字段。

转载自: http://www.cocos2dx.net/post/250

分类: cocos2d, cocos2d-js 标签:

【cocos2d-js官方文档】二十一、v3相对于v2版本的api变动

2014年12月18日 没有评论

CCAudio.js

SimpleAudioEngine.js改名为CCAudio.js

AudioEngine中删除了以下几个方法:

preloadMusic
preloadEffect
isFormatSupported
preloadSound

cc.AudioEngine.end被移到了实例中,而不是作为类的静态方法。

cc.textureCache

删除了以下的几个api:

cc.loadImg
cc.loadImage.handler
cc.computeImageFormatType

addImageAsync方法被合并到了addImage中去了。

CCTGAlib.js

移除了cc.tgaLoad

cc.Texture2D

改动:

cc.TEXTURE_2D_PIXEL_FORMAT_RGBA8888     --> cc.Texture2D.PIXEL_FORMAT_RGBA8888
cc.TEXTURE_2D_PIXEL_FORMAT_RGB888       --> cc.Texture2D.PIXEL_FORMAT_RGB888
cc.TEXTURE_2D_PIXEL_FORMAT_RGB565       --> cc.Texture2D.PIXEL_FORMAT_RGB565
cc.TEXTURE_2D_PIXEL_FORMAT_A8           --> cc.Texture2D.PIXEL_FORMAT_A8
cc.TEXTURE_2D_PIXEL_FORMAT_I8           --> cc.Texture2D.PIXEL_FORMAT_I8
cc.TEXTURE_2D_PIXEL_FORMAT_AI88         --> cc.Texture2D.PIXEL_FORMAT_AI88
cc.TEXTURE_2D_PIXEL_FORMAT_RGBA4444     --> cc.Texture2D.PIXEL_FORMAT_RGBA4444
cc.TEXTURE_2D_PIXEL_FORMAT_RGB5A1       --> cc.Texture2D.PIXEL_FORMAT_RGB5A1
cc.TEXTURE_2D_PIXEL_FORMAT_PVRTC4       --> cc.Texture2D.PIXEL_FORMAT_PVRTC4
cc.TEXTURE_2D_PIXEL_FORMAT_PVRTC2       --> cc.Texture2D.PIXEL_FORMAT_PVRTC2
cc.TEXTURE_2D_PIXEL_FORMAT_DEFAULT      --> cc.Texture2D.PIXEL_FORMAT_DEFAULT
cc.Texture2D.setDefaultAlphaPixelFormat(format) --> cc.Texture2D.defaultPixelFormat = format
cc.Texture2D.getDefaultAlphaPixelFormat()       --> cc.Texture2D.defaultPixelFormat
cc.Texture2D.defaultAlphaPixelFormat()          --> cc.Texture2D.defaultPixelFormat

cc.Scheduler

cc.PRIORITY_SYSTEM改为cc.Scheduler.PRIORITY_SYSTEM

数组操作函数

这些函数有些将名字开头改为小写,有些废弃了直接用Array的函数进行操作。

cc.ArrayVerifyType --> cc.arrayVerifyType
cc.ArrayRemoveObject --> cc.arrayRemoveObject
cc.ArrayRemoveArray ---> cc.arrayRemoveArray
cc.ArrayAppendObjectsToIndex --> cc.arrayAppendObjectsToIndex

cc.ArrayRemoveObjectAtIndex(arr, index) --> arr.splice(index, 1)
cc.ArrayGetIndexOfValue(arr, value) --> arr.indexOf(value)
cc.ArrayAppendObject(arr, addObj) --> arr.push(addObj)
cc.ArrayAppendObjectToIndex(arr, addObj, index) --> arr.splice(index, 0, addObj)
cc.ArrayGetIndexOfObject(arr, findObj) --> arr.indexOf(findObj)
cc.ArrayContainsObject(arr, findObj) --> arr.indexOf(findObj) != -1

remove cc.HASH_FIND_INT

共有方法或对象变成私有方法或对象:

cc.setup                    --> cc._setup
cc.initDebugSetting         --> cc._initDebugSetting
cc.canvas                   --> cc._canvas
cc.drawingUtil              --> cc._drawingUtil
cc.renderContext            --> cc._renderContext
cc.gameDiv                  --> cc._gameDiv
cc.setContextMenuEnable     --> cc._setContextMenuEnable
cc.renderContextType        --> cc._renderType
cc.CANVAS                   --> cc._RENDER_TYPE_CANVAS
cc.WEBGL                    --> cc._RENDER_TYPE_CANVAS
cc.mainRenderContextBackup  --> cc._mainRenderContextBackup
cc.RectFromString           --> cc.spriteFrameCache._rectFromString
cc.PointFromString          --> cc.spriteFrameCache._pointFromString
cc.SizeFromString           --> cc.spriteFrameCache._sizeFromString

常量

删除:

cc.IS_SHOW_DEBUG_ON_PAGE
cc.COCOS2D_DEBUG

其他

修改

cc.dumpConfig ---> cc.sys.dump

删除:

cc.isAddedHiddenEvent
cc.originalCanvasSize

新增:

cc.BuilderReader.registerController

转载自: http://www.cocos2dx.net/post/247

分类: cocos2d, cocos2d-js 标签:

【cocos2d-js官方文档】二十、moduleConfig.json

2014年12月17日 没有评论

概述

该配置文件相当于v2版本中的jsloader.js。改造的目的是为了使得配置纯粹化,同时也能比较好的支持cocos-consolecocos-utils甚至是用户自定义脚本工具。

字段说明

module

配置各个模块的js列表。key名即为模块名称。这些key名将会在project.jsonmodules字段中使用。倘若不清楚project.json里面究竟有哪些模块可以配置,就可以直接查看该文件。

每个模块的配置对象是一个数组,数组项分两种,一种是模块名,一种是js路径。

例如:

"menus" : [
    "core", "actions",

    "cocos2d/menus/CCMenuItem.js",
    "cocos2d/menus/CCMenu.js"
]

此配置的意思是,menus模块依赖于coreactions模块,并且自身包含cocos2d/menus/CCMenuItem.jscocos2d/menus/CCMenu.js

转载自:http://www.cocos2dx.net/post/245

分类: cocos2d, cocos2d-js 标签:

【cocos2d-js官方文档】十九、Cocos2d-JS单文件引擎使用指引

2014年12月17日 没有评论

这篇指引主要介绍如何使用从在线下载工具下载下来的Cocos2d-JS的单文件引擎。

你有可能下载了下面三个版本中的一个:

  • Cocos2d-JS Full Version: 完整版引擎包含Cocos2d-JS引擎的所有功能特性以及所有扩展,使用这个版本可以帮助你发掘Cocos2d-JS令人惊艳的创造力和可能性。你可以从官方文档首页中查看Cocos2d-JS所支持的特性列表。

  • Cocos2d-JS Lite Version: 精简版本只包含Cocos2d-JS的核心特性,它的优势是稳定,轻量,简单易用。它所包含的特性列表如下:

    • Canvas渲染器 (不支持WebGL)
    • 场景和图层
    • 事件管理器
    • 计时器
    • 精灵和贴图
    • TTF文本
    • 声音
    • 动作
    • 菜单和菜单项
  • Customized Version: 如果你选择了定制版本的引擎,引擎脚本文件将包含你所选择的所有特性。

使用方式

单文件引擎的使用方式和其他Web库完全一样,你只需要将脚本嵌入到你的页面中即可,可以参考下载目录中的HelloWorld.html。

请注意脚本的加载时机,在HelloWorld的示例代码中:

window.onload = function(){
    cc.game.onStart = function(){
        //...
    };
    cc.game.run("gameCanvas");
};

可以看到,cc.game.onStartcc.game.run都在window的onload函数中,因为只有在这时才能保证cocos2d-js-v3.0.js已经被加载成功,并且可以在你的用户脚本中使用Cocos2d-JS的API。在我们后面章节中将提到Cocos2d-JS的另一种传统工作流,那种工作流中由引擎脚本控制脚本的加载顺序,所以不需要检测页面的加载。

你需要将这些文件放到一个本地服务器或在线服务器并通过服务器访问才可以看到正确的结果。

帮助链接

关于脚本压缩

你可以使用Google Closure Compiler来将所有js文件压缩成一个文件,Closure Compiler的高级压缩压缩比非常高,即便你下载的是压缩版引擎,也可以获得可观的压缩比。具体压缩步骤如下:

  1. 下载Closure Compiler的jar程序文件
  2. 按照自己的环境配置build.xml
  3. 在控制台运行ant命令
  4. 将页面中的所有js引用删除,引入打包出的game.min.js

请注意,你不可以在html页面中写任何js脚本,所有js脚本都必须一起打包起来,否则会引起错误。

注意

当你通过服务器访问游戏页面的时候,你将在控制台中发现一个错误提示: “Failed to load resource: the server responded with a status of 404 (Not Found)”,提示project.json文件找不到

这是正常现象,并不是问题,你可以忽略它。或者可以添加一个空的project.json文件来避免这个错误报告。

分类: cocos2d, cocos2d-js 标签:

【cocos2d-js官方文档】十八、Cocos2d-js v3.0的对象构造和类继承

2014年12月16日 没有评论

在Cocos2d-JS中,对象的构造方式和Cocos2d-x一样,使用各个类的create函数来构造。在Cocos2d-JS v3.0我们还将为你带来一种传统的方式,即使用new操作符。另外,在v3.0
alpha1版本中,因为我们还没有找到较好的解决办法,所以不能继承JSB中的引擎类。但是在v3.0 alpha2中,这个问题已经解决了。由于使用new操作符,编写继承代码也更加容易了。

在这篇文档中,我们将会介绍如何使用它们,以及简要的实现原理。

1.
弃用的create函数

由于Cocos2d-JS v3.0支持了更简单方便的new构造方式,所有create以及createWithXXX函数都被弃用了,调用它们将会收到警告消息。new构造方式支持所有类型的旧create函数的参数。

开发者有两种方式构造一个Sprite对象:统一的create函数和new操作符调用构造函数,它们接受相同的参数。在html5和jsb中都支持这2种方式,但是他们的实现原理大不相同。

2.
构造函数

我们现在可以直接使用new操作符来调用类的构造函数了。例如,开发者们应该使用new
cc.Sprite(...)
来创建一个cc.Sprite对象,在html5和jsb中都支持这种方式,但是他们的实现原理大不相同:

var sprite = new cc.Sprite(filename, rect);
var sprite = new cc.Sprite(texture, rect);
var sprite = new cc.Sprite(spriteFrameName);

在html5引擎中,我们重构了所有引擎类的ctor函数,使它们可以接受和create函数相同的参数。

在JSB中如果使用new操作符来调用cc.Sprite的构造函数,我们实际上在C++层会调用js_cocos2dx_Sprite_constructor函数。在这个C++函数中,会为这个精灵对象分配内存,并把它添加到自动回收池,然后调用js层的_ctor函数来完成初始化。在_ctor函数中会根据参数类型和数量调用不同的init函数,这些init函数也是C++函数的绑定:

Javascript JSB Cocos2d-x
cc.Sprite.initWithSpriteFrameName js_cocos2dx_Sprite_initWithSpriteFrameName cocos2d::Sprite::initWithSpriteFrameName
cc.Sprite.initWithSpriteFrame js_cocos2dx_Sprite_initWithSpriteFrame cocos2d::Sprite::initWithSpriteFrame
cc.Sprite.initWithFile js_cocos2dx_Sprite_initWithFile cocos2d::Sprite::initWithFile
cc.Sprite.initWithTexture js_cocos2dx_Sprite_initWithTexture cocos2d::Sprite::initWithTexture

这个过程的顺序图如下:

【cocos2d-js官方文档】十八、Cocos2d-js v3.0的对象构造和类继承

3.
继承

在Cocos2d-html5 2.x中,当我们继承一个类时,我们需要在create函数中使用不同的init函数,例如:

var MySprite = cc.Sprite.extend({
    ctor:function(){
        this._super();
        // 自定义初始化
    }
    // 添加自己的属性和方法
});
MySprite.create = function(filename,rect){
    var sprite = new MySprite();
    // 使用材质和矩形区域初始化
    sprite.initWithTexture(fileName, rect);
    return sprite;
};

// 创建你的精灵
var sprite = MySprite.create(texture,cc.rect(0,0,480,320));

在Cocos2d-JS中,我们只需要编写带有正确参数的ctor函数,并调用_super函数就可以了。

var MySprite = cc.Sprite.extend({
    ctor:function(filename,rect){
        this._super(filename,rect);
        // 自定义初始化
    }
    // 添加自己的属性和方法
});

// 创建你的精灵
var sprite = new MySprite(texture,cc.rect(0,0,480,320));

在html5引擎中这很好理解,因为我们支持使用new操作符。

但在JSB中这有点复杂,在_super函数中我们会调用Sprite的C++层ctor函数:js_cocos2dx_Sprite_ctor,这个函数不仅实例化精灵对象,也会调用cc.Sprite.prototype._ctor并传递参数。_ctor函数对精灵类真正的初始化函数做了封装,会根据传递的参数来调用不同的初始化函数,这样我们最终就完成了自定义ctor函数的执行。

这个过程的顺序图如下:

【cocos2d-js官方文档】十八、Cocos2d-js v3.0的对象构造和类继承

转载:http://www.cocos2dx.net/post/238

分类: cocos2d, cocos2d-js 标签:

【cocos2d-js官方文档】十八、Cocos2d-JS v3.0中的属性风格API

2014年12月16日 没有评论

1. 新的API风格

我们直接来看看你可以如何使用Cocos2d-JS v3.0:

以前的API 新的API
node.setPosition(x, y); node.x = x;

node.y = y;
node.setRotation(r); node.rotation = r;

如表格中可以看到的,设置position属性的函数调用在3.0版中会被替换为直接的对象属性存取。不仅仅是示例中的xyrotation,几乎所有节点类型中关于属性存取的函数都会被替换为直接的对象属性访问。具体的属性列表在文档最后。

得益于JavaScript的getter/setter,我们可以为对象的某一个属性名分别设置其getter/setter函数。这就是Cocos2d-JS如何做到从函数到属性的转换。比如说,node.x
= x;
实际上调用了setPositionX函数并传入x作为参数,所以在使用属性风格API的时候请不要因为它的简单而感到担心,在很多情况下这等同于以前的函数调用。

你也可以给自己的对象属性定义getter/setter函数,只需要使用下面这行代码:

cc.defineGetterSetter(object, "propertyName", getterFunc, setterFunc);

这样的话,var a = object.propertyName;会通过getterFunc获取propertyName的当前值,object.propertyName
= newvalue;
则会通过setterFunc来给propertyName赋新值。

至于属性的命名,我们尽可能提供了类似css风格的属性名,除此之外的属性都尽力维持与v2.2.2中一致。选择类似css的属性名是为了给JavaScript开发者以最自然的开发体验。

2.
cc.Node的attr函数

新API使得Cocos2d-JS代码更加简洁,但这还不够,我们为cc.Node添加了更为简单易用的attr函数。与jQuery的attr函数相同,这个函数允许开发者批量设置多个属性。示例如下:

node.attr({
    x: 20,
    y: 20,
    anchorX: 0.5,
    anchorY: 0.5,
    width: 400,
    height: 300,
    scale: 2
});

值得一提的是,这个函数不仅仅支持文末列表中的属性,也支持开发者的自定义属性。

3.
改变的初衷

为什么Cocos2d-JS要对已稳定的API做出如此大的改变呢?我想最显而易见的答案已经体现在前面的示例中了:那就是更简单。

但是我们真正想改变的目标,并不仅仅是更简单而已,或者说简单并不是目标,而是结果。长期以来,Cocos2d-JS一直被WEB开发者诟病其复杂程度导致难于学习和使用。在与其他html5游戏引擎比较之后,我们发现我们引擎最大的问题是,它并不是为JavaScript开发者设计的。事实上确实如此,到目前为止,Cocos2d-JS引擎的实现目标一直是尽力与Cocos2d-x的API保持一致,而Cocos2d-x是为C++开发者设计的,与此同时,Cocos2d家族的起源Cocos2d-iPhone也在引擎中留下了非常多objective-C风格的API设计。很显然,正是由于这些API被直接移植到h5引擎中,JavaScript开发者才会觉得引擎非常复杂难用。

所以引擎3.0版本的主要目标就是提供给开发者一套全新的JavaScript风格API,开发团队决定冒着很大的风险推动这次重构。

回到属性风格API,cc.Node以及所有继承自cc.Node的类都使用属性风格重构。以往的大多数getXXX()setXXX(value)都被直接属性存取取代了。同时也有也有少数其他适合属性风格的类使用这种方式重构,它们都可以在文末的列表中找到。

4.
关于Closure Compiler

由于attr函数使用键值对来配置节点,当我们使用Closure Compiler的高级模式来混淆时,这可能会引起一些意想不到的错误。

简单来说,键值对中的键实质上是String类型,混淆过程中它并不会被压缩,而与之相对应的属性名却会被压缩,这导致了两者命名的不匹配。所幸,在引擎中我们保障了常用的属性不会被压缩,至于其他的属性和用户自定义属性,可以使用Closure Compiler的expose声明来避免出现问题。需要注意的是这个问题只有在开发者尝试使用attr函数来配置属性的时候才会出现,如果没有使用attr函数就不需要做任何额外的处理。

/** @expose */
node.shaderProgram;

/** @expose */
node.customProperty;

node.attr({
    shaderProgram: program,
    customProperty: 0
});

5.
通过继承来重载属性

另一个重要的问题是在继承过程中,如何重载父类中的属性。好消息是我们已经将这一机制在Cocos2d-JS的cc.Class中实现了。只要你重载了父类中的getter/setter函数,那么不需要重新定义,新的getter/setter会自动被绑定到属性上。下面是一个重载Sprite类中的x属性的例子:

var MySprite = cc.Sprite.extend({
    ctor: function() {
        this._super();
        this.init();
    },
    getPositionX: function() {
        // Your own implementation
    },
    setPositionX: function(x) {
        // Your own implementation
    }
});

var mySprite = new MySprite();

mySprite.x = x;会调用MySprite类的setPositionX函数而不是Sprite类的,getter函数也是同理。用户代码中唯一需要保证的是重载的getter/setter函数名必须和父类中定义的属性的getter/setter函数同名。否则你将需要通过cc.defineGetterSetter重新定义属性。

6.
属性列表

cc.Node

Property Type Accessibility Getter/Setter function Advanced Compress Ready
x Number R&W getPositionX, setPositionX YES
y Number R&W getPositionY, setPositionY YES
width Number R&W _getWidth, _setWidth YES
height Number R&W _getHeight, _setHeight YES
anchorX Number R&W _getAnchorX, _setAnchorX YES
anchorY Number R&W _getAnchorY, _setAnchorY YES
skewX Number R&W getSkewX, setSkewX YES
skewY Number R&W getSkewY, setSkewY YES
zIndex Number R&W getLocalZOrder, setLocalZOrder YES
vertexZ Number R&W getVertexZ, setVertexZ YES
rotation Number R&W getRotation, setRotation YES
rotationX Number R&W getRotationX, setRotationX YES
rotationY Number R&W getRotationY, setRotationY YES
scale Number R&W getScale, setScale YES
scaleX Number R&W getScaleX, setScaleX YES
scaleY Number R&W getScaleY, setScaleY YES
opacity Number R&W getOpacity, setOpacity YES
opacityModifyRGB Boolean R&W isOpacityModifyRGB, setOpacityModifyRGB YES
cascadeOpacity Boolean R&W isCascadeOpacityEnabled, setCascadeOpacityEnabled YES
color cc.Color R&W getColor, setColor YES
cascadeColor Boolean R&W isCascadeColorEnabled, setCascadeColorEnabled YES
children Array readonly getChildren YES
childrenCount Number readonly getChildrenCount YES
parent cc.Node R&W getParent, setParent YES
visible Boolean R&W isVisible, setVisible YES
running Boolean readonly isRunning YES
ignoreAnchor Boolean R&W isIgnoreAnchorPointForPosition, ignoreAnchorPointForPosition YES
tag Number R&W None YES
userData Object R&W None YES
userObject Object R&W None YES
arrivalOrder Number R&W None YES
actionManager cc.ActionManager R&W getActionManager, setActionManager YES
scheduler cc.Scheduler R&W getScheduler, setScheduler YES
grid cc.GridBase R&W None NO
shaderProgram cc.GLProgram R&W getShaderProgram, setShaderProgram YES

cc.Texture2D

Property Type Accessibility Getter/Setter function Advanced Compress Ready
name WebGLTexture readonly getName NO
pixelFormat Number readonly getPixelFormat NO
pixelsWidth Number readonly getPixelsWide NO
pixelsHeight Number readonly getPixelsHigh NO
width Number R&W _getWidth, _setWidth NO
height Number R&W _getHeight, _setHeight NO
shaderProgram cc.GLProgram R&W None NO
maxS Number R&W None NO
maxT Number R&W None NO

cc.Sprite

Extend from cc.NodeRGBA

Property Type Accessibility Getter/Setter function Advanced Compress Ready
dirty Boolean R&W None YES
flippedX Boolean R&W isFlippedX, setFlippedX YES
flippedY Boolean R&W isFlippedY, setFlippedY YES
offsetX Number readonly _getOffsetX YES
offsetY Number readonly _getOffsetY YES
atlasIndex Number R&W None YES
texture cc.Texture2D R&W getTexture, setTexture YES
textureRectRotated Boolean readonly isTextureRectRotated YES
textureAtlas cc.TextureAtlas R&W None YES
batchNode cc.SpriteBatchNode R&W getBatchNode, setBatchNode YES
quad cc.V3F_C4B_T2F_Quad readonly getQuad YES

cc.LabelTTF

Extend from cc.Sprite

Property Type Accessibility Getter/Setter function Advanced Compress Ready
string String R&W getString, setString YES
textAlign Number R&W getHorizontalAlignment, setHorizontalAlignment YES
verticalAlign Number R&W getVerticalAlignment, setVerticalAlignment YES
fontSize Number R&W getFontSize, setFontSize YES
fontName String R&W getFontName, setFontName YES
font String R&W _getFont, _setFont YES
boundingWidth Number R&W _getBoundingWidth, _setBoundingWidth YES
boundingHeight Number R&W _getBoundingHeight, _setBoundingHeight YES
fillStyle cc.Color R&W _getFillStyle, setFontFillColor YES
strokeStyle cc.Color R&W _getStrokeStyle, _setStrokeStyle YES
lineWidth Number R&W _getLineWidth, _setLineWidth YES
shadowOffsetX Number R&W _getShadowOffsetX, _setShadowOffsetX YES
shadowOffsetY Number R&W _getShadowOffsetY, _setShadowOffsetY YES
shadowOpacity Number R&W _getShadowOpacity, _setShadowOpacity YES
shadowBlur Number R&W _getShadowBlur, _setShadowBlur YES

cc.Node

Property Type Accessibility Getter/Setter function Advanced Compress Ready
x Number R&W getPositionX, setPositionX YES
y Number R&W getPositionY, setPositionY YES
width Number R&W _getWidth, _setWidth YES
height Number R&W _getHeight, _setHeight YES
anchorX Number R&W _getAnchorX, _setAnchorX YES
anchorY Number R&W _getAnchorY, _setAnchorY YES
skewX Number R&W getSkewX, setSkewX YES
skewY Number R&W getSkewY, setSkewY YES
zIndex Number R&W getLocalZOrder, setLocalZOrder YES
vertexZ Number R&W getVertexZ, setVertexZ YES
rotation Number R&W getRotation, setRotation YES
rotationX Number R&W getRotationX, setRotationX YES
rotationY Number R&W getRotationY, setRotationY YES
scale Number R&W getScale, setScale YES
scaleX Number R&W getScaleX, setScaleX YES
scaleY Number R&W getScaleY, setScaleY YES
opacity Number R&W getOpacity, setOpacity YES
opacityModifyRGB Boolean R&W isOpacityModifyRGB, setOpacityModifyRGB YES
cascadeOpacity Boolean R&W isCascadeOpacityEnabled, setCascadeOpacityEnabled YES
color cc.Color R&W getColor, setColor YES
cascadeColor Boolean R&W isCascadeColorEnabled, setCascadeColorEnabled YES
children Array readonly getChildren YES
childrenCount Number readonly getChildrenCount YES
parent cc.Node R&W getParent, setParent YES
visible Boolean R&W isVisible, setVisible YES
running Boolean readonly isRunning YES
ignoreAnchor Boolean R&W isIgnoreAnchorPointForPosition, ignoreAnchorPointForPosition YES
tag Number R&W None YES
userData Object R&W None YES
userObject Object R&W None YES
arrivalOrder Number R&W None YES
actionManager cc.ActionManager R&W getActionManager, setActionManager YES
scheduler cc.Scheduler R&W getScheduler, setScheduler YES
grid cc.GridBase R&W None NO
shaderProgram cc.GLProgram R&W getShaderProgram, setShaderProgram YES

cc.Texture2D

Property Type Accessibility Getter/Setter function Advanced Compress Ready
name WebGLTexture readonly getName NO
pixelFormat Number readonly getPixelFormat NO
pixelsWidth Number readonly getPixelsWide NO
pixelsHeight Number readonly getPixelsHigh NO
width Number R&W _getWidth, _setWidth NO
height Number R&W _getHeight, _setHeight NO
shaderProgram cc.GLProgram R&W None NO
maxS Number R&W None NO
maxT Number R&W None NO

cc.TextureAtlas

Property Type Accessibility Getter/Setter function Advanced Compress Ready
dirty Boolean R&W None NO
texture Image R&W None NO
capacity Number readonly getCapacity NO
totalQuads Number readonly getTotalQuads NO
quads Array readonly getQuads, setQuads NO

cc.AtlasNode

Extend from cc.NodeRGBA

Property Type Accessibility Getter/Setter function Advanced Compress Ready
texture cc.Texture2D R&W getTexture, setTexture YES
textureAtlas cc.TextureAtlas R&W None YES
quadsToDraw Number R&W None YES

cc.LayerRGBA

Extend from cc.Layer

Property Type Accessibility Getter/Setter function Advanced Compress Ready
opacityModifyRGB Boolean R&W isOpacityModifyRGB, setOpacityModifyRGB YES
opacity Number R&W getOpacity, setOpacity YES
cascadeOpacity Boolean R&W isCascadeOpacityEnabled, setCascadeOpacityEnabled YES
color cc.Color R&W getColor, setColor YES
cascadeColor Boolean R&W isCascadeColorEnabled, setCascadeColorEnabled YES

cc.LayerGradient

Extend from cc.LayerColor

Property Type Accessibility Getter/Setter function Advanced Compress Ready
startColor cc.Color R&W getStartColor, setStartColor YES
endColor cc.Color R&W getEndColor, setEndColor YES
startOpacity Number R&W getStartOpacity, setStartOpacity YES
endOpacity Number R&W getEndOpacity, setEndOpacity YES
vector Number R&W getVector, setVector YES
compresseInterpolation Number R&W None NO

cc.ClippingNode

Extend from cc.Node

Property Type Accessibility Getter/Setter function Advanced Compress Ready
alphaThreshold Number R&W None NO
inverted Boolean R&W None NO
stencil cc.Node R&W getStencil, setStencil YES

cc.SpriteBatchNode

Extend from cc.Node

Property Type Accessibility Getter/Setter function Advanced Compress Ready
textureAtlas cc.TextureAtlas R&W None NO
descendants Array readonly getDescendants NO

cc.Sprite

Extend from cc.NodeRGBA

Property Type Accessibility Getter/Setter function Advanced Compress Ready
dirty Boolean R&W None YES
flippedX Boolean R&W isFlippedX, setFlippedX YES
flippedY Boolean R&W isFlippedY, setFlippedY YES
offsetX Number readonly _getOffsetX YES
offsetY Number readonly _getOffsetY YES
atlasIndex Number R&W None YES
texture cc.Texture2D R&W getTexture, setTexture YES
textureRectRotated Boolean readonly isTextureRectRotated YES
textureAtlas cc.TextureAtlas R&W None YES
batchNode cc.SpriteBatchNode R&W getBatchNode, setBatchNode YES
quad cc.V3F_C4B_T2F_Quad readonly getQuad YES

cc.LabelTTF

Extend from cc.Sprite

Property Type Accessibility Getter/Setter function Advanced Compress Ready
string String R&W getString, setString YES
textAlign Number R&W getHorizontalAlignment, setHorizontalAlignment YES
verticalAlign Number R&W getVerticalAlignment, setVerticalAlignment YES
fontSize Number R&W getFontSize, setFontSize YES
fontName String R&W getFontName, setFontName YES
font String R&W _getFont, _setFont YES
boundingWidth Number R&W _getBoundingWidth, _setBoundingWidth YES
boundingHeight Number R&W _getBoundingHeight, _setBoundingHeight YES
fillStyle cc.Color R&W _getFillStyle, setFontFillColor YES
strokeStyle cc.Color R&W _getStrokeStyle, _setStrokeStyle YES
lineWidth Number R&W _getLineWidth, _setLineWidth YES
shadowOffsetX Number R&W _getShadowOffsetX, _setShadowOffsetX YES
shadowOffsetY Number R&W _getShadowOffsetY, _setShadowOffsetY YES
shadowOpacity Number R&W _getShadowOpacity, _setShadowOpacity YES
shadowBlur Number R&W _getShadowBlur, _setShadowBlur YES

cc.LabelAtlas

Extend from cc.AtlasNode

Property Type Accessibility Getter/Setter function Advanced Compress Ready
string String R&W getString, setString YES

cc.LabelBMFont

Extend from cc.SpriteBatchNode

Property Type Accessibility Getter/Setter function Advanced Compress Ready
string String R&W getString, _setStringForSetter YES
textAlign enum R&W _getAlignment, setAlignment YES
boundingWidth Number R&W _getBoundingWidth, setBoundingWidth YES
opacityModifyRGB Boolean R&W isOpacityModifyRGB, setOpacityModifyRGB YES
opacity Number R&W getOpacity, setOpacity YES
cascadeOpacity Boolean R&W isCascadeOpacityEnabled, setCascadeOpacityEnabled YES
color cc.Color R&W getColor, setColor YES
cascadeColor Boolean R&W isCascadeColorEnabled, setCascadeColorEnabled YES

cc.Menu

Extend from cc.LayerRGBA

Property Type Accessibility Getter/Setter function Advanced Compress Ready
enabled Boolean R&W None YES

cc.MenuItem

Extend from cc.NodeRGBA

Property Type Accessibility Getter/Setter function Advanced Compress Ready
enabled Boolean R&W isEnabled, setEnabled YES

cc.MenuItemLabel

Extend from cc.MenuItem

Property Type Accessibility Getter/Setter function Advanced Compress Ready
string String R&W getString, setString YES
label cc.Node R&W getLabel, setLabel YES
disabledColor cc.Color R&W getDisabledColor, setDisabledColor YES

cc.MenuItemFont

Extend from cc.MenuItemLabel

Property Type Accessibility Getter/Setter function Advanced Compress Ready
fontSize Number R&W getFontSize, setFontSize YES
fontName String R&W getFontName, setFontName YES

cc.MenuItemSprite

Extend from cc.MenuItem

Property Type Accessibility Getter/Setter function Advanced Compress Ready
normalImage cc.Sprite R&W getNormalImage, setNormalImage YES
selectedImage cc.Sprite R&W getSelectedImage, setSelectedImage YES
disabledImage cc.Sprite R&W getDisabledImage, setDisabledImage YES

cc.NodeGrid

Extend from cc.Node

Property Type Accessibility Getter/Setter function Advanced Compress Ready
grid cc.GridBase R&W None YES
target cc.Node writeonly setTarget YES

cc.ParticleBatchNode

Extend from cc.Node

Property Type Accessibility Getter/Setter function Advanced Compress Ready
textureAtlas cc.TextureAtlas R&W None NO
texture cc.Texture2D R&W getTexture, setTexture YES

cc.ParticleSystem

Extend from cc.Node

Property Type Accessibility Getter/Setter function Advanced Compress Ready
opacityModifyRGB Boolean R&W isOpacityModifyRGB, setOpacityModifyRGB YES
batchNode cc.SpriteBatchNode R&W getBatchNode, setBatchNode YES
active Boolean readonly isActive YES
shapeType Number R&W None NO
atlasIndex Number R&W None NO
particleCount Number R&W None NO
duration Number R&W None NO
sourcePos cc.Point R&W getSourcePosition, setSourcePosition YES
posVar cc.Point R&W getPosVar, setPosVar YES
life Number R&W None NO
lifeVar Number R&W None NO
angle Number R&W None NO
angleVar Number R&W None NO
startSize Number R&W None NO
startSizeVar Number R&W None NO
endSize Number R&W None NO
endSizeVar Number R&W None NO
startSpin Number R&W None NO
startSpinVar Number R&W None NO
endSpin Number R&W None NO
endSpinVar Number R&W None NO
gravity cc.Point R&W getGravity, setGravity YES
speed cc.Point R&W getSpeed, setSpeed YES
speedVar cc.Point R&W getSpeedVar, setSpeedVar YES
tangentialAccel Number R&W None NO
tangentialAccelVar Number R&W None NO
tangentialAccel Number R&W getTangentialAccel, setTangentialAccel YES
tangentialAccelVar Number R&W getTangentialAccelVar, setTangentialAccelVar YES
rotationIsDir Boolean R&W getRotationIsDir, setRotationIsDir YES
startRadius Number R&W getStartRadius, setStartRadius YES
startRadiusVar Number R&W getStartRadiusVar, setStartRadiusVar YES
endRadius Number R&W getEndRadius, setEndRadius YES
endRadiusVar Number R&W getEndRadiusVar, setEndRadiusVar YES
rotatePerS Number R&W getRotatePerSecond, setRotatePerSecond YES
rotatePerSVar Number R&W getRotatePerSecondVar, setRotatePerSecondVar YES
startColor cc.Color R&W getStartColor, setStartColor YES
startColorVar cc.Color R&W getStartColorVar, setStartColorVar YES
endColor cc.Color R&W getEndColor, setEndColor YES
endColorVar cc.Color R&W getEndColorVar, setEndColorVar YES
emissionRate Number R&W None NO
emitterMode Number R&W None NO
positionType Number R&W None NO
totalParticles Number R&W getTotalParticles, setTotalParticles YES
autoRemoveOnFinish Boolean R&W None NO
texture cc.Texture2D R&W getTexture, setTexture YES

cc.ProgressTimer

Extend from cc.NodeRGBA

Property Type Accessibility Getter/Setter function Advanced Compress Ready
midPoint cc.Point R&W getMidpoint, setMidpoint YES
barChangeRate cc.Point R&W getBarChangeRate, setBarChangeRate YES
type enum R&W getType, setType YES
percentage Number R&W getPercentage, setPercentage YES
sprite cc.Sprite R&W getSprite, setSprite YES
reverseDir Boolean R&W isReverseDirection, setReverseDirection YES

cc.RenderTexture

Extend from cc.Node

Property Type Accessibility Getter/Setter function Advanced Compress Ready
sprite cc.Sprite R&W None NO
clearFlags Number R&W None NO
clearDepthVal Number R&W None NO
clearStencilVal Number R&W None NO
clearColorVal cc.Color R&W getClearColor, setClearColor NO
autoDraw Boolean R&W None NO

cc.TMXLayer

Extend from cc.SpriteBatchNode

Property Type Accessibility Getter/Setter function Advanced Compress Ready
tiles Array R&W None NO
tileset cc.TMXTilesetInfo R&W None NO
layerOrientation Number R&W None NO
properties Array R&W None NO
layerName String R&W None NO
layerWidth Number R&W _getLayerWidth, _setLayerWidth NO
layerHeight Number R&W _getLayerHeight, _setLayerHeight NO
tileWidth Number R&W _getTileWidth, _setTileWidth NO
tileHeight Number R&W _getTileHeight, _setTileHeight NO

cc.TMXTiledMap

Extend from cc.NodeRGBA

Property Type Accessibility Getter/Setter function Advanced Compress Ready
properties Array R&W None NO
mapOrientation Number R&W None NO
objectGroups Array R&W None NO
mapWidth Number R&W _getMapWidth, _setMapWidth NO
mapHeight Number R&W _getMapHeight, _setMapHeight NO
tileWidth Number R&W _getTileWidth, _setTileWidth NO
tileHeight Number R&W _getTileHeight, _setTileHeight NO

ccui.Widget

Extend from ccui.Node

Property Type Accessibility Getter/Setter function Advanced Compress Ready
xPercent Number R&W _getXPercent, _setXPercent YES
yPercent Number R&W _getYPercent, _setYPercent YES
widthPercent Number R&W _getWidthPercent, _setWidthPercent YES
heightPercent Number R&W _getHeightPercent, _setHeightPercent YES
widgetParent ccui.Widget readonly getWidgetParent YES
enabled Boolean R&W isEnabled, setEnabled YES
focused Boolean R&W isFocused, setFocused YES
touchEnabled Boolean R&W isTouchEnabled, setTouchEnabled YES
updateEnabled Boolean R&W isUpdateEnabled, setUpdateEnabled YES
bright Boolean R&W isBright, setBright YES
name String R&W getName, setName YES
actionTag Number R&W getActionTag, setActionTag YES

ccui.Layout

Extend from ccui.Widget

Property Type Accessibility Getter/Setter function Advanced Compress Ready
clippingEnabled Boolean R&W isClippingEnabled, setClippingEnabled YES

ccui.Button

Extend from ccui.Widget

Property Type Accessibility Getter/Setter function Advanced Compress Ready
titleText String R&W getTitleText, setTitleText YES
titleFont String R&W _getTitleFont, _setTitleFont YES
titleFontSize Number R&W getTitleFontSize, setTitleFontSize YES
titleFontName String R&W getTitleFontName, setTitleFontName YES
titleFontColor cc.Color R&W None NO
pressedActionEnabled Boolean R&W None NO

ccui.CheckBox

Extend from ccui.Widget

Property Type Accessibility Getter/Setter function Advanced Compress Ready
selected Boolean R&W getSelectedState, setSelectedState YES

ccui.LoadingBar

Extend from ccui.Widget

Property Type Accessibility Getter/Setter function Advanced Compress Ready
percent Number R&W getPercent, setPercent YES

ccui.Slider

Extend from ccui.Widget

Property Type Accessibility Getter/Setter function Advanced Compress Ready
percent Number R&W getPercent, setPercent YES

ccui.Text

Extend from ccui.Widget

Property Type Accessibility Getter/Setter function Advanced Compress Ready
boundingWidth Number R&W _getBoundingWidth, _setBoundingWidth YES
boundingHeight Number R&W _getBoundingHeight, _setBoundingHeight YES
string String R&W getStringValue, setText YES
stringLength Number readonly getStringLength YES
font String R&W _getFont, _setFont YES
fontName String R&W getFontName, setFontName YES
fontSize Number R&W getFontSize, setFontSize YES
textAlign Number R&W getTextHorizontalAlignment, setTextHorizontalAlignment YES
verticalAlign Number R&W getTextVerticalAlignment, setTextVerticalAlignment YES
touchScaleEnabled Boolean R&W None NO

ccui.TextAtlas

Extend from ccui.Widget

Property Type Accessibility Getter/Setter function Advanced Compress Ready
string String R&W getStringValue, setStringValue YES

ccui.TextBMFont

Extend from ccui.Widget

Property Type Accessibility Getter/Setter function Advanced Compress Ready
string String R&W getStringValue, setStringValue YES

ccui.TextField

Extend from ccui.Widget

Property Type Accessibility Getter/Setter function Advanced Compress Ready
maxLengthEnabled Boolean R&W isMaxLengthEnabled, setMaxLengthEnabled YES
maxLength Number R&W getMaxLength, setMaxLength YES
passwordEnabled Boolean R&W isPasswordEnabled, setPasswordEnabled YES
string String R&W getStringValue, setText YES
font String R&W _getFont, _setFont YES
fontSize Number R&W getFontSize, setFontSize YES
fontName String R&W getFontName, setFontName YES

ccui.ScrollView

Extend from ccui.Layout

Property Type Accessibility Getter/Setter function Advanced Compress Ready
innerWidth Number R&W _getInnerWidth, _setInnerWidth YES
innerHeight Number R&W _getInnerHeight, _setInnerHeight YES
bounceEnabled Boolean R&W None NO
inertiaScrollEnabled Boolean R&W None NO

ccs.Armature

Extend from ccs.NodeRGBA

Property Type Accessibility Getter/Setter function Advanced Compress Ready
parentBone ccs.Bone R&W getParentBone, setParentBone YES
animation ccs.ArmatureAnimation R&W None NO
armatureData ccs.ArmatureData R&W None NO
name String R&W None NO
batchNode cc.SpriteBatchNode R&W None NO
version Number R&W None NO
body Object R&W getBody, setBody YES
colliderFilter ccs.ColliderFilter writeonly setColliderFilter YES

ccs.Bone

Extend from ccs.NodeRGBA

Property Type Accessibility Getter/Setter function Advanced Compress Ready
boneData ccs.BoneData R&W getBoneData, setBoneData YES
armature ccs.Armature R&W getArmature, setArmature YES
parentBone ccs.Bone R&W None NO
childArmature ccs.Armature R&W getChildArmature, setChildArmature YES
childrenBone Array readonly getChildrenBone YES
tween ccs.Tween readonly getTween YES
tweenData ccs.FrameData readonly getTweenData YES
transformDirty Boolean R&W None NO
colliderFilter ccs.ColliderFilter R&W getColliderFilter, setColliderFilter YES
displayManager ccs.DisplayManager R&W None NO
ignoreMovementBoneData Boolean R&W None NO
name String R&W None NO
blendDirty Boolean R&W None NO

ccs.Skin

Extend from ccs.Sprite

Property Type Accessibility Getter/Setter function Advanced Compress Ready
skinData Object R&W getSkinData, setSkinData YES
bone ccs.Bone R&W None NO
displayName String readonly getDisplayName YES

cc.EditBox

Extend from cc.ControlButton

Property Type Accessibility Getter/Setter function Advanced Compress Ready
font String R&W _setFont YES
fontName String R&W setFontName YES
fontSize Number R&W setFontSize YES
string String R&W getText, setText YES
maxLength Number R&W getMaxLength, setMaxLength YES

cc.Control

Extend from cc.LayerRGBA

Property Type Accessibility Getter/Setter function Advanced Compress Ready
state Number readonly getState YES
enabled Boolean R&W isEnabled, setEnabled YES
selected Boolean R&W isSelected, setSelected YES
highlighted Boolean R&W isHighlighted, setHighlighted YES

cc.ControlButton

Extend from cc.Control

Property Type Accessibility Getter/Setter function Advanced Compress Ready
adjustBackgroundImage Boolean R&W None NO
zoomOnTouchDown Boolean R&W None NO
preferredSize cc.Size R&W getPreferredSize, setPreferredSize YES
labelAnchor Boolean R&W getLabelAnchorPoint, setLabelAnchorPoint YES

cc.ControlColourPicker

Extend from cc.Control

Property Type Accessibility Getter/Setter function Advanced Compress Ready
background cc.Sprite readonly getBackground YES

cc.ControlHuePicker

Extend from cc.Control

Property Type Accessibility Getter/Setter function Advanced Compress Ready
hue Number R&W getHue, setHue YES
huePercent Number R&W getHuePercentage, setHuePercentage YES
background cc.Sprite readonly getBackground YES
slider cc.Sprite readonly getSlider YES
startPos cc.Point readonly getStartPos YES

cc.ControlPotentiometer

Extend from cc.Control

Property Type Accessibility Getter/Setter function Advanced Compress Ready
value Number R&W getValue, setValue YES
minValue Number R&W getMinimumValue, setMinimumValue YES
maxValue Number R&W getMaximumValue, setMaximumValue YES
progressTimer cc.ProgressTimer R&W getProgressTimer, setProgressTimer YES
thumbSprite cc.Sprite R&W getThumbSprite, setThumbSprite YES
prevLocation cc.Point R&W getPreviousLocation, setPreviousLocation YES

cc.ControlSaturationBrightnessPicker

Extend from cc.Control

Property Type Accessibility Getter/Setter function Advanced Compress Ready
saturation Number readonly getSaturation YES
brightness Number readonly getBrightness YES
background cc.Sprite readonly getBackground YES
overlay cc.Sprite readonly getOverlay YES
shadow cc.Sprite readonly getShadow YES
slider cc.Sprite readonly getSlider YES
startPos cc.Point readonly getStartPos YES

cc.ControlSlider

Extend from cc.Control

Property Type Accessibility Getter/Setter function Advanced Compress Ready
value Number R&W getValue, setValue YES
minValue Number R&W getMinimumValue, setMinimumValue YES
maxValue Number R&W getMaximumValue, setMaximumValue YES
minAllowedValue Number R&W getMinimumAllowedValue, setMinimumAllowedValue YES
maxAllowedValue Number R&W getMaximumAllowedValue, setMaximumAllowedValue YES
thumbSprite Number readonly getThumbSprite YES
progressSprite cc.Sprite readonly getProgressSprite YES
backgroundSprite cc.Sprite readonly getBackgroundSprite YES

cc.ControlStepper

Extend from cc.Control

Property Type Accessibility Getter/Setter function Advanced Compress Ready
wraps Boolean R&W getWraps, setWraps YES
value Number R&W getValue, setValue YES
minValue Number R&W getMinimumValue, setMinimumValue YES
maxValue Number R&W getMaximumValue, setMaximumValue YES
stepValue Number R&W getStepValue, setStepValue YES
continuous Boolean readonly isContinuous YES
minusSprite cc.Sprite R&W getMinusSprite, setMinusSprite YES
plusSprite cc.Sprite R&W getPlusSprite, setPlusSprite YES
minusLabel cc.LabelTTF R&W getMinusLabel, setMinusLabel YES
plusSLabel cc.LabelTTF R&W None NO

cc.Scale9Sprite

Extend from cc.NodeRGBA

Property Type Accessibility Getter/Setter function Advanced Compress Ready
preferredSize cc.Size R&W getPreferredSize, setPreferredSize YES
capInsets cc.Rect R&W getCapInsets, setCapInsets YES
insetLeft Number R&W getInsetLeft, setInsetLeft YES
insetTop Number R&W getInsetTop, setInsetTop YES
insetRight Number R&W getInsetRight, setInsetRight YES
insetBottom Number R&W getInsetBottom, setInsetBottom YES

cc.TableViewCell

Extend from cc.Node

Property Type Accessibility Getter/Setter function Advanced Compress Ready
objectId Number R&W getObjectID, setObjectID YES

转载请注明:http://www.cocos2dx.net/post/235

分类: cocos2d, cocos2d-js 标签:

【cocos2d-js官方文档】十七、事件分发机制

2014年12月15日 没有评论

简介

游戏开发中一个很重要的功能就是交互,如果没有与用户的交互,那么游戏将变成动画,而处理用户交互就需要使用事件监听器了。

总概:

  • 事件监听器(cc.EventListener) 封装用户的事件处理逻辑
  • 事件管理器(cc.eventManager) 管理用户注册的事件监听器,根据触发的事件类型分发给相应的事件监听器
  • 事件对象(cc.Event) 包含事件相关信息的对象

如何使用呢? 首先需要创建一个事件监听器,事件监听器包含以下几种类型:

  • 触摸事件监听器 (cc.EventListenerTouch)
  • 键盘事件监听器 (cc.EventListenerKeyboard)
  • 加速计事件监听器 (cc.EventListenerAcceleration)
  • 鼠标事件监听器 (cc.EventListenerMouse)
  • 自定义事件监听器 (cc.EventListenerCustom)

在监听器中实现各种事件的处理逻辑,然后将监听器加入到事件管理器中, 当事件触发时,事件管理器会根据事件类型分发给相应的事件监听器。下面以一个简单的示例来演示使用的方法。

使用方法

现在会在一个场景中添加三个按钮(cc.Sprite),三个按钮将会互相遮挡,并且都需要能够监听和处理触摸事件,以下是具体实现

首先创建三个精灵,作为三个按钮的显示图片

    var sprite1 = new cc.Sprite("Images/CyanSquare.png");
    sprite1.x = size.width/2 - 80;
    sprite1.y = size.height/2 + 80;
    this.addChild(sprite1, 10);

    var sprite2 = new cc.Sprite("Images/MagentaSquare.png");
    sprite2.x = size.width/2;
    sprite2.y = size.height/2;
    this.addChild(sprite2, 20);

    var sprite3 = new cc.Sprite("Images/YellowSquare.png");
    sprite3.x = 0;
    sprite3.y = 0;
    sprite2.addChild(sprite3, 1);

【cocos2d-js官方文档】十七、事件分发机制

创建一个单点触摸事件监听器(事件类型:TOUCH_ONE_BY_ONE),并完成逻辑处理内容

    // 创建一个事件监听器 OneByOne 为单点触摸
    var listener1 = cc.EventListener.create({
        event: cc.EventListener.TOUCH_ONE_BY_ONE,
        swallowTouches: true,                       // 设置是否吞没事件,在 onTouchBegan 方法返回 true 时吞掉事件,不再向下传递。
        onTouchBegan: function (touch, event) {     //实现 onTouchBegan 事件处理回调函数
            var target = event.getCurrentTarget();  // 获取事件所绑定的 target, 通常是cc.Node及其子类 

            // 获取当前触摸点相对于按钮所在的坐标
            var locationInNode = target.convertToNodeSpace(touch.getLocation());    
            var s = target.getContentSize();
            var rect = cc.rect(0, 0, s.width, s.height);

            if (cc.rectContainsPoint(rect, locationInNode)) {       // 判断触摸点是否在按钮范围内
                cc.log("sprite began... x = " + locationInNode.x + ", y = " + locationInNode.y);
                target.opacity = 180;
                return true;
            }
            return false;
        },
        onTouchMoved: function (touch, event) {         //实现onTouchMoved事件处理回调函数, 触摸移动时触发
            // 移动当前按钮精灵的坐标位置
            var target = event.getCurrentTarget();
            var delta = touch.getDelta();              //获取事件数据: delta
            target.x += delta.x;
            target.y += delta.y;
        },
        onTouchEnded: function (touch, event) {         // 实现onTouchEnded事件处理回调函数
            var target = event.getCurrentTarget();
            cc.log("sprite onTouchesEnded.. ");
            target.setOpacity(255);
            if (target == sprite2) {                    
                sprite1.setLocalZOrder(100);            // 重新设置 ZOrder,显示的前后顺序将会改变
            } else if (target == sprite1) {
                sprite1.setLocalZOrder(0);
            }
        }
    });

引擎提供了cc.EventListener.create统一来创建各类型的事件监听器,可以通过指定不同的 event 来设置想要创建的监听器类型,如上例中的cc.EventListener.TOUCH_ONE_BY_ONE
为单点触摸事件监听器。

可选event类型列表:

  1. cc.EventListener.TOUCH_ONE_BY_ONE (单点触摸)
  2. cc.EventListener.TOUCH_ALL_AT_ONCE (多点触摸)
  3. cc.EventListener.KEYBOARD (键盘)
  4. cc.EventListener.MOUSE (鼠标)
  5. cc.EventListener.ACCELERATION (加速计)
  6. cc.EventListener.CUSTOM (自定义)

将事件监听器添加到事件管理器中

    // 添加监听器到管理器
    cc.eventManager.addListener(listener1, sprite1);
    cc.eventManager.addListener(listener1.clone(), sprite2);
    cc.eventManager.addListener(listener1.clone(), sprite3);

这里的cc.eventManager 是一个单例对象,可直接拿来使用。通过调用 addListener 函数可以将listener加入到管理器中,需要注意的是第二个参数,如果传入的是一个Node对象,则加入的是SceneGraphPriority(精灵以显示优先级)
类型的listener,如果是一个数值类型的参数,则加入到的是FixedPriority 类型的listener。

注意: 这里当我们想给不同的节点使用相同的事件监听器时,需要使用 clone() 函数克隆出一个新的监听器,因为在使用 addListener 方法时,会对当前使用的事件监听器添加一个已注册的标记,这使得它不能够被添加多次。另外,有一点非常重要,FixedPriority
类型的 listener添加完之后需要手动删除,而SceneGraphPriority 类型的 listener是跟node绑定的,在node调用cleanup时会被移除。具体的示例用法可以参考引擎自带的tests。

更快速的添加事件监听器到管理器的方式

下面提交一种更快捷绑定事件到节点的方式, 不过这样做就不会得到监听器的引用,无法再对监听器进行其他操作,适用于一些简单的事件操作, 代码如下:

    cc.eventManager.addListener({
        event: cc.EventListener.TOUCH_ALL_AT_ONCE,
        onTouchesMoved: function (touches, event) {
            var touch = touches[0];
            var delta = touch.getDelta();

            var node = event.getCurrentTarget().getChildByTag(TAG_TILE_MAP);
            var diff = cc.pAdd(delta, node.getPosition());
            node.setPosition(diff);
        }
    }, this);

cc.eventManager的 addListener 的第一个参数也支持两种类型的参数: cc.EventListener 类型对象和json格式的对象,如果是json格式对象,方法会根据传入的event属性来创建对应的监听器。

新的触摸机制

以上的步骤相对于 2.x 版本触摸机制实现,稍显复杂了点。在老的版本中只需在节点中重载onTouchBegan/onTouchesBegan 等方法,
处理对应的触摸事件逻辑,然后调用cc.registerTargetedDelegatecc.registerStandardDelegate 将节点加入到触摸事件分发器中就可以了,甚至有些已封装的类只需要调用setTouchEnabled,
就可以开启触摸事件,比如:cc.Layer

而新机制将事件处理逻辑独立出来,封装到一个 监听器(listner) 中,使得不同对象可以使用同一份监听器代码(使用clone()来达到目的)。另外,cc.eventManager加入了精灵以显示优先级
(SceneGraphPriority)排序的功能,以这种类型注册的监听器,事件管理器会根据屏幕显示的情况来决定事件会优化分发给哪个事件监听器。 而2.x要实现这样的功能却非常的麻烦,需要用户自己通过调用setPriority来管理节点的事件响应优先级。

注意:与 SceneGraphPriority 所不同的是 FixedPriority 将会依据手动设定的 Priority 值来决定事件相应的优先级,值越小优先级越高,
后面章节中会作更具体的讲解。

其它事件派发处理模块

除了触摸事件响应之外,还可以使用相同的事件处理方式来处理其他事件。

键盘响应事件

除了可以监听键盘按键,还可以是终端设备的各个菜单键,都能使用同一个监听器来进行处理。

    //给statusLabel绑定键盘事件
    cc.eventManager.addListener({
        event: cc.EventListener.KEYBOARD,
        onKeyPressed:  function(keyCode, event){
            var label = event.getCurrentTarget();
            //通过判断keyCode来确定用户按下了哪个键
            label.setString("Key " + keyCode.toString() + " was pressed!");
        },
        onKeyReleased: function(keyCode, event){
            var label = event.getCurrentTarget();
            label.setString("Key " + keyCode.toString() + " was released!");
        }
    }, statusLabel);    

加速计事件

在使用加速计事件监听器之前,需要先启用此硬件设备, 代码如下:

cc.inputManager.setAccelerometerEnabled(true);

然后将相应的事件处理监听器与sprite进行绑定就可以了,如下:

        cc.eventManager.addListener({
            event: cc.EventListener.ACCELERATION,
            callback: function(acc, event){
                //这里处理逻辑
            }
        }, sprite); 

鼠标响应事件

对于PC和超级本,添加鼠标事件的的处理,可以加强用户的体验,其处理逻辑与触摸事件基本一样,多了一些鼠标特有的事件响应,如滚轮事件(onMouseScroll).

    cc.eventManager.addListener({
        event: cc.EventListener.MOUSE,
        onMouseMove: function(event){
            var str = "MousePosition X: " + event.getLocationX() + "  Y:" + event.getLocationY();
            // do something...
        },
        onMouseUp: function(event){
            var str = "Mouse Up detected, Key: " + event.getButton();
            // do something...
        },
        onMouseDown: function(event){
            var str = "Mouse Down detected, Key: " + event.getButton();
            // do something...
        },
        onMouseScroll: function(event){
            var str = "Mouse Scroll detected, X: " + event.getLocationX() + "  Y:" + event.getLocationY();
            // do something...
        }
    },this);

注意: 由于在PC浏览器中,没有触摸事件,而此时强制要求用户写鼠标事件的响应代码,必然会让开发者多写很多代码,事实上触摸响应的逻辑与鼠标相差不大,所以引擎在检测到不支持触摸事件时,会让鼠标事件模拟成触摸事件进行分发,开发者只需编写触摸事件监听器就能完成大部分工作,而对于针对鼠标操作而设计的游戏,需要判断用户按下什么键,响应滚轮等,这就需要开发者编写鼠标事件监听器了。

(开发者反馈,鼠标事件监听器也需要有swallowTouches这个选项,我们将会有v3.1版本中加入这个项.)

自定义事件

以上是系统自带的事件类型,这些事件由系统内部自动触发,如 触摸屏幕,键盘响应等,除此之外,还提供了一种 自定义事件,简而言之,它不是由系统自动触发,而是人为的干涉,如下:

    var _listener1 = cc.EventListener.create({
        event: cc.EventListener.CUSTOM,
        eventName: "game_custom_event1",
        callback: function(event){
            // 可以通过getUserData来设置需要传输的用户自定义数据
            statusLabel.setString("Custom event 1 received, " + event.getUserData() + " times");
        }
    });    
    cc.eventManager.addListener(this._listener1, 1);

以上定义了一个 “自定义事件监听器”,实现了一些逻辑, 并且添加到事件分发器。那么以上逻辑是在什么情况下响应呢?请看如下:

    ++this._item1Count;
    var event = new cc.EventCustom("game_custom_event1");
    event.setUserData(this._item1Count.toString());
    cc.eventManager.dispatchEvent(event);       

创建了一个自定义事件(EventCustom)对象 ,并且设置了其用户自定义(UserData)数据,手动调用cc.eventManager.dispatchEvent(event); 将此事件分发出去,从而触发之前监听器中所实现的逻辑。

cc.eventManager加入自定义事件的处理,开发者就可以很方便的使用该功能来实现观察者模式。

移除事件监听器

我们可以通过以下方法移除一个已经被添加了的监听器。

    cc.eventManager.removeListener(listener);           //移除一个已添加的监听器

也可以使用removeListeners,移除注册到cc.eventManager中指定类型的所有监听器,当然使用该函数时,传入的参数如果是一个节点(cc.Node及其子类)对象,
事件管理器将移除与该对象相关的所有事件监听器, 代码如下:

    cc.eventManager.removeListeners(cc.EventListener.TOUCH_ONE_BY_ONE);         //移除所有单点触摸事件监听器
    cc.eventManager.removeListeners(aSprite);                                   //移除所有与aSprite相关的监听器

事件管理器还提供了函数用来移除已注册的所有监听器。

    cc.eventManager.removeAllListeners();

当使用 removeAllListeners 的时候,此节点的所有的监听将被移除,推荐使用 指定删除的方式。

_注意:调用removeAllListeners 之后 菜单(cc.Menu)
也不能响应。因为它内部有一个触摸事件监听器,也会从事件管理器中删除。

暂停/恢复
与场景相关(SceneGraph类型)的监听器

开发过程中,我们经常会遇到这样的情况:想要让一个Layer中所有的Node对象的事件都停止响应。 在响应用户事件后,又要恢复该Layer的所有事件响应。如: 用户想要显示一个模式对话框,显示对话框后,禁止对话框后所有对象的事件响应。 在用户关闭对话框后,又恢复这些对象的事件响应。

我们只需要暂停根node的事件,就可以让根节点以及其子节点暂停事件响应。 代码如下:

    cc.eventManager.pauseTarget(aLayer, true);                      //让aLayer对象暂停响应事件

而恢复对象的事件响应也非常简单:

    cc.eventManager.resumeTarget(aLayer, true);                     //让aLayer对象恢复响应事件

注意: 第二个参数为可选参数,默认值为false, 表示是否递归调用子节点的暂停/恢复操作.

进阶话题

SceneGraphPriority类型与FixedPriority类型详解

事件管理器将监听器类型分为两大类:SceneGraphPriority和FixedPriority, 下面将会详细说明它们之间的区别, 并介绍FixedPriority的使用场景与使用方法。

SceneGraphPriority事件类型是指事件的响应优先级与监听器关联对象在场景中显示顺序(zOrder)相关, 比如一个精灵对象在场景的显示在最上层时,它对事件的响应优先级最高。 这样开发者就不需要再像v2.x中那样在场景对象的zOrder变化后,手动再调用setPriority来改变相应的优先级了,这些事将交由管理器来处理。

而 FixedPriority 事件类型则是相对于 SceneGraphPriority 来定义的,不需要与场景显示顺序相关的事件监听器 也就是优化级固定的(fixed),就可以注册成FixedPriority类型事件。 我们的SceneGraphPriority定义的系统优先级是0, 在添加监听器(addListener)时,
如果第二个参数设置为负数时,该监听器就会拥有比所有场景相关监听器都高的优先级, 而如果是正数,则反之。

那么什么情况下使用FixedPriority类型的监听器呢? 比如,一个冒险类的游戏中,游戏主角应该要最先响应触摸事件,而UI界面的按钮往往会安排在界面的最上层。但是,如果主角移动到了按钮的后面,这时点击游戏主角,如果游戏主角注册的是SceneGraphPriority类型监听器,响应的将会是按钮事件。而如果注册成FixedPriority类型,并把它的优先级设置为负数,将会响应游戏主角的事件。

有开发者反馈想保持他们在v2.x的响应优先级管理机制,因为他们有特殊的需求,那么这部分开发者也可以使用FixedPriority来管理,cc.eventManager 也提供了一个setPriority函数来管理优先级。

UI控件的事件处理详解

Cocos提供一套UI控件,许多开发者对于控件的事件响应,特别是对于容器类控件(如:ccui.PageView, ccui.ScrollView)的事件响应有些疑惑。这里将详细说明控件的事件处理流程。

首先来看一下ccui.Widget的事件实现, 所有的控件的事件监听器都是单点触摸事件,并且会吞食事件,注册代码如下:

    this._touchListener = cc.EventListener.create({
        event: cc.EventListener.TOUCH_ONE_BY_ONE,
        swallowTouches: true,
        onTouchBegan: this.onTouchBegan.bind(this),
        onTouchMoved: this.onTouchMoved.bind(this),
        onTouchEnded: this.onTouchEnded.bind(this)
     });
     cc.eventManager.addListener(this._touchListener, this);

然后看一下它的各事件响应函数,会发现每个函数都会有类似这样的语句: if (widgetParent) widgetParent.interceptTouchEvent(ccui.Widget.TOUCH_XXXXX, this,
touch);

这句的意思是,在控件处理完自己的触摸事件之后,都会向父节点(widgetParent)发送事件响应通知。那么,interceptTouchEvent的实现是什么呢? 代码如下:

    interceptTouchEvent: function(eventType, sender, touch){
        var widgetParent = this.getWidgetParent();
        if (widgetParent)
            widgetParent.interceptTouchEvent(eventType,sender,touch);
    }

对于像ccui.Button, ccui.ImageView这样的控件,它只是简单的向父类发送事件通知就行了,而对于像ccui.PageView这样的容器类控件,会对这些通知做出响应,代码如下:

    interceptTouchEvent: function (eventType, sender, touch) {
        var touchPoint = touch.getLocation();
        switch (eventType) {
            case ccui.Widget.TOUCH_BEGAN:
                this._touchBeganPosition.x = touchPoint.x;
                this._touchBeganPosition.y = touchPoint.y;
                break;
            case ccui.Widget.TOUCH_MOVED:
                this._touchMovePosition.x = touchPoint.x;
                this._touchMovePosition.y = touchPoint.y;
                var offset = 0;
                offset = Math.abs(sender.getTouchBeganPosition().x - touchPoint.x);
                if (offset > this._childFocusCancelOffset) {
                    sender.setFocused(false);
                    this._handleMoveLogic(touch);  
                }
                break;
            case ccui.Widget.TOUCH_ENDED:
            case ccui.Widget.TOUCH_CANCELED:
                this._touchEndPosition.x = touchPoint.x;
                this._touchEndPosition.y = touchPoint.y;
                this._handleReleaseLogic(touch);
                break;
        }
    }

这样的处理,就能实现在按钮上滑动时,也能让其父节点的PageView触摸事件。不然,如果不采用这种机制,当一个PageView中填满了子控件时,PageView将无法响应触摸事件。

属性与方法列表

cc.Event
(事件类)

属性/方法 类型 参数说明 用法说明
getType Number no 返回事件类型,包含:TOUCH, KEYBOARD, ACCELERATION, MOUSE, CUSTOM
stopPropagation void no 停止当前事件的冒泡
isStopped Boolean no 事件是否已停止
getCurrentTarget cc.Node no 返回事件相关的Node对象, 如果事件未与cc.Node对象关联,则返回null

cc.EventCustom
(自定义事件)

cc.EventCustom 继承自 cc.Event

属性/方法 类型 参数说明 用法说明
setUserData void data: 要设置的自定义数据 设置用户自定义数据
getUserData * no 返回用户设置的自定义数据
getEventName String no 返回自定义事件名称

cc.EventMouse
(鼠标事件)

cc.EventMouse 继承自 cc.Event

属性/方法 类型 参数说明 用法说明
setScrollData void scrollX, scrollY 设置滚轮数据
getScrollX Number no 返回x轴滚轮数据
getScrollY Number no 返回y轴滚轮数据
setLocation void x, y 设置鼠标光标位置
getLocation cc.Point no 获取鼠标光标位置
getLocationInView cc.Point no 返回鼠标光标在屏幕上的位置
getDelta cc.Point no 获取当前光标与上一光标的偏移量
setButton void button 设置鼠标按键
getButton Number no 获取鼠标按键

cc.EventTouch
()

cc.EventTouch 继承自 cc.Event

属性/方法 类型 参数说明 用法说明
getEventCode Number no 获取触摸事件类型代码: BEGAN, MOVED, ENDED, CANCELLED
getTouches Array no 获取触摸事件中所有点信息

cc.EventListener
(事件监听器)

属性/方法 类型 参数说明 用法说明
checkAvailable boolean no 检测监听器是否有效
clone cc.EventListener no 克隆一个监听器,其子类会重写本函数
create cc.EventListener json object 通过json对象创建事件监听器

cc.EventListener.create 函数参数列表:

创建EventListenerTouchOneByOne对象:

event: cc.EventListener.TOUCH_ONE_BY_ONE

可选参数:

  1. swallowTouches, boolean, 是否吞下该touch点
  2. onTouchBegan, function, TouchBegan 事件回调
  3. onTouchMoved, function, TouchMoved 事件回调
  4. onTouchEnded, function, TouchEnded 事件回调
  5. onTouchCancelled, function, TouchCancelled 事件回调

创建EventListenerTouchAllAtOnce对象:

event: cc.EventListener.TOUCH_ALL_AT_ONCE

可选参数:

  1. onTouchesBegan, function, TouchesBegan 事件回调
  2. onTouchesMoved, function, TouchesMoved 事件回调
  3. onTouchesEnded, function, TouchesEnded 事件回调
  4. onTouchesCancelled, function, TouchesCancelled 事件回调

创建EventListenerKeyboard对象:

event: cc.EventListener.KEYBOARD

可选参数:

  1. onKeyPressed, function, KeyPressed (键按下) 事件回调
  2. onKeyReleased, function, keyRelease (键放开) 事件回调

创建EventListenerMouse对象:

event: cc.EventListener.MOUSE

可选参数:

  1. onMouseDown, function, MouseDown 事件回调
  2. onMouseUp, function, MouseUp 事件回调
  3. onMouseMove, function, MouseMove 事件回调
  4. onMouseScroll, function, MouseScroll 事件回调

创建EventListenerAcceleration对象:

event: cc.EventListener.ACCELERATION

可选参数:

  1. callback, function, Acclerometer 事件回调

创建EventListenerCustom对象:

event: cc.EventListener.CUSTOM

可选参数:

  1. callback, function, 自定义事件回调

cc.eventManager

属性/方法 类型 参数说明 用法说明
pauseTarget void node, recursive(是否递归调用子类) 暂停传入的node相关的所有监听器的事件响应
resumeTarget void node, recursive 恢复传入的node相关的所有监听器的事件响应
addListener void json对象或cc.EventListener, node对象或优化值 向事件管理器添加一个监听器
addCustomListener void eventName, callback 向事件管理器添加一个自定义事件监听器
removeListener void listener 移除一个事件监听器
removeListeners void listenerType cc.Node, recursive
removeCustomListeners void customEventName 移除同一事件名的自定义事件监听器
removeAllListeners void no 移除所有事件监听器
setPriority void listener, fixedPriority 设置FixedPriority类型监听器的优先集
setEnabled void enabled 是否允许分发事件
isEnabled boolean no 检测事件管理器是否分发事件
dispatchEvent void event 分发事件
dispatchCustomEvent void eventName, optionalUserData 分发自定义事件

转载请注明: http://www.cocos2dx.net/post/232

分类: cocos2d, cocos2d-js 标签: