quick-x 2.2.1 语法摘记之framework.display(一)

display.newScene

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

从一个场景切换到另一个场景时，会自动调用两个场景对象的 onEnter()、onExit() 等方法。这些方法的调用顺序如下：

• 从 SceneA 切换到 SceneB（使用过渡效果）：
  • SceneA:onExitTransitionStart()
  • SceneB:onEnter()
  • SceneB:onEnterTransitionFinish()
  • SceneA:onExit()
  • SceneA:onCleanup()

markAutoCleanupImage

添加需要在场景退出时自动卸载的图像。

格式：

scene:markAutoCleanupImage(图像文件名)

如果一个图像文件仅在当前场景中使用，那就应该用 markAutoCleanupImage() 方法将该文件标记为自动清理。这样在场景退出时，quick 会从缓存里删除标记为自动清理的图像数据。

display.wrapSceneWithTransition

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

格式：

transition = display.wrapSceneWithTransition(scene, 过渡效果名, 过渡时间, [过渡效果附加参数])

用法示例：

-- 创建一个新场景
local nextScene = display.newScene("NextScene")
-- 包装过渡效果
local transition = display.wrapSceneWithTransition(nextScene, "fade", 0.5)
-- 切换到新场景
display.replaceScene(nextScene)

可用的过渡效果有：

• crossFade 淡出当前场景的同时淡入下一个场景
• fade 淡出当前场景到指定颜色，默认颜色为 ccc3(0, 0, 0)，可用 wrapSceneWithTransition() 的最后一个参数指定颜色
• fadeBL 从左下角开始淡出场景
• fadeDown 从底部开始淡出场景
• fadeTR 从右上角开始淡出场景
• fadeUp 从顶部开始淡出场景
• flipAngular 当前场景倾斜后翻转成下一个场景，默认从左边开始翻转，可以指定为：
  • kCCTransitionOrientationLeftOver 从左边开始
  • kCCTransitionOrientationRightOver 从右边开始
  • kCCTransitionOrientationUpOver 从顶部开始
  • kCCTransitionOrientationDownOver 从底部开始
• flipX 水平翻转，默认从左往右翻转，可用的附加参数同上
• flipY 垂直翻转，默认从上往下翻转，可用的附加参数同上
• zoomFlipAngular 倾斜翻转的同时放大，可用的附加参数同上
• zoomFlipX 水平翻转的同时放大，可用的附加参数同上
• zoomFlipY 垂直翻转的同时放大，可用的附加参数同上
• jumpZoom 跳跃放大切换场景
• moveInB 新场景从底部进入，现有场景同时从顶部退出
• moveInL 新场景从左侧进入，现有场景同时从右侧退出
• moveInR 新场景从右侧进入，现有场景同时从左侧退出
• moveInT 新场景从顶部进入，现有场景同时从底部退出
• pageTurn 翻页效果，如果指定附加参数为 true，则表示从左侧往右翻页
• rotoZoom 旋转放大切换场景
• shrinkGrow 收缩交叉切换场景
• slideInB 新场景从底部进入，直接覆盖现有场景
• slideInL 新场景从左侧进入，直接覆盖现有场景
• slideInR 新场景从右侧进入，直接覆盖现有场景
• slideInT 新场景从顶部进入，直接覆盖现有场景
• splitCols 分成多列切换入新场景
• splitRows 分成多行切换入新场景，类似百叶窗
• turnOffTiles 当前场景分成多个块，逐渐替换为新场景

display.replaceScene

切换到新场景。

格式：

display.replaceScene(场景对象, [过渡效果名], 过渡时间, [过渡效果附加参数])

用法示例：

-- 使用红色做过渡色
display.replaceScene(nextScene, "fade", 0.5, ccc3(255, 0, 0))

display.getRunningScene

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

格式：

scene = display.getRunningScene()

display.pause

暂停当前场景。

~~

display.resume

恢复当前暂停的场景。

display.newLayer

创建并返回一个 CCLayer 层对象。

格式：

layer = display.newLayer()

CCLayer 对象是一种特殊的显示对象，主要功能是响应触摸事件、重力感应事件，以及 Android 按键事件。

layer:addTouchEventListener(回调函数,
                            [是否是多点触摸],
                            [优先级],
                            [是否吞噬触摸事件])

注销触摸事件回调。

layer:removeTouchEventListener()

设置是否接受触摸事件：

layer:setTouchEnabled(true) -- 是否允许触摸
 
print(layer:isTouchEnabled()) -- 确认是否已经允许触摸

设置触摸模式：

layer:setTouchMode(kCCTouchesAllAtOnce) -- 一次性把所有点的数据传入回调函数
layer:setTouchMode(kCCTouchesOneByOne) -- 多个点分成多次传入，也就是说多点触摸时，回调函数会调用多次
 
