cocos2d-X 节点（UIWidget.h）API
本文来自http://blog.csdn.net/runaying ，引用必须注明出处！
cocos2d-X 节点（UIWidget.h）API
温馨提醒：为了大家能更好学习，强烈推荐大家看看本人的这篇博客 Cocos2d-X权威指南笔记
/widget 的基类多数 UI 控件都是它的子类，通常情况我们不会直接使用它，而是使用他的子类，它实现了 修改 发光类型，触摸事件的回调，尺寸改变时的回调，可见性，绘制顺序，在 parent widget的位置，缩放，长 clicked .....
/////cocos2d-x-3.0alpha0/extensions/CocoStudio/GUI/BaseClasses
//widget 的基类 多数 UI 控件 都是它的子类，通常情况我们不会直接使用它，而是使用他的子类，它实现了 修改 发光类型，触摸事件的回调，尺寸改变时的回调，可见性，绘制顺序，在 parent widget 的位置，缩放，长 clicked .....
#ifndef __UIWIDGET_H__
#define __UIWIDGET_H__
#include "cocos2d.h"
#include "ExtensionMacros.h"
#include "../Layouts/UILayoutDefine.h"
#include "../Layouts/LayoutParameter.h"
NS_CC_EXT_BEGIN
//亮度类型
typedef enum
{
BRIGHT_NONE = -1,
BRIGHT_NORMAL,
BRIGHT_HIGHLIGHT
}BrightStyle;
//widget 类型
typedef enum
{
WidgetTypeWidget, //control
WidgetTypeContainer //container
}WidgetType;
// texture 分辨率类型
typedef enum
{
UI_TEX_TYPE_LOCAL,
UI_TEX_TYPE_PLIST
}TextureResType;
//触摸事件类型
typedef enum
{
TOUCH_EVENT_BEGAN,
TOUCH_EVENT_MOVED,
TOUCH_EVENT_ENDED,
TOUCH_EVENT_CANCELED
}TouchEventType;
//尺寸类型
typedef enum
{
SIZE_ABSOLUTE,
SIZE_PERCENT
}SizeType;
//位置类型
typedef enum
{
POSITION_ABSOLUTE,
POSITION_PERCENT
}PositionType;
typedef void (Object::*SEL_TouchEvent)(Object*,TouchEventType);
#define toucheventselector(_SELECTOR) (cocos2d::extension::SEL_TouchEvent)(&_SELECTOR)
//class UILayer;
/*temp action*/
class UIActionNode;
class UIWidget : public Object
{
public:
/**
* Default constructor
*/
UIWidget(void);
/**
* Default destructor
*/
virtual ~UIWidget();
/**
* 分配并初始化一个widget。
*/
static UIWidget* create();
/**
* 设置是否启用 widget
*
* Highest(最高) control of widget.
* 默认值是 true， widget 默认为启用
*
* @param enabled true 如果 widget 启用了, widget 是可见的，可以被触摸, false 如果 widget 禁用了 widget 会被隐藏，不可以被触摸.
*/
virtual void setEnabled(bool enabled);
/**
* 确定 widget 是否启用了
*
* @return true if the widget is enabled, false if the widget is disabled.
*/
bool isEnabled() const;
/**
* 设置 widget 是否可见
*
*默认值是 true， widget 默认是可见的
*
* @param visible true if the widget is visible, false if the widget is hidden.
*/
void setVisible(bool visible);
/**
* 确定 widget 是否可见
*
* @return true if the widget is visible, false if the widget is hidden.
*/
bool isVisible() const;
/**
* 设置widget 是否是否发光
*
* 默认值是true， widget 默认会发光
*
* @param visible true if the widget is bright, false if the widget is dark.
*/
void setBright(bool bright);
/**
* 确定 widget 是否是否发光
*
* @return true if the widget is bright, false if the widget is dark.
*/
bool isBright() const;
/**
* Sets widget 是否启用触摸
*
* 默认值是false， widget 默认没有启用触摸
*
* @param visible true if the widget is touch enabled, false if the widget is touch disabled.
*/
virtual void setTouchEnabled(bool enabled);
/**
* 设置 widget 的发光风格.
*
* @see BrightStyle
*
* @param style BRIGHT_NORMAL the widget is normal state, BRIGHT_HIGHLIGHT the widget is height light state.
*/
void setBrightStyle(BrightStyle style);
/**
* 确定是否启用 widget 触摸
*
* @return true if the widget is touch enabled, false if the widget is touch disabled.
*/
bool isTouchEnabled() const;
/**
* 确定 widget 是否获取到了焦点
*
* @return true if the widget is on focused, false if the widget is not on focused.
*/
bool isFocused() const;
/**
* 设置 widget 是否获取到焦点
*
* 默认值是false， widget 默认没有获得焦点
*
* @param fucosed true if the widget is on focused, false if the widget is not on focused.
*/
void setFocused(bool fucosed);
/**
* 设定Z顺序它代表的绘制顺序，并重新排列这个widget在其父母的孩子数组
*
* widget的Z顺序是相对于它的“兄弟”：同父的孩子。他和 OpenGL的Z顶点是没有任何关系的
* 只影响在cocos2d widget 的绘制顺序，较大的数字，在每条 widget 消息循环绘制里面绘制的越晚
* 不同之处请参考 setVertexZ(float)
*
* @param nZOrder Z order of this widget.
*/
void setZOrder(int z);
/**
* 获取 widget 的Z顺序。
*
* @see setZOrder(int)
*
* @return The Z order.
*/
int getZOrder();
/**
* 获取 widget 左边界的位置。
*
* @return The left boundary position of this widget. //边界
*/
float getLeftInParent();
/**
*获取 widget 底部边界位置。
*
* @return The bottom boundary position of this widget. //边界
*/
float getBottomInParent();
/**
* 获取 widget 右边界的位置。
*
* @return The right boundary position of this widget.
*/
float getRightInParent();
/**
*获取 widget 顶部边界位置。
*
* @return The top boundary position of this widget. //边界
*/
float getTopInParent();
/**
* 往容器里面添加一个 child
*
* @param child A child widget
*/
virtual bool addChild(UIWidget* child);
/**
* 从容器里面删除并清理 child
*
* @param child The child widget which will be removed.
*
* @return the result of removing, succeeded or failed.
*/
virtual bool removeChild(UIWidget* child);
/**
* 从这个 widget 的parent 删除这个 widget
* If the widget orphan, then it will destroy itself.
*/
virtual void removeFromParent();
/**
*从容器中移除所有的 child，根据清理参数清理所有正在运行的 action。
*/
virtual void removeAllChildren();
/**
* Unschedules the "update" method. //取消预定的更新方法
*/
void disableUpdate();
/**
* 根据一个新的 z 值，重新排序 child
*
* @param child 一个已经 added 的 child node. 它必须是已经 added.
* @param zOrder Z顺序是绘制优先级. 请参考 CCNode::setZOrder(int)
*/
virtual void reorderChild(UIWidget* child);
/**
* 使用他的名字从容器里面获取 child
*
* @param name An key to find the child widget.
*
* @return 一个UIWidget对象，其 name 等于输入参数
*/
UIWidget* getChildByName(const char* name);
/**
* 使用 tag（标识）从容器里面获取 child
*
* @param tag 一个查找 child widget 的标识.
*
* @return 一个UIWidget对象，其 tag 等于输入参数 //标识
*/
UIWidget* getChildByTag(int tag);
/**
* 返回一个 children 数组
*
* Composing(组成) "tree" 结构，他是 UIWidget 里面的一个非常重要的属性
*
* @return An array of children
*/
virtual Array* getChildren();
/**
* Gets widget 的渲染
*
* 要绘制的 CCNode 渲染
*
* @return a CCNode object
*/
Node* getRenderer();
/**
* 添加的CCNode进行渲染
*
* 要绘制的 CCNode 渲染
*
* @param renderer A render node //渲染
*
* @param zOrder Z顺序是绘制优先级. 请参考 CCNode::setZOrder(int)
*/
void addRenderer(Node* renderer, int zOrder);
/**
* 从 widget 里面移除一个 widget.
*
* 要绘制的 CCNode 渲染
*
* @param renderer 需要移除的渲染 Node
*
* @param cleanup true 渲染节点上运行的所有 action 和 callBacks 都会被清理, false otherwise.
*/
void removeRenderer(Node* renderer, bool cleanup);
/**
* Sets the parent widget
*
* @param parent A pointer to the parnet widget
*/
void setParent(UIWidget* parent);
/**
* Returns 指向 parent widget 的指针
*
* @see setParent(UIWidget*)
*
* @returns A pointer to the parnet widget
*/
UIWidget* getParent();
/**
* 设置菜单项的触摸事件 target/selector
*/
void addTouchEventListener(Object* target,SEL_TouchEvent selector);
//cocos2d property
/**
* Changes the position (x,y) of the widget in OpenGL coordinates
*
* 通常我们使用 ccp(x,y) 组成的Point对象
* 原来的点（0,0）是在屏幕的左下角
*
* @param position The position (x,y) of the widget in OpenGL coordinates
*/
void setPosition(const Point &pos);
const Point& getPosition();
/**
* 改变 widget 在 OpenGL 坐标系中的位置 (x,y)
*
* 通常我们使用 ccp(x,y) 组成的Point对象
* 原来的点（0,0）是在屏幕的左下角
*
* @param percent The percent (x,y) of the widget in OpenGL coordinates
*/
void setPositionPercent(const Point &percent);
const Point& getPositionPercent();
/**
* Changes widget 的位置类型
*
* @see PositionType
*
* @param type the position type of widget
*/
void setPositionType(PositionType type);
PositionType getPositionType() const;
/**
* 以百分比形式设置锚点。
*
* anchorPoint 是所有 位置/转换 的环绕点.
* 他就像一个针，关联在他的 parent 上.
* 正常的 anchorPoint 想一个百吨比. 0,0）表示的左下角（1,1）表示右上角。
* 但是你可以使用的值比（1,1）高比比（0,0）低。
* 默认的 anchorPoint 是 (0.5,0.5), 所以它开始在 widget 的中心
*
* @param anchorPoint The anchor point of widget.
*/
virtual void setAnchorPoint(const Point &pt);
const Point& getAnchorPoint();
/**
* 改变 widget X 和 Y 上面的 比例银子.
*
* 如果在同一时间修改X和Y比例系数，默认值是1.0
*
* @param scale The scale factor for both X and Y axis.
*/
virtual void setScale(float fScale);
/**
* 如果在同一时间修改X和Y比例系数，那么获取 widget 的比例系数
*
* @warning Assert when m_fScaleX != m_fScaleY. 它们两个值不相等时会出现断言
* @see setScale(float)
*
* @return The scale factor of the widget.
*/
float getScale();
/**
* 更改这个widget的X轴的比例系数
*
* 如果你以前没有改变它，默认值是1.0。
*
* @param fScaleX The scale factor on X axis.
*/
virtual void setScaleX(float fScaleX);
float getScaleX();
/**
* 更改这个widget的Y轴的比例系数
*
* 如果你以前没有改变它，默认值是1.0。
*
* @param fScaleY The scale factor on Y axis.
*/
virtual void setScaleY(float fScaleY);
float getScaleY();
/**
* 设置 widge 的旋转(度)，塌毁垂直倾斜旋转
*
* 0 是默认的旋转角.
* 正值，顺时针旋转，负值，逆时针旋转
*
* @param fRotation The roration of the widget in degrees.
*/
void setRotation(float rotation);
float getRotation();
/**
* 设置 widge 的 X 轴旋转(度)，塌毁垂直倾斜旋转
*
* 0 是默认的旋转角.
* 正值，顺时针旋转，负值，逆时针旋转
*
* @param fRotationX The X rotation in degrees which performs a horizontal rotational skew.
*/
void setRotationX(float rotationX);
float getRotationX();
/**
* 设置 widge 的 Y 轴旋转(度)，塌毁垂直倾斜旋转
*
* 0 是默认的旋转角.
* 正值，顺时针旋转，负值，逆时针旋转
*
* @param fRotationY The Y rotation in degrees.
*/
void setRotationY(float rotationY);
float getRotationY();
/**
* Sets widget 是否应该水平翻转
*
* @param bFlipX true 如果widget 应该水平翻转, false otherwise.
*/
virtual void setFlipX(bool flipX){};
/**
* 返回 widget 是否水平翻转的标识
*它只翻转 widget 的texture ,而不翻转 widget's children 的 texture
*
* 另外 翻转 texture 也不会改变他的 anchorPoint(锚点).
* 如果你也想翻转 anchorPoint(锚点) , and/or 也翻转 children ，你可以使用:
* widget->setScaleX(sprite->getScaleX() * -1);
*
* @return true if the widget is flipped horizaontally, false otherwise.
*/
virtual bool isFlipX(){return false;};
/**
* Sets widget 是否应该垂直翻转
*
* @param bFlipY true 如果widget 应该垂直翻转, flase otherwise.
*/
virtual void setFlipY(bool flipY){};
/**
* 返回 widget 是否垂直翻转的标识
*
*它只翻转 widget 的texture ,而不翻转 widget's children 的 texture
*
* 另外 翻转 texture 也不会改变他的 anchorPoint(锚点).
* 如果你也想翻转 anchorPoint(锚点) , and/or 也翻转 children ，你可以使用:
* widget->setScaleY(widget->getScaleY() * -1);
*
* @return true 如果 widget 垂直翻转, flase otherwise.
*/
virtual bool isFlipY(){return false;};
/**
* Sets widget 的颜色
*
* 它默认会修改 widget‘s children 的颜色
*
* @param color
*/
virtual void setColor(const Color3B &color);
virtual const Color3B& getColor();
/**
* Sets widget 的不透明度
* 它默认会修改 widget‘s children 的不透明度
*
*
* @param color
*/
virtual void setOpacity(int opacity);
/**
* 获取 widget 的不透明度
*
* @return opacity
*/
virtual int getOpacity();
virtual bool isCascadeOpacityEnabled();
virtual void setCascadeOpacityEnabled(bool cascadeOpacityEnabled);
virtual bool isCascadeColorEnabled();
virtual void setCascadeColorEnabled(bool cascadeColorEnabled);
void setBlendFunc(BlendFunc blendFunc);
//cocos action
virtual void setActionManager(ActionManager* actionManager);
virtual ActionManager* getActionManager();
Action* runAction(Action* action);
void stopAllActions(void);
void stopAction(Action* action);
void stopActionByTag(int tag);
Action* getActionByTag(int tag);
/**
* widget 失去焦点时的回调函数
*/
void didNotSelectSelf();
/*
* Checks 一个点是否在 parent's 区域.
*
* @param point
*
* @return true 如果这个点在 parent's 区域, flase otherwise.
*/
bool clippingParentAreaContainPoint(const Point &pt);
/*
* 发送触摸事件到 widget's parent
*/
virtual void checkChildInfo(int handleState,UIWidget* sender,const Point &touchPoint);
/*
* 获取 widget 选择时的触摸开始的点
*
* @return the touch began point.
*/
const Point& getTouchStartPos();
/*
* Gets the touch move point of widget when widget is selected.
*
* @return the touch move point.
*/
const Point& getTouchMovePos();
/*
* 获取 widget 选择时的触摸点
*
* @return the touch end point.
*/
const Point& getTouchEndPos();
/**
* Changes 可以方便识别 widget 的标识.
*
* @param A interger that indentifies the widget. // 识别
*/
void setTag(int tag);
int getTag() const;
/**
* Changes 可以方便识别 widget 的名字.
*
* @param A const char* that indentifies the widget.
*/
void setName(const char* name);
/**
* Returns 可以方便识别 widget 的名字.
*
* 你可以设置 widget tag(标识) 然后很容易的识别它们
*
* @return A const char* that identifies the widget. //识别
*/
const char* getName() const;
/**
* Returns widget's 类型
*
* @see WidgetType
*
* @return A WidgetType
*/
WidgetType getWidgetType() const;
/**
* 改变 widget's 的尺寸
*
* @param size that is widget's size
*/
virtual void setSize(const Size &size);
/**
* 改变 widget's 的百分比大小
*
* @param percent that is widget's percent size 百分比
*/
virtual void setSizePercent(const Point &percent);
/**
* Changes widget 的尺寸类型.
*
* @see SizeType
*
* @param type that is widget's size type
*/
void setSizeType(SizeType type);
/**
* Gets widget 的尺寸类型.
*
* @see SizeType
*
* @param type that is widget's size type
*/
SizeType getSizeType() const;
/**
* Returns widget 的尺寸
*
* @return size
*/
const Size& getSize() const;
/**
* Returns size percent of widget //返回 widget 尺寸的 百分比
*
* @return size percent
*/
const Point& getSizePercent() const;
/**
* Checks a point if is in widget's space //检查这个点是否在 widget's 上
*
* @param point
*
* @return true 如果这个点在 widget's 上, flase otherwise.
*/
virtual bool hitTest(const Point &pt);
/**
* A call back function called when widget is selected, and on touch began. //widget 被选择并且触摸开始时调用的函数
*
* @param touch point
*
* @return true 如果事件传递到它的 parent, flase otherwise.
*/
virtual bool onTouchBegan(const Point &touchPoint);
/**
* A call back function called when widget is selected, and on touch moved. //widget 被选择并且移动触摸点时调用的函数
*
* @param touch point
*/
virtual void onTouchMoved(const Point &touchPoint);
/**
* A call back function called when widget is selected, and on touch ended. //widget 被选择并且触摸结束时调用的函数
*
* @param touch point
*/
virtual void onTouchEnded(const Point &touchPoint);
/**
* A call back function called when widget is selected, and on touch canceled. //widget 被选择并且取消触摸时调用的函数
*
* @param touch point
*/
virtual void onTouchCancelled(const Point &touchPoint);
/**
* A call back function called when widget is selected, and on touch long clicked. // widget 被选择并且长时间触摸 clicked (点击) 时调用的函数
*
* @param touch point
*/
virtual void onTouchLongClicked(const Point &touchPoint);
/**
* Sets a LayoutParameter to widget. //设置 widget 的 LayoutParameter 参数
*
* @see LayoutParameter
*
* @param LayoutParameter pointer
*/
void setLayoutParameter(LayoutParameter* parameter);
/**
* Gets LayoutParameter of widget. 获取这个 widget 的 LayoutParameter
*
* @see LayoutParameter
*/
LayoutParameter* getLayoutParameter();
/**
* Ignore the widget size //忽略 widget 的尺寸
*
* @param ignore, true 将忽略它的大小, use texture size, false otherwise. Default value is true.
*/
virtual void ignoreContentAdaptWithSize(bool ignore);
/**
* Gets the widget if is ignore it's size. //如果他的大小，那么就获取这个 widget
*
* @param ignore, true widget 将忽略它的大小, use texture size, false otherwise. Default value is true.
*/
bool isIgnoreContentAdaptWithSize() const;
/**
* Gets world position of widget. 获取 widget 在 world 坐标系中的位置
*
* @return world position of widget. // widget 在 world 坐标系中的位置
*/
Point getWorldPosition();
/**
* Converts a Point to world space coordinates. The result is in Points. //把 点 转化为世界坐标系中的的一个点，结果是一个点
*/
Point convertToWorldSpace(const Point& pt);
/**
* Gets the Virtual Renderer of widget. //获取 widget 的虚渲染器
*
* For example, a button's Virtual Renderer is it's texture renderer. //如 button's 的需渲染器是他的 texture 渲染
*
* @return CCNode pointer.
*/
virtual Node* getVirtualRenderer();
/**
* Schedules the "update" method. //设置是否启用 scheduled 的 update 方法
*/
void setUpdateEnabled(bool enable);
/**
* is the "update" method scheduled. //是否启用了 scheduled 的 update 方法
*/
bool isUpdateEnabled();
/**
* Gets the content size of widget. //获取 widget 的内痛尺寸
*
* Content size is widget's texture size. //内容尺寸是 widget's 的 texture 尺寸
*/
virtual const Size& getContentSize() const;
virtual void onEnter();
virtual void onExit();
/**
* Returns the "class name" of widget. //返回 widget 的名字
*/
virtual const char* getDescription() const;
/*temp(临时) action*/
void setActionTag(int tag);
int getActionTag();
protected:
//call back function called when size changed. //尺寸改变时调用的回调函数
virtual void onSizeChanged();
//initializes state of widget. //初始化 widget 的状态
virtual bool init();
//initializes renderer of widget. //初始化 widget 渲染
virtual void initRenderer();
//call back function called widget's state changed to normal. // 把 widget 的状态改变为 normal（正常） 的回调函数
virtual void onPressStateChangedToNormal();
//call back function called widget's state changed to selected. // 把 widget 的状态改变为 selectde 的回调函数
virtual void onPressStateChangedToPressed();
//call back function called widget's state changed to dark. // 把 widget 的状态改变为 dark(暗) 的回调函数
virtual void onPressStateChangedToDisabled();
void pushDownEvent();
void moveEvent();
void releaseUpEvent();
void cancelUpEvent();
void longClickEvent();
void updateAnchorPoint();
/**
* 释放 widget 的 texture 资源
* 释放 renderer（渲染）.
* 如果你重写了 releaseResoures, 你应该调用它 parent's 的那一个, e.g. UIWidget::releaseResoures().
*/
virtual void releaseResoures();
void updateSizeAndPosition();
protected:
bool _enabled; ///< Highest(最高) control of widget
bool _visible; ///< is this widget visible(可见)
bool _bright; ///< is this widget bright // widget 是否发光
bool _touchEnabled; ///< is this widget touch endabled
bool _touchPassedEnabled; ///< is the touch event should be passed //是否传递触摸事件
bool _focus; ///< is the widget on focus // widget 是否获得焦点
int _widgetZOrder; ///< z-order value that affects the draw order and touch order //z顺序值，会影响绘制顺序和触摸顺序
Point _anchorPoint; ///< anchor point normalized //统一的 锚点
UIWidget* _widgetParent; ///< parent of widget
BrightStyle _brightStyle; ///< bright style // 发光风格
bool _updateEnabled; ///< is "update" method scheduled (预定)
Node* _renderer; ///< base renderer 基础渲染器
Point _touchStartPos; ///< touch began point
Point _touchMovePos; ///< touch moved point
Point _touchEndPos; ///< touch ended point 触摸结束点
Object* _touchEventListener;
SEL_TouchEvent _touchEventSelector;
int _widgetTag;
std::string _name;
WidgetType _widgetType;
int _actionTag;
Size _size;
Size _customSize;
LayoutParameter* _layoutParameter;
bool _ignoreSize;
Array* _children;
bool _affectByClipping;
Scheduler* _scheduler;
SizeType _sizeType;
Point _sizePercent;
PositionType _positionType;
Point _positionPercent;
bool _isRunning;
};
class GUIRenderer : public NodeRGBA
{
public:
GUIRenderer();
virtual ~GUIRenderer();
virtual void visit(void);
static GUIRenderer* create();
void setEnabled(bool enabled);
bool isEnabled() const;
protected:
bool _enabled;
};
NS_CC_EXT_END
#endif /* defined(__UIWidget__) */