diff --git a/cocos/2d/CCFont.h b/cocos/2d/CCFont.h index d79d394730..4f893cf56a 100644 --- a/cocos/2d/CCFont.h +++ b/cocos/2d/CCFont.h @@ -33,9 +33,7 @@ NS_CC_BEGIN class FontAtlas; -// fwd -class FontAtlas; - +/// @cond class CC_DLL Font : public Ref { @@ -67,7 +65,8 @@ protected: }; +/// @endcond + NS_CC_END - #endif diff --git a/cocos/2d/CCFontAtlas.h b/cocos/2d/CCFontAtlas.h index 3925b9927c..eecc8eeb53 100644 --- a/cocos/2d/CCFontAtlas.h +++ b/cocos/2d/CCFontAtlas.h @@ -40,6 +40,8 @@ class Texture2D; class EventCustom; class EventListenerCustom; +/// @cond + struct FontLetterDefinition { unsigned short letteCharUTF16; @@ -128,6 +130,7 @@ protected: bool _antialiasEnabled; }; +/// @endcond NS_CC_END diff --git a/cocos/2d/CCFontAtlasCache.h b/cocos/2d/CCFontAtlasCache.h index 1fc473c22d..2d1968b13d 100644 --- a/cocos/2d/CCFontAtlasCache.h +++ b/cocos/2d/CCFontAtlasCache.h @@ -34,6 +34,8 @@ NS_CC_BEGIN class FontAtlas; +/// @cond + class CC_DLL FontAtlasCache { public: @@ -56,6 +58,8 @@ private: static std::unordered_map _atlasMap; }; +/// @endcond + NS_CC_END #endif diff --git a/cocos/2d/CCFontCharMap.h b/cocos/2d/CCFontCharMap.h index c902a35192..7cafb77f02 100644 --- a/cocos/2d/CCFontCharMap.h +++ b/cocos/2d/CCFontCharMap.h @@ -30,6 +30,8 @@ NS_CC_BEGIN +/// @cond + class FontCharMap : public Font { public: @@ -61,6 +63,8 @@ private: }; +/// @endcond + NS_CC_END #endif /* defined(_CCFontCharMap_h_) */ diff --git a/cocos/2d/CCFontFNT.h b/cocos/2d/CCFontFNT.h index 78413fcf53..f414741c5e 100644 --- a/cocos/2d/CCFontFNT.h +++ b/cocos/2d/CCFontFNT.h @@ -32,6 +32,8 @@ NS_CC_BEGIN class BMFontConfiguration; +/// @cond FontFNT + class CC_DLL FontFNT : public Font { @@ -63,6 +65,8 @@ private: }; +/// @endcond + NS_CC_END #endif /* defined(__cocos2d_libs__CCFontFNT__) */ diff --git a/cocos/2d/CCFontFreeType.h b/cocos/2d/CCFontFreeType.h index 71e2f413f3..fbe3930954 100644 --- a/cocos/2d/CCFontFreeType.h +++ b/cocos/2d/CCFontFreeType.h @@ -44,9 +44,10 @@ #undef internal #endif - NS_CC_BEGIN +/// @cond + class CC_DLL FontFreeType : public Font { public: @@ -91,6 +92,8 @@ private: float _outlineSize; }; +/// @endcond + NS_CC_END #endif diff --git a/cocos/2d/CCLabel.h b/cocos/2d/CCLabel.h index c62f2e0a34..048e82a78b 100644 --- a/cocos/2d/CCLabel.h +++ b/cocos/2d/CCLabel.h @@ -1,6 +1,6 @@ /**************************************************************************** Copyright (c) 2013 Zynga Inc. - Copyright (c) 2013-2014 Chukong Technologies Inc. + Copyright (c) 2013-2015 Chukong Technologies Inc. http://www.cocos2d-x.org @@ -23,7 +23,6 @@ THE SOFTWARE. ****************************************************************************/ - #ifndef _COCOS2D_CCLABEL_H_ #define _COCOS2D_CCLABEL_H_ @@ -33,22 +32,39 @@ NS_CC_BEGIN +/** +* @addtogroup GUI +* @{ +* @addtogroup Label +* @{ +*/ + +/** + * @brief Possible GlyphCollection used by Label. + * + */ enum class GlyphCollection { - DYNAMIC, NEHE, ASCII, CUSTOM }; +/** + * @brief Possible LabelEffect used by Label. + * + */ enum class LabelEffect { - NORMAL, OUTLINE, SHADOW, GLOW }; +/** + * @struct TTFConfig + * + */ typedef struct _ttfConfig { std::string fontFilePath; @@ -74,171 +90,347 @@ typedef struct _ttfConfig } }TTFConfig; +/** + * @brief Label is a subclass of SpriteBatchNode that knows how to render text labels. + * + * Label can be created with: + * - A true type font file. + * - A bitmap font file. + * - A char map file. + * - The built in system font. + * + * Bitmap Font supported editors: + * - http://glyphdesigner.71squared.com/ (Commercial, Mac OS X) + * - http://www.n4te.com/hiero/hiero.jnlp (Free, Java) + * - http://slick.cokeandcode.com/demos/hiero.jnlp (Free, Java) + * - http://www.angelcode.com/products/bmfont/ (Free, Windows only) + */ class CC_DLL Label : public SpriteBatchNode, public LabelProtocol { public: static const int DistanceFieldFontSize; + /// @name Creators + /// @{ + + /** + * Allocates and initializes a Label, with default settings. + * + * @return An automatically released Label object. + */ static Label* create(); - /** Creates a label with an initial string,font[font name or font file],font size, dimension in points, horizontal alignment and vertical alignment. - * @warning It will generate texture by the platform-dependent code + /** + * Allocates and initializes a Label, base on platform-dependent API. + * + * @param text The initial text. + * @param font A font file or a font family name. + * @param fontSize The font size. This value must be > 0. + * @param dimensions + * @param hAlignment The text horizontal alignment. + * @param vAlignment The text vertical alignment. + * + * @warning It will generate texture by the platform-dependent code. + * + * @return An automatically released Label object. */ static Label* createWithSystemFont(const std::string& text, const std::string& font, float fontSize, const Size& dimensions = Size::ZERO, TextHAlignment hAlignment = TextHAlignment::LEFT, TextVAlignment vAlignment = TextVAlignment::TOP); - /** Creates a label with an initial string,font file,font size, dimension in points, horizontal alignment and vertical alignment. - * @warning Not support font name. - * @warning Cache textures for each different font size or font file. - */ - static Label * createWithTTF(const std::string& text, const std::string& fontFile, float fontSize, + /** + * Allocates and initializes a Label, base on FreeType2. + * + * @param text The initial text. + * @param fontFilePath A font file. + * @param fontSize The font size. This value must be > 0. + * @param dimensions + * @param hAlignment The text horizontal alignment. + * @param vAlignment The text vertical alignment. + * + * @return An automatically released Label object. + */ + static Label * createWithTTF(const std::string& text, const std::string& fontFilePath, float fontSize, const Size& dimensions = Size::ZERO, TextHAlignment hAlignment = TextHAlignment::LEFT, TextVAlignment vAlignment = TextVAlignment::TOP); - /** Create a label with TTF configuration - * @warning Not support font name. - * @warning Cache textures for each different font file when enable distance field. - * @warning Cache textures for each different font size or font file when disable distance field. - */ - static Label* createWithTTF(const TTFConfig& ttfConfig, const std::string& text, TextHAlignment alignment = TextHAlignment::LEFT, int maxLineWidth = 0); + /** + * Allocates and initializes a Label, base on FreeType2. + * + * @param ttfConfig A pointer to a TTFConfig object. + * @param text The initial text. + * @param hAlignment The text horizontal alignment. + * @param maxLineWidth The max line width. + * + * @return An automatically released Label object. + * @see TTFConfig setTTFConfig setMaxLineWidth + */ + static Label* createWithTTF(const TTFConfig& ttfConfig, const std::string& text, TextHAlignment hAlignment = TextHAlignment::LEFT, int maxLineWidth = 0); - /* Creates a label with an FNT file,an initial string,horizontal alignment,max line width and the offset of image*/ - static Label* createWithBMFont(const std::string& bmfontFilePath, const std::string& text, - const TextHAlignment& alignment = TextHAlignment::LEFT, int maxLineWidth = 0, + /** + * Allocates and initializes a Label, with a bitmap font file. + * + * @param bmfontPath A bitmap font file, it's a FNT format. + * @param text The initial text. + * @param hAlignment Text horizontal alignment. + * @param maxLineWidth The max line width. + * @param imageOffset + * + * @return An automatically released Label object. + * @see setBMFontFilePath setMaxLineWidth + */ + static Label* createWithBMFont(const std::string& bmfontPath, const std::string& text, + const TextHAlignment& hAlignment = TextHAlignment::LEFT, int maxLineWidth = 0, const Vec2& imageOffset = Vec2::ZERO); + /** + * Allocates and initializes a Label, with char map configuration. + * + * @param charMapFile A char map file, it's a PNG format. + * @param itemWidth The width in points of each element. + * @param itemHeight The height in points of each element. + * @param startCharMap The starting char of the char map. + * + * @return An automatically released Label object. + */ static Label * createWithCharMap(const std::string& charMapFile, int itemWidth, int itemHeight, int startCharMap); + + /** + * Allocates and initializes a Label, with char map configuration. + * + * @param texture A pointer to an existing Texture2D object. + * @param itemWidth The width in points of each element. + * @param itemHeight The height in points of each element. + * @param startCharMap The starting char of the char map. + * + * @return An automatically released Label object. + */ static Label * createWithCharMap(Texture2D* texture, int itemWidth, int itemHeight, int startCharMap); + + /** + * Allocates and initializes a Label, with char map configuration. + * + * @param plistFile A configuration file of char map. + * + * @return An automatically released Label object. + */ static Label * createWithCharMap(const std::string& plistFile); - /** set TTF configuration for Label */ + // end of creators group + /// @} + + /// @{ + /// @name Font methods + + /** + * Sets a new TTF configuration to Label. + * @see `TTFConfig` + */ virtual bool setTTFConfig(const TTFConfig& ttfConfig); + + /** + * Returns the TTF configuration object used by the Label. + * @see `TTFConfig` + */ virtual const TTFConfig& getTTFConfig() const { return _fontConfig;} + /** Sets a new bitmap font to Label */ virtual bool setBMFontFilePath(const std::string& bmfontFilePath, const Vec2& imageOffset = Vec2::ZERO); + + /** Returns the bitmap font used by the Label.*/ const std::string& getBMFontFilePath() const { return _bmFontPath;} + /** + * Sets a new char map configuration to Label. + * + * @see `createWithCharMap(const std::string&,int,int,int)` + */ virtual bool setCharMap(const std::string& charMapFile, int itemWidth, int itemHeight, int startCharMap); + + /** + * Sets a new char map configuration to Label. + * + * @see `createWithCharMap(Texture2D*,int,int,int)` + */ virtual bool setCharMap(Texture2D* texture, int itemWidth, int itemHeight, int startCharMap); + + /** + * Sets a new char map configuration to Label. + * + * @see `createWithCharMap(const std::string&)` + */ virtual bool setCharMap(const std::string& plistFile); - /* Sets the system font[font name or font file] of label*/ - virtual void setSystemFontName(const std::string& systemFont); + /** + * Sets a new system font to Label. + * + * @param font A font file or a font family name. + * @warning + */ + virtual void setSystemFontName(const std::string& font); + + /** Returns the system font used by the Label.*/ virtual const std::string& getSystemFontName() const { return _systemFont;} - /* Sets the system font size of label.*/ + /* Sets the system font size of Label.*/ virtual void setSystemFontSize(float fontSize); + + /** Returns the bitmap font path used by the Label.*/ virtual float getSystemFontSize() const { return _systemFontSize;} + /** + * @warning This method is not recommended for game developers. + */ virtual void requestSystemFontRefresh() { _systemFontDirty = true;} - /** changes the string to render - * @warning It is as expensive as changing the string if you haven't set up TTF/BMFont/CharMap for the label. - */ + + // end of font methods + /// @} + + /** Sets the text that this Label is to display.*/ virtual void setString(const std::string& text) override; + /** Return the text the Label is displaying.*/ virtual const std::string& getString() const override { return _originalUTF8String; } - /** Sets the text color of the label - * Only support for TTF and system font - * @warning Different from the color of Node. + int getStringNumLines() const; + + int getStringLength() const; + + /** + * Sets the text color of Label. + * + * The text color is different from the color of Node. + * + * @warning Limiting use to only when the Label created with true type font or system font. */ virtual void setTextColor(const Color4B &color); - /** Returns the text color of this label - * Only support for TTF and system font - * @warning Different from the color of Node. - */ + + /** Returns the text color of the Label.*/ const Color4B& getTextColor() const { return _textColor;} /** - * Enable shadow for the label + * Enable shadow effect to Label. * - * @todo support blur for shadow effect + * @todo Support blur for shadow effect. */ virtual void enableShadow(const Color4B& shadowColor = Color4B::BLACK,const Size &offset = Size(2,-2), int blurRadius = 0); - /** only support for TTF */ + /** + * Enable outline effect to Label. + * @warning Limiting use to only when the Label created with true type font or system font. + */ virtual void enableOutline(const Color4B& outlineColor,int outlineSize = -1); - /** only support for TTF */ + /** + * Enable glow effect to Label. + * @warning Limiting use to only when the Label created with true type font. + */ virtual void enableGlow(const Color4B& glowColor); - /** disable shadow/outline/glow rendering */ + /** + * Disable all effect to Label. + */ virtual void disableEffect(); + /** Sets the Label's text horizontal alignment.*/ void setAlignment(TextHAlignment hAlignment) { setAlignment(hAlignment,_vAlignment);} + + /** Returns the Label's text horizontal alignment.*/ TextHAlignment getTextAlignment() const { return _hAlignment;} + /** Sets the Label's text alignment.*/ void setAlignment(TextHAlignment hAlignment,TextVAlignment vAlignment); + /** Sets the Label's text horizontal alignment.*/ void setHorizontalAlignment(TextHAlignment hAlignment) { setAlignment(hAlignment,_vAlignment); } + + /** Returns the Label's text horizontal alignment.*/ TextHAlignment getHorizontalAlignment() const { return _hAlignment; } + /** Sets the Label's text vertical alignment.*/ void setVerticalAlignment(TextVAlignment vAlignment) { setAlignment(_hAlignment,vAlignment); } + + /** Returns the Label's text vertical alignment.*/ TextVAlignment getVerticalAlignment() const { return _vAlignment; } + /** + * Specify what happens when a line is too long for Label. + * + * @param breakWithoutSpace Lines are automatically broken between words if this value is false. + */ void setLineBreakWithoutSpace(bool breakWithoutSpace); - /** Sets the max line width of the label. - * The label's max line width be used for force line breaks if the set value not equal zero. - * The label's width and max line width has not always to be equal. + /** + * Makes the Label at most this line untransformed width. + * The Label's max line width be used for force line breaks if the value not equal zero. */ void setMaxLineWidth(float maxLineWidth); float getMaxLineWidth() { return _maxLineWidth; } - /** Sets the untransformed size of the label. - * The label's width be used for text align if the set value not equal zero. - * The label's max line width will be equal to the same value. + /** + * Makes the Label exactly this untransformed width. + * + * The Label's width be used for text align if the value not equal zero. */ void setWidth(float width) { setDimensions(width,_labelHeight);} float getWidth() const { return _labelWidth; } - /** Sets the untransformed size of the label. - * The label's height be used for text align if the set value not equal zero. - * The text will display of incomplete when the size of label not enough to support display all text. + /** + * Makes the Label exactly this untransformed height. + * + * The Label's height be used for text align if the value not equal zero. + * The text will display of incomplete when the size of Label not enough to support display all text. */ void setHeight(float height){ setDimensions(_labelWidth, height); } float getHeight() const { return _labelHeight; } - /** Sets the untransformed size of the label in a more efficient way. */ + /** Sets the untransformed size of the Label in a more efficient way. */ void setDimensions(float width, float height); const Size& getDimensions() const{ return _labelDimensions;} - /** update content immediately.*/ + /** Update content immediately.*/ virtual void updateContent(); + /** + * Provides a way to treats each character like a Sprite. + * @warning No support system font. + */ virtual Sprite * getLetter(int lettetIndex); - /** clip upper and lower margin for reduce height of label. - */ + /** Makes the Label to clip upper and lower margin for reduce height of Label.*/ void setClipMarginEnabled(bool clipEnabled) { _clipEnabled = clipEnabled; } + bool isClipMarginEnabled() const { return _clipEnabled; } - /** Sets the line height of the label - @warning Not support system font - @since v3.2.0 + /** Sets the line height of the Label. + * @warning Not support system font. + * @since v3.2.0 */ void setLineHeight(float height); - /** Returns the line height of this label - @warning Not support system font + + /** + * Returns the line height of this Label. + * @warning Not support system font. + * @since v3.2.0 */ float getLineHeight() const; - /** Sets the additional kerning of the label - @warning Not support system font - @since v3.2.0 + /** + * Sets the additional kerning of the Label. + * + * @warning Not support system font. + * @since v3.2.0 */ void setAdditionalKerning(float space); - /** Returns the additional kerning of this label - @warning Not support system font - @since v3.2.0 + + /** + * Returns the additional kerning of the Label. + * + * @warning Not support system font. + * @since v3.2.0 */ float getAdditionalKerning() const; - // string related stuff - int getStringNumLines() const; - int getStringLength() const; - FontAtlas* getFontAtlas() { return _fontAtlas; } virtual void setBlendFunc(const BlendFunc &blendFunc) override; @@ -275,15 +467,21 @@ public: CC_DEPRECATED_ATTRIBUTE virtual void setFontDefinition(const FontDefinition& textDefinition); CC_DEPRECATED_ATTRIBUTE const FontDefinition& getFontDefinition() const { return _fontDefinition; } + /** + * @deprecated Use `getLineHeight` instead. + */ CC_DEPRECATED_ATTRIBUTE int getCommonLineHeight() const { return (int)getLineHeight();} CC_CONSTRUCTOR_ACCESS: /** + * Constructor of Label. * @js NA */ Label(FontAtlas *atlas = nullptr, TextHAlignment hAlignment = TextHAlignment::LEFT, TextVAlignment vAlignment = TextVAlignment::TOP,bool useDistanceField = false,bool useA8Shader = false); + /** + * Destructor of Label. * @js NA * @lua NA */ @@ -407,7 +605,8 @@ protected: bool _clipEnabled; bool _blendFuncDirty; - bool _insideBounds; /// whether or not the sprite was inside bounds the previous frame + /// whether or not the sprite was inside bounds the previous frame + bool _insideBounds; private: CC_DISALLOW_COPY_AND_ASSIGN(Label); @@ -415,6 +614,9 @@ private: friend class LabelTextFormatter; }; +// end group +/// @} +/// @} NS_CC_END diff --git a/cocos/2d/CCLabelAtlas.h b/cocos/2d/CCLabelAtlas.h index 87caad6fc2..e90111bedc 100644 --- a/cocos/2d/CCLabelAtlas.h +++ b/cocos/2d/CCLabelAtlas.h @@ -41,47 +41,53 @@ NS_CC_BEGIN * @{ */ -/** @brief LabelAtlas is a subclass of AtlasNode. - -It can be as a replacement of Label since it is MUCH faster. - -LabelAtlas versus Label: -- LabelAtlas is MUCH faster than Label -- LabelAtlas "characters" have a fixed height and width -- LabelAtlas "characters" can be anything you want since they are taken from an image file - -A more flexible class is LabelBMFont. It supports variable width characters and it also has a nice editor. -*/ +/** + * @class LabelAtlas + * @brief LabelAtlas is a subclass of AtlasNode. + * + * It can be as a replacement of Label since it is MUCH faster. + * + * LabelAtlas versus Label: + * - LabelAtlas is MUCH faster than Label. + * - LabelAtlas "characters" have a fixed height and width. + * - LabelAtlas "characters" can be anything you want since they are taken from an image file. + * + * A more flexible class is LabelBMFont. It supports variable width characters and it also has a nice editor. + */ class CC_DLL LabelAtlas : public AtlasNode, public LabelProtocol { public: - /** creates an empty LabelAtlas, user need to call initWithString(...) later to make this object work properly **/ + /** + * Creates an empty LabelAtlas. + * User need to call initWithString(...) later to make this object work properly. + */ static LabelAtlas* create(); - /** creates the LabelAtlas with a string, a char map file(the atlas), the width and height of each element and the starting char of the atlas */ + /** Creates the LabelAtlas with a string, a char map file(the atlas), the width and height of each element and the starting char of the atlas. */ static LabelAtlas* create(const std::string& string, const std::string& charMapFile, int itemWidth, int itemHeight, int startCharMap); - /** creates the LabelAtlas with a string and a configuration file - @since v2.0 + /** + * Creates the LabelAtlas with a string and a configuration file. + * @since v2.0 */ static LabelAtlas* create(const std::string& string, const std::string& fntFile); - /** initializes the LabelAtlas with a string, a char map file(the atlas), the width and height of each element and the starting char of the atlas */ + /** Initializes the LabelAtlas with a string, a char map file(the atlas), the width and height of each element and the starting char of the atlas. */ bool initWithString(const std::string& string, const std::string& charMapFile, int itemWidth, int itemHeight, int startCharMap); - /** initializes the LabelAtlas with a string and a configuration file - @since v2.0 + /** + * Initializes the LabelAtlas with a string and a configuration file. + * @since v2.0 */ bool initWithString(const std::string& string, const std::string& fntFile); - /** initializes the LabelAtlas with a string, a texture, the width and height in points of each element and the starting char of the atlas */ + /** Initializes the LabelAtlas with a string, a texture, the width and height in points of each element and the starting char of the atlas */ bool initWithString(const std::string& string, Texture2D* texture, int itemWidth, int itemHeight, int startCharMap); - // super methods - virtual void updateAtlasValues() override; - virtual void setString(const std::string &label) override; virtual const std::string& getString(void) const override; + + virtual void updateAtlasValues() override; virtual std::string getDescription() const override; #if CC_LABELATLAS_DEBUG_DRAW @@ -112,7 +118,7 @@ protected: // string to render std::string _string; - // the first char in the charmap + // the first char in the char map int _mapStartChar; }; diff --git a/cocos/2d/CCLabelBMFont.h b/cocos/2d/CCLabelBMFont.h index 88f380d122..b6982be760 100644 --- a/cocos/2d/CCLabelBMFont.h +++ b/cocos/2d/CCLabelBMFont.h @@ -42,6 +42,8 @@ Use any of these editors to generate BMFonts: NS_CC_BEGIN +/// @cond + #if defined(__GNUC__) && ((__GNUC__ >= 4) || ((__GNUC__ == 3) && (__GNUC_MINOR__ >= 1))) #pragma GCC diagnostic ignored "-Wdeprecated-declarations" #elif _MSC_VER >= 1400 //vs 2005 or higher @@ -154,6 +156,9 @@ private: #elif _MSC_VER >= 1400 //vs 2005 or higher #pragma warning (pop) #endif + +/// @endcond + NS_CC_END #endif //__CCBITMAP_FONT_ATLAS_H__ diff --git a/cocos/2d/CCLabelTTF.h b/cocos/2d/CCLabelTTF.h index f83b77a1cc..6ac50ad0ff 100644 --- a/cocos/2d/CCLabelTTF.h +++ b/cocos/2d/CCLabelTTF.h @@ -37,6 +37,8 @@ NS_CC_BEGIN #pragma warning (disable: 4996) #endif +/// @cond + class Label; /** @@ -173,6 +175,9 @@ protected: #elif _MSC_VER >= 1400 //vs 2005 or higher #pragma warning (pop) #endif + +/// @endcond + NS_CC_END #endif //__CCLABEL_H__ diff --git a/cocos/2d/CCLabelTextFormatter.h b/cocos/2d/CCLabelTextFormatter.h index abd9155e59..16b7c294ad 100644 --- a/cocos/2d/CCLabelTextFormatter.h +++ b/cocos/2d/CCLabelTextFormatter.h @@ -32,6 +32,7 @@ NS_CC_BEGIN class Label; +/// @cond class CC_DLL LabelTextFormatter { public: @@ -42,6 +43,8 @@ public: }; +/// @endcond + NS_CC_END #endif diff --git a/cocos/audio/include/AudioEngine.h b/cocos/audio/include/AudioEngine.h index 3fbe9867c9..7690a62907 100644 --- a/cocos/audio/include/AudioEngine.h +++ b/cocos/audio/include/AudioEngine.h @@ -40,18 +40,28 @@ #undef ERROR #endif // ERROR +/** +* @addtogroup Audio +* @{ +*/ + NS_CC_BEGIN namespace experimental{ +/** + * @class AudioProfile + * + * @brief + */ class EXPORT_DLL AudioProfile { public: - //name can't be empty + //Profile name can't be empty. std::string name; - + //The maximum number of simultaneous audio instance. unsigned int maxInstances; - /* minimum delay in between sounds */ + /* Minimum delay in between sounds */ double minDelay; AudioProfile() @@ -65,14 +75,17 @@ public: class AudioEngineImpl; /** - @class AudioEngine - @brief - @note + * @class AudioEngine + * + * @brief Offers a interface to play audio. + * + * @note Make sure to call AudioEngine::end() when the audio engine is not needed anymore to release resources. */ class EXPORT_DLL AudioEngine { public: + /** AudioState enum,all possible states of an audio instance.*/ enum class AudioState { ERROR = -1, @@ -86,132 +99,179 @@ public: static const float TIME_UNKNOWN; static bool lazyInit(); + /** - * Release related objects - @warning It must be called before the application exit + * Release objects relating to AudioEngine. + * + * @warning It must be called before the application exit. */ static void end(); - /** Gets the default profile of audio instances - * @return the default profile of audio instances + /** + * Gets the default profile of audio instances. + * + * @return The default profile of audio instances. */ static AudioProfile* getDefaultProfile(); - /** Play 2d sound - * @param filePath The path of an audio file - * @param loop Whether audio instance loop or not - * @param volume volume value (range from 0.0 to 1.0) - * @param profile a profile for audio instance - * @return an audio ID. It allows you to dynamically change the behavior of an audio instance on the fly. + /** + * Play 2d sound. + * + * @param filePath The path of an audio file. + * @param loop Whether audio instance loop or not. + * @param volume Volume value (range from 0.0 to 1.0). + * @param profile A profile for audio instance. When profile is not specified, default profile will be used. + * @return An audio ID. It allows you to dynamically change the behavior of an audio instance on the fly. + * + * @see `AudioProfile` */ static int play2d(const std::string& filePath, bool loop = false, float volume = 1.0f, const AudioProfile *profile = nullptr); - /** Sets whether an audio instance loop or not. - @param audioID an audioID returned by the play2d function - @param loop Whether audio instance loop or not + /** + * Sets whether an audio instance loop or not. + * + * @param audioID An audioID returned by the play2d function. + * @param loop Whether audio instance loop or not. */ static void setLoop(int audioID, bool loop); - /** Checks whether an audio instance is loop. - * @param audioID an audioID returned by the play2d function + /** + * Checks whether an audio instance is loop. + * + * @param audioID An audioID returned by the play2d function. * @return Whether or not an audio instance is loop. */ static bool isLoop(int audioID); - /** Sets volume for an audio instance. - * @param audioID an audioID returned by the play2d function - * @param volume volume value (range from 0.0 to 1.0) + /** + * Sets volume for an audio instance. + * + * @param audioID An audioID returned by the play2d function. + * @param volume Volume value (range from 0.0 to 1.0). */ static void setVolume(int audioID, float volume); - /** Gets the volume value of an audio instance. - * @param audioID an audioID returned by the play2d function - * @return volume value (range from 0.0 to 1.0) + /** + * Gets the volume value of an audio instance. + * + * @param audioID An audioID returned by the play2d function. + * @return Volume value (range from 0.0 to 1.0). */ static float getVolume(int audioID); - /** Pause an audio instance. - * @param audioID an audioID returned by the play2d function + /** + * Pause an audio instance. + * + * @param audioID An audioID returned by the play2d function. */ static void pause(int audioID); - /** Pause all playing audio instances */ + /** Pause all playing audio instances. */ static void pauseAll(); - /** Resume an audio instance. - * @param audioID an audioID returned by the play2d function + /** + * Resume an audio instance. + * + * @param audioID An audioID returned by the play2d function. */ static void resume(int audioID); - /** Resume all suspended audio instances */ + /** Resume all suspended audio instances. */ static void resumeAll(); - /** Stop an audio instance. - * @param audioID an audioID returned by the play2d function + /** + * Stop an audio instance. + * + * @param audioID An audioID returned by the play2d function. */ static void stop(int audioID); - /** Stop all audio instances */ + /** Stop all audio instances. */ static void stopAll(); - /** Sets the current playback position of an audio instance. - * @param audioID an audioID returned by the play2d function + /** + * Sets the current playback position of an audio instance. + * + * @param audioID An audioID returned by the play2d function. * @return */ static bool setCurrentTime(int audioID, float time); - /** Gets the current playback position of an audio instance. - * @param audioID an audioID returned by the play2d function - * @return the current playback position of an audio instance + /** + * Gets the current playback position of an audio instance. + * + * @param audioID An audioID returned by the play2d function. + * @return The current playback position of an audio instance. */ static float getCurrentTime(int audioID); - /** Gets the duration of an audio instance. - * @param audioID an audioID returned by the play2d function - * @return the duration of an audio instance + /** + * Gets the duration of an audio instance. + * + * @param audioID An audioID returned by the play2d function. + * @return The duration of an audio instance. */ static float getDuration(int audioID); - /** Returns the state of an audio instance. - * @param audioID an audioID returned by the play2d function - * @return the status of an audio instance + /** + * Returns the state of an audio instance. + * + * @param audioID An audioID returned by the play2d function. + * @return The status of an audio instance. */ static AudioState getState(int audioID); - /** Register a callback to be invoked when an audio instance has completed playing. - * @param audioID an audioID returned by the play2d function - * @param callback + /** + * Register a callback to be invoked when an audio instance has completed playing. + * + * @param audioID An audioID returned by the play2d function. + * @param callback */ static void setFinishCallback(int audioID, const std::function& callback); + /** + * Gets the maximum number of simultaneous audio instance of AudioEngine. + */ static int getMaxAudioInstance() {return _maxInstances;} + /** + * Sets the maximum number of simultaneous audio instance for AudioEngine. + * + * @param maxInstances The maximum number of simultaneous audio instance. + */ static bool setMaxAudioInstance(int maxInstances); - /** Uncache the audio data from internal buffer. - * AudioEngine cache audio data on ios platform + /** + * Uncache the audio data from internal buffer. + * AudioEngine cache audio data on ios,mac, and win32 platform. + * * @warning This can lead to stop related audio first. - * @param filePath The path of an audio file + * @param filePath Audio file path. */ static void uncache(const std::string& filePath); - /** Uncache all audio data from internal buffer. + /** + * Uncache all audio data from internal buffer. + * * @warning All audio will be stopped first. - * @param */ static void uncacheAll(); - /** Gets the audio profile by id of audio instance. - * @param audioID an audioID returned by the play2d function - * @return the audio profile + /** + * Gets the audio profile by id of audio instance. + * + * @param audioID An audioID returned by the play2d function. + * @return The audio profile. */ static AudioProfile* getProfile(int audioID); - /** Gets the audio profile by name. - * @param name name of audio profile - * @return the audio profile + /** + * Gets an audio profile by name. + * + * @param profileName A name of audio profile. + * @return The audio profile. */ - static AudioProfile* getProfile(const std::string &name); + static AudioProfile* getProfile(const std::string &profileName); protected: @@ -273,6 +333,7 @@ protected: } NS_CC_END - +// end audio group +/// @} #endif // __AUDIO_ENGINE_H_ #endif diff --git a/cocos/audio/include/SimpleAudioEngine.h b/cocos/audio/include/SimpleAudioEngine.h index d57eed70e1..702d923bdb 100644 --- a/cocos/audio/include/SimpleAudioEngine.h +++ b/cocos/audio/include/SimpleAudioEngine.h @@ -1,7 +1,7 @@ /**************************************************************************** Copyright (c) 2010 Steve Oldmeadow Copyright (c) 2010-2012 cocos2d-x.org -Copyright (c) 2013-2014 Chukong Technologies Inc. +Copyright (c) 2013-2015 Chukong Technologies Inc. http://www.cocos2d-x.org @@ -37,97 +37,105 @@ THE SOFTWARE. #define CC_DEPRECATED_ATTRIBUTE #endif +/** +* @addtogroup Audio +* @{ +*/ + namespace CocosDenshion { /** - @class SimpleAudioEngine - @brief Offers a VERY simple interface to play background music & sound effects. - @note Make sure to call SimpleAudioEngine::end() when the sound engine is not needed anymore - to release allocated resources. + * @class SimpleAudioEngine + * + * @brief Offers a very simple interface to play background music & sound effects. + * + * @note Make sure to call SimpleAudioEngine::end() when the sound engine is not needed anymore to release allocated resources. */ class EXPORT_DLL SimpleAudioEngine { public: /** - @brief Get the shared Engine object,it will new one when first time be called + * Returns a shared instance of the SimpleAudioEngine. */ static SimpleAudioEngine* getInstance(); + /** + * @deprecated Use `getInstance` instead. * @js NA * @lua NA */ CC_DEPRECATED_ATTRIBUTE static SimpleAudioEngine* sharedEngine() { return SimpleAudioEngine::getInstance(); } /** - @brief Release the shared Engine object - @warning It must be called before the application exit, or a memory leak will be casued. + * Release the shared Engine object. + * + * @warning It must be called before the application exit, or it will lead to memory leaks. */ static void end(); -protected: - SimpleAudioEngine(); - virtual ~SimpleAudioEngine(); - -public: - /** - @brief Preload background music - @param pszFilePath The path of the background music file. + * Preload background music. + * + * @param filePath The path of the background music file. * @js preloadMusic * @lua preloadMusic */ - virtual void preloadBackgroundMusic(const char* pszFilePath); + virtual void preloadBackgroundMusic(const char* filePath); /** - @brief Play background music - @param pszFilePath The path of the background music file,or the FileName of T_SoundResInfo - @param bLoop Whether the background music loop or not + * Play background music. + * + * @param filePath The path of the background music file,or the FileName of T_SoundResInfo. + * @param loop Whether the background music loop or not. * @js playMusic * @lua playMusic */ - virtual void playBackgroundMusic(const char* pszFilePath, bool bLoop = false); + virtual void playBackgroundMusic(const char* filePath, bool loop = false); /** - @brief Stop playing background music - @param bReleaseData If release the background music data or not.As default value is false + * Stop playing background music. + * + * @param releaseData If release the background music data or not.As default value is false. * @js stopMusic * @lua stopMusic */ - virtual void stopBackgroundMusic(bool bReleaseData = false); + virtual void stopBackgroundMusic(bool releaseData = false); /** - @brief Pause playing background music + * Pause playing background music. * @js pauseMusic * @lua pauseMusic */ virtual void pauseBackgroundMusic(); /** - @brief Resume playing background music + * Resume playing background music. * @js resumeMusic * @lua resumeMusic */ virtual void resumeBackgroundMusic(); /** - @brief Rewind playing background music + * Rewind playing background music. * @js rewindMusic * @lua rewindMusic */ virtual void rewindBackgroundMusic(); /** - @brief Indicates whether any background music can be played or not. - @return true if background music can be played, otherwise false. + * Indicates whether any background music can be played or not. + * + * @return true if background music can be played, otherwise false. * @js willPlayMusic * @lua willPlayMusic */ virtual bool willPlayBackgroundMusic(); /** - @brief Indicates whether the background music is playing - @return true if the background music is playing, otherwise false + * Indicates whether the background music is playing. + * + * @return true if the background music is playing, otherwise false. * @js isMusicPlaying * @lua isMusicPlaying */ @@ -138,97 +146,120 @@ public: // /** - @brief The volume of the background music within the range of 0.0 as the minimum and 1.0 as the maximum. + * The volume of the background music within the range of 0.0 as the minimum and 1.0 as the maximum. * @js getMusicVolume * @lua getMusicVolume */ virtual float getBackgroundMusicVolume(); /** - @brief Set the volume of background music - @param volume must be within the range of 0.0 as the minimum and 1.0 as the maximum. + * Set the volume of background music. + * + * @param volume must be within the range of 0.0 as the minimum and 1.0 as the maximum. * @js setMusicVolume * @lua setMusicVolume */ virtual void setBackgroundMusicVolume(float volume); /** - @brief The volume of the effects within the range of 0.0 as the minimum and 1.0 as the maximum. - */ + * The volume of the effects within the range of 0.0 as the minimum and 1.0 as the maximum. + */ virtual float getEffectsVolume(); /** - @brief Set the volume of sound effects - @param volume must be within the range of 0.0 as the minimum and 1.0 as the maximum. - */ + * Set the volume of sound effects. + * + * @param volume must be within the range of 0.0 as the minimum and 1.0 as the maximum. + */ virtual void setEffectsVolume(float volume); // // for sound effects /** - @brief Play sound effect with a file path, pitch, pan and gain - @param pszFilePath The path of the effect file. - @param bLoop Determines whether to loop the effect playing or not. The default value is false. - @param pitch Frequency, normal value is 1.0. Will also change effect play time. - @param pan Stereo effect, in the range of [-1..1] where -1 enables only left channel. - @param gain Volume, in the range of [0..1]. The normal value is 1. - @return the OpenAL source id - - @note Full support is under development, now there are limitations: - - no pitch effect on Samsung Galaxy S2 with OpenSL backend enabled; - - no pitch/pan/gain on emscrippten, win32, marmalade. - */ - virtual unsigned int playEffect(const char* pszFilePath, bool bLoop = false, + * Play sound effect with a file path, pitch, pan and gain. + * + * @param filePath The path of the effect file. + * @param loop Determines whether to loop the effect playing or not. The default value is false. + * @param pitch Frequency, normal value is 1.0. Will also change effect play time. + * @param pan Stereo effect, in the range of [-1..1] where -1 enables only left channel. + * @param gain Volume, in the range of [0..1]. The normal value is 1. + * @return The sound id. + * + * @note Full support is under development, now there are limitations: + * - no pitch effect on Samsung Galaxy S2 with OpenSL backend enabled; + * - no pitch/pan/gain on win32. + */ + virtual unsigned int playEffect(const char* filePath, bool loop = false, float pitch = 1.0f, float pan = 0.0f, float gain = 1.0f); /** - @brief Pause playing sound effect - @param nSoundId The return value of function playEffect - */ - virtual void pauseEffect(unsigned int nSoundId); + * Pause playing sound effect. + * + * @param soundId The return value of function playEffect. + */ + virtual void pauseEffect(unsigned int soundId); /** - @brief Pause all playing sound effect - */ + * Pause all playing sound effect. + */ virtual void pauseAllEffects(); /** - @brief Resume playing sound effect - @param nSoundId The return value of function playEffect - */ - virtual void resumeEffect(unsigned int nSoundId); + * Resume playing sound effect. + * + * @param soundId The return value of function playEffect. + */ + virtual void resumeEffect(unsigned int soundId); /** - @brief Resume all playing sound effect - */ + * Resume all playing sound effect. + */ virtual void resumeAllEffects(); /** - @brief Stop playing sound effect - @param nSoundId The return value of function playEffect - */ - virtual void stopEffect(unsigned int nSoundId); + * Stop playing sound effect. + * + * @param soundId The return value of function playEffect. + */ + virtual void stopEffect(unsigned int soundId); /** - @brief Stop all playing sound effects - */ + * Stop all playing sound effects. + */ virtual void stopAllEffects(); /** - @brief preload a compressed audio file - @details the compressed audio will be decoded to wave, then written into an internal buffer in SimpleAudioEngine - @param pszFilePath The path of the effect file - */ - virtual void preloadEffect(const char* pszFilePath); + * Preload a compressed audio file. + * + * The compressed audio will be decoded to wave, then written into an internal buffer in SimpleAudioEngine. + * + * @param filePath The path of the effect file. + */ + virtual void preloadEffect(const char* filePath); /** - @brief unload the preloaded effect from internal buffer - @param pszFilePath The path of the effect file + * Unload the preloaded effect from internal buffer. + * + * @param filePath The path of the effect file. + */ + virtual void unloadEffect(const char* filePath); + +protected: + /** + * Constructor of SimpleAudioEngine. */ - virtual void unloadEffect(const char* pszFilePath); + SimpleAudioEngine(); + + /** + * Destructor of SimpleAudioEngine. + */ + virtual ~SimpleAudioEngine(); }; } // end of namespace CocosDenshion +// end audio group +/// @} + #endif // _SIMPLE_AUDIO_ENGINE_H_ diff --git a/cocos/base/CCController.h b/cocos/base/CCController.h index 0cc6440800..b664c15c2b 100644 --- a/cocos/base/CCController.h +++ b/cocos/base/CCController.h @@ -38,10 +38,15 @@ class EventListenerController; class EventController; class EventDispatcher; +/** + * @class Controller + * @brief A Controller object represents a connected physical game controller. + */ class Controller { public: - /** Controllers' standard key + /** + * Controllers' standard key * Controller receives only standard key which contained within enum Key by default. */ enum Key @@ -80,49 +85,89 @@ public: KEY_MAX }; + /** + * @struct KeyStatus + * + */ typedef struct _keyStatus { + /** A Boolean value that indicates whether the key is considered pressed. */ bool isPressed; + /** The value of key.This value is used in conjunction with the isPressed parameter. */ float value; + /** A Boolean value that indicates whether the value of key is analog. + * If isAnalog is true, the key value might be a float from -1 to 1. + * If isAnalog is false, the key value would be contain one number: 0 or 1. + */ bool isAnalog; }KeyStatus; static const int TAG_UNSET = -1; + /** + * Gets all Controller objects. + */ static const std::vector& getAllController(){ return s_allController;} - /** Gets a controller with its tag + + /** + * Gets a Controller object with tag. + * * @param tag An identifier to find the controller. + * @return A Controller object. */ static Controller* getControllerByTag(int tag); - /** To start discovering new controllers - * @warning The API only work on the IOS platform.Empty implementation on Android + + /** + * Start discovering new controllers. + * + * @warning The API only work on the IOS platform. Empty implementation on other platform. */ static void startDiscoveryController(); - /** End the discovery process - * @warning The API only work on the IOS platform.Empty implementation on Android + + /** + * Stop the discovery process. + * + * @warning The API only work on the IOS platform.Empty implementation on other platform. */ static void stopDiscoveryController(); + /** + * Gets the name of this Controller object. + */ const std::string& getDeviceName() const { return _deviceName;} + + /** + * Gets the Controller id. + */ int getDeviceId() const { return _deviceId;} + /** + * Indicates whether the Controller is connected. + */ bool isConnected() const; + /** + * + */ const KeyStatus& getKeyStatus(int keyCode); - /** Activate receives key event from external key. e.g. back,menu. + /** + * Activate receives key event from external key. e.g. back,menu. * Controller receives only standard key which contained within enum Key by default. + * * @warning The API only work on the android platform for support diversified game controller. * - * @param externalKeyCode external key code - * @param receive true if external key event on this controller should be receive, false otherwise. + * @param externalKeyCode External key code. + * @param receive True if external key event on this controller should be receive, false otherwise. */ void receiveExternalKeyEvent(int externalKeyCode,bool receive); - /** Changes the tag that is used to identify the controller easily. + /** + * Changes the tag that is used to identify the controller easily. * @param tag A integer that identifies the controller. */ void setTag(int tag) { _controllerTag = tag;} + /** * Returns a tag that is used to identify the controller easily. * diff --git a/cocos/base/CCEventController.h b/cocos/base/CCEventController.h index 14b3c0870a..e83cb03794 100644 --- a/cocos/base/CCEventController.h +++ b/cocos/base/CCEventController.h @@ -31,6 +31,7 @@ NS_CC_BEGIN +/// @cond EventController class Controller; class EventListenerController; @@ -64,7 +65,7 @@ protected: friend class EventListenerController; }; - +/// @endcond EventController NS_CC_END #endif /* defined(__cocos2d_libs__EventController__) */ diff --git a/cocos/ui/UIVideoPlayer.h b/cocos/ui/UIVideoPlayer.h index a1ca1392ee..9f5932f21a 100644 --- a/cocos/ui/UIVideoPlayer.h +++ b/cocos/ui/UIVideoPlayer.h @@ -33,6 +33,13 @@ NS_CC_BEGIN namespace experimental{ namespace ui{ + /** + * @class VideoPlayer + * @brief Displays a video file. + * + * @note VideoPlayer displays a video file base on system widget. + * It's mean VideoPlayer displays a video file above all graphical elements of cocos2d-x. + */ class VideoPlayer : public cocos2d::ui::Widget { public: diff --git a/cocos/ui/UIWebView.h b/cocos/ui/UIWebView.h index bea6dfd29d..713b3f1549 100644 --- a/cocos/ui/UIWebView.h +++ b/cocos/ui/UIWebView.h @@ -40,120 +40,130 @@ namespace experimental{ class WebViewImpl; +/** + * @class WebView + * @brief A View that displays web pages. + * + * @note WebView displays web pages base on system widget. + * It's mean WebView displays web pages above all graphical elements of cocos2d-x. + */ class CC_GUI_DLL WebView : public cocos2d::ui::Widget { public: /** - * Allocates and initializes a WebView. - */ + * Allocates and initializes a WebView. + */ static WebView *create(); /** - * Set javascript interface scheme. - * @see #onJsCallback - */ + * Set javascript interface scheme. + * + * @see #onJsCallback + */ void setJavascriptInterfaceScheme(const std::string &scheme); - /** - * Sets the main page contents, MIME type, content encoding, and base URL. - * @param data The content for the main page. - * @param MIMEType The MIME type of the data. - * @param encoding the encoding of the data. - * @param baseURL The base URL for the content. - */ + * Sets the main page contents, MIME type, content encoding, and base URL. + * + * @param data The content for the main page. + * @param MIMEType The MIME type of the data. + * @param encoding The encoding of the data. + * @param baseURL The base URL for the content. + */ void loadData(const cocos2d::Data &data, const std::string &MIMEType, const std::string &encoding, const std::string &baseURL); - /** - * Sets the main page content and base URL. - * @param string The content for the main page. - * @param baseURL The base URL for the content. - */ + * Sets the main page content and base URL. + * + * @param string The content for the main page. + * @param baseURL The base URL for the content. + */ void loadHTMLString(const std::string &string, const std::string &baseURL = ""); /** - * Loads the given URL. - * @param url content URL - */ + * Loads the given URL. + * + * @param url Content URL. + */ void loadURL(const std::string &url); /** - * Loads the given fileName. - * @param fileName content fileName - */ + * Loads the given fileName. + * + * @param fileName Content fileName. + */ void loadFile(const std::string &fileName); /** - * Stops the current load. - */ + * Stops the current load. + */ void stopLoading(); /** - * Reloads the current URL. - */ + * Reloads the current URL. + */ void reload(); /** - * Gets whether this WebView has a back history item. - * @return web view has a back history item. - */ + * Gets whether this WebView has a back history item. + * + * @return WebView has a back history item. + */ bool canGoBack(); /** - * Gets whether this WebView has a forward history item. - * @return web view has a forward history item. - */ + * Gets whether this WebView has a forward history item. + * + * @return WebView has a forward history item. + */ bool canGoForward(); /** - * Goes back in the history. - */ + * Goes back in the history. + */ void goBack(); /** - * Goes forward in the history. - */ + * Goes forward in the history. + */ void goForward(); /** - * evaluates JavaScript in the context of the currently displayed page - */ + * Evaluates JavaScript in the context of the currently displayed page. + */ void evaluateJS(const std::string &js); /** - * Set WebView should support zooming. The default value is false. - */ + * Set WebView should support zooming. The default value is false. + */ void setScalesPageToFit(const bool scalesPageToFit); - - virtual void draw(cocos2d::Renderer *renderer, cocos2d::Mat4 const &transform, uint32_t flags) override; - - virtual void setVisible(bool visible) override; - - typedef std::function ccWebViewCallback; - /** * Call before a web view begins loading. + * * @param sender The web view that is about to load new content. - * @param url content URL. + * @param url Content URL. * @return YES if the web view should begin loading content; otherwise, NO . */ void setOnShouldStartLoading(const std::function& callback); + typedef std::function ccWebViewCallback; + /** * Call after a web view finishes loading. + * * @param sender The web view that has finished loading. - * @param url content URL. + * @param url Content URL. */ void setOnDidFinishLoading(const ccWebViewCallback& callback); /** * Call if a web view failed to load content. + * * @param sender The web view that has failed loading. - * @param url content URL. + * @param url Content URL. */ void setOnDidFailLoading(const ccWebViewCallback& callback); @@ -166,6 +176,10 @@ public: ccWebViewCallback getOnDidFinishLoading()const; ccWebViewCallback getOnDidFailLoading()const; ccWebViewCallback getOnJSCallback()const; + + virtual void draw(cocos2d::Renderer *renderer, cocos2d::Mat4 const &transform, uint32_t flags) override; + + virtual void setVisible(bool visible) override; protected: virtual cocos2d::ui::Widget* createCloneInstance() override; @@ -180,12 +194,12 @@ protected: ccWebViewCallback _onJSCallback; /** - * Default constructor + * Default constructor. */ WebView(); /** - * Default destructor + * Default destructor. */ virtual ~WebView();