Outdated Docs > Easy to Learn - API Style

Easy to Learn - API Style

Two phase constructor and static create() function

Cocos2d-x uses a 2-phase constructor. This isn't new. Objective-C implementations, Symbian SDK and Bada SDK are similar in construct.

The first phase is running the class constructor. In the C++ class’s default constructor, member variables should be set to default values. We shouldn’t write any logic in the default constructor. Example:

:m_pData(NULL) // set all member variables to default values
    memset(m_Array, 0, sizeof(m_Array)); // only set default values here, but not logics

The reason we SHOULD NOT write any logic here is because the C++ default constructor cannot return a bool value which indicates whether our logic is correct or not.
A try{} catch{} can also return failure status to the caller but will increase the compiled binary size of your source code.

The second phase is to invoke MyClass::init() function, like this.

bool MyClass::initWithFilename(const char* filename)
    // just take loading texture as a sample, this behaviour can fail if the image file doesn't exist. 
    bool bReturnValue = loadTextureIntoMemory(filename);  
    return bReturnValue;

So we can construct + init MyClass like this

MyClass* obj = new MyClass;
if (true == obj->initWithFilename("texture.png"))
    // congratulations, go ahead!
    // error process

In cocos2d-x, we wrapped this 2-phase constructor and auto-released reference count together into a static function: create(). Each cocos2d class, except singletons, has its static CCClass* CCClass::create(...) method. This method is highly recommended. Sample code:

CCSprite* _sprite = CCSprite::create("Monster.png");
_sprite->setPosition(ccp(visibleSize.width/2 + origin.x, visibleSize.height/2 + origin.y));

As a result, when you want to new a cocos2d-x object, like CCSprite, CCLabelTTF, CCAction, you should firstly find its CCBlabla::create() method from header file or API documentation.


This is the most common style of function names. It’s applied everywhere in cocos2d-x/-html5. The first word is a verb, and the second word is a noun. Such as replaceScene(CCScene*), getTexture().


It’s a transform of doSomething() method. You can usually see it in initWithTexture(CCTexture*), initWithFilename(const char*).


When you see a function name like this void onEnter(), the “onAction” style means that, it’s a callback function. Other classes will invoke this method if some condition triggers. For example:

class CCLayer
    virtual void onEnter();
    virtual void onExit();
    virtual void onEnterTransitionDidFinish();

This style hasn’t been applied on all callback methods according to historic reasons. We need to keep the compatibility with old versions. The bad case is CCTouchDelegate, its callbacks are still named as bool ccTouchBegan(...), bool ccTouchMoved(...) etc. We may modify these in future versions.

h2.sharedInstance() and getInstance()

In cocos2d-x, if you can find a sharedXxxx method instead of create(), then it’s a singleton class. For example, CCDirector::sharedDirector(). This style is inherit from cocos2d-iphone and objective-c. Since we don’t consider this a good naming style, in cocos2d-html5 and Javascript binding API, we use getInstance() instead. e.g. cc.TextureCache.getInstance(), cc.Director.getInstance(). Cocos2d-x will sync with it in the future, v3.0 maybe.


There is no “property” concept in C*+ or C*+11 so we use many getter/setters in Cocos2d-x.


To change a property’s value. It usually affects the object’s behaviour. e.g. _sprite->setPosition(ccp(0,0)) will move this sprite to bottom-left corner.


Different from setProperty, getProperty will never change the object’s member variables and behaviours. e.g., we usually get visible size or windows size to calculate items’ positions like this _director->getVisibleSize().width.
The default style of getProperty() looks like:

const CCSize& getSize() const;

Firstly, according to the performance optimisation, here we returns a CCSize reference instead of construct another CCSize. When changing this CCSize& would affects the object’s internal member variable, so this CCSize& is const.
And secondly, getSize() method should not change the object’s other member variables, so this function itself is const.


The same as getProperty but returns a boolean value.

To sum up:
* if a property is a READ-ONLY one, it will have no setProperty(type) method;
* if a property IS a bool value, it will have setProperty(bool) and isProperty pair. e.g. CCSprite::isDirty() and CCSprite::setDirty(bool bDirty).
* if a property IS NOT a bool value, it will have setProperty(type) and getProperty pair. e.g. void CCSprite::setTexture(CCTexture2D*) and CCTexture2D* CCSprite::getTexture()

Need to re-edit documentation

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.