Merge branch 'next' of https://github.com/blackberry-gaming/GamePlay into next-kcunney

gameplay/src/AbsoluteLayout.h

@@ -40,6 +40,7 @@ protected:
      * It simply calls update() on any control that is dirty.
      *
      * @param container The container to update.
+     * @param offset The layout offset.
      */
     void update(const Container* container, const Vector2& offset);
 

gameplay/src/CheckBox.h

@@ -119,6 +119,7 @@ protected:
      * properties, such as its text viewport.
      *
      * @param container This control's parent container.
+     * @param offset The position offset.
      */
     void update(const Control* container, const Vector2& offset);
 

gameplay/src/Container.h

@@ -147,9 +147,9 @@ public:
     Scroll getScroll() const;
 
     /**
-     * Set whether scrollbars are always visible, or only visible while scrolling.
+     * Set whether scrollbars auto hidden when they become static.
      *
-     * @param alwaysVisible Whether scrollbars are always visible.
+     * @param autoHide true to auto hide the scrollbars when they become static.
      */
     void setScrollBarsAutoHide(bool autoHide);
 
@@ -196,6 +196,8 @@ protected:
      * Create an empty container.  A container's layout type must be specified at creation time.
      *
      * @param type The container's layout type.
+     *
+     * @return The new container.
      */
     static Container* create(Layout::Type type);
 
@@ -215,6 +217,7 @@ protected:
      * and positions them according to the container's layout.
      *
      * @param container This container's parent container.
+     * @param offset The offset.
      */
     virtual void update(const Control* container, const Vector2& offset);
 
@@ -246,28 +249,42 @@ protected:
 
     /**
      * Gets a Layout::Type enum from a matching string.
+     *
+     * @param layoutString The layout string to parse
      */
     static Layout::Type getLayoutType(const char* layoutString);
 
     /**
      * Returns whether this control is a container.
-     * This is true in this case.
+     * 
+     * @return true if this is a container, false if not.
      */
     bool isContainer();
 
     /**
      * Returns whether this container or any of its controls have been modified and require an update.
+     * 
+     * @return true if this container or any of its controls have been modified and require an update.
      */
     virtual bool isDirty();
 
     /**
      * Adds controls nested within a properties object to this container,
      * searching for styles within the given theme.
+     *
+     * @param theme The them to add controls from
+     * @param properties The properties to use.
      */
     void addControls(Theme* theme, Properties* properties);
 
     /**
-     * Draws a sprite batch for the specified clipping rect 
+     * Draws a sprite batch for the specified clipping rect .
+     *
+     * @param spriteBatch The sprite batch to use.
+     * @param clip The clipping rectangle.
+     * @param needsClear Whether it needs to be cleared.
+     * @param cleared Whether it was previously cleared
+     * @param targetHeight The targets height
      */
     virtual void draw(SpriteBatch* spriteBatch, const Rectangle& clip, bool needsClear, bool cleared, float targetHeight);
 
@@ -279,6 +296,11 @@ protected:
     /**
      * Applies touch events to scroll state.
      *
+     * @param evt The touch event that occurred.
+     * @param x The x position of the touch in pixels. Left edge is zero.
+     * @param y The y position of the touch in pixels. Top edge is zero.
+     * @param contactIndex The order of occurrence for multiple touch contacts starting at zero.
+     *
      * @return Whether the touch event was consumed by scrolling within this container.
      *
      * @see Touch::TouchEvent
@@ -298,64 +320,122 @@ protected:
      * The container's layout.
      */
     Layout* _layout;
-
     /**
      * List of controls within the container.
      */
     std::vector<Control*> _controls;
-
-    // Images used to draw scrollbars.
+    /**
+     * Scrollbar top cap image.
+     */
     Theme::ThemeImage* _scrollBarTopCap;
+    /**
+     * Scrollbar verticle image.
+     */
     Theme::ThemeImage* _scrollBarVertical;
+    /**
+     * Scrollbar bottom cap image.
+     */
     Theme::ThemeImage* _scrollBarBottomCap;
+    /**
+     * Scrollbar left cap image.
+     */
     Theme::ThemeImage* _scrollBarLeftCap;
+    /**
+     * Scrollbar horizontal image.
+     */
     Theme::ThemeImage* _scrollBarHorizontal;
+    /**
+     * Scrollbar horizontal image.
+     */
     Theme::ThemeImage* _scrollBarRightCap;
-
-    // Flag representing whether scrolling is enabled, and in which directions.
+    /** 
+     * Flag representing whether scrolling is enabled, and in which directions.
+     */
     Scroll _scroll;
-    // Scroll bar bounds
+    /** 
+     * Scroll bar bounds
+     */
     Rectangle _scrollBarBounds;
-    // How far this layout has been scrolled in each direction.
+    /** 
+     * How far this layout has been scrolled in each direction.
+     */
     Vector2 _scrollPosition;
-    // Should the scrollbars auto hide. Default is false.
+    /** 
+     * Should the scrollbars auto hide. Default is false.
+     */
     bool _scrollBarsAutoHide;
