badman250

quick-cocos2d-x API函数汇总

quick-cocos2d-x API函数汇总

1. init

在quick\framework\init.lua文件中。

quick framework 初始化，载入 quickframework 预定义的常量、模块。

1.1 常量

在初始化框架之前，可以定义以下常量：

· DEBUG: 设置框架的调试输出级别

·         DEBUG = 0           -- 不输出任何调试信息（默认值）

·         DEBUG = 1           -- 输出基本的调试信息

·         DEBUG = 2           -- 输出详细的调试信息

· DEBUG_FPS: 设置是否在画面中显示渲染帧率等信息

·         DEBUG_FPS = false   -- 不显示（默认值）

·         DEBUG_FPS = true    -- 显示

· DEBUG_MEM: 设置是否输出内存占用信息

·         DEBUG_MEM = false   -- 不输出（默认值）

·         DEBUG_MEM = true    -- 每 10 秒输出一次

· LOAD_DEPRECATED_API: 是否载入过时的 API 定义，默认为 false

· DISABLE_DEPRECATED_WARNING: 使用过时的 API 时是否显示警告信息，默认为 true

· USE_DEPRECATED_EVENT_ARGUMENTS:是否使用过时的 Node 事件参数格式，默认为 false

1.2 自动载入的模块

框架初始化时，会自动载入以下基本模块：

· debug: 调试接口

· functions: 提供一组常用的函数，以及对 Lua 标准库的扩展

· cocos2dx: 对 cocos2d-x C++ 接口的封装和扩展

· device: 针对设备接口的扩展

· transition: 与动作相关的接口

· display: 创建场景、图像、动画的接口

· filter: 具备过滤器渲染的 Sprite 接口

· audio: 音乐和音效的接口

· network: 网络相关的接口

· crypto: 加密相关的接口

· json: JSON 的编码和解码接口

· luaj: 提供从 Lua 调用 Java 方法的接口（仅限 Android 平台）

· luaoc: 提供从 Lua 调用 Objective-C 方法的接口（仅限 iOS 平台）

· cc: quick 框架扩展的基础类和组件

quick\framework\platform\mac.lua文件

quick\framework\cc\mac.lua文件

2. debug

quick\framework\debug.lua文件

提供调试接口

Functions

DEPRECATED(newfunction, oldname, newname)

定义一个作废的接口

PRINT_DEPRECATED(msg)

显示作废信息

printLog(tag, fmt, ...)

打印调试信息

printError(fmt, ...)

输出 tag 为 ERR 的调试信息

printInfo(fmt, ...)

输出 tag 为 INFO 的调试信息

dump(value, desciption, nesting)

输出值的内容

Functions

DEPRECATED()

DEPRECATED(newfunction, oldname, newname)

定义一个作废的接口

PRINT_DEPRECATED()

PRINT_DEPRECATED(msg)

显示作废信息

printLog()

printLog(tag, fmt, ...)

打印调试信息

用法示例

printLog("WARN", "Network connection lost at %d", os.time())

Parameters

· string tag 调试信息的 tag

· string fmt 调试信息格式

· [mixed ...] 更多参数

printError()

printError(fmt, ...)

输出 tag 为 ERR 的调试信息

Parameters

· string fmt 调试信息格式

· [mixed ...] 更多参数

printInfo()

printInfo(fmt, ...)

输出 tag 为 INFO 的调试信息

Parameters

· string fmt 调试信息格式

· [mixed ...] 更多参数

dump()

dump(value, desciption, nesting)

输出值的内容

用法示例

local t = {comp = "chukong", engine = "quick"}

dump(t)

Parameters

· mixed value 要输出的值

· [string desciption] 输出内容前的文字描述

@parma [integer nesting] 输出时的嵌套层级，默认为 3

3. functions

quick\framework\ functions.lua文件

提供一组常用函数，以及对 Lua 标准库的扩展

Functions

printf(fmt, ...)

输出格式化字符串

checknumber(value, base)

检查并尝试转换为数值，如果无法转换则返回 0

checkint(value)

检查并尝试转换为整数，如果无法转换则返回 0

checkbool(value)

检查并尝试转换为布尔值，除了 nil 和 false，其他任何值都会返回 true

checktable(value)

检查值是否是一个表格，如果不是则返回一个空表格

isset(hashtable, key)

如果表格中指定 key 的值为 nil，或者输入值不是表格，返回 false，否则返回 true

clone(object)

深度克隆一个值

class(classname, super)

创建一个类

iskindof(obj, classname)

如果对象是指定类或其子类的实例，返回 true，否则返回 false

import(moduleName, currentModuleName)

载入一个模块

handler(obj, method)

将 Lua 对象及其方法包装为一个匿名函数

math.newrandomseed()

根据系统时间初始化随机数种子，让后续的 math.random() 返回更随机的值

math.round(value)

对数值进行四舍五入，如果不是数值则返回 0

math.angle2radian(angle)

角度转弧度

math.radian2angle(radian)

弧度转角度

io.exists(path)

检查指定的文件或目录是否存在，如果存在返回 true，否则返回 false

io.readfile(path)

读取文件内容，返回包含文件内容的字符串，如果失败返回 nil

io.writefile(path, content, mode)

以字符串内容写入文件，成功返回 true，失败返回 false

io.pathinfo(path)

拆分一个路径字符串，返回组成路径的各个部分

io.filesize(path)

返回指定文件的大小，如果失败返回 false

table.nums(t)

计算表格包含的字段数量

table.keys(hashtable)

返回指定表格中的所有键

table.values(hashtable)

返回指定表格中的所有值

table.merge(dest, src)

将来源表格中所有键及其值复制到目标表格对象中，如果存在同名键，则覆盖其值

table.insertto(dest, src, begin)

在目标表格的指定位置插入来源表格，如果没有指定位置则连接两个表格

table.indexof(array, value, begin)

从表格中查找指定值，返回其索引，如果没找到返回 false

table.keyof(hashtable, value)

从表格中查找指定值，返回其 key，如果没找到返回 nil

table.removebyvalue(array, value, removeall)

从表格中删除指定值，返回删除的值的个数

table.map(t, fn)

对表格中每一个值执行一次指定的函数，并用函数返回值更新表格内容

table.walk(t, fn)

对表格中每一个值执行一次指定的函数，但不改变表格内容

table.filter(t, fn)

对表格中每一个值执行一次指定的函数，如果该函数返回 false，则对应的值会从表格中删除

table.unique(t)

遍历表格，确保其中的值唯一

string.htmlspecialchars(input)

将特殊字符转为 HTML 转义符

string.restorehtmlspecialchars(input)

将 HTML 转义符还原为特殊字符，功能与 string.htmlspecialchars() 正好相反

string.nl2br(input)

将字符串中的 \n 换行符转换为 HTML 标记

string.text2html(input)

将字符串中的特殊字符和 \n 换行符转换为 HTML 转移符和标记

string.split(input, delimiter)

用指定字符或字符串分割输入字符串，返回包含分割结果的数组

string.ltrim(input)

去除输入字符串头部的空白字符，返回结果

string.rtrim(input)

去除输入字符串尾部的空白字符，返回结果

string.trim(input)

去掉字符串首尾的空白字符，返回结果

string.ucfirst(input)

将字符串的第一个字符转为大写，返回结果

string.urlencode(input)

将字符串转换为符合 URL 传递要求的格式，并返回转换结果

string.urldecode(input)

将 URL 中的特殊字符还原，并返回结果

string.utf8len(input)

计算 UTF8 字符串的长度，每一个中文算一个字符

string.formatnumberthousands(num)

将数值格式化为包含千分位分隔符的字符串

Functions

printf()

printf(fmt, ...)

输出格式化字符串

printf("The value = %d", 100)

Parameters

· string fmt 输出格式

· [mixed ...] 更多参数

checknumber()

checknumber(value, base)

检查并尝试转换为数值，如果无法转换则返回 0

Parameters

· mixed value 要检查的值

· [integer base] 进制，默认为十进制

Returns

· number

checkint()

checkint(value)

检查并尝试转换为整数，如果无法转换则返回 0

Parameters

· mixed value 要检查的值

Returns

· integer

checkbool()

checkbool(value)

检查并尝试转换为布尔值，除了 nil 和 false，其他任何值都会返回 true

Parameters

· mixed value 要检查的值

Returns

· boolean

checktable()

checktable(value)

检查值是否是一个表格，如果不是则返回一个空表格

Parameters

· mixed value 要检查的值

Returns

· table

isset()

isset(hashtable, key)

如果表格中指定 key 的值为 nil，或者输入值不是表格，返回 false，否则返回 true

Parameters

· table hashtable 要检查的表格

· mixed key 要检查的键名

Returns

· boolean

clone()

clone(object)

深度克隆一个值

-- 下面的代码，t2 是 t1 的引用，修改 t2 的属性时，t1 的内容也会发生变化

local t1 = {a = 1, b = 2}

local t2 = t1

t2.b = 3    -- t1 = {a = 1, b = 3} <-- t1.b 发生变化

-- clone() 返回 t1 的副本，修改 t2 不会影响 t1

local t1 = {a = 1, b = 2}

local t2 = clone(t1)

t2.b = 3    -- t1 = {a = 1, b = 2} <-- t1.b 不受影响

Parameters

· mixed object 要克隆的值

Returns

· mixed

class()

class(classname, super)

创建一个类

-- 定义名为 Shape 的基础类

local Shape = class("Shape")

-- ctor() 是类的构造函数，在调用 Shape.new() 创建 Shape 对象实例时会自动执行

function Shape:ctor(shapeName)

    self.shapeName = shapeName

    printf("Shape:ctor(%s)", self.shapeName)

end

-- 为 Shape 定义个名为 draw() 的方法

function Shape:draw()

    printf("draw %s", self.shapeName)

end

--

-- Circle 是 Shape 的继承类

local Circle = class("Circle", Shape)

function Circle:ctor()

    -- 如果继承类覆盖了 ctor() 构造函数，那么必须手动调用父类构造函数

    -- 类名.super 可以访问指定类的父类

    Circle.super.ctor(self, "circle")

    self.radius = 100

end

function Circle:setRadius(radius)

    self.radius = radius

end

-- 覆盖父类的同名方法

function Circle:draw()

    printf("draw %s, raidus = %0.2f", self.shapeName, self.raidus)

end

--

local Rectangle = class("Rectangle", Shape)

function Rectangle:ctor()

    Rectangle.super.ctor(self, "rectangle")

end

--

local circle = Circle.new()             -- 输出: Shape:ctor(circle)

circle:setRaidus(200)

circle:draw()                           -- 输出: draw circle, radius = 200.00

local rectangle = Rectangle.new()       -- 输出: Shape:ctor(rectangle)

rectangle:draw()                        -- 输出: draw rectangle

高级用法

class() 除了定义纯 Lua 类之外，还可以从 C++ 对象继承类。

比如需要创建一个工具栏，并在添加按钮时自动排列已有的按钮，那么我们可以使用如下的代码：

-- 从 cc.Node 对象派生 Toolbar 类，该类具有 cc.Node 的所有属性和行为

local Toolbar = class("Toolbar", function()

    return display.newNode() -- 返回一个 cc.Node 对象

end)

-- 构造函数

function Toolbar:ctor()

    self.buttons = {} -- 用一个 table 来记录所有的按钮

end

-- 添加一个按钮，并且自动设置按钮位置

