COcos2d-X 节点（CCScheduler.h）API

本文来自http://blog.csdn.net/runaying ，引用必须注明出处！

COcos2d-X 节点（CCScheduler.h）API

温馨提醒：为了大家能更好学习，强烈推荐大家看看本人的这篇博客 Cocos2d-X权威指南笔记

/****************************************************************************
 
///cocos2d-x-3.0alpha0/cocos2dx

#ifndef __CCSCHEDULER_H__
#define __CCSCHEDULER_H__

#include "cocoa/CCObject.h"
#include "support/data_support/uthash.h"

NS_CC_BEGIN

/**
 * @addtogroup global
 * @{
 */

class Set;
//
// Timer
//
/** @brief Light-weight timer */    //轻量级定时器
//
class CC_DLL Timer : public Object
{
public:
    /** 使用一个 selector 、 一个 target 分配一个定时器. */
    static Timer* create(Object *target, SEL_SCHEDULE selector);
    /** 使用一个 selector 、 一个 target、一个时间间隔（以秒为单位） 分配一个定时器. */
    static Timer* create(Object *target, SEL_SCHEDULE selector, float seconds);
    /** 使用一个 脚本回调函数、一个时间间隔（以秒为单位） 分配一个定时器。
     * @js NA
     * @lua NA
     */
    static Timer* createWithScriptHandler(int nHandler, float seconds);
    
    CC_DEPRECATED_ATTRIBUTE static Timer* timerWithTarget(Object *target, SEL_SCHEDULE selector) { return Timer::create(target, selector); }
    CC_DEPRECATED_ATTRIBUTE static Timer* timerWithTarget(Object *target, SEL_SCHEDULE selector, float seconds) { return Timer::create(target, selector, seconds); }
    CC_DEPRECATED_ATTRIBUTE static Timer* timerWithScriptHandler(int nHandler, float seconds) { return Timer::createWithScriptHandler(nHandler, seconds); }
    
    Timer(void);
    
    /**  使用一个 selector 、 一个 target 初始化一个定时器. */
    bool initWithTarget(Object *target, SEL_SCHEDULE selector);
    /**  使用一个 selector 、 一个 target、一个时间间隔（以秒为单位）、重复次数、延迟几秒钟后执行 初始化一个定时器. */
    bool initWithTarget(Object *target, SEL_SCHEDULE selector, float seconds, unsigned int nRepeat, float fDelay);
    /**  使用一个 脚本回调函数、一个时间间隔（以秒为单位） 分配一个定时器。 */
    bool initWithScriptHandler(int nHandler, float seconds);
    
    /** get 以秒为单位的时间间隔*/
    float getInterval() const;
    /** set 以秒为单位的时间间隔 */
    void setInterval(float interval);
    /**
     * @js NA
     * @lua NA
     */
    SEL_SCHEDULE getSelector() const;
    
    /** 触发定时器*/
    void update(float dt);
    
    inline int getScriptHandler() const { return _scriptHandler; };
    
protected:
    Object *_target;
    float _elapsed;
    bool _runForever;
    bool _useDelay;
    unsigned int _timesExecuted;
    unsigned int _repeat; //0 = once, 1 is 2 x executed
    float _delay;
    float _interval;
    SEL_SCHEDULE _selector;
    
    int _scriptHandler;
};

//
// Scheduler
//
struct _listEntry;
struct _hashSelectorEntry;
struct _hashUpdateEntry;

class Array;

/** @brief Scheduler 负责触发 scheduled callbacks.
 你不应该使用 NSTimer. 代替这个类.
 
 这里有两种不同类型的 callbacks (selectors):
 
 - update selector:  'update' selector 每一帧都会调用。您可以自定义他的优先级.
 - custom selector: 自定义的 selector  每一帧都会调用, 或者和一个自定义的时间间隔
 
 应该尽量避免使用 'custom selectors' 。因为  'update selector' 已经很快了，它只消耗很少的内存
 
 */
class CC_DLL Scheduler : public Object
{
public:
    // 系统服务预留优先级
    static const int PRIORITY_SYSTEM;
    
    //最低优先级的用户调度。
    static const int PRIORITY_NON_SYSTEM_MIN;
    /**
     * @js ctor
     */
    Scheduler();
    /**
     * @js NA
     * @lua NA
     */
    ~Scheduler(void);
    
    inline float getTimeScale(void) { return _timeScale; }
    /**修改所有的 scheduled callbacks 时间.
     您可以使用这个属性来创建一个'慢动作'或'快进'效应。
         默认值为1.0。要创建一个“慢动作”效果，使用值在1.0以下。
         要创建一个'快进'的效果，使用高于1.0的值。
     @since v0.8
     @warning 这将影响到每一个 scheduled 的 selector / action.
     */
    inline void setTimeScale(float fTimeScale) { _timeScale = fTimeScale; }
    
    /** 'update' the scheduler.
     你不应该调用此方法，除非你知道你在做什么。
     * @js NA
     * @lua NA
     */
    void update(float dt);
    
    /** The scheduled 方法每一个'interval'（间隔，以秒为单位） 都会被调用.
     如果 paused 的值是 true, 那么他不会被调用除非他被 resumed.
     如果 'interval'（间隔，以秒为单位）是 0, 他每一帧都会被调用,这个时候,建议使用 'scheduleUpdateForTarget:' 来代替.
     如果 selector 已经在 scheduled 里面了, 那么只用 interval （间隔，以秒为单位）参数会被更新而不是每次都 re-scheduling .
     repeat 让 action 重复 repeat + 1 次, 使用 kRepeatForever 让 action 一直运行
     delay 在开始前 action 等待的时间
     
     @since v0.99.3, repeat and delay added in v1.1
     */
    void scheduleSelector(SEL_SCHEDULE selector, Object *target, float fInterval, unsigned int repeat, float delay, bool bPaused);
    