-    // Used to animate scrollbars fading out.
+    /** 
+     * Used to animate scrollbars fading out.
+     */
     float _scrollBarOpacity;
-    // Whether the user is currently touching / holding the mouse down within this layout's container.
+    /** 
+     * Whether the user is currently touching / holding the mouse down within this layout's container.
+     */
     bool _scrolling;
-    // First scrolling touch x position
+    /** 
+     * First scrolling touch x position
+     */ 
     int _scrollingFirstX;
-    // First scrolling touch y position
+    /** 
+     * First scrolling touch y position
+     */ 
     int _scrollingFirstY;
-    // The last y position when scrolling
+    /** 
+     * The last y position when scrolling
+     */ 
     int _scrollingLastX;
-    // The last x position when scrolling
+    /** 
+     * The last x position when scrolling
+     */ 
     int _scrollingLastY;
-    // Time we started scrolling in the x
+    /** 
+     * Time we started scrolling in the x
+     */ 
     long _scrollingStartTimeX;
-    // Time we started scrolling in the y
+    /** 
+     * Time we started scrolling in the y
+     */ 
     long _scrollingStartTimeY;
-    // The last time we were scrolling
+    /** 
+     * The last time we were scrolling
+     */
     long _scrollingLastTime;
-    // Speed to continue scrolling at after touch release.
+    /** 
+     * Speed to continue scrolling at after touch release.
+     */ 
     Vector2 _scrollingVelocity;
-    // Friction dampens velocity.
+    /** 
+     * Friction dampens velocity.
+     */ 
     float _scrollingFriction;
-    // Are we scrolling to the right?
+    /** 
+     * Are we scrolling to the right?
+     */ 
     bool _scrollingRight;
-    // Are we scrolling down?
+    /** 
+     * Are we scrolling down?
+     */ 
     bool _scrollingDown;
 
 private:
 
+    /**
+     * Constructor.
+     */
     Container(const Container& copy);
 
     AnimationClip* _scrollBarOpacityClip;
     int _zIndexDefault;
 };
 
-// Sort funtion for use with _controls.sort(), based on Z-Order.
+
+/**
+ * Sort funtion for use with _controls.sort(), based on Z-Order.
+ * 
+ * @param c1 The first control
+ * @param c2 The second control
+ * return true if the first controls z index is less than the second.
+ */
 bool sortControlsByZOrder(Control* c1, Control* c2);
 
 }

gameplay/src/Control.h

@@ -758,7 +758,6 @@ protected:
      *
      * @param spriteBatch The sprite batch containing this control's icons.
      * @param clip The clipping rectangle of this control's parent container.
-     * @param offset Layout-computed positioning offset to add to the control's position.
      */
     virtual void drawImages(SpriteBatch* spriteBatch, const Rectangle& clip);
 
@@ -766,10 +765,18 @@ protected:
      * Draw this control's text.
      *
      * @param clip The clipping rectangle of this control's parent container.
-     * @param offset Layout-computed positioning offset to add to the control's position.
      */
     virtual void drawText(const Rectangle& clip);
 
+    /**
+     * Draws a sprite batch for the specified clipping rect .
+     *
+     * @param spriteBatch The sprite batch to use.
+     * @param clip The clipping rectangle.
+     * @param needsClear Whether it needs to be cleared.
+     * @param cleared Whether it was previously cleared
+     * @param targetHeight The targets height
+     */
     virtual void draw(SpriteBatch* spriteBatch, const Rectangle& clip, bool needsClear, bool cleared, float targetHeight);
 
     /**
@@ -865,6 +872,9 @@ protected:
      */
     Rectangle _viewportClipBounds;
 
+    /**
+     * If the control is dirty and need updating.
+     */
     bool _dirty;
     
     /**
@@ -901,7 +911,10 @@ protected:
      * The current opacity of the control.
      */
     float _opacity;
-
+    
+    /**
+     * The z-order of the control.
+     */
     int _zIndex;
 
 private:

gameplay/src/FlowLayout.h

