From 3d8d0e40eec7326677947e7c63d2691fc583ab66 Mon Sep 17 00:00:00 2001 From: Timothy Qiu Date: Mon, 5 Aug 2013 20:46:57 +0800 Subject: [PATCH 1/3] Fixed broken links and wrong encoding in the doc. Fixed Obj-C names when referening functions. Changed some GB2312 encoded characters to UTF-8. --- extensions/GUI/CCControlExtension/CCControl.h | 4 ++-- .../CCControlSaturationBrightnessPicker.h | 6 +++--- .../GUI/CCControlExtension/CCControlSlider.h | 4 ++-- .../GUI/CCControlExtension/CCScale9Sprite.h | 16 ++++++++-------- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/extensions/GUI/CCControlExtension/CCControl.h b/extensions/GUI/CCControlExtension/CCControl.h index 021ae6d99f..a28d918108 100644 --- a/extensions/GUI/CCControlExtension/CCControl.h +++ b/extensions/GUI/CCControlExtension/CCControl.h @@ -164,7 +164,7 @@ public: * * @param touch A Touch object that represents a touch. * - * @return YES whether a touch is inside the receiver¡¯s rect. + * @return Whether a touch is inside the receiver's rect. */ virtual bool isTouchInside(Touch * touch); @@ -260,4 +260,4 @@ protected: NS_CC_EXT_END -#endif \ No newline at end of file +#endif diff --git a/extensions/GUI/CCControlExtension/CCControlSaturationBrightnessPicker.h b/extensions/GUI/CCControlExtension/CCControlSaturationBrightnessPicker.h index 07fb821551..9588280311 100644 --- a/extensions/GUI/CCControlExtension/CCControlSaturationBrightnessPicker.h +++ b/extensions/GUI/CCControlExtension/CCControlSaturationBrightnessPicker.h @@ -47,9 +47,9 @@ NS_CC_EXT_BEGIN class ControlSaturationBrightnessPicker : public Control { - /** Contains the receiver¡¯s current saturation value. */ + /** Contains the receiver's current saturation value. */ CC_SYNTHESIZE_READONLY(float, _saturation, Saturation); - /** Contains the receiver¡¯s current brightness value. */ + /** Contains the receiver's current brightness value. */ CC_SYNTHESIZE_READONLY(float, _brightness, Brightness); //not sure if these need to be there actually. I suppose someone might want to access the sprite? @@ -88,4 +88,4 @@ protected: NS_CC_EXT_END -#endif \ No newline at end of file +#endif diff --git a/extensions/GUI/CCControlExtension/CCControlSlider.h b/extensions/GUI/CCControlExtension/CCControlSlider.h index 03f55a855f..f477429a62 100644 --- a/extensions/GUI/CCControlExtension/CCControlSlider.h +++ b/extensions/GUI/CCControlExtension/CCControlSlider.h @@ -55,7 +55,7 @@ public: * Creates a slider with a given background sprite and a progress bar and a * thumb item. * - * @see initWithBackgroundSprite:progressSprite:thumbMenuItem: + * @see initWithSprites */ static ControlSlider* create(Sprite * backgroundSprite, Sprite* pogressSprite, Sprite* thumbSprite); @@ -94,7 +94,7 @@ protected: float valueForLocation(Point location); //maunally put in the setters - /** Contains the receiver¡¯s current value. */ + /** Contains the receiver's current value. */ CC_SYNTHESIZE_READONLY(float, _value, Value); /** Contains the minimum value of the receiver. diff --git a/extensions/GUI/CCControlExtension/CCScale9Sprite.h b/extensions/GUI/CCControlExtension/CCScale9Sprite.h index 093101711d..a6bc2df7c3 100644 --- a/extensions/GUI/CCControlExtension/CCScale9Sprite.h +++ b/extensions/GUI/CCControlExtension/CCScale9Sprite.h @@ -63,7 +63,7 @@ public: * Creates a 9-slice sprite with a texture file, a delimitation zone and * with the specified cap insets. * - * @see initWithFile:rect:centerRegion: + * @see initWithFile(const char *file, Rect rect, Rect capInsets) */ static Scale9Sprite* create(const char* file, Rect rect, Rect capInsets); @@ -71,7 +71,7 @@ public: * Creates a 9-slice sprite with a texture file. The whole texture will be * broken down into a 3×3 grid of equal blocks. * - * @see initWithFile:capInsets: + * @see initWithFile(Rect capInsets, const char *file) */ static Scale9Sprite* create(Rect capInsets, const char* file); @@ -79,7 +79,7 @@ public: * Creates a 9-slice sprite with a texture file and a delimitation zone. The * texture will be broken down into a 3×3 grid of equal blocks. * - * @see initWithFile:rect: + * @see initWithFile(const char *file, Rect rect) */ static Scale9Sprite* create(const char* file, Rect rect); @@ -87,7 +87,7 @@ public: * Creates a 9-slice sprite with a texture file. The whole texture will be * broken down into a 3×3 grid of equal blocks. * - * @see initWithFile: + * @see initWithFile(const char *file) */ static Scale9Sprite* create(const char* file); @@ -97,7 +97,7 @@ public: * to resize the sprite will all it's 9-slice goodness intract. * It respects the anchorPoint too. * - * @see initWithSpriteFrame: + * @see initWithSpriteFrame(SpriteFrame *spriteFrame) */ static Scale9Sprite* createWithSpriteFrame(SpriteFrame* spriteFrame); @@ -107,7 +107,7 @@ public: * to resize the sprite will all it's 9-slice goodness intract. * It respects the anchorPoint too. * - * @see initWithSpriteFrame:centerRegion: + * @see initWithSpriteFrame(SpriteFrame *spriteFrame, Rect capInsets) */ static Scale9Sprite* createWithSpriteFrame(SpriteFrame* spriteFrame, Rect capInsets); @@ -117,7 +117,7 @@ public: * to resize the sprite will all it's 9-slice goodness intract. * It respects the anchorPoint too. * - * @see initWithSpriteFrameName: + * @see initWithSpriteFrameName(const char *spriteFrameName) */ static Scale9Sprite* createWithSpriteFrameName(const char*spriteFrameName); @@ -128,7 +128,7 @@ public: * to resize the sprite will all it's 9-slice goodness intract. * It respects the anchorPoint too. * - * @see initWithSpriteFrameName:centerRegion: + * @see initWithSpriteFrameName(const char *spriteFrameName, Rect capInsets) */ static Scale9Sprite* createWithSpriteFrameName(const char*spriteFrameName, Rect capInsets); From 3c394da6a48ce2a6b472860d231ac47aca995688 Mon Sep 17 00:00:00 2001 From: Timothy Qiu Date: Fri, 9 Aug 2013 02:16:52 +0800 Subject: [PATCH 2/3] Changed two 'XXX class for cocos2d for iphone'. --- extensions/GUI/CCScrollView/CCScrollView.h | 2 +- extensions/GUI/CCScrollView/CCTableView.h | 5 ++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/extensions/GUI/CCScrollView/CCScrollView.h b/extensions/GUI/CCScrollView/CCScrollView.h index cf3c66a45f..886e894f76 100644 --- a/extensions/GUI/CCScrollView/CCScrollView.h +++ b/extensions/GUI/CCScrollView/CCScrollView.h @@ -48,7 +48,7 @@ public: /** - * ScrollView support for cocos2d for iphone. + * ScrollView support for cocos2d-x. * It provides scroll view functionalities to cocos2d projects natively. */ class ScrollView : public Layer diff --git a/extensions/GUI/CCScrollView/CCTableView.h b/extensions/GUI/CCScrollView/CCTableView.h index acbe9359ec..399b6a3e2e 100644 --- a/extensions/GUI/CCScrollView/CCTableView.h +++ b/extensions/GUI/CCScrollView/CCTableView.h @@ -124,10 +124,9 @@ public: /** - * UITableView counterpart for cocos2d for iphone. - * - * this is a very basic, minimal implementation to bring UITableView-like component into cocos2d world. + * UITableView support for cocos2d-x. * + * This is a very basic, minimal implementation to bring UITableView-like component into cocos2d world. */ class TableView : public ScrollView, public ScrollViewDelegate { From 2bb119baef024440250709c92f95f9b120210c5c Mon Sep 17 00:00:00 2001 From: Timothy Qiu Date: Fri, 9 Aug 2013 12:40:20 +0800 Subject: [PATCH 3/3] Documentation & Cocos2d-x C++ Style --- cocos2dx/cocoa/CCAutoreleasePool.cpp | 41 ++++++------ cocos2dx/cocoa/CCAutoreleasePool.h | 96 +++++++++++++++++++++++----- cocos2dx/cocoa/CCObject.cpp | 18 +++--- cocos2dx/cocoa/CCObject.h | 84 ++++++++++++++++++++---- 4 files changed, 180 insertions(+), 59 deletions(-) diff --git a/cocos2dx/cocoa/CCAutoreleasePool.cpp b/cocos2dx/cocoa/CCAutoreleasePool.cpp index a736f316ff..8c360e383a 100644 --- a/cocos2dx/cocoa/CCAutoreleasePool.cpp +++ b/cocos2dx/cocoa/CCAutoreleasePool.cpp @@ -28,31 +28,31 @@ NS_CC_BEGIN static PoolManager* s_pPoolManager = NULL; -AutoreleasePool::AutoreleasePool(void) +AutoreleasePool::AutoreleasePool() { _managedObjectArray = new Array(); _managedObjectArray->init(); } -AutoreleasePool::~AutoreleasePool(void) +AutoreleasePool::~AutoreleasePool() { CC_SAFE_DELETE(_managedObjectArray); } -void AutoreleasePool::addObject(Object* pObject) +void AutoreleasePool::addObject(Object* object) { - _managedObjectArray->addObject(pObject); + _managedObjectArray->addObject(object); - CCASSERT(pObject->_reference > 1, "reference count should be greater than 1"); - ++(pObject->_autoReleaseCount); - pObject->release(); // no ref count, in this case autorelease pool added. + CCASSERT(object->_reference > 1, "reference count should be greater than 1"); + ++(object->_autoReleaseCount); + object->release(); // no ref count, in this case autorelease pool added. } -void AutoreleasePool::removeObject(Object* pObject) +void AutoreleasePool::removeObject(Object* object) { - for (unsigned int i = 0; i < pObject->_autoReleaseCount; ++i) + for (unsigned int i = 0; i < object->_autoReleaseCount; ++i) { - _managedObjectArray->removeObject(pObject, false); + _managedObjectArray->removeObject(object, false); } } @@ -113,14 +113,13 @@ PoolManager::PoolManager() PoolManager::~PoolManager() { - - finalize(); + finalize(); // we only release the last autorelease pool here _curReleasePool = 0; - _releasePoolStack->removeObjectAtIndex(0); + _releasePoolStack->removeObjectAtIndex(0); - CC_SAFE_DELETE(_releasePoolStack); + CC_SAFE_DELETE(_releasePoolStack); } void PoolManager::finalize() @@ -156,12 +155,12 @@ void PoolManager::pop() return; } - int nCount = _releasePoolStack->count(); + int nCount = _releasePoolStack->count(); _curReleasePool->clear(); - if(nCount > 1) - { + if (nCount > 1) + { _releasePoolStack->removeObjectAtIndex(nCount-1); // if(nCount > 1) @@ -175,16 +174,16 @@ void PoolManager::pop() /*_curReleasePool = NULL;*/ } -void PoolManager::removeObject(Object* pObject) +void PoolManager::removeObject(Object* object) { CCASSERT(_curReleasePool, "current auto release pool should not be null"); - _curReleasePool->removeObject(pObject); + _curReleasePool->removeObject(object); } -void PoolManager::addObject(Object* pObject) +void PoolManager::addObject(Object* object) { - getCurReleasePool()->addObject(pObject); + getCurReleasePool()->addObject(object); } diff --git a/cocos2dx/cocoa/CCAutoreleasePool.h b/cocos2dx/cocoa/CCAutoreleasePool.h index c443b2a4b3..2cf6bb839d 100644 --- a/cocos2dx/cocoa/CCAutoreleasePool.h +++ b/cocos2dx/cocoa/CCAutoreleasePool.h @@ -36,36 +36,98 @@ NS_CC_BEGIN class CC_DLL AutoreleasePool : public Object { - Array* _managedObjectArray; + /** + * The underlying array of object managed by the pool. + * + * Although Array retains the object once when an object is added, proper + * Object::release() is called outside the array to make sure that the pool + * does not affect the managed object's reference count. So an object can + * be destructed properly by calling Object::release() even if the object + * is in the pool. + */ + Array *_managedObjectArray; public: - AutoreleasePool(void); - ~AutoreleasePool(void); + AutoreleasePool(); + ~AutoreleasePool(); - void addObject(Object *pObject); - void removeObject(Object *pObject); + /** + * Add a given object to this pool. + * + * The same object may be added several times to the same pool; When the + * pool is destructed, the object's Object::release() method will be called + * for each time it was added. + * + * @param object The object to add to the pool. + */ + void addObject(Object *object); + /** + * Remove a given object from this pool. + * + * @param object The object to be removed from the pool. + */ + void removeObject(Object *object); + + /** + * Clear the autorelease pool. + * + * Object::release() will be called for each time the managed object is + * added to the pool. + */ void clear(); }; class CC_DLL PoolManager { - Array* _releasePoolStack; - AutoreleasePool* _curReleasePool; + Array *_releasePoolStack; + AutoreleasePool *_curReleasePool; - AutoreleasePool* getCurReleasePool(); + AutoreleasePool *getCurReleasePool(); public: - PoolManager(); - ~PoolManager(); - void finalize(); - void push(); - void pop(); - - void removeObject(Object* pObject); - void addObject(Object* pObject); - static PoolManager* sharedPoolManager(); static void purgePoolManager(); + PoolManager(); + ~PoolManager(); + + /** + * Clear all the AutoreleasePool on the pool stack. + */ + void finalize(); + + /** + * Push a new AutoreleasePool to the pool stack. + */ + void push(); + + /** + * Pop one AutoreleasePool from the pool stack. + * + * This method will ensure that there is at least one AutoreleasePool on + * the stack. + * + * The AutoreleasePool being poped is destructed. + */ + void pop(); + + /** + * Remove a given object from the current autorelease pool. + * + * @param object The object to be removed. + * + * @see AutoreleasePool::removeObject + */ + void removeObject(Object *object); + + /** + * Add a given object to the current autorelease pool. + * + * @param object The object to add. + * + * @see AutoreleasePool::addObject + */ + void addObject(Object *object); + friend class AutoreleasePool; }; diff --git a/cocos2dx/cocoa/CCObject.cpp b/cocos2dx/cocoa/CCObject.cpp index fbc1fa9836..d79fa8151f 100644 --- a/cocos2dx/cocoa/CCObject.cpp +++ b/cocos2dx/cocoa/CCObject.cpp @@ -30,7 +30,7 @@ THE SOFTWARE. NS_CC_BEGIN -Object::Object(void) +Object::Object() : _luaID(0) , _reference(1) // when the object is created, the reference count of it is 1 , _autoReleaseCount(0) @@ -40,7 +40,7 @@ Object::Object(void) _ID = ++uObjectCount; } -Object::~Object(void) +Object::~Object() { // if the object is managed, we should remove it // from pool manager @@ -64,7 +64,7 @@ Object::~Object(void) } } -void Object::release(void) +void Object::release() { CCASSERT(_reference > 0, "reference count should greater than 0"); --_reference; @@ -75,32 +75,32 @@ void Object::release(void) } } -void Object::retain(void) +void Object::retain() { CCASSERT(_reference > 0, "reference count should greater than 0"); ++_reference; } -Object* Object::autorelease(void) +Object* Object::autorelease() { PoolManager::sharedPoolManager()->addObject(this); return this; } -bool Object::isSingleReference(void) const +bool Object::isSingleReference() const { return _reference == 1; } -unsigned int Object::retainCount(void) const +unsigned int Object::retainCount() const { return _reference; } -bool Object::isEqual(const Object *pObject) +bool Object::isEqual(const Object *object) { - return this == pObject; + return this == object; } void Object::acceptVisitor(DataVisitor &visitor) diff --git a/cocos2dx/cocoa/CCObject.h b/cocos2dx/cocoa/CCObject.h index a5d7b612cf..b1fe11b7c2 100644 --- a/cocos2dx/cocoa/CCObject.h +++ b/cocos2dx/cocoa/CCObject.h @@ -64,25 +64,85 @@ public: class CC_DLL Object { public: - // object id, ScriptSupport need public _ID + /// object id, ScriptSupport need public _ID unsigned int _ID; - // Lua reference id + /// Lua reference id int _luaID; protected: - // count of references + /// count of references unsigned int _reference; - // count of autorelease + /// count of autorelease unsigned int _autoReleaseCount; public: - Object(void); - virtual ~Object(void); + /** + * Constructor + * + * The object's reference count is 1 after construction. + */ + Object(); + + virtual ~Object(); - void release(void); - void retain(void); - Object* autorelease(void); - bool isSingleReference(void) const; - unsigned int retainCount(void) const; - virtual bool isEqual(const Object* pObject); + /** + * Release the ownership immediately. + * + * This decrements the object's reference count. + * + * If the reference count reaches 0 after the descrement, this object is + * destructed. + * + * @see retain, autorelease + */ + void release(); + + /** + * Retains the ownership. + * + * This increases the object's reference count. + * + * @see release, autorelease + */ + void retain(); + + /** + * Release the ownership sometime soon automatically. + * + * This descrements the object's reference count at the end of current + * autorelease pool block. + * + * If the reference count reaches 0 after the descrement, this object is + * destructed. + * + * @returns The object itself. + * + * @see AutoreleasePool, retain, release + */ + Object* autorelease(); + + /** + * Returns a boolean value that indicates whether there is only one + * reference to the object. That is, whether the reference count is 1. + * + * @returns Whether the object's reference count is 1. + */ + bool isSingleReference() const; + + /** + * Returns the object's current reference count. + * + * @returns The object's reference count. + */ + unsigned int retainCount() const; + + /** + * Returns a boolean value that indicates whether this object and a given + * object are equal. + * + * @param object The object to be compared to this object. + * + * @returns True if this object and @p object are equal, otherwise false. + */ + virtual bool isEqual(const Object* object); virtual void acceptVisitor(DataVisitor &visitor);