    /** 使用  kRepeatForever 、 0 延迟 ，调用 scheduleSelector*/
    void scheduleSelector(SEL_SCHEDULE selector, Object *target, float fInterval, bool bPaused);
    /** 对于一个给定的 target 和一个给定的 priority（优先级） Schedules the 'update' selector.
     The 'update' selector 他每一帧都会被调用.
     priority(优先级) 越低越早调用.
     @since v0.99.3
     */
    void scheduleUpdateForTarget(Object *target, int nPriority, bool bPaused);
    
    /**检查是否有一个 selector 和给定的 scheduled 的 taget 相同.
     @since v3.0.0
     */
    bool isScheduledForTarget(SEL_SCHEDULE selector, Object *target);
    
    /** 取消给定的 target 对应的 selectort.
     如果你想取消 "update" ，可以使用 unscheudleUpdateForTarget.
     @since v0.99.3
     */
    void unscheduleSelector(SEL_SCHEDULE selector, Object *target);
    
    /**  取消给定的 target 对应的 update selector
     @since v0.99.3
     */
    void unscheduleUpdateForTarget(const Object *target);
    
    /**  取消给定的 target 对应的所有 selectort.
     这也包括 "update" selector.
     @since v0.99.3
     */
    void unscheduleAllForTarget(Object *target);
    
    /** 取消所有 targets 对应的 selectors.
     你不应该调用此方法，除非你知道你在做什么.
     
     @since v0.99.3
     */
    void unscheduleAll(void);
    
    /** 取消所有使用 nMinPriority 的 targets 对应的 selectors.
     你应该只在使用 kPriorityNonSystemMin or higher 时调用这个方法.
     @since v2.0.0
     */
    void unscheduleAllWithMinPriority(int nMinPriority);
    
    /**  scheduled 脚本回调每一个 'interval'（间隔、以秒为单位）都会被调用.
     如果 paused 的值是 true, 那么他不会被调用除非他被 resumed.
     如果 'interval'（间隔，以秒为单位）是 0, 他每一帧都会被调用.
     return schedule script（脚本） entry（条目） ID, used for unscheduleScriptFunc().
     */
    unsigned int scheduleScriptFunc(unsigned int nHandler, float fInterval, bool bPaused);
    
    /** Unschedule（取消） a script（脚本） entry（条目）. */
    void unscheduleScriptEntry(unsigned int uScheduleScriptEntryID);
    
    /** Pauses the target.
     给定的 target 对应的 scheduled 的所有 selectors/update 都不会被 'ticked'（打勾） 直到这个 target 被 resumed.
     如果 target 不存在的，什么也不会发生.
     @since v0.99.3
     */
    void pauseTarget(Object *target);
    
    /** Resumes the target.
     给定的 'target' 将取消暂停, 他所对应的 schedules 的所有 selectors/update 将再次被 'ticked'（选择）.
      如果 target 不存在的，什么也不会发生.
     @since v0.99.3
     */
    void resumeTarget(Object *target);
    
    /** Returns 这个 target 是否被暂停了
     @since v1.0.0
     * In js: var isTargetPaused(var jsObject)
     * @lua NA
     */
    bool isTargetPaused(Object *target);
    
    /** 暂停所有 targets 对应的 selectors
     你不应该调用此方法，除非你知道你在做什么.
     @since v2.0.0
     */
    Set* pauseAllTargets();
    
    /** 使用 minimum （最小的）优先级，暂停所有 targets 对应的 selectors
     你应该只在使用 kPriorityNonSystemMin or higher 时调用这个方法.
     
     @since v2.0.0
     */
    Set* pauseAllTargetsWithMinPriority(int nMinPriority);
    
    /** Resume（恢复） 一组 targets 对应的所有 selectors .
    这是非常有用的，撤销调用 pauseAllSelectors .
     @since v2.0.0
     */
    void resumeTargets(Set* targetsToResume);
    
private:
    void removeHashElement(struct _hashSelectorEntry *pElement);
    void removeUpdateFromHash(struct _listEntry *entry);
    
    // update specific      //特定更新
    
    void priorityIn(struct _listEntry **ppList, Object *target, int nPriority, bool bPaused);
    void appendIn(struct _listEntry **ppList, Object *target, bool bPaused);
    
protected:
    float _timeScale;
    
    //
    // "updates with priority" stuff    //更新优先级的东西
    //
    struct _listEntry *_updatesNegList;        // list of priority < 0          //优先级
    struct _listEntry *_updates0List;            // list priority == 0
    struct _listEntry *_updatesPosList;        // list priority > 0
    struct _hashUpdateEntry *_hashForUpdates; // hash 用于快速获取 pause,delete,etc 列表项 
    
    // Used for "selectors with interval"（selectors 的间隔）
    struct _hashSelectorEntry *_hashForTimers;
    struct _hashSelectorEntry *_currentTarget;
    bool _currentTargetSalvaged;
    // 如果 unschedule 的值是 true，将不会从 hash 里面删除任何东西. Elements 仅仅被标记为 deletion.
    bool _updateHashLocked;
    Array* _scriptHandlerEntries;
};

// end of global group
/// @}

NS_CC_END

#endif // __CCSCHEDULER_H__