print(layer:getTouchMode()) -- 返回多点触摸事件的坐标传递方式

Android 按键事件

注册键盘事件回调函数。

格式：

layer:addKeypadEventListener(回调函数)

用法示例：

local function onKeypad(event)
    if event == "back" then
    elseif event == "menu" then
    end
end
 
layer:addKeypadEventListener(onKeypad)
layer:setKeypadEnabled(true)

~

注销键盘事件：

layer:removeKeypadEventListener()

设置是否允许接受按键事件：

layer:setKeypadEnabled(true) -- 是否允许按键事件
 
print(layer:isKeypadEnabled()) -- 确认是否已经允许按键事件

重力感应事件

注册重力感应事件。

格式：

local function onAccelerate(x, y, z, timestamp)
    -- x, y, z 分别是三个轴的重力值，从 -1.0 到 1.0
    -- timestamp 是发生事件的时间点（秒）
end
 
layer:addAccelerateEventListener(onAccelerate)
layer:setAccelerometerEnabled(true)

~

注销重力感应事件：

layer:removeAccelerateEventListener()

设置是否允许接受重力感应事件：

layer:setAccelerometerEnabled(true) -- 是否允许重力感应事件
 
print(layer:isAccelerometerEnabled()) -- 确认是否已经允许重力感应事件

~

设置重力感应事件的时间间隔：

layer:setAccelerometerInterval(1.0 / 30) -- 每秒接收 30 次事件

注意： 间隔时间越短，重力感应越敏感，但也会消耗更多电力。如果没有特别需求，建议不要修改默认值。

CCNode

CCNode 对象是所有显示对象的基础类。

主要功能：

• 提供所有类型显示对象公用的属性，例如位置、尺寸、角度、显示层级等
• 作为其他显示对象的容器
• 可以执行各种动作

内容尺寸

如果是 CCSprite 这样的显示对象，其内容尺寸就是图片的尺寸。而其他类型的内容尺寸默认都是 (0,0)，并且不包含子对象。

local size = node:getContentSize()
print(size.width, size.height)

如果有需要，也可以明确指定一个内容尺寸：

-- 设置内容尺寸为 200 个点宽，100 个点高
node:setContentSize(CCSize(200, 100))

内容尺寸不考虑对象的位置、缩放、旋转等属性。

-- 设置锚点
node:setAnchorPoint(CCPoint(0, 0))

CCNode 提供了 getBoundingBox() 方法，用于取得一个显示对象的位置和尺寸信息。

local rect = node:getBoundingBox()
 
print(rect.origin.x, rect.origin.y) -- 输出对象的左下角坐标（计算了锚点）
print(rect.size.width, rect.size.height) -- 输出对象的宽度和高度（ContentSize）

显示层级

当多个显示对象属于同一个父对象时，它们之间的显示层级决定了画面上的互相遮盖关系。

在 quick 中，设置显示层次有两种途径：ZOrder 和 OpenGL Z 轴。

 ZOrder 的值最好在 -30000 到 +30000 之间，超过此范围的值有时候可能出问题

addChild() 支持用第二个参数指定子对象的 ZOrder，因此上面的代码可以写成：

scene:addChild(hero, 1000)

与 ZOrder 不同，OpenGL Z 轴设定完全无视了显示对象的树状层次结构。而是根据 VertexZ 值来决定整个画面中显示对象的前后遮挡关系。VertexZ 的取值范围是 -1.0 到 1.0 的浮点数，数值越大层级越高。

node:setZOrder(z)
local z = node:getZOrder()
 
node:setVertexZ(z)
local z = node:getVertexZ()

变形

quick 可以指定一个显示对象的变形属性，例如缩放、倾斜等。改变一个对象的变形属性后，这个对象中所有的子对象都会受到影响。

node1:setScale(2.0) -- 放大为 2 倍显示
node2:setScaleX(1.5) -- 水平方向拉伸为 1.5 倍
node3:setScaleY(3.0) -- 垂直方向拉伸为 3.0 倍

注意：  如果 scaleX 和 scaleY 使用了不同的值，那么调用对象的 getScale() 方法会报告错误（因为 getScale() 不知道该返回 scaleX 还是 scaleY 的值）。

是否可见

不可见的对象不会渲染，也不会接受触摸事件，除此之外与可见对象没有任何区别，帧事件、延迟调用、动作等都会正常工作。

node:setVisible(false) -- 设置对象不可见
 
print(node:isVisible())

添加和管理子对象