function Toolbar:addButton(button)

    -- 将按钮对象加入 table

    self.buttons[#self.buttons + 1] = button

    -- 添加按钮对象到 cc.Node 中，以便显示该按钮

    -- 因为 Toolbar 是从 cc.Node 继承的，所以可以使用 addChild() 方法

    self:addChild(button)

    -- 按照按钮数量，调整所有按钮的位置

    local x = 0

    for _, button in ipairs(self.buttons) do

        button:setPosition(x, 0)

        -- 依次排列按钮，每个按钮之间间隔 10 点

        x = x + button:getContentSize().width + 10

end

end

class() 的这种用法让我们可以在 C++ 对象基础上任意扩展行为。

既然是继承，自然就可以覆盖 C++ 对象的方法：

function Toolbar:setPosition(x, y)

    -- 由于在 Toolbar 继承类中覆盖了 cc.Node 对象的 setPosition() 方法

    -- 所以我们要用以下形式才能调用到 cc.Node 原本的 setPosition() 方法

    getmetatable(self).setPosition(self, x, y)

    printf("x = %0.2f, y = %0.2f", x, y)

end

注意: Lua 继承类覆盖的方法并不能从 C++ 调用到。也就是说通过 C++ 代码调用这个 cc.Node 对象的 setPosition() 方法时，并不会执行我们在 Lua 中定义的 Toolbar:setPosition() 方法。

Parameters

· string classname 类名

· [mixed super] 父类或者创建对象实例的函数

Returns

· table

iskindof()

iskindof(obj, classname)

如果对象是指定类或其子类的实例，返回 true，否则返回 false

local Animal = class("Animal")

local Duck = class("Duck", Animal)

print(iskindof(Duck.new(), "Animal")) -- 输出 true

Parameters

· mixed obj 要检查的对象

· string classname 类名

Returns

· boolean

import()

import(moduleName, currentModuleName)

载入一个模块

import() 与 require() 功能相同，但具有一定程度的自动化特性。

假设我们有如下的目录结构：

app/

app/classes/

app/classes/MyClass.lua

app/classes/MyClassBase.lua

app/classes/data/Data1.lua

app/classes/data/Data2.lua

MyClass 中需要载入 MyClassBase 和MyClassData。如果用 require()，MyClass 内的代码如下：

local MyClassBase = require("app.classes.MyClassBase")

local MyClass = class("MyClass", MyClassBase)

local Data1 = require("app.classes.data.Data1")

local Data2 = require("app.classes.data.Data2")

假如我们将 MyClass 及其相关文件换一个目录存放，那么就必须修改 MyClass 中的 require() 命令，否则将找不到模块文件。

而使用 import()，我们只需要如下写：

local MyClassBase = import(".MyClassBase")

local MyClass = class("MyClass", MyClassBase)

local Data1 = import(".data.Data1")

local Data2 = import(".data.Data2")

当在模块名前面有一个"." 时，import() 会从当前模块所在目录中查找其他模块。因此 MyClass 及其相关文件不管存放到什么目录里，我们都不再需要修改MyClass 中的 import() 命令。这在开发一些重复使用的功能组件时，会非常方便。

我们可以在模块名前添加多个"." ，这样 import() 会从更上层的目录开始查找模块。

不过 import() 只有在模块级别调用（也就是没有将 import() 写在任何函数中）时，才能够自动得到当前模块名。如果需要在函数中调用 import()，那么就需要指定当前模块名：

# MyClass.lua

# 这里的 ... 是隐藏参数，包含了当前模块的名字，所以最好将这行代码写在模块的第一行

local CURRENT_MODULE_NAME = ...

local function testLoad()

    local MyClassBase = import(".MyClassBase", CURRENT_MODULE_NAME)

    # 更多代码

end

Parameters

· string moduleName 要载入的模块的名字

· [string currentModuleName] 当前模块名

Returns

· module

handler()

handler(obj, method)

将 Lua 对象及其方法包装为一个匿名函数

在quick-cocos2d-x 中，许多功能需要传入一个 Lua 函数做参数，然后在特定事件发生时就会调用传入的函数。例如触摸事件、帧事件等等。

local MyScene = class("MyScene", function()

    return display.newScene("MyScene")

end)

function MyScene:ctor()

    self.frameTimeCount = 0

    -- 注册帧事件

    self:addNodeEventListener(cc.NODE_ENTER_FRAME_EVENT, self.onEnterFrame)

    self:scheduleUpdate()

end

function MyScene:onEnterFrame(dt)

    self.frameTimeCount = self.frameTimeCount + dt

end

上述代码执行时将出错，报告"Invalid self" ，这就是因为 C++ 无法识别 Lua 对象方法。因此在调用我们传入的 self.onEnterFrame 方法时没有提供正确的参数。

要让上述的代码正常工作，就需要使用 handler() 进行一下包装：

function MyScene:ctor()

    self.frameTimeCount = 0

    -- 注册帧事件

    self:addNodeEventListener(cc.ENTER_FRAME_EVENT, handler(self, self.onEnterFrame))

    self:scheduleUpdate()

end

实际上，除了 C++ 回调 Lua 函数之外，在其他所有需要回调的地方都可以使用handler()。

Parameters

· mixed obj Lua 对象

· function method 对象方法

Returns

· function

math.newrandomseed()

根据系统时间初始化随机数种子，让后续的 math.random() 返回更随机的值

math.round()

math.round(value)

对数值进行四舍五入，如果不是数值则返回 0

Parameters

· number value 输入值

Returns

· number

math.angle2radian()

math.angle2radian(angle)

角度转弧度

math.radian2angle()

math.radian2angle(radian)

弧度转角度

io.exists()

io.exists(path)

检查指定的文件或目录是否存在，如果存在返回 true，否则返回 false

可以使用 cc.FileUtils:fullPathForFilename() 函数查找特定文件的完整路径，例如：

local path = cc.FileUtils:getInstance():fullPathForFilename("gamedata.txt")

if io.exists(path) then

    ....

end

Parameters

· string path 要检查的文件或目录的完全路径

Returns

· boolean

io.readfile()

io.readfile(path)

读取文件内容，返回包含文件内容的字符串，如果失败返回 nil

io.readfile() 会一次性读取整个文件的内容，并返回一个字符串，因此该函数不适宜读取太大的文件。

Parameters

· string path 文件完全路径

Returns

· string

io.writefile()

io.writefile(path, content, mode)

以字符串内容写入文件，成功返回 true，失败返回 false

"mode 写入模式" 参数决定io.writefile() 如何写入内容，可用的值如下：

· "w+" : 覆盖文件已有内容，如果文件不存在则创建新文件

· "a+" : 追加内容到文件尾部，如果文件不存在则创建文件

此外，还可以在 "写入模式" 参数最后追加字符"b" ，表示以二进制方式写入数据，这样可以避免内容写入不完整。

Android 特别提示: 在 Android 平台上，文件只能写入存储卡所在路径，assets 和 data等目录都是无法写入的。

Parameters

· string path 文件完全路径

· string content 要写入的内容

· [string mode] 写入模式，默认值为 "w+b"

Returns

· boolean

io.pathinfo()

io.pathinfo(path)

拆分一个路径字符串，返回组成路径的各个部分

local pathinfo  = io.pathinfo("/var/app/test/abc.png")

-- 结果:

-- pathinfo.dirname  = "/var/app/test/"

-- pathinfo.filename = "abc.png"

-- pathinfo.basename = "abc"

-- pathinfo.extname  = ".png"

Parameters

· string path 要分拆的路径字符串

Returns

· table

io.filesize()

io.filesize(path)

返回指定文件的大小，如果失败返回 false

Parameters

· string path 文件完全路径

Returns

· integer

table.nums()

table.nums(t)

计算表格包含的字段数量

Lua table 的 "#" 操作只对依次排序的数值下标数组有效，table.nums() 则计算 table 中所有不为 nil 的值的个数。

Parameters

· table t 要检查的表格

Returns

· integer

table.keys()

table.keys(hashtable)

返回指定表格中的所有键

local hashtable = {a = 1, b = 2, c = 3}

local keys = table.keys(hashtable)

-- keys = {"a", "b", "c"}

Parameters

· table hashtable 要检查的表格

Returns

· table

table.values()

table.values(hashtable)

返回指定表格中的所有值

local hashtable = {a = 1, b = 2, c = 3}

local values = table.values(hashtable)

-- values = {1, 2, 3}

Parameters

· table hashtable 要检查的表格

Returns

· table

table.merge()

table.merge(dest, src)

将来源表格中所有键及其值复制到目标表格对象中，如果存在同名键，则覆盖其值

local dest = {a = 1, b = 2}

local src  = {c = 3, d = 4}

table.merge(dest, src)

-- dest = {a = 1, b = 2, c = 3, d = 4}

Parameters

· table dest 目标表格

· table src 来源表格

table.insertto()

table.insertto(dest, src, begin)

在目标表格的指定位置插入来源表格，如果没有指定位置则连接两个表格

local dest = {1, 2, 3}

local src  = {4, 5, 6}

table.insertto(dest, src)

-- dest = {1, 2, 3, 4, 5, 6}

dest = {1, 2, 3}

table.insertto(dest, src, 5)

-- dest = {1, 2, 3, nil, 4, 5, 6}

Parameters

· table dest 目标表格

· table src 来源表格

· [integer begin] 插入位置

table.indexof()

table.indexof(array, value, begin)

从表格中查找指定值，返回其索引，如果没找到返回 false

local array = {"a", "b", "c"}

print(table.indexof(array, "b")) -- 输出 2

Parameters

· table array 表格

· mixed value 要查找的值

· [integer begin] 起始索引值

Returns

· integer

table.keyof()

table.keyof(hashtable, value)

从表格中查找指定值，返回其 key，如果没找到返回 nil

local hashtable = {name = "dualface", comp = "chukong"}

print(table.keyof(hashtable, "chukong")) -- 输出 comp

Parameters

· table hashtable 表格

· mixed value 要查找的值

Returns

· string 该值对应的 key

table.removebyvalue()

table.removebyvalue(array, value, removeall)

从表格中删除指定值，返回删除的值的个数

local array = {"a", "b", "c", "c"}

print(table.removebyvalue(array, "c", true)) -- 输出 2

Parameters

· table array 表格

· mixed value 要删除的值

· [boolean removeall] 是否删除所有相同的值

Returns

· integer

table.map()

table.map(t, fn)

对表格中每一个值执行一次指定的函数，并用函数返回值更新表格内容

local t = {name = "dualface", comp = "chukong"}

table.map(t, function(v, k)

    -- 在每一个值前后添加括号

    return "[" .. v .. "]"

end)

-- 输出修改后的表格内容

for k, v in pairs(t) do

    print(k, v)

end

-- 输出

-- name [dualface]

-- comp [chukong]

fn 参数指定的函数具有两个参数，并且返回一个值。原型如下：

function map_function(value, key)

    return value

end

Parameters

· table t 表格

· function fn 函数

table.walk()

table.walk(t, fn)

对表格中每一个值执行一次指定的函数，但不改变表格内容

local t = {name = "dualface", comp = "chukong"}

table.walk(t, function(v, k)

    -- 输出每一个值

    print(v)

end)

fn 参数指定的函数具有两个参数，没有返回值。原型如下：

function map_function(value, key)

end

Parameters

· table t 表格

· function fn 函数

table.filter()

table.filter(t, fn)

对表格中每一个值执行一次指定的函数，如果该函数返回 false，则对应的值会从表格中删除

local t = {name = "dualface", comp = "chukong"}

table.filter(t, function(v, k)

    return v ~= "dualface" -- 当值等于 dualface 时过滤掉该值

end)

-- 输出修改后的表格内容

for k, v in pairs(t) do

    print(k, v)

end

-- 输出

-- comp chukong

fn 参数指定的函数具有两个参数，并且返回一个 boolean 值。原型如下：

function map_function(value, key)

    return true or false

end

Parameters

· table t 表格

· function fn 函数

table.unique()

table.unique(t)

遍历表格，确保其中的值唯一

local t = {"a", "a", "b", "c"} -- 重复的 a 会被过滤掉

local n = table.unique(t)

for k, v in pairs(n) do

    print(v)

end

-- 输出

-- a

-- b

-- c

Parameters

· table t 表格

Returns

· table 包含所有唯一值的新表格

string.htmlspecialchars()

string.htmlspecialchars(input)

将特殊字符转为 HTML 转义符

print(string.htmlspecialchars(""))

-- 输出 <ABC>

Parameters

· string input 输入字符串

Returns

· string 转换结果

string.restorehtmlspecialchars()

string.restorehtmlspecialchars(input)

将 HTML转义符还原为特殊字符，功能与 string.htmlspecialchars() 正好相反

print(string.restorehtmlspecialchars("<ABC>"))

-- 输出

Parameters

· string input 输入字符串

Returns

· string 转换结果

string.nl2br()

string.nl2br(input)

将字符串中的 \n 换行符转换为 HTML 标记

print(string.nl2br("Hello\nWorld"))

-- 输出

-- Hello
World

Parameters

· string input 输入字符串

Returns

· string 转换结果

string.text2html()

string.text2html(input)

将字符串中的特殊字符和 \n 换行符转换为 HTML 转移符和标记

print(string.nl2br("\nWorld"))

-- 输出

-- <Hello>
World

Parameters

· string input 输入字符串

Returns

· string 转换结果

string.split()

string.split(input, delimiter)

用指定字符或字符串分割输入字符串，返回包含分割结果的数组

local input = "Hello,World"

local res = string.split(input, ",")

-- res = {"Hello", "World"}

local input = "Hello-+-World-+-Quick"

local res = string.split(input, "-+-")

-- res = {"Hello", "World", "Quick"}

Parameters

· string input 输入字符串

· string delimiter 分割标记字符或字符串

Returns

· array 包含分割结果的数组

string.ltrim()

string.ltrim(input)

去除输入字符串头部的空白字符，返回结果

local input = "  ABC"

print(string.ltrim(input))

-- 输出 ABC，输入字符串前面的两个空格被去掉了

空白字符包括：

· 空格

· 制表符 \t

· 换行符 \n

· 回到行首符 \r

Parameters

· string input 输入字符串

Returns

· string 结果

@see string.rtrim, string.trim

string.rtrim()

string.rtrim(input)

去除输入字符串尾部的空白字符，返回结果

local input = "ABC  "

print(string.ltrim(input))

-- 输出 ABC，输入字符串最后的两个空格被去掉了

Parameters

· string input 输入字符串

Returns

· string 结果

@see string.ltrim, string.trim

string.trim()

string.trim(input)

去掉字符串首尾的空白字符，返回结果

Parameters

· string input 输入字符串

Returns

· string 结果

@see string.ltrim, string.rtrim

string.ucfirst()

string.ucfirst(input)

将字符串的第一个字符转为大写，返回结果

local input = "hello"

print(string.ucfirst(input))

-- 输出 Hello

Parameters

· string input 输入字符串

Returns

· string 结果

string.urlencode()

string.urlencode(input)

将字符串转换为符合 URL 传递要求的格式，并返回转换结果

local input = "hello world"

print(string.urlencode(input))

-- 输出

-- hello%20world

Parameters

· string input 输入字符串

Returns

· string 转换后的结果

@see string.urldecode

string.urldecode()

string.urldecode(input)

将 URL 中的特殊字符还原，并返回结果

local input = "hello%20world"

print(string.urldecode(input))

-- 输出

-- hello world

Parameters

· string input 输入字符串

Returns

· string 转换后的结果

@see string.urlencode

string.utf8len()

string.utf8len(input)

计算 UTF8 字符串的长度，每一个中文算一个字符

local input = "你好World"

print(string.utf8len(input))

-- 输出 7

Parameters

· string input 输入字符串

Returns

· integer 长度

string.formatnumberthousands()

string.formatnumberthousands(num)

将数值格式化为包含千分位分隔符的字符串

print(string.formatnumberthousands(1924235))

-- 输出 1,924,235

Parameters

· number num 数值

Returns

· string 格式化结果

4. cocos2dx

\quick\framework\cocos2dx.lua文件

\quick\framework\cocos2dx文件夹中文件

针对 cocos2d-x 的一些封装和扩展

预定义的节点事件：

· cc.NODE_EVENT - enter, exit 等事件

· cc.NODE_ENTER_FRAME_EVENT - 帧事件

· cc.NODE_TOUCH_EVENT - 触摸事件

· cc.NODE_TOUCH_CAPTURE_EVENT - 捕获触摸事件

预定义的层事件：

· cc.ACCELERATE_EVENT - 重力感应事件

· cc.KEYPAD_EVENT - 硬件按键事件

预定义的触摸模式：

· cc.TOUCH_MODE_ALL_AT_ONCE - 多点触摸

· cc.TOUCH_MODE_ONE_BY_ONE - 单点触摸

5. device

quick\framework\device.lua文件

提供设备相关属性的查询，以及设备功能的访问

当框架初始完成后，device 模块提供下列属性：

· device.platform 返回当前运行平台的名字，可用值： ios, android, mac, windows.

· device.model 返回设备型号，可用值： unknown, iphone, ipad

· device.language 返回设备当前使用的语言，可用值：

· cn：中文

· fr：法语

· it：意大利语

· gr：德语

· sp：西班牙语

· ru：俄语

· jp：日语

· en：英语

· device.writablePath 返回设备上可以写入数据的首选路径：

· iOS 上返回应用程序所在的 Documents 目录

· Android 上返回存储卡的根目录

· 其他平台的返回值由 quick-x-player 决定

· device.cachePath 返回设备上可以写入数据的缓存目录：

· iOS 上返回应用程序所在的 Library/Caches 目录

· 其他平台的返回值同 device.writablePath

· device.directorySeparator 目录分隔符，在 Windows 平台上是 “\”，其他平台都是 “/”

· device.pathSeparator 路径分隔符，在 Windows 平台上是 “;”，其他平台都是 “:”

Functions

device.showActivityIndicator()

显示活动指示器

device.hideActivityIndicator()

隐藏正在显示的活动指示器

device.showAlert(title, message, buttonLabels, listener)

显示一个包含按钮的弹出对话框

device.cancelAlert()

取消正在显示的对话框。

device.getOpenUDID()

返回设备的 OpenUDID 值

device.openURL(url)

用浏览器打开指定的网址

device.showInputBox(title, message, defaultValue)

显示一个输入框，并返回用户输入的内容。

Functions

device.showActivityIndicator()

显示活动指示器

在 iOS 和Android 设备上显示系统的活动指示器，可以用于阻塞操作时通知用户需要等待。

device.hideActivityIndicator()

隐藏正在显示的活动指示器

device.showAlert()

device.showAlert(title, message, buttonLabels, listener)

显示一个包含按钮的弹出对话框

local function onButtonClicked(event)

    if event.buttonIndex == 1 then

        .... 玩家选择了 YES 按钮

    else

        .... 玩家选择了 NO 按钮

end

end

device.showAlert("Confirm Exit", "Are you sure exit game ?", {"YES", "NO"}, onButtonClicked)

当没有指定按钮标题时，对话框会默认显示一个“OK”按钮。回调函数获得的表格中，buttonIndex 指示玩家选择了哪一个按钮，其值是按钮的显示顺序。

Parameters

· string title 对话框标题

· string message 内容

· table buttonLabels 包含多个按钮标题的表格对象

· function listener 回调函数

device.cancelAlert()

取消正在显示的对话框。

提示：取消对话框，不会执行显示对话框时指定的回调函数。

device.getOpenUDID()

返回设备的 OpenUDID 值

OpenUDID 是为设备仿造的 UDID（唯一设备识别码），可以用来识别用户的设备。

但OpenUDID 存在下列问题：

· 如果删除了应用再重新安装，获得的 OpenUDID 会发生变化

· iOS 7 不支持 OpenUDID

Returns

· string 设备的 OpenUDID 值

device.openURL()

device.openURL(url)

用浏览器打开指定的网址

-- 打开网页

device.openURL("http://dualface.github.com/quick-cocos2d-x/")

-- 打开设备上的邮件程序，并创建新邮件，填入收件人地址

device.openURL("mailto:[email protected]")

-- 增加主题和内容

local subject = string.urlencode("Hello")

local body = string.urlencode("How are you ?")

device.openURL(string.format("mailto:[email protected]?subject=%s&body=%s", subject, body))

-- 打开设备上的拨号程序

device.openURL("tel:123-456-7890")

Parameters

· string 网址，邮件，拨号等的字符串

device.showInputBox()

device.showInputBox(title, message, defaultValue)

显示一个输入框，并返回用户输入的内容。

当用户点击取消按钮时，showInputBox() 函数返回空字符串。

Parameters

· string title 对话框标题

· string message 提示信息

· string defaultValue 输入框默认值

Returns

· string 用户输入的字符串

6. transition

quick\framework\transition.lua文件

为图像创造效果

Functions

transition.newEasing(action, easingName, more)

创建一个缓动效果

transition.create(action, args)

创建一个动作效果

transition.execute(target, action, args)

执行一个动作效果

transition.rotateTo(target, args)

将显示对象旋转到指定角度，并返回 Action 动作对象。

transition.moveTo(target, args)

将显示对象移动到指定位置，并返回 Action 动作对象。

transition.moveBy(target, args)

将显示对象移动一定距离，并返回 Action 动作对象。

transition.fadeIn(target, args)

淡入显示对象，并返回 Action 动作对象。

transition.fadeOut(target, args)

淡出显示对象，并返回 Action 动作对象。

transition.fadeTo(target, args)

将显示对象的透明度改变为指定值，并返回 Action 动作对象。

transition.scaleTo(target, args)

将显示对象缩放到指定比例，并返回 Action 动作对象。

transition.sequence(actions)

创建一个动作序列对象。

transition.playAnimationOnce(target, animation, removeWhenFinished, onComplete, delay)

在显示对象上播放一次动画，并返回 Action 动作对象。

transition.playAnimationForever(target, animation, delay)

在显示对象上循环播放动画，并返回 Action 动作对象。

transition.removeAction(action)

停止一个正在执行的动作

transition.stopTarget(target)

停止一个显示对象上所有正在执行的动作

transition.pauseTarget(target)

暂停显示对象上所有正在执行的动作

transition.resumeTarget(target)

恢复显示对象上所有暂停的动作

Functions

transition.newEasing()

transition.newEasing(action, easingName, more)

创建一个缓动效果

Parameters

· Action action 动作对象

· string easingName 缓冲效果的名字, 具体参考 transition.execute() 方法

· mixed more 创建缓冲效果的参数

Returns

· mixed 结果

transition.create()

transition.create(action, args)

创建一个动作效果

Parameters

· Action action 动作对象

· table args 参数表格对象

Returns

· mixed 结果

transition.execute()

transition.execute(target, action, args)

执行一个动作效果

-- 等待 1.0 后开始移动对象

-- 耗时 1.5 秒，将对象移动到屏幕中央

-- 移动使用 backout 缓动效果

-- 移动结束后执行函数，显示 move completed

transition.execute(sprite, MoveTo:create(1.5, cc.p(display.cx, display.cy)), {

    delay = 1.0,

    easing = "backout",

    onComplete = function()

        print("move completed")

    end,

})

transition.execute() 是一个强大的工具，可以为原本单一的动作添加各种附加特性。

transition.execute() 的参数表格支持下列参数：

· delay: 等待多长时间后开始执行动作

· easing: 缓动效果的名字及可选的附加参数，效果名字不区分大小写

· onComplete: 动作执行完成后要调用的函数

· time: 执行动作需要的时间

transition.execute() 支持的缓动效果：

· backIn

· backInOut

· backOut

· bounce

· bounceIn

· bounceInOut

· bounceOut

· elastic, 附加参数默认为 0.3

· elasticIn, 附加参数默认为 0.3

· elasticInOut, 附加参数默认为 0.3

· elasticOut, 附加参数默认为 0.3

· exponentialIn, 附加参数默认为 1.0

· exponentialInOut, 附加参数默认为 1.0

· exponentialOut, 附加参数默认为 1.0

· In, 附加参数默认为 1.0

· InOut, 附加参数默认为 1.0

· Out, 附加参数默认为 1.0

· rateaction, 附加参数默认为 1.0

· sineIn

· sineInOut

· sineOut

Parameters

· cc.Node target 显示对象

· Action action 动作对象

· table args 参数表格对象

Returns

· mixed 结果

transition.rotateTo()

transition.rotateTo(target, args)

将显示对象旋转到指定角度，并返回 Action 动作对象。

-- 耗时 0.5 秒将 sprite 旋转到 180 度

transition.rotateTo(sprite, {rotate = 180, time = 0.5})

Parameters

· cc.Node target 显示对象

· table args 参数表格对象

Returns

· mixed 结果

transition.moveTo()

transition.moveTo(target, args)

将显示对象移动到指定位置，并返回 Action 动作对象。

-- 移动到屏幕中心

transition.moveTo(sprite, {x = display.cx, y = display.cy, time = 1.5})

-- 移动到屏幕左边，不改变 y

transition.moveTo(sprite, {x = display.left, time = 1.5})

-- 移动到屏幕底部，不改变 x

transition.moveTo(sprite, {y = display.bottom, time = 1.5})

Parameters

· cc.Node target 显示对象

· table args 参数表格对象

Returns

· mixed 结果

transition.moveBy()

transition.moveBy(target, args)

将显示对象移动一定距离，并返回 Action 动作对象。

-- 向右移动 100 点，向上移动 100 点

transition.moveBy(sprite, {x = 100, y = 100, time = 1.5})

-- 向左移动 100 点，不改变 y

transition.moveBy(sprite, {x = -100, time = 1.5})

-- 向下移动 100 点，不改变 x

transition.moveBy(sprite, {y = -100, time = 1.5})

Parameters

· cc.Node target 显示对象

· table args 参数表格对象

Returns

· mixed 结果

transition.fadeIn()

transition.fadeIn(target, args)

淡入显示对象，并返回 Action 动作对象。

fadeIn 操作会首先将对象的透明度设置为 0（0%，完全透明），然后再逐步增加为 255（100%，完全不透明）。

如果不希望改变对象当前的透明度，应该用 fadeTo()。

action = transition.fadeIn(sprite, {time = 1.5})

Parameters

· cc.Node target 显示对象

· table args 参数表格对象

Returns

· mixed 结果

transition.fadeOut()

transition.fadeOut(target, args)

淡出显示对象，并返回 Action 动作对象。

fadeOut 操作会首先将对象的透明度设置为 255（100%，完全不透明），然后再逐步减少为 0（0%，完全透明）。

如果不希望改变对象当前的透明度，应该用 fadeTo()。

action = transition.fadeOut(sprite, {time = 1.5})

Parameters

· cc.Node target 显示对象

· table args 参数表格对象

Returns

· mixed 结果

transition.fadeTo()

transition.fadeTo(target, args)

将显示对象的透明度改变为指定值，并返回 Action 动作对象。

-- 不管显示对象当前的透明度是多少，最终设置为 128

transition.fadeTo(sprite, {opacity = 128, time = 1.5})

Parameters

· cc.Node target 显示对象

· table args 参数表格对象

Returns

· mixed 结果

transition.scaleTo()

transition.scaleTo(target, args)

将显示对象缩放到指定比例，并返回 Action 动作对象。

-- 整体缩放为 50%

transition.scaleTo(sprite, {scale = 0.5, time = 1.5})

-- 单独水平缩放

transition.scaleTo(sprite, {scaleX = 0.5, time = 1.5})

-- 单独垂直缩放

transition.scaleTo(sprite, {scaleY = 0.5, time = 1.5})

Parameters

· cc.Node target 显示对象

· table args 参数表格对象

Returns

· mixed 结果

transition.sequence()

transition.sequence(actions)

创建一个动作序列对象。

local sequence = transition.sequence({

    cc.MoveTo:create(0.5, cc.p(display.cx, display.cy)),

    cc.FadeOut:create(0.2),

    cc.DelayTime:create(0.5),

    cc.FadeIn:create(0.3),

})

sprite:runAction(sequence)

Parameters

· table args 动作的表格对象

Returns

· Sequence 动作序列对象

transition.playAnimationOnce()

transition.playAnimationOnce(target, animation,removeWhenFinished, onComplete, delay)

在显示对象上播放一次动画，并返回 Action 动作对象。

local frames = display.newFrames("Walk%04d.png", 1, 20)

local animation = display.newAnimation(frames, 0.5 / 20) -- 0.5s play 20 frames

transition.playAnimationOnce(sprite, animation)

还可以用 Sprite 对象的 playAnimationOnce() 方法来直接播放动画：

local frames = display.newFrames("Walk%04d.png", 1, 20)

local animation = display.newAnimation(frames, 0.5 / 20) -- 0.5s play 20 frames

sprite:playAnimationOnce(animation)

playAnimationOnce() 提供了丰富的功能，例如在动画播放完成后就删除用于播放动画的Sprite 对象。例如一个爆炸效果：

local frames = display.newFrames("Boom%04d.png", 1, 8)

local boom = display.newSprite(frames[1])

-- playAnimationOnce() 第二个参数为 true 表示动画播放完后删除 boom 这个 Sprite 对象

-- 这样爆炸动画播放完毕，就自动清理了不需要的显示对象

boom:playAnimationOnce(display.newAnimation(frames, 0.3/ 8), true)

此外，playAnimationOnce() 还允许在动画播放完成后执行一个指定的函数，以及播放动画前等待一段时间。合理运用这些功能，可以大大简化我们的游戏代码。

Parameters

· cc.Node target 显示对象

· cc.Node animation 动作对象

· boolean removeWhenFinished 播放完成后删除显示对象

· function onComplete 播放完成后要执行的函数

· number delay 播放前等待的时间

Returns

· table 动作表格对象

transition.playAnimationForever()

transition.playAnimationForever(target, animation, delay)

在显示对象上循环播放动画，并返回 Action 动作对象。

local frames = display.newFrames("Walk%04d.png", 1, 20)

local animation = display.newAnimation(frames, 0.5 / 20) -- 0.5s play 20 frames

sprite:playAnimationForever(animation)

Parameters

· cc.Node target 显示对象

· cc.Node animation 动作对象

· number delay 播放前等待的时间

Returns

· table 动作表格对象

transition.removeAction()

transition.removeAction(action)

停止一个正在执行的动作

-- 开始移动

local action = transition.moveTo(sprite, {time = 2.0, x = 100, y = 100})

....

transition.removeAction(action) -- 停止移动

Parameters

· mixed target

transition.stopTarget()

transition.stopTarget(target)

停止一个显示对象上所有正在执行的动作

-- 开始移动

transition.moveTo(sprite, {time = 2.0, x = 100, y = 100})

transition.fadeOut(sprite, {time = 2.0})

....

transition.stopTarget(sprite)

注意:显示对象的 performWithDelay() 方法是用动作来实现延时回调操作的，所以如果停止显示对象上的所有动作，会清除该对象上的延时回调操作。

Parameters

· mixed target

transition.pauseTarget()

transition.pauseTarget(target)

暂停显示对象上所有正在执行的动作

Parameters

· mixed target

transition.resumeTarget()

transition.resumeTarget(target)

恢复显示对象上所有暂停的动作

Parameters

· mixed target

7. display

quick\framework\display.lua文件

与显示图像、场景有关的功能

display 模块封装了绝大部分与显示有关的功能，并负责根据 config.lua 中定义的分辨率设定计算屏幕的设计分辨率。

框架初始化后，display 模块提供下列属性：

· display.sizeInPixels.width,

· display.sizeInPixels.height 屏幕的像素分辨率

· display.widthInPixels,

· display.heightInPixels 屏幕的像素分辨率

· display.contentScaleFactor 内容缩放因子

· display.size.width,

· display.size.height 屏幕的设计分辨率

· display.width,

· display.height 屏幕的设计分辨率

· display.cx,

· display.cy 屏幕中央的 x 坐标和 y 坐标

· display.left,

· display.top,

· display.right,

· display.bottom 屏幕四边的坐标

· display.c_left,

· display.c_top,

· display.c_right,

· display.c_bottom 当父对象在屏幕中央时，屏幕四边的坐标

颜色：

· display.COLOR_WHITE 白色, cc.c3b(255, 255, 255)

· display.COLOR_BLACK 黑色, cc.c3b(0, 0, 0)

Functions

display.newScene(name)

创建一个新场景，并返回 Scene 场景对象。

display.newPhysicsScene(name)

创建一个新场景，并返回 Scene 场景对象。

display.wrapSceneWithTransition(scene, transitionType, time, more)

用场景切换过渡效果包装场景对象，并返回场景过渡对象。

display.replaceScene(newScene, transitionType, time, more)

切换到新场景

display.getRunningScene()

返回当前正在运行的场景对象

display.pause()

暂停当前场景

display.resume()

恢复当前暂停的场景

display.newLayer()

创建并返回一个 Layer 层对象

display.newColorLayer(color)

创建一个颜色填充层

display.newNode()

创建并返回一个 Node 对象

display.newClippingRegionNode(rect)

创建并返回一个 ClippingRegionNode 对象。

display.newSprite(filename, x, y, params)

创建并返回一个 Sprite 显示对象。

display.newScale9Sprite(filename, x, y, size, capInsets)

创建并返回一个 Sprite9Scale 显示对象。

display.newTilesSprite(filename, rect)

创建并返回一个平铺的 Sprite 显示对象

display.newTiledBatchNode(filename, plistFile, size, hPadding, vPadding)

create a tiled SpriteBatchNode, the image can not a POT file.

display.newMaskedSprite(__mask, __pic)

Create a masked sprite

display.newFilteredSprite(filename, filters, params)

Create a Filtered Sprite

display.newGraySprite(filename, params)

Create a Gray Sprite by FilteredSprite

display.newDrawNode()

创建并返回一个空的 DrawNode 对象

display.newSolidCircle(radius, params)

创建并返回一个 DrawNode（实心圆）对象。

display.newCircle(radius, params)

创建并返回一个 DrawNode （圆）对象。

display.newRect(rect, params)

创建并返回一个 DrawNode （矩形）对象。

display.newLine(points, params)

创建并返回一个 DrawNode （线性）对象。

display.newPolygon(points, params, drawNode)

创建并返回一个 PolygonShape （多边形）对象。

display.newBMFontLabel(params)

用位图字体创建文本显示对象，并返回 Label 对象。

display.newTTFLabel(params)

使用 TTF 字体创建文字显示对象，并返回 Label 对象。

display.align(target, anchorPoint, x, y)

将指定的显示对象按照特定锚点对齐。

display.addSpriteFrames(plistFilename, image, handler)

将指定的 Sprite Sheets 材质文件及其数据文件载入图像帧缓存。

display.removeSpriteFramesWithFile(plistFilename, imageName)

从内存中卸载 Sprite Sheets 材质和数据文件

display.setTexturePixelFormat(filename, format)

设置材质格式。

display.removeSpriteFrameByImageName(imageName)

从图像帧缓存中删除一个图像。

display.newBatchNode(image, capacity)

从指定的图像文件创建并返回一个批量渲染对象。

display.newSpriteFrame(frameName)

创建并返回一个图像帧对象。

display.newFrames(pattern, begin, length, isReversed)

以特定模式创建一个包含多个图像帧对象的数组。

display.newAnimation(frames, time)

以包含图像帧的数组创建一个动画对象。

display.setAnimationCache(name, animation)

以指定名字缓存创建好的动画对象，以便后续反复使用。

display.getAnimationCache(name)

取得以指定名字缓存的动画对象，如果不存在则返回 nil。

display.removeAnimationCache(name)

删除指定名字缓存的动画对象。

display.removeUnusedSpriteFrames()

从内存中卸载没有使用 Sprite Sheets 材质

display.newProgressTimer(image, progresssType)

创建一个进度条的节点

display.printscreen(node, args)

获取一个节点的纹理内容

Functions

display.newScene()

display.newScene(name)

创建一个新场景，并返回 Scene 场景对象。

指定场景名称方便调试。

Parameters

· string name 场景名称

Returns

· Scene 场景对象

@see Scene

display.newPhysicsScene()

display.newPhysicsScene(name)

创建一个新场景，并返回 Scene 场景对象。

指定场景名称方便调试。

Parameters

· string name 场景名称

Returns

· Scene 场景对象

@see Scene

display.wrapSceneWithTransition()

display.wrapSceneWithTransition(scene, transitionType, time,more)

用场景切换过渡效果包装场景对象，并返回场景过渡对象。

-- 创建一个新场景

local nextScene = display.newScene("NextScene")

-- 包装过渡效果

local transition = display.wrapSceneWithTransition(nextScene, "fade", 0.5)

-- 切换到新场景

display.replaceScene(nextScene)

可用的过渡效果有：

· crossFade 淡出当前场景的同时淡入下一个场景

· fade 淡出当前场景到指定颜色，默认颜色为 cc.c3b(0, 0, 0)，可用 wrapSceneWithTransition() 的最后一个参数指定颜色

· fadeBL 从左下角开始淡出场景

· fadeDown 从底部开始淡出场景

· fadeTR 从右上角开始淡出场景

· fadeUp 从顶部开始淡出场景

· flipAngular 当前场景倾斜后翻转成下一个场景，默认从左边开始翻转，可以指定为：

· cc.TRANSITION_ORIENTATION_LEFT_OVER从左边开始

· cc.TRANSITION_ORIENTATION_RIGHT_OVER从右边开始

· cc.TRANSITION_ORIENTATION_UP_OVER从顶部开始

· cc.TRANSITION_ORIENTATION_DOWN_OVER从底部开始

· flipX 水平翻转，默认从左往右翻转，可用的附加参数同上

· flipY 垂直翻转，默认从上往下翻转，可用的附加参数同上

· zoomFlipAngular 倾斜翻转的同时放大，可用的附加参数同上

· zoomFlipX 水平翻转的同时放大，可用的附加参数同上

· zoomFlipY 垂直翻转的同时放大，可用的附加参数同上

· jumpZoom 跳跃放大切换场景

· moveInB 新场景从底部进入，现有场景同时从顶部退出

· moveInL 新场景从左侧进入，现有场景同时从右侧退出

· moveInR 新场景从右侧进入，现有场景同时从左侧退出

· moveInT 新场景从顶部进入，现有场景同时从底部退出

· pageTurn 翻页效果，如果指定附加参数为 true，则表示从左侧往右翻页

· rotoZoom 旋转放大切换场景

· shrinkGrow 收缩交叉切换场景

· slideInB 新场景从底部进入，直接覆盖现有场景

· slideInL 新场景从左侧进入，直接覆盖现有场景

· slideInR 新场景从右侧进入，直接覆盖现有场景

· slideInT 新场景从顶部进入，直接覆盖现有场景

· splitCols 分成多列切换入新场景

· splitRows 分成多行切换入新场景，类似百叶窗

· turnOffTiles 当前场景分成多个块，逐渐替换为新场景

Parameters

· Scene scene 场景对象

· string transitionType 过渡效果名

· number time 过渡时间

· string more 过渡效果附加参数

Returns

· Scene 场景对象

display.replaceScene()

display.replaceScene(newScene, transitionType, time, more)

切换到新场景

-- 使用红色做过渡色

display.replaceScene(nextScene, "fade", 0.5, cc.c3b(255, 0, 0))

Parameters

· Scene newScene 场景对象

· string transitionType 过渡效果名

· number time 过渡时间

· mixed more 过渡效果附加参数

display.getRunningScene()

返回当前正在运行的场景对象

Returns

· Scene 场景对象

display.pause()

暂停当前场景

display.resume()

恢复当前暂停的场景

display.newLayer()

创建并返回一个 Layer 层对象

Layer 对象提供了触摸事件、重力感应、Android 按键检测等功能，具体请参考 Layer。

@see Layer

display.newColorLayer()

display.newColorLayer(color)

创建一个颜色填充层

LayerColor 对象使用指定的颜色填充。

Parameters

· ccColor3B color

Returns

· LayerColor

@see LayerColor

display.newNode()

创建并返回一个 Node 对象

Node 对象并不能显示对象，但可以作为其他显示对象的容器（起到群组的作用）。具体请参考 Node。

local group = display.newNode()     -- 创建一个容器

group:addChild(sprite1)             -- 添加显示对象到容器中

group:addChild(sprite2)             -- 添加显示对象到容器中

-- 移动容器时，其中包含的子对象也会同时移动

transition.moveBy(group, {time = 2.0, x = 100})

Returns

· Node Node对象

@see Node

display.newClippingRegionNode()

display.newClippingRegionNode(rect)

创建并返回一个 ClippingRegionNode 对象。

创建 ClippingRegionNode 对象时需要指定一个屏幕区域，然后在显示时，所以加入ClippingRegionNode 对象的内容都会进行剪裁，超出指定区域的内容不会显示。

-- 剪裁区域从屏幕左下角靠内 100 点，到屏幕右上角

local rect = cc.rect(display.left + 100,

                    display.bottom + 100,

                    display.width - 200,

                    display.height - 200)

local clipnode = display.newClippingRegionNode(rect)

clipnode:addChild(sprite1)

clipnode:addChild(sprite2)

scene:addChild(clipnode)

注意：ClippingRegionNode 的父对象其坐标必须是 0, 0。

Parameters

· table rect 指定的区域

Returns

· ClippingRegionNodeClippingRegionNode对象

display.newSprite()

display.newSprite(filename, x, y, params)

创建并返回一个 Sprite 显示对象。

display.newSprite() 有三种方式创建显示对象：

· 从图片文件创建

· 从缓存的图像帧创建

· 从 SpriteFrame 对象创建

-- 从图片文件创建显示对象

local sprite1 = display.newSprite("hello1.png")

-- 从缓存的图像帧创建显示对象

-- 图像帧的名字就是图片文件名，但为了和图片文件名区分，所以此处需要在文件名前添加 “#” 字符

-- 添加 “#” 的规则适用于所有需要区分图像和图像帧的地方

local sprite2 = display.newSprite("#frame0001.png")

-- 从 SpriteFrame 对象创建

local frame = display.newFrame("frame0002.png")

local sprite3 = display.newSprite(frame)

如果指定了 x,y 参数，那么创建显示对象后会调用对象的 setPosition() 方法设置对象位置。

Parameters

· mixed 图像名或SpriteFrame对象

· number x

· number y

· table params

Returns

· Sprite

@see Sprite

display.newScale9Sprite()

display.newScale9Sprite(filename, x, y, size, capInsets)

创建并返回一个 Sprite9Scale 显示对象。

格式：

sprite = display.newScale9Sprite(图像名, [x,y], [size 对象])

Sprite9Scale 就是通常所說的“九宫格”图像。一个矩形图像会被分为 9 部分，然后根据要求拉伸图像，同时保证拉伸后的图像四边不变形。

-- 创建一个 Scale9 图像，并拉伸到 400, 300 点大小

local sprite = display.newScale9Sprite("Box.png", 0, 0, cc.size(400, 300))

Parameters

· string filename 图像名

· integer x

· integer y

· table size

Returns

· Sprite9Scale Sprite9Scale显示对象

display.newTilesSprite()

display.newTilesSprite(filename, rect)

创建并返回一个平铺的 Sprite 显示对象

Parameters

· string filename 图像名

· cc.rect rect 平铺范围

Returns

· Sprite

display.newTiledBatchNode()

display.newTiledBatchNode(filename, plistFile, size, hPadding,vPadding)

create a tiled SpriteBatchNode, the image can not a POT file.

Parameters

· mixed filename As same a the firstparameter for display.newSprite

· string plistFile Texture(plist) imagefilename, filename must be a part of the texture.

· size size The tiled node size,use cc.size create it please.

· integer hPadding Horizontal padding, itwill display 1 px gap on moving the node, set padding for fix it.

· integer vPadding Vertical padding.

Returns

· SpriteBatchNode

display.newMaskedSprite()

display.newMaskedSprite(__mask, __pic)

Create a masked sprite

Parameters

· string mask 裁剪形状的图片名

· string pic 被裁减的图片名

Returns

· Sprite

display.newFilteredSprite()

display.newFilteredSprite(filename, filters, params)

Create a Filtered Sprite

Parameters

· mixed filename As same a the firstparameter for display.newSprite

· mixed filters One of the following:

· A Filter name;

· More Filter names(in atable);

· An instance of Filter;

· Some instances of Filter(in atable);

· A Array inclueds someinstances of Filter.

· table params A or some parameters for Filter.

Returns

· An instance of FilteredSprite

display.newGraySprite()

display.newGraySprite(filename, params)

Create a Gray Sprite by FilteredSprite

Parameters

· mixed filename As same a the firstparameter for display.newSprite

· table params As same as the third parameterfor display.newFilteredSprite

Returns

· An instance of FilteredSprite

display.newDrawNode()

创建并返回一个空的 DrawNode 对象

Returns

· DrawNode

@see DrawNode

display.newSolidCircle()

display.newSolidCircle(radius, params)

创建并返回一个 DrawNode（实心圆）对象。

local circle = display.newSolidCircle(10, {x = 150, y = 150, color = cc.c4f(1, 1, 1, 1)})

circle:addTo(scene)

Parameters

· number radius 实心圆的半径

· table params 创建圆的参数 x,y为圆点位置 color中圆的颜色

Returns

· DrawNode

@see DrawNode

display.newCircle()

display.newCircle(radius, params)

创建并返回一个 DrawNode （圆）对象。

--创建一个半径为50, 圆心在(100,100),中间填充为红色,边线为绿色,边线的宽度为2 的圆

local circle = display.newCircle(50,

        {x = 100, y = 100,

        fillColor = cc.c4f(1, 0, 0, 1),

        borderColor = cc.c4f(0, 1, 0, 1),

        borderWidth = 2})

Parameters

· number radius

· table params 有参数，x,y 圆的位置填充色 fillColor, 边线色 borderColor 及边线宽度 borderWidth

Returns

· DrawNode

@see DrawNode

display.newRect()

display.newRect(rect, params)

创建并返回一个 DrawNode （矩形）对象。

格式：

shape = display.newRect(rect表, [参数])

-- 创建一个宽度 200，高度 100 的矩形，并且定位于 50, 80

local shape3 = display.newRect(cc.rect(50, 80, 200, 100))

-- 创建一个宽度 100, 高度 100 的矩形，并定位于 40,40

-- 并设置它的中间填充色 fillColor, 边线色 borderColor 及边线宽度 borderWidth

local shape4 = display.newRect(cc.rect(100, 100, 40, 40),

        {fillColor = cc.c4f(1,0,0,1), borderColor = cc.c4f(0,1,0,1), borderWidth = 5})

Parameters

· table rect table

· table params 有参数，填充色 fillColor, 边线色 borderColor 及边线宽度 borderWidth

Returns

· DrawNode

@see ShapeNode

display.newLine()

display.newLine(points, params)

创建并返回一个 DrawNode （线性）对象。

格式：

shape = display.newLine(point表, [参数])

-- 创建一个线宽为2，颜色为红色，从(10,10)到(100,100)的线段

local shape3 = display.newLine({(10, 10), (100,100)},

    {borderColor = cc.c4f(1.0, 0.0, 0.0, 1.0),

    borderWidth = 1})

Parameters

· table point table

· table params 有参数，边线色 borderColor 及边线宽度 borderWidth

Returns

· DrawNode

@see ShapeNode

display.newPolygon()

display.newPolygon(points, params, drawNode)

创建并返回一个 PolygonShape （多边形）对象。

local points = {

    {10, 10},  -- point 1

    {50, 50},  -- point 2

    {100, 10}, -- point 3

local polygon = display.newPolygon(points)

Parameters

· table points 包含多边形每一个点坐标的表格对象

· number scale 缩放比例

Returns

· DrawNode DrawNode

@see DrawNode

display.newBMFontLabel()

display.newBMFontLabel(params)

用位图字体创建文本显示对象，并返回 Label 对象。

BMFont 通常用于显示英文内容，因为英文字母加数字和常用符号也不多，生成的BMFont 文件较小。如果是中文，应该用 TTFLabel。

可用参数：

· text: 要显示的文本

· font: 字体文件名

· align: 文字的水平对齐方式（可选）

· maxLineWidth: 最大行宽（可选）

· offsetX: 图像的X偏移量（可选）

· offsetY: 图像的Y偏移量（可选）

· x, y: 坐标（可选）

local label = display.newBMFontLabel({

    text = "Hello",

    font = "UIFont.fnt",

})

Parameters

· table params 参数表格对象

Returns

· Label Label对象

display.newTTFLabel()

display.newTTFLabel(params)

使用 TTF 字体创建文字显示对象，并返回 Label 对象。

可用参数：

· text: 要显示的文本

· font: 字体名，如果是非系统自带的 TTF 字体，那么指定为字体文件名

· size: 文字尺寸，因为是 TTF 字体，所以可以任意指定尺寸

· color: 文字颜色（可选），用 cc.c3b() 指定，默认为白色

· align: 文字的水平对齐方式（可选）

· valign: 文字的垂直对齐方式（可选），仅在指定了 dimensions 参数时有效

· dimensions: 文字显示对象的尺寸（可选），使用 cc.size() 指定

· x, y: 坐标（可选）

align 和 valign 参数可用的值：

· cc.TEXT_ALIGNMENT_LEFT 左对齐

· cc.TEXT_ALIGNMENT_CENTER 水平居中对齐

· cc.TEXT_ALIGNMENT_RIGHT 右对齐

· cc.VERTICAL_TEXT_ALIGNMENT_TOP垂直顶部对齐

· cc.VERTICAL_TEXT_ALIGNMENT_CENTER垂直居中对齐

· cc.VERTICAL_TEXT_ALIGNMENT_BOTTOM垂直底部对齐

-- 创建一个居中对齐的文字显示对象

local label = display.newTTFLabel({

    text = "Hello, World",

    font = "Marker Felt",

    size = 64,

    align = cc.TEXT_ALIGNMENT_CENTER -- 文字内部居中对齐

})

-- 左对齐，并且多行文字顶部对齐

local label = display.newTTFLabel({

    text = "Hello, World\n您好，世界",

    font = "Arial",

    size = 64,

    color = cc.c3b(255, 0, 0), -- 使用纯红色

    align = cc.TEXT_ALIGNMENT_LEFT,

    valign = cc.VERTICAL_TEXT_ALIGNMENT_TOP,

    dimensions = cc.size(400, 200)

})

Parameters

· table params 参数表格对象

Returns

· UILabel UILabel对象

display.align()

display.align(target, anchorPoint, x, y)

将指定的显示对象按照特定锚点对齐。

格式：

display.align(显示对象, 锚点位置, [x, y])

显示对象锚点位置：

· display.CENTER 图像中央

· display.LEFT_TOP,

· display.TOP_LEFT 图像左上角

· display.CENTER_TOP,

· display.TOP_CENTER 图像顶部的中间

· display.RIGHT_TOP,

· display.TOP_RIGHT 图像顶部的中间

· display.CENTER_LEFT,

· display.LEFT_CENTER 图像左边的中间

· display.CENTER_RIGHT,

· display.RIGHT_CENTER 图像右边的中间

· display.BOTTOM_LEFT,

· display.LEFT_BOTTOM 图像左边的底部

· display.BOTTOM_RIGHT,

· display.RIGHT_BOTTOM 图像右边的底部

· display.BOTTOM_CENTER,

· display.CENTER_BOTTOM 图像中间的底部

-- 将图像按左上角对齐，并放置在屏幕左上角

display.align(sprite, display.LEFT_TOP, 0, 0)

Parameters

· Sprite target 显示对象

· integer anchorPoint 锚点位置

· integer x

· integer y

display.addSpriteFrames()

display.addSpriteFrames(plistFilename, image, handler)

将指定的 Sprite Sheets 材质文件及其数据文件载入图像帧缓存。

格式：

display.addSpriteFrames(数据文件名, 材质文件名)

-- 同步加载纹理

display.addSpriteFrames("Sprites.plist", "Sprites.png")

-- 异步加载纹理

local cb = function(plist, image)

    -- do something

end

display.addSpriteFrames("Sprites.plist", "Sprites.png", cb)

Sprite Sheets 通俗一点解释就是包含多张图片的集合。Sprite Sheets 材质文件由多张图片组成，而数据文件则记录了图片在材质文件中的位置等信息。

Parameters

· string plistFilename 数据文件名

· string image 材质文件名

@see Sprite Sheets

display.removeSpriteFramesWithFile()

display.removeSpriteFramesWithFile(plistFilename, imageName)

从内存中卸载 Sprite Sheets 材质和数据文件

Parameters

· string plistFilename 数据文件名

· string image 材质文件名

display.setTexturePixelFormat()

display.setTexturePixelFormat(filename, format)

设置材质格式。

为了节约内存，我们会使用一些颜色品质较低的材质格式，例如针对背景图使用 cc.TEXTURE2_D_PIXEL_FORMAT_RG_B565 格式。

display.setTexturePixelFormat() 可以指定材质文件的材质格式，这样在加载材质文件时就会使用指定的格式。

Parameters

· string filename 材质文件名

· integer format 材质格式

@see Texture Pixel Format

display.removeSpriteFrameByImageName()

display.removeSpriteFrameByImageName(imageName)

从图像帧缓存中删除一个图像。

有时候，某些图像仅在特定场景中使用，例如背景图。那么在场景退出时，就可以用 display.removeSpriteFrameByImageName() 从缓存里删除不再使用的图像数据。

此外，Scene 提供了 markAutoCleanupImage() 接口，可以指定场景退出时需要自动清理的图像，推荐使用。

Parameters

· string imageName 图像文件名

display.newBatchNode()

display.newBatchNode(image, capacity)

从指定的图像文件创建并返回一个批量渲染对象。

local imageName = "Sprites.png"

display.addSpriteFrames("Sprites.plist", imageName) -- 载入图像到帧缓存

-- 下面的代码绘制 100 个图像只用了 1 次 OpenGL draw call

local batch = display.newBatch(imageName)

for i = 1, 100 do

    local sprite = display.newSprite("#Sprite0001.png")

    batch:addChild(sprite)

end

-- 下面的代码绘制 100 个图像则要使用 100 次 OpenGL draw call

local group = display.newNode()

for i = 1, 100 do

    local sprite = display.newSprite("#Sprite0001.png")

    group:addChild(sprite)

end

Parameters

· string image 图像文件名

· integer capacity

Returns

· SpriteBatchNode

@see Batch Node

display.newSpriteFrame()

display.newSpriteFrame(frameName)

创建并返回一个图像帧对象。

display.addSpriteFrames("Sprites.plist", "Sprites.png")

-- 创建一个 Sprite

local sprite = display.newSprite("#Yes.png")

-- 创建一个图像帧

local frameNo = display.newSpriteFrame("No.png")

-- 在需要时，修改 Sprite 的显示内容

sprite:setSpriteFrame(frameNo)

Parameters

· string 图像帧名称

Returns

· SpriteFrameCache

display.newFrames()

display.newFrames(pattern, begin, length, isReversed)

以特定模式创建一个包含多个图像帧对象的数组。

-- 创建一个数组，包含 Walk0001.png 到 Walk0008.png 的 8 个图像帧对象

local frames = display.newFrames("Walk%04d.png", 1, 8)

-- 创建一个数组，包含 Walk0008.png 到 Walk0001.png 的 8 个图像帧对象

local frames = display.newFrames("Walk%04d.png", 1, 8, true)

Parameters

· string pattern 模式字符串

· integer begin 起始索引

· integer length 长度

· boolean isReversed 是否是递减索引

Returns

· table 图像帧数组

display.newAnimation()

display.newAnimation(frames, time)

以包含图像帧的数组创建一个动画对象。

local frames = display.newFrames("Walk%04d.png", 1, 8)

local animation = display.newAnimation(frames, 0.5 / 8) -- 0.5 秒播放 8 桢

sprite:playAnimationOnce(animation) -- 播放一次动画

Parameters

· table frames 图像帧的数组

· number time 每一桢动画之间的间隔时间

Returns

· Animation Animation对象

display.setAnimationCache()

display.setAnimationCache(name, animation)

以指定名字缓存创建好的动画对象，以便后续反复使用。

local frames = display.newFrames("Walk%04d.png", 1, 8)

local animation = display.newAnimation(frames, 0.5 / 8) -- 0.5 秒播放 8 桢

display.setAnimationCache("Walk", animation)

-- 在需要使用 Walk 动画的地方

sprite:playAnimationOnce(display.getAnimationCache("Walk")) -- 播放一次动画

Parameters

· string name 名字

· Animation animation 动画对象

display.getAnimationCache()

display.getAnimationCache(name)

取得以指定名字缓存的动画对象，如果不存在则返回 nil。

Parameters

· string name

Returns

· Animation

display.removeAnimationCache()

display.removeAnimationCache(name)

删除指定名字缓存的动画对象。

Parameters

· string name

display.removeUnusedSpriteFrames()

从内存中卸载没有使用 Sprite Sheets 材质

display.newProgressTimer()

display.newProgressTimer(image, progresssType)

创建一个进度条的节点

进度条类型有:

· display.PROGRESS_TIMER_BAR 环形

· display.PROGRESS_TIMER_RADIAL

Parameters

-

Returns

display.printscreen()

display.printscreen(node, args)

获取一个节点的纹理内容

display.printscreen() 提供:

· 保存节点的纹理到磁盘文件

· 以节点的纹理创建一个精灵并返回

注意：node 的 content size 必须大于 (0, 0). 否则会收到错误信息: LUAERROR: ASSERT FAILED ON LUA EXECUTE: Invalid size

-- 截屏并保存

display.printscreen(node, {file="save.png"})

-- 使用截屏纹理创建一个精灵并返回

local sp = display.printscreen(node, {})

-- Get a screenshot of a Node -- @author zrong(zengrong.net) --Creation: 2014-04-10

Parameters

· node A node to print.

· args

Returns

· An instance of Sprite orFilteredSprite.

8. filter

quick\framework\filter.lua文件

滤镜功能

Functions

filter.newFilter(__filterName, __param)

创建一个滤镜效果，并返回 Filter 场景对象。

filter.newFilters(__filterNames, __params)

创建滤镜数组，并返回 Filter 的数组对象

Functions

filter.newFilter()

filter.newFilter(__filterName, __param)

创建一个滤镜效果，并返回 Filter 场景对象。

Parameters

· string __filterName 滤镜名称

· table __param

Returns

· Filter的子类

filter.newFilters()

filter.newFilters(__filterNames, __params)

创建滤镜数组，并返回 Filter 的数组对象

Parameters

· table __filterNames 滤镜名称数组

· table __params 对应参数数组

Returns

· Filter数组

9. audio

quick\framework\audio.lua文件

播放音乐、音效

Functions

audio.getMusicVolume()

返回音乐的音量值

audio.setMusicVolume(volume)

设置音乐的音量

audio.getSoundsVolume()

返回音效的音量值

audio.setSoundsVolume(volume)

设置音效的音量

audio.preloadMusic(filename)

预载入一个音乐文件

audio.playMusic(filename, isLoop)

播放音乐

audio.stopMusic(isReleaseData)

停止播放音乐

audio.pauseMusic()

暂停音乐的播放

audio.resumeMusic()

恢复暂停的音乐

audio.rewindMusic()

从头开始重新播放当前音乐

audio.willPlayMusic()

检查是否可以开始播放音乐

audio.isMusicPlaying()

检查当前是否正在播放音乐

audio.playSound(filename, isLoop)

播放音效，并返回音效句柄

audio.pauseSound(handle)

暂停指定的音效

audio.pauseAllSounds()

暂停所有音效

audio.resumeSound(handle)

恢复暂停的音效

audio.resumeAllSounds()

恢复所有的音效

audio.stopSound(handle)

停止指定的音效

audio.stopAllSounds()

停止所有音效

audio.preloadSound(filename)

预载入一个音效文件

audio.unloadSound(filename)

从内存卸载一个音效

Functions

audio.getMusicVolume()

返回音乐的音量值

Returns

· number 返回值在 0.0 到 1.0 之间，0.0 表示完全静音，1.0 表示 100% 音量

audio.setMusicVolume()

audio.setMusicVolume(volume)

设置音乐的音量

Parameters

· number volume 音量在 0.0 到 1.0 之间, 0.0 表示完全静音，1.0 表示 100% 音量

audio.getSoundsVolume()

返回音效的音量值

Returns

· number 返回值在 0.0 到 1.0 之间, 0.0 表示完全静音，1.0 表示 100% 音量

audio.setSoundsVolume()

audio.setSoundsVolume(volume)

设置音效的音量

Parameters

· number volume 音量在 0.0 到 1.0 之间, 0.0 表示完全静音，1.0 表示 100% 音量

audio.preloadMusic()

audio.preloadMusic(filename)

预载入一个音乐文件

在播放音乐前预先载入，可以在需要播放音乐时无延迟立即播放。不过限于硬件设备和操作系统的限制，通常只能预载入一个音乐文件。

Parameters

· string filename 音乐文件名

audio.playMusic()

audio.playMusic(filename, isLoop)

播放音乐

如果音乐文件尚未载入，则会首先载入音乐文件，然后开始播放。

注意：即便音乐音量为 0.0，audio.playMusic() 仍然会进行播放操作。如果希望停止音乐来降低 CPU 占用，应该使用 audio.stopMusic() 接口完全停止音乐播放。

Parameters

· string filename 音乐文件名

· boolean isLoop 是否循环播放，默认为 true

audio.stopMusic()

audio.stopMusic(isReleaseData)

停止播放音乐

Parameters

· boolean isReleaseData 是否释放音乐数据，默认为 true

audio.pauseMusic()

暂停音乐的播放

audio.resumeMusic()

恢复暂停的音乐

audio.rewindMusic()

从头开始重新播放当前音乐

audio.willPlayMusic()

检查是否可以开始播放音乐

如果可以则返回 true。

如果尚未载入音乐，或者载入的音乐格式不被设备所支持，该方法将返回 false。

Returns

· boolean

audio.isMusicPlaying()

检查当前是否正在播放音乐

如果有音乐正在播放则返回 true，否则返回 false

Returns

· boolean

audio.playSound()

audio.playSound(filename, isLoop)

播放音效，并返回音效句柄

如果音效尚未载入，则会载入后开始播放。

该方法返回的音效句柄用于 audio.stopSound()、audio.pauseSound() 等方法。

Parameters

· string filename 音效文件名

· boolean isLoop 是否重复播放，默认为 false

Returns

· integer 音效句柄

audio.pauseSound()

audio.pauseSound(handle)

暂停指定的音效

Parameters

· integer 音效句柄

audio.pauseAllSounds()

暂停所有音效

audio.resumeSound()

audio.resumeSound(handle)

恢复暂停的音效

Parameters

· integer 音效句柄

audio.resumeAllSounds()

恢复所有的音效

audio.stopSound()

audio.stopSound(handle)

停止指定的音效

Parameters

· integer 音效句柄

audio.stopAllSounds()

停止所有音效

audio.preloadSound()

audio.preloadSound(filename)

预载入一个音效文件

可以在进入场景前，载入该场景需要的所有音效。这样就不会因为首次播放某个未载入的音效，而导致游戏暂停执行。

Parameters

· string 音效文件名

audio.unloadSound()

audio.unloadSound(filename)

从内存卸载一个音效

退出场景时，可以卸载掉只有该场景使用的音效，从而节约内存。

Parameters

· string 音效文件名

10. network

quick\framework\network.lua文件

网络服务

Functions

network.isLocalWiFiAvailable()

检查地 WIFI 网络是否可用

network.isInternetConnectionAvailable()

检查互联网连接是否可用

network.isHostNameReachable(hostname)

检查是否可以解析指定的主机名

network.getInternetConnectionStatus()

返回互联网连接状态值

network.createHTTPRequest(callback, url, method)

创建异步 HTTP 请求，并返回 cc.HTTPRequest 对象。

Functions

network.isLocalWiFiAvailable()

检查地 WIFI 网络是否可用

提示： WIFI 网络可用不代表可以访问互联网。

Returns

· boolean 网络是否可用

network.isInternetConnectionAvailable()

检查互联网连接是否可用

通常，这里接口返回 3G 网络的状态，具体情况与设备和操作系统有关。

Returns

· boolean 网络是否可用

network.isHostNameReachable()

network.isHostNameReachable(hostname)

检查是否可以解析指定的主机名

if network.isHostNameReachable("www.google.com") then

    -- 域名可以解析

end

注意：该接口会阻塞程序，因此在调用该接口时应该提醒用户应用程序在一段时间内会失去响应。

Returns

· boolean 主机名是否可以解析

network.getInternetConnectionStatus()

返回互联网连接状态值

状态值有三种：

· kCCNetworkStatusNotReachable:无法访问互联网

· kCCNetworkStatusReachableViaWiFi:通过 WIFI

· kCCNetworkStatusReachableViaWWAN:通过 3G 网络

Returns

· string 互联网连接状态值

network.createHTTPRequest()

network.createHTTPRequest(callback, url, method)

创建异步 HTTP 请求，并返回 cc.HTTPRequest 对象。

function onRequestFinished(event)

    local ok = (event.name == "completed")

    local request = event.request

    if not ok then

        -- 请求失败，显示错误代码和错误消息

        print(request:getErrorCode(), request:getErrorMessage())

        return

end

    local code = request:getResponseStatusCode()

    if code ~= 200 then

        -- 请求结束，但没有返回 200 响应代码

        print(code)

        return

end

    -- 请求成功，显示服务端返回的内容

    local response = request:getResponseString()

    print(response)

end

-- 创建一个请求，并以 POST 方式发送数据到服务端

local url = "http://www.mycompany.com/request.php"

local request = network.createHTTPRequest(onRequestFinished, url, "POST")

request:addPOSTValue("KEY", "VALUE")

-- 开始请求。当请求完成时会调用 callback() 函数

request:start()

Returns

· HTTPRequest 结果

11. crypto

quick\framework\crypto.lua文件

加解密、数据编码

Functions

crypto.encryptAES256(plaintext, key)

使用 AES256 算法加密内容

crypto.decryptAES256(ciphertext, key)

使用 AES256 算法解密内容

crypto.encryptXXTEA(plaintext, key)

使用 XXTEA 算法加密内容

crypto.decryptXXTEA(ciphertext, key)

使用 XXTEA 算法解密内容

crypto.encodeBase64(plaintext)

使用 BASE64 算法编码内容

crypto.decodeBase64(ciphertext)

使用 BASE64 算法解码内容

crypto.md5(input, isRawOutput)

计算内容的 MD5 码

crypto.md5file(path)

计算文件的 MD5 码

Functions

crypto.encryptAES256()

crypto.encryptAES256(plaintext, key)

使用 AES256 算法加密内容

提示：AES256 仅在 iOS 和 Mac 平台可用。加解密尽量选择跨平台的 XXTEA 接口。

Parameters

· string plaintext 明文字符串

· string key 密钥字符串

Returns

· string 加密后的字符串

crypto.decryptAES256()

crypto.decryptAES256(ciphertext, key)

使用 AES256 算法解密内容

提示： AES256 仅在 iOS 和 Mac 平台可用。加解密尽量选择跨平台的 XXTEA 接口。

Parameters

· string ciphertext 加密后的字符串

· string key 密钥字符串

Returns

· string 明文字符串

crypto.encryptXXTEA()

crypto.encryptXXTEA(plaintext, key)

使用 XXTEA 算法加密内容

Parameters

· string plaintext 明文字符串

· string key 密钥字符串

Returns

· string 加密后的字符串

crypto.decryptXXTEA()

crypto.decryptXXTEA(ciphertext, key)

使用 XXTEA 算法解密内容

Parameters

· string ciphertext 加密后的字符串

· string key 密钥字符串

Returns

· string 明文字符串

crypto.encodeBase64()

crypto.encodeBase64(plaintext)

使用 BASE64 算法编码内容

Parameters

· string plaintext 原文字符串

Returns

· string 编码后的字符串

crypto.decodeBase64()

crypto.decodeBase64(ciphertext)

使用 BASE64 算法解码内容

Parameters

· string ciphertext 编码后的字符串

Returns

· string 原文字符串

crypto.md5()

crypto.md5(input, isRawOutput)

计算内容的 MD5 码

Parameters

· string input 内容字符串

· boolean isRawOutput 是否返回二进制 MD5 码

Returns

· string MD5 字符串

crypto.md5file()

crypto.md5file(path)

计算文件的 MD5 码

Parameters

· string path 文件路径

Returns

· string MD5 字符串

12. json

quick\framework\json.lua文件

Functions

safeLoad()

JSON 编码与解码

json.encode(var)

将表格数据编码为 JSON 字符串

json.decode(text)

将 JSON 字符串解码为表格对象

Functions

safeLoad()

JSON 编码与解码

json.encode()

json.encode(var)

将表格数据编码为 JSON 字符串

local str = json.encode({a=1,b="ss",c={c1=1,c2=2},d={10,11},100})

echo(str) -- {"a":1,"b":"ss","c":{"c1":1,"c2":2},"d":[10,11],"1":100}

local str = json.encode({1,2,"3",{10,11}})

echo(str) -- [ 1,2,"3",[10,11] ]

注意: table作为字典使用时，整型键值将被转换为字符串键值

local str = json.encode({a=1,[5]=3})

echo(str) -- {"a":1,"5":3}

注意: table所有键值为整型时，会当作数组看待，空位将转化为null

local str = json.encode({[3]=2,[5]=3})

echo(str) -- [null,null,2,null,3]

Parameters

· table 表格对象

Returns

· string json字符串

json.decode()

json.decode(text)

将 JSON字符串解码为表格对象

local json = require("framework.shared.json")

local tb = json.decode('{"a":1,"b":"ss","c":{"c1":1,"c2":2},"d":[10,11],"1":100}')

dump(tb) --[ [

- "" = {

-     "1" = 100

-     "a" = 1

-     "b" = "ss"

-     "c" = {

-         "c1" = 1

-         "c2" = 2

-     }

-     "d" = {

-         1 = 10

-         2 = 11

-     }

- }

] ]

local tb = json.decode('[1,2,"3",[10,11] ]')

dump(tb) --[ [

- "" = {

-     1 = 1

-     2 = 2

-     3 = "3"

-     4 = {

-         1 = 10

-         2 = 11

-     }

- }

] ]

Parameters

· string json字符串

Returns

· table 表格对象

13. luaj

quick\framework\luaj.lua文件

Lua 与 Java的交互接口

Functions

checkArguments(args, sig)

私有方法

luaj.callStaticMethod(className, methodName, args, sig)

调用java类的接口。

Functions

checkArguments()

checkArguments(args, sig)

私有方法

luaj.callStaticMethod()

luaj.callStaticMethod(className, methodName, args, sig)

调用java类的接口。

只能调用java类的静态方法

Parameters

· string className java类名

· string methodName java类静态方法名

· table args java类静态方法所需要的各种参数数组

· [string sig] java类方法的签名

Returns

· boolean ok, mixed ret ok为是否调用成功, ok为true时,ret为java方法的返回值,ok为false时,ret为出错原因

14. luaoc

quick\framework\luaoc.lua文件

Lua 与Objective-C 的交互接口

Functions

luaoc.callStaticMethod(className, methodName, args)

调用Objective-C类的接口。

Functions

luaoc.callStaticMethod()

luaoc.callStaticMethod(className, methodName, args)

调用Objective-C类的接口。

只能调用Objective-C类的类方法

Parameters

· string className Objective-C类名

· string methodName Objective-C类方法名

· table args Objective-C类方法所需要的各种参数字典,key值为方法的参数名

Returns

· boolean ok, mixed ret ok为是否调用成功, ok为true时,ret为Objective-C方法的返回值,ok为false时,ret为出错原因

15. ui

quick\framework\ui.lua文件

创建和管理用户界面

Functions

ui.newEditBox(params)

创建一个文字输入框，并返回 EditBox 对象。

ui.newBMFontLabel(params)

用位图字体创建文本显示对象，并返回 LabelBMFont 对象。

ui.newTTFLabel(params)

使用 TTF 字体创建文字显示对象，并返回 LabelTTF 对象。

ui.newTTFLabelWithShadow(params)

创建带阴影的 TTF 文字显示对象，并返回 LabelTTF 对象。

ui.newTTFLabelWithOutline(params)

创建带描边效果的 TTF 文字显示对象，并返回 LabelTTF 对象。

Functions

ui.newEditBox()

ui.newEditBox(params)

创建一个文字输入框，并返回 EditBox 对象。

可用参数：

· image: 输入框的图像，可以是图像名或者是 Sprite9Scale 显示对象。用 display.newScale9Sprite() 创建 Sprite9Scale 显示对象。

· imagePressed: 输入状态时输入框显示的图像（可选）

· imageDisabled: 禁止状态时输入框显示的图像（可选）

· listener: 回调函数

· size: 输入框的尺寸，用 cc.size(宽度, 高度) 创建

· x, y: 坐标（可选）

local function onEdit(event, editbox)

    if event == "began" then

        -- 开始输入

    elseif event == "changed" then

        -- 输入框内容发生变化

    elseif event == "ended" then

        -- 输入结束

    elseif event == "return" then

        -- 从输入框返回

end

end

local editbox = ui.newEditBox({

    image = "EditBox.png",

    listener = onEdit,

    size = cc.size(200, 40)

})

注意: 使用setInputFlag(0) 可设为密码输入框。

注意：构造输入框时，请使用setPlaceHolder来设定初始文本显示。setText为出现输入法后的默认文本。

注意：事件触发机制，player模拟器上与真机不同，请使用真机实测(不同ios版本貌似也略有不同)。

注意：changed事件中，需要条件性使用setText（如trim或转化大小写等），否则在某些ios版本中会造成死循环。

--错误，会造成死循环

editbox:setText(string.trim(editbox:getText()))

--正确，不会造成死循环

local _text = editbox:getText()

local _trimed = string.trim(_text)

if _trimed ~= _text then

    editbox:setText(_trimed)

end

Parameters

· table params 参数表格对象

Returns

· EditBox 文字输入框

ui.newBMFontLabel()

ui.newBMFontLabel(params)

用位图字体创建文本显示对象，并返回 LabelBMFont 对象。

BMFont 通常用于显示英文内容，因为英文字母加数字和常用符号也不多，生成的BMFont 文件较小。如果是中文，应该用 TTFLabel。

可用参数：

· text: 要显示的文本

· font: 字体文件名

· align: 文字的水平对齐方式（可选）

· x, y: 坐标（可选）

local label = ui.newBMFontLabel({

    text = "Hello",

    font = "UIFont.fnt",

})

Parameters

· table params 参数表格对象

Returns

· LabelBMFont LabelBMFont对象

ui.newTTFLabel()

ui.newTTFLabel(params)

使用 TTF 字体创建文字显示对象，并返回 LabelTTF 对象。

可用参数：

· text: 要显示的文本

· font: 字体名，如果是非系统自带的 TTF 字体，那么指定为字体文件名

· size: 文字尺寸，因为是 TTF 字体，所以可以任意指定尺寸

· color: 文字颜色（可选），用 cc.c3b() 指定，默认为白色

· align: 文字的水平对齐方式（可选）

· valign: 文字的垂直对齐方式（可选），仅在指定了 dimensions 参数时有效

· dimensions: 文字显示对象的尺寸（可选），使用 cc.size() 指定

· x, y: 坐标（可选）

align 和 valign 参数可用的值：

· ui.TEXT_ALIGN_LEFT 左对齐

· ui.TEXT_ALIGN_CENTER 水平居中对齐

· ui.TEXT_ALIGN_RIGHT 右对齐

· ui.TEXT_VALIGN_TOP 垂直顶部对齐

· ui.TEXT_VALIGN_CENTER 垂直居中对齐

· ui.TEXT_VALIGN_BOTTOM 垂直底部对齐

-- 创建一个居中对齐的文字显示对象

local label = ui.newTTFLabel({

    text = "Hello, World",

    font = "Marker Felt",

    size = 64,

    align = ui.TEXT_ALIGN_CENTER -- 文字内部居中对齐

})

-- 左对齐，并且多行文字顶部对齐

local label = ui.newTTFLabel({

    text = "Hello, World\n您好，世界",

    font = "Arial",

    size = 64,

    color = cc.c3b(255, 0, 0), -- 使用纯红色

    align = ui.TEXT_ALIGN_LEFT,

    valign = ui.TEXT_VALIGN_TOP,

    dimensions = cc.size(400, 200)

})

Parameters

· table params 参数表格对象

Returns

· LabelTTF LabelTTF对象

ui.newTTFLabelWithShadow()

ui.newTTFLabelWithShadow(params)

创建带阴影的 TTF 文字显示对象，并返回 LabelTTF 对象。

相比 ui.newTTFLabel() 增加一个参数：

· shadowColor: 阴影颜色（可选），用 cc.c4b() 指定，默认为黑色

Parameters

· table params 参数表格对象

Returns

· LabelTTF LabelTTF对象

ui.newTTFLabelWithOutline()

ui.newTTFLabelWithOutline(params)

创建带描边效果的 TTF 文字显示对象，并返回 LabelTTF 对象。

相比 ui.newTTFLabel() 增加一个参数：

outlineColor: 描边颜色（可选），用 cc.c4b() 指定，默认为黑色

Parameters

· table params 参数表格对象

Returns

· LabelTTF LabelTTF对象

16. Shortcodes

quick\framework\shortcodes.lua文件

Functions

- Node:add(child, zorder, tag)

在当前结点中加入一个子结点

- Node:addTo(target, zorder, tag)

把当前结点作为一个子结点加到target中

- Node:show()

显示当前结点,让当前结点可显示

- Node:hide()

隐藏当前结点,让当前结点不可显示

- Node:pos(x, y)

设置当前结点的位置

- Node:center()

设置当前结点的锚点在它的中心

- Node:scale(scale)

设置当前结点的缩放值

- Node:rotation(r)

设置当前结点的旋转角度值

- Node:size(width, height)

设置当前结点的大小

- Node:opacity(opacity)

设置当前结点的透明度, 0到255,0为完全透明

- Node:zorder(z)

设置当前结点z值

- Sprite:displayFrame(frame)

设置当前精灵的显示帧

- Sprite:flipX(b)

在X方向上翻转当前精灵

- Sprite:flipY(b)

在Y方向上翻转当前精灵

- Layer:onTouch(listener)

在层上注册触摸监听

- Layer:enableTouch(enabled)

设置层的触摸是否打开

- Layer:onKeypad(listener)

在层上注册键盘监听

- Layer:enableKeypad(enabled)

设置层的键盘事件是否打开

- Layer:onAccelerate(listener)

在层上注册重力感应监听

- Layer:enableAccelerometer(enabled)

设置层的重力感应事件是否打开

- Node:stop()

停止结点的所有动作

- Node:fadeIn(time)

渐显动画

- Node:fadeOut(time)

渐隐动画

- Node:fadeTo(time, opacity)

渐变到一个固定透明度

- Node:moveTo(time, x, y)

在一段时间内移动结点到特定位置

- Node:moveBy(time, x, y)

在一段时间内移动相对位置

- Node:rotateTo(time, rotation)

在一段时间内旋转的角度

- Node:rotateBy(time, rotation)

在一段时间内旋转的相对角度

- Node:scaleTo(time, scale)

在一段时间内缩放

- Node:scaleBy(time, scale)

在一段时间内的相对缩放

- Node:skewTo(time, sx, sy)

在一段时间内倾斜的大小

- Node:skewBy(time, sx, sy)

在一段时间内倾斜的相对大小

- Node:tintTo(time, r, g, b)

在一段时间内染色

- Node:tintBy(time, r, g, b)

在一段时间内相对染色

Functions

Node:add()

Node:add(child, zorder, tag)

在当前结点中加入一个子结点

Parameters

· node child 要加入的结点

· number zorder 要加入结点的Z值

· number tag 要加入结点的tag

Returns

· node 当前结点

Node:addTo()

Node:addTo(target, zorder, tag)

把当前结点作为一个子结点加到target中

Parameters

· node target 想作为其子结点的结点

· number zorder 当前结点的Z值

· number tag 当前结点的tag

Returns

· node 当前结点

Node:show()

显示当前结点,让当前结点可显示

Returns

· node 当前结点

Node:hide()

隐藏当前结点,让当前结点不可显示

Returns

· node 当前结点

Node:pos()

Node:pos(x, y)

设置当前结点的位置

Parameters

· number x X值

· number y Y值

Returns

· node 当前结点

Node:center()

设置当前结点的锚点在它的中心

Returns

· node 当前结点

Node:scale()

Node:scale(scale)

设置当前结点的缩放值

Parameters

· number scale 要缩放的值

Returns

· node 当前结点

Node:rotation()

Node:rotation(r)

设置当前结点的旋转角度值

Parameters

· number r 旋转角度

Returns

· node 当前结点

Node:size()

Node:size(width, height)

设置当前结点的大小

Parameters

· mixed width 宽度或cc.size表

· number height 高度

Returns

· node 当前结点

Node:opacity()

Node:opacity(opacity)

设置当前结点的透明度, 0到255,0为完全透明

Parameters

· number opacity 透明度

Returns

· node 当前结点

Node:zorder()

Node:zorder(z)

设置当前结点z值

Parameters

· number z z值

Returns

· node 当前结点

Sprite:displayFrame()

Sprite:displayFrame(frame)

设置当前精灵的显示帧

Parameters

· mixed frame 要显示的图片名或图片帧的frame

Returns

· Sprite 当前精灵

Sprite:flipX()

Sprite:flipX(b)

在X方向上翻转当前精灵

Parameters

· boolean b 是否翻转

Returns

· Sprite 当前精灵

Sprite:flipY()

Sprite:flipY(b)

在Y方向上翻转当前精灵

Parameters

· boolean b 是否翻转

Returns

· Sprite 当前精灵

Layer:onTouch()

Layer:onTouch(listener)

在层上注册触摸监听

Parameters

· function listener 监听函数

Returns

· Layer 当前层

Layer:enableTouch()

Layer:enableTouch(enabled)

设置层的触摸是否打开

Parameters

· boolean enabled 是否打开触摸

Returns

· Layer 当前层

Layer:onKeypad()

Layer:onKeypad(listener)

在层上注册键盘监听

Parameters

· function listener 监听函数

Returns

· Layer 当前层

Layer:enableKeypad()

Layer:enableKeypad(enabled)

设置层的键盘事件是否打开

Parameters

· boolean enabled 是否打开键盘事件

Returns

· Layer 当前层

Layer:onAccelerate()

Layer:onAccelerate(listener)

在层上注册重力感应监听

Parameters

· function listener 监听函数

Returns

· Layer 当前层

Layer:enableAccelerometer()

Layer:enableAccelerometer(enabled)

设置层的重力感应事件是否打开

Parameters

· boolean enabled 是否打开加速度事件

Returns

· Layer 当前层

Node:stop()

停止结点的所有动作

Returns

· node 当前结点

Node:fadeIn()

Node:fadeIn(time)

渐显动画

Parameters

· number time 渐显时间

Returns

· node 当前结点

Node:fadeOut()

Node:fadeOut(time)

渐隐动画

Parameters

· number time 渐隐时间

Returns

· node 当前结点

Node:fadeTo()

Node:fadeTo(time, opacity)

渐变到一个固定透明度

Parameters

· number time 渐变时间

· number opacity 最终的透明度

Returns

· node 当前结点

Node:moveTo()

Node:moveTo(time, x, y)

在一段时间内移动结点到特定位置

Parameters

· number time 移动时间

· number x 要移动到的X点

· number y 要移动到的Y点

Returns

· node 当前结点

Node:moveBy()

Node:moveBy(time, x, y)

在一段时间内移动相对位置

Parameters

· number time 移动时间

· number x 要移动的相对X值

· number y 要移动的相对Y值

Returns

· node 当前结点

Node:rotateTo()

Node:rotateTo(time, rotation)

在一段时间内旋转的角度

Parameters

· number time 移动时间

· number rotation 旋转的角度

Returns

· node 当前结点

Node:rotateBy()

Node:rotateBy(time, rotation)

在一段时间内旋转的相对角度

Parameters

· number time 移动时间

· number rotation 旋转的相对角度

Returns

· node 当前结点

Node:scaleTo()

Node:scaleTo(time, scale)

在一段时间内缩放

Parameters

· number time 移动时间

· number scale 缩放的值

Returns

· node 当前结点

Node:scaleBy()

Node:scaleBy(time, scale)

在一段时间内的相对缩放

Parameters

· number time 移动时间

· number scale 相对缩放的值

Returns

· node 当前结点

Node:skewTo()

Node:skewTo(time, sx, sy)

在一段时间内倾斜的大小

Parameters

· number time 移动时间

· number sx 倾斜的X值

· number sy 倾斜的Y值

Returns

· node 当前结点

Node:skewBy()

Node:skewBy(time, sx, sy)

在一段时间内倾斜的相对大小

Parameters

· number time 移动时间

· number sx 倾斜的相对X值

· number sy 倾斜的相对Y值

Returns

· node 当前结点

Node:tintTo()

Node:tintTo(time, r, g, b)

在一段时间内染色

Parameters

· number time 移动时间

· number r 染色的R值

· number g 染色的G值

· number b 染色的B值

Returns

· node 当前结点

Node:tintBy()

Node:tintBy(time, r, g, b)

在一段时间内相对染色

Parameters

· number time 移动时间

· number r 染色的相对R值

· number g 染色的相对G值

· number b 染色的相对B值

Returns

· node 当前结点

17. scheduler

quick\framework\scheduler.lua文件

--[[--

全局计时器、计划任务

«该模块在框架初始化时不会自动载入»

加载方式: local scheduler =require(cc.PACKAGE_NAME .. ".scheduler")

]]

全局计时器、计划任务

«该模块在框架初始化时不会自动载入»

加载方式: local scheduler =require(cc.PACKAGE_NAME .. ".scheduler")

Functions

scheduler.scheduleUpdateGlobal(listener)

计划一个全局帧事件回调，并返回该计划的句柄。

scheduler.scheduleGlobal(listener, interval)

计划一个以指定时间间隔执行的全局事件回调，并返回该计划的句柄。

scheduler.unscheduleGlobal(handle)

取消一个全局计划

scheduler.performWithDelayGlobal(listener, time)

计划一个全局延时回调，并返回该计划的句柄。

Functions

scheduler.scheduleUpdateGlobal()

scheduler.scheduleUpdateGlobal(listener)

计划一个全局帧事件回调，并返回该计划的句柄。

全局帧事件在任何场景中都会执行，因此可以在整个应用程序范围内实现较为精确的全局计时器。

该函数返回的句柄用作 scheduler.unscheduleGlobal() 的参数，可以取消指定的计划。

Parameters

· function 回调函数

Returns

· mixed schedule句柄

scheduler.scheduleGlobal()

scheduler.scheduleGlobal(listener, interval)

计划一个以指定时间间隔执行的全局事件回调，并返回该计划的句柄。

local function onInterval(dt)

end

-- 每 0.5 秒执行一次 onInterval()

local handle = scheduler.scheduleGlobal(onInterval, 0.5)

Parameters

· function listener 回调函数

· number interval 间隔时间

Returns

· mixed schedule句柄

scheduler.unscheduleGlobal()

scheduler.unscheduleGlobal(handle)

取消一个全局计划

scheduler.unscheduleGlobal() 的参数就是scheduler.scheduleUpdateGlobal() 和 scheduler.scheduleGlobal() 的返回值。

Parameters

· mixed schedule句柄

scheduler.performWithDelayGlobal()

scheduler.performWithDelayGlobal(listener, time)

计划一个全局延时回调，并返回该计划的句柄。

scheduler.performWithDelayGlobal() 会在等待指定时间后执行一次回调函数，然后自动取消该计划。

Parameters

· function listener 回调函数

· number time 延迟时间

Returns

· mixed schedule句柄