cocos2dx 源码分析 之Widget 头文件 （3.11.1）

//一直想找时间梳理下，虽然我可能讲的不好，但多写多讲才会进步啊！嗯，厚脸皮的试试。
/****************************************************************************
Copyright (c) 2013-2014 Chukong Technologies Inc.

http://www.cocos2d-x.org

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
****************************************************************************/

#ifndef __UIWIDGET_H__
#define __UIWIDGET_H__

#include "2d/CCProtectedNode.h"
#include "ui/UILayoutParameter.h"
#include "ui/GUIDefine.h"
#include "ui/GUIExport.h"
#include "base/CCMap.h"

/**
 * @addtogroup ui
 * @{
 */
NS_CC_BEGIN
// 单点触摸事件
class EventListenerTouchOneByOne;
// 摄像机
class Camera;

namespace ui {
    class LayoutComponent;

/**
 * Touch event type.
 *@deprecated use `Widget::TouchEventType` instead
 */
// 触摸事件的事件名枚举 分别是 开始点击 移动 离开 不正常离开属于取消
typedef enum
{
    TOUCH_EVENT_BEGAN,
    TOUCH_EVENT_MOVED,
    TOUCH_EVENT_ENDED,
    TOUCH_EVENT_CANCELED
}TouchEventType;
    
/**
 * Touch event callback.
 *@deprecated use `Widget::ccWidgetTouchCallback` instead
 */
// 触摸事件回调处理
typedef void (Ref::*SEL_TouchEvent)(Ref*,TouchEventType);
#define toucheventselector(_SELECTOR) (SEL_TouchEvent)(&_SELECTOR)
#if (CC_TARGET_PLATFORM == CC_PLATFORM_WINRT)
#ifdef ABSOLUTE
#undef ABSOLUTE
#endif
#endif

/** 
*@brief Base class for all ui widgets. 
* This class inherent from `ProtectedNode` and `LayoutParameterProtocol`. 
* If you want to implements your own ui widget, you should subclass it. 
*/
class CC_GUI_DLL Widget : public ProtectedNode, public LayoutParameterProtocol
{
public: 
    /** 
    * Widget focus direction. 
    */
    enum class FocusDirection 
    {
        LEFT, 
        RIGHT, 
        UP, 
        DOWN 
    }; 

    /** 
    * Widget position type for layout. 
    */
    // 坐标的方式，前者是标准化，直接设置坐标的数字，
    // 第二种是按照比例，以父节点大小为参考，设置百分比来作为坐标，好处是可以不用get一下父节点的大小再来设置具体数字，而且父节点大小修改的时候不需要再调整一次位置
    enum class PositionType 
    { 
        ABSOLUTE, 
        PERCENT 
    }; 

    /** 
    * Widget size type for layout. 
    */
    // 类似上面的，坐标换为大小而已
    enum class SizeType
    {
        ABSOLUTE,
        PERCENT
    };
    
    /**
     * Touch event type.
     */
    // 有点跟上面重复？这是为啥
    enum class TouchEventType
    {
        BEGAN,
        MOVED,
        ENDED,
        CANCELED
    };
    
    /**
     * Texture resource type.
     * - LOCAL:  It means the texture is loaded from image.
     * - PLIST: It means the texture is loaded from texture atlas.
     */
    // 纹理加载的两个方式
    // 默认是 传入图片路径
    // 第二种是序列帧里使用的 把碎图合在大图里，但使用的时候只是要其中一项，使用前要先放入帧缓存中，再用plist里面的名字把它拿出来用
    enum class TextureResType
    {
        LOCAL = 0,
        PLIST = 1
    };
    
    /**
     * Widget bright style.
     */
    enum class BrightStyle
    {
        NONE = -1,
        NORMAL,
        HIGHLIGHT
    };

    
    /**
     * Widget touch event callback.
     */
    // 触摸事件的回调
    typedef std::function<void(Ref*,Widget::TouchEventType)> ccWidgetTouchCallback; 
    
    /** 
    * Widget click event callback. 
    */
    // 点击事件的回调
    typedef std::function<void(Ref*)> ccWidgetClickCallback; 

    /** 
    * Widget custom event callback. 
    * It is mainly used together with Cocos Studio. 
    */
    // cocostudio里面注册事件的回调
    typedef std::function<void(Ref*, int)> ccWidgetEventCallback; 

    /** 
    * Default constructor 
    * @js ctor 
    * @lua new 
    */ 
    Widget(void); 

    /** 
    * Default destructor 
    * @js NA 
    * @lua NA 
    */ 
    virtual ~Widget(); 

    /** 
    * Create and return a empty Widget instance pointer. 
    */
    // 创建
    static Widget* create();

    /**
     * Sets whether the widget is enabled
     * 
     * true if the widget is enabled, widget may be touched , false if the widget is disabled, widget cannot be touched.
     *
     * Note: If you want to change the widget's appearance  to disabled state, you should also call  `setBright(false)`.
     *
     * The default value is true, a widget is default to enable touch.
     *
     * @param enabled Set to true to enable touch, false otherwise.
     */
    // UI组件特有的基本属性,CC类是没有的  _enabled  用来控制是否接收触摸事件（当_visible和_enabled都为true才接收触摸)

    virtual void setEnabled(bool enabled);

    /**
     * Determines if the widget is enabled or not.
     *
     * @return true if the widget is enabled, false if the widget is disabled.
     */
    bool isEnabled() const;

    /**
     * Sets whether the widget is bright
     *
     * The default value is true, a widget is default to bright
     *
     * @param bright   true if the widget is bright, false if the widget is dark.
     */
    // UI组件特有的基本属性,CC类是没有的 用于按钮等需要切换状态的
    // 相关接口onPressStateChangedToNormal() onPressStateChangedToPressed() onPressStateChangedToDisabled()
    void setBright(bool bright);

    /**
     * Determines if the widget is bright
     *
     * @return true if the widget is bright, false if the widget is dark.
     */
    bool isBright() const;

    /**
     * Sets whether the widget is touch enabled.
     *
     * The default value is false, a widget is default to touch disabled.
     *
     * @param enabled   True if the widget is touch enabled, false if the widget is touch disabled.
     */
    // UI组件特有的基本属性,CC类是没有的  _touchEnabled  能否点击 注册点击事件
    virtual void setTouchEnabled(bool enabled);

    /**
     * To set the bright style of widget.
     *
     * @see BrightStyle
     *
     * @param style   BrightStyle::NORMAL means the widget is in normal state, BrightStyle::HIGHLIGHT means the widget is in highlight state.
     */
    void setBrightStyle(BrightStyle style);

    /**
     * Determines if the widget is touch enabled
     *
     * @return true if the widget is touch enabled, false if the widget is touch disabled.