@@ -6,6 +6,9 @@
 namespace gameplay
 {
 
+/**
+ * Defines a layout that arranges controls in order, left-to-right, row by row.
+ */
 class FlowLayout : public Layout
 {
     friend class Form;
@@ -33,6 +36,7 @@ protected:
      * Update the controls contained by the specified container.
      *
      * @param container The container to update.
+     * @param offset The offset position.
      */
     void update(const Container* container, const Vector2& offset);
 

gameplay/src/Joystick.h

@@ -6,6 +6,9 @@
 namespace gameplay
 {
 
+/**
+ * Defines a control representing a joystick (axis).
+ */
 class Joystick : public Control
 {
     friend class Container;
@@ -121,7 +124,6 @@ protected:
      *
      * @param spriteBatch The sprite batch containing this control's icons.
      * @param clip The clipping rectangle of this control's parent container.
-     * @param offset Layout-computed positioning offset to add to the control's position.
      */
     void drawImages(SpriteBatch* spriteBatch, const Rectangle& clip);
 

gameplay/src/Label.cpp

@@ -58,8 +58,11 @@ void Label::setText(const char* text)
 {
     assert(text);
 
-    _text = text;
-    _dirty = true;
+    if (strcmp(text, _text.c_str()) != 0)
+    {
+        _text = text;
+        _dirty = true;
+    }
 }
 
 const char* Label::getText()

gameplay/src/Label.h

@@ -116,7 +116,11 @@ protected:
      * The text color being used to display the label.
      */
     Vector4 _textColor;
-    Rectangle _textBounds;  // The position and size of this control's text area, before clipping.  Used for text alignment.
+
+    /**
+     * The position and size of this control's text area, before clipping.  Used for text alignment.
+     */
+    Rectangle _textBounds;
 
 private:
 

gameplay/src/Layout.h

@@ -64,10 +64,12 @@ public:
     virtual Type getType() = 0;
 
 protected:
+
     /**
      * Position, resize, and update the controls within a container.
      *
      * @param container The container to update.
+     * @param offset The update offset.
      */
     virtual void update(const Container* container, const Vector2& offset) = 0;
 

gameplay/src/ParticleEmitter.h

@@ -616,10 +616,13 @@ public:
     void draw();
 
     /**
-     * Gets a BlendMode enum from a corresponding string.
+     * Gets a TextureBlending enum from a corresponding string.
      */
     static TextureBlending getTextureBlendingFromString(const char* src);
 
+    /**
+     * Sets a TextureBlending enum from a corresponding string.
+     */
     void setTextureBlending(TextureBlending blending);
 
 private:
@@ -639,28 +642,20 @@ private:
      */
     void setNode(Node* node);
 
-    /**
-     * Generates a scalar within the range defined by min and max.
-     */
+    // Generates a scalar within the range defined by min and max.
     float generateScalar(float min, float max);
 
     long generateScalar(long min, long max);
 
-    /**
-     * Generates a vector within the domain defined by a base vector and its variance.
-     */
+    // Generates a vector within the domain defined by a base vector and its variance.
     void generateVectorInRect(const Vector3& base, const Vector3& variance, Vector3* dst);
 
-    /**
-     * Generates a vector within the ellipsoidal domain defined by a center point and scale vector.
-     */
+    // Generates a vector within the ellipsoidal domain defined by a center point and scale vector.
     void generateVectorInEllipsoid(const Vector3& center, const Vector3& scale, Vector3* dst);
 
     void generateVector(const Vector3& base, const Vector3& variance, Vector3* dst, bool ellipsoid);
 
-    /**
-     * Generates a color within the domain defined by a base vector and its variance.
-     */
+    // Generates a color within the domain defined by a base vector and its variance.
     void generateColor(const Vector4& base, const Vector4& variance, Vector4* dst);
 
     /**

gameplay/src/RadioButton.h

@@ -113,6 +113,7 @@ protected:
      * properties, such as its text viewport.
      *
      * @param container This control's parent container.
+     * @param offset Positioning offset to add to the control's position.
      */
     void update(const Control* container, const Vector2& offset);
 

gameplay/src/SpriteBatch.h

@@ -146,6 +146,24 @@ public:
     void draw(const Vector3& dst, float width, float height, float u1, float v1, float u2, float v2, const Vector4& color,
               const Vector2& rotationPoint, float rotationAngle, bool positionIsCenter = false);
     
+    /**
+     * Draws a single sprite, rotated around rotationPoint by rotationAngle.
+     * 
+     * @param x The destination x position.
+     * @param y The destination y position.
+     * @param z The destination z position.
+     * @param width The source width.
+     * @param height The source height.
+     * @param u1 Texture coordinate.
+     * @param v1 Texture coordinate.
+     * @param u2 Texture coordinate.
+     * @param v2 Texture coordinate.
+     * @param color The color to tint the sprite. Use white for no tint.
+     * @param rotationPoint The point to rotate around, relative to dst's x and y values.
+     *                      (e.g. Use Vector2(0.5f, 0.5f) to rotate around the quad's center.)
+     * @param rotationAngle The rotation angle.
+     * @param positionIsCenter Specified whether the given destination is to be the center of the sprite or not (if not, it is treated as the bottom-left).
+     */
     void draw(float x, float y, float z, float width, float height, float u1, float v1, float u2, float v2, const Vector4& color,
               const Vector2& rotationPoint, float rotationAngle, bool positionIsCenter = false);
 

gameplay/src/TextBox.h

@@ -111,6 +111,7 @@ protected:
      * properties, such as its text viewport.
      *
      * @param container This control's parent container.
+     * @param offset Positioning offset to add to the control's position.
      */
     void update(const Control* container, const Vector2& offset);
 
@@ -126,6 +127,10 @@ protected:
      * The current position of the TextBox's caret.
      */
     Vector2 _caretLocation;
+
+    /**
+     * The previous position of the TextBox's caret.
+     */
     Vector2 _prevCaretLocation;
 
     /**

gameplay/src/VerticalLayout.h

@@ -66,6 +66,7 @@ protected:
      * the bottom-most edge of the container is reached.
      *
      * @param container The container to update.
+     * @param offset Positioning offset to add to the control's position.
      */
     void update(const Container* container, const Vector2& offset);