CCNode 最强大的功能之一是可以作为其他显示对象的容器。例如我们要制作一个对话框，可以将对话框的所有内容都添加到一个 CCNode 对象里。对这个 CCNode 设定位置、改变大小等操作，就会作用到整个对话框上。

node:addChild(childNode) -- 添加子对象
node:addChild(childNode, z) -- 同时指定子对象的 ZOrder
node:addChild(childNode, z, tag) -- 同时指定子对象的 tag

子对象可以用多种途径访问：

print(node) -- 输出 node 值
-- 查询指定 tag 的子对象，如果有多个返回第一个，否则返回 nil
local childNode = node:getChildByTag(tag)
 
-- 返回子对象的总数（不含子对象的子对象）
print(node:getChildrenCount())
 
-- 获得一个包含所有子对象的 CCArray 对象，然后遍历其中所有子对象
local array = node:getChildren()
for i = 0, array:count() - 1 do
--
    local childNode = tolua.cast(array:objectAtIndex(i), "CCNode")
    print(childNode:getParent()) -- 输出子对象的父对象，应该与 node 的值相同
end

tolua

提供几个 C++ 与 Lua 进行数据交换的工具函数。

tolua.type

返回一个 C++ 对象的类型描述字符串。

local node = display.newNode()
print(tolua.type(node)) -- 输出 CCNode

tolua.cast

强制转换对象类型

格式：

tolua.cast(对象, 类型名称)

要删除子对象也有多种途径：

childNode:removeSelf() -- 从父对象中删除自己
 
node:removeChild(childNode) -- 删除一个子对象
 
-- 删除指定 tag 的子对象，如果有多个 tag 相同的子对象，删除第一个
childNode:setTag(1) -- 设置子对象的 tag 为 1
node:removeChildByTag(1)
 
-- 删除所有子对象
node:removeAllChildren()

事件

CCNode 提供了两类事件：显示对象事件和帧事件。

显示对象在被加入父对象和从父对象删除时，会分别触发 onEnter 和 onExit 事件。

local node = display.newNode()
 
node.onEnter = function()
    -- 显示对象加入父对象时调用
end
 
node.onExit = function()
    -- 显示对象从父对象删除时调用
    -- 利用 onExit 事件，可以做一些清理工作
end
 
node:setNodeEventEnabled(true) -- 允许显示对象的事件

要禁用显示对象事件：

node:setNodeEventEnabled(false)

执行动作

动作是 quick 里最强大的功能之一。

如果连续调用多次 runAction()，可以实现并列执行多个动作，例如：

-- 移动的同时旋转
node:runAction(CCMoveTo:create(0.3, CCPoint(100, 200)))
node:runAction(CCRotateBy:create(0.3, 360))

如果希望依次执行多个动作，应该借助 transition.sequence() ：

local sequence = transition.sequence({
    CCMoveTo:create(0.5, CCPoint(display.cx, display.cy)),
    CCFadeOut:create(0.2),
    CCDelayTime:create(0.5),
    CCFadeIn:create(0.3),
})
node:runAction(sequence)

我们可以查询显示对象上当前有多少个动作在执行：

print(node:getNumberOfRunningActions())

transition.playAnimationOnce

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

格式：

action = transition.playAnimationOnce(显示对象,
                                      动画对象,
                                      [播放完成后删除显示对象],
                                      [播放完成后要执行的函数],
                                      [播放前等待的时间])

用法示例：

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)

还可以用 CCSprite 对象的 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)

transition.playAnimationForever

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

格式：

action = transition.playAnimationForever(显示对象, 动画对象, [播放前等待的时间])

用法示例：

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)

transition.removeAction

停止一个正在执行的动作。

格式：

transition.removeAction(CCAction 动作对象)

用法示例：

-- 开始移动
local action = transition.moveTo(sprite, {time = 2.0, x = 100, y = 100})
....
transition.removeAction(action) -- 停止移动

transition.stopTarget

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

用法示例：

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

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

transition.pauseTarget

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

格式：

transition.pauseTarget(显示对象)

~~

transition.resumeTarget

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

格式：

transition.resumeTarget(显示对象)

如果我们需要在一个显示对象上等待一段时间再执行某个函数，可以用 performWithDelay ：

node:performWithDelay(function()
    -- 等待 1.5 秒后执行代码
    node:runAction(....)
end, 1.5)

display.newClippingRegionNode

创建并返回一个 CCClippingRegionNode 对象。

格式：

clipnode = display.newClippingRegionNode(CCRect 对象)

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

用法示例：

-- 剪裁区域从屏幕左下角靠内 100 点，到屏幕右上角
local rect = CCRect(display.left + 100,
                    display.bottom + 100,
                    display.width - 200,
                    display.height - 200)
local clipnode = display.newClippingRegionNode(rect)

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