More comments and refactoring.

gameplay/src/AbsoluteLayout.h

@@ -16,6 +16,7 @@ class AbsoluteLayout : public Layout
     friend class Container;
 
 public:
+
     /**
      * Get the type of this Layout.
      *
@@ -24,6 +25,7 @@ public:
     Layout::Type getType();
 
 protected:
+
     /**
      * Create an AbsoluteLayout.
      *
@@ -42,6 +44,7 @@ protected:
     void update(const Container* container);
 
 private:
+
     AbsoluteLayout();
     AbsoluteLayout(const AbsoluteLayout& copy);
     virtual ~AbsoluteLayout();

gameplay/src/Button.cpp

@@ -14,7 +14,7 @@ namespace gameplay
     Button* Button::create(Theme::Style* style, Properties* properties)
     {
         Button* button = new Button();
-        button->init(style, properties);
+        button->initialize(style, properties);
 
         return button;
     }

gameplay/src/Button.h

@@ -28,6 +28,16 @@ class Button : public Label
 
 protected:
 
+    /**
+     * Constructor.
+     */
+    Button();
+
+    /**
+     * Destructor.
+     */
+    virtual ~Button();
+
     /**
      * Create a button with a given style and properties.
      *
@@ -52,10 +62,6 @@ protected:
      */
     bool touchEvent(Touch::TouchEvent evt, int x, int y, unsigned int contactIndex);
 
-    Button();
-
-    virtual ~Button();
-
 private:
 
     Button(const Button& copy);

gameplay/src/CheckBox.cpp

@@ -22,7 +22,7 @@ CheckBox::~CheckBox()
 CheckBox* CheckBox::create(Theme::Style* style, Properties* properties)
 {
     CheckBox* checkBox = new CheckBox();
-    checkBox->init(style, properties);
+    checkBox->initialize(style, properties);
     properties->getVector2("iconSize", &checkBox->_imageSize);
     checkBox->_checked = properties->getBool("checked");
 

gameplay/src/CheckBox.h

@@ -29,6 +29,7 @@ class CheckBox : public Button
     friend class Container;
 
 public:
+
     /**
      * Gets whether this checkbox is checked.
      *
@@ -63,10 +64,16 @@ public:
      */
     virtual void addListener(Control::Listener* listener, int eventFlags);
 
-  //  virtual void animationEvent(AnimationClip* clip, EventType type);
-
 protected:
+
+    /**
+     * Constructor.
+     */
     CheckBox();
+
+    /**
+     * Destructor.
+     */
     ~CheckBox();
 
     /**
@@ -97,7 +104,7 @@ protected:
      * Called when a control's properties change.  Updates this control's internal rendering
      * properties, such as its text viewport.
      *
-     * @param position The control's position within its container.
+     * @param clip The clipping rectangle of this control's parent container.
      */
     void update(const Rectangle& clip);
 
@@ -113,6 +120,7 @@ protected:
     Vector2 _imageSize;  // The size to draw the checkbox icon, if different from its size in the texture.
 
 private:
+
     CheckBox(const CheckBox& copy);
 };
 

gameplay/src/Container.cpp

@@ -56,7 +56,7 @@ namespace gameplay
     {
         const char* layoutString = properties->getString("layout");
         Container* container = Container::create(getLayoutType(layoutString));
-        container->init(style, properties);
+        container->initialize(style, properties);
         container->addControls(theme, properties);
 
         return container;

gameplay/src/Container.h

@@ -106,8 +106,14 @@ public:
 
 protected:
 
+    /**
+     * Constructor.
+     */
     Container();
 
+    /**
+     * Destructor.
+     */
     virtual ~Container();
 
     /**

gameplay/src/Control.cpp

@@ -32,7 +32,7 @@ namespace gameplay
         }
     }
 
-    void Control::init(Theme::Style* style, Properties* properties)
+    void Control::initialize(Theme::Style* style, Properties* properties)
     {
         _style = style;
 
@@ -42,7 +42,7 @@ namespace gameplay
         properties->getVector2("size", &size);
         _bounds.set(position.x, position.y, size.x, size.y);
 
-        _state = Control::getStateFromString(properties->getString("state"));
+        _state = Control::getState(properties->getString("state"));
 
         const char* id = properties->getId();
         if (id)
@@ -696,7 +696,7 @@ namespace gameplay
         return false;
     }
 
-    Control::State Control::getStateFromString(const char* state)
+    Control::State Control::getState(const char* state)
     {
         if (!state)
         {

gameplay/src/Control.h

@@ -25,6 +25,7 @@ class Control : public Ref, public AnimationTarget
     friend class VerticalLayout;
 
 public:
+
     /**
      * The possible states a control can be in.
      */
@@ -57,6 +58,10 @@ public:
      */
     static const unsigned char STATE_ALL = NORMAL | FOCUS | ACTIVE | DISABLED;
 
+    /**
+     * Implement Control::Listener and call Control::addListener()
+     * in order to listen for events on controls.
+     */
     class Listener
     {
     public:
@@ -201,7 +206,6 @@ public:
      */
     float getHeight() const;
 
-    // Themed properties.
     /**
      * Set the size of this control's border.
      *
@@ -489,7 +493,6 @@ public:
      * @param opacity The new opacity.
      * @param states The states to set this property on.
      *               One or more members of the Control::State enum, ORed together.
-     * @param duration The duration to animate opacity by.
      */
     void setOpacity(float opacity, unsigned char states = STATE_ALL);
 
@@ -502,10 +505,6 @@ public:
      */
     float getOpacity(State state = NORMAL) const;
 
-    // TODO
-    // Controls must state the names of the images they use, for the purposes of a future UI editor.
-    //virtual std::vector<std::string> getImageNames() = 0;
-
     /**
      * Get the bounds of this control, relative to its parent container, after clipping.
      *
@@ -608,7 +607,15 @@ public:
     void setAnimationPropertyValue(int propertyId, AnimationValue* value, float blendWeight = 1.0f);
 
 protected:
+
+    /**
+     * Constructor.
+     */
     Control();
+
+    /**
+     * Destructor.
+     */
     virtual ~Control();
 
     /**
@@ -652,16 +659,6 @@ protected:
      */
     virtual void update(const Rectangle& clip);
 
-private:
-    /**
-     * Draws the themed border and background of a control.
-     *
-     * @param spriteBatch The sprite batch containing this control's border images.
-     * @param clip The clipping rectangle of this control's parent container.
-     */
-    virtual void drawBorder(SpriteBatch* spriteBatch, const Rectangle& clip);
-
-protected:
     /**
      * Draw the images associated with this control.
      *
@@ -680,30 +677,38 @@ protected:
     /**
      * Initialize properties common to STATE_ALL Controls.
      */
-    virtual void init(Theme::Style* style, Properties* properties);
+    virtual void initialize(Theme::Style* style, Properties* properties);
 
     /**
      * Container and classes that extend it should implement this and return true.
+     *
+     * @return true if this object is of class Container, false otherwise.
      */
     virtual bool isContainer();
 
     /**
      * Returns whether this control has been modified and requires an update.
+     *
+     * @return Whether this control has been modified and requires an update.
      */
     virtual bool isDirty();
 
     /**
      * Get a Control::State enum from a matching string.
+     *
+     * @param state The string to match.
+     *
+     * @return The Control::State enum that matches the given string.
      */
-    static State getStateFromString(const char* state);
+    static State getState(const char* state);
 
     /**
-     * Notify STATE_ALL listeners of a specific event.
+     * Notify this control's listeners of a specific event.
+     *
+     * @param eventType The event to trigger.
      */
     void notifyListeners(Listener::EventType eventType);
 
-    void addSpecificListener(Control::Listener* listener, Listener::EventType eventType);
-
     std::string _id;
     State _state;           // Determines overlay used during draw().
     Rectangle _bounds;      // Position, relative to parent container's clipping window, and desired size.
@@ -716,6 +721,7 @@ protected:
     std::map<Listener::EventType, std::list<Listener*>*>* _listeners;
 
 private:
+
     // Animation blending bits.
     static const char ANIMATION_POSITION_X_BIT = 0x01;
     static const char ANIMATION_POSITION_Y_BIT = 0x02;
@@ -731,6 +737,18 @@ private:
     void applyAnimationValueSizeHeight(float height, float blendWeight);
     void applyAnimationValueOpacity();
 
+    Control(const Control& copy);
+
+    /**
+     * Draws the themed border and background of a control.
+     *
+     * @param spriteBatch The sprite batch containing this control's border images.
+     * @param clip The clipping rectangle of this control's parent container.
+     */
+    virtual void drawBorder(SpriteBatch* spriteBatch, const Rectangle& clip);
+
+    void addSpecificListener(Control::Listener* listener, Listener::EventType eventType);
+
     // Gets the overlays requested in the overlayTypes bitflag.
     Theme::Style::Overlay** getOverlays(unsigned char overlayTypes, Theme::Style::Overlay** overlays);
 
@@ -741,8 +759,6 @@ private:
 
     // Ensures that this control has a copy of its style so that it can override it without affecting other controls.
     void overrideStyle();
-
-    Control(const Control& copy);
 };
 
 }

gameplay/src/Form.cpp

@@ -58,24 +58,9 @@ namespace gameplay
         // Create new form with given ID, theme and layout.
         const char* themeFile = formProperties->getString("theme");
         const char* layoutString = formProperties->getString("layout");
-        Form* form = Form::create(themeFile, getLayoutType(layoutString));
-
-        Theme* theme = form->_theme;
-        const char* styleName = formProperties->getString("style");
-        form->init(theme->getStyle(styleName), formProperties);
-
-        // Add all the controls to the form.
-        form->addControls(theme, formProperties);
-
-        SAFE_DELETE(properties);
-
-        return form;
-    }
-
-    Form* Form::create(const char* themeFile, Layout::Type type)
-    {
+        
         Layout* layout;
-        switch (type)
+        switch (getLayoutType(layoutString))
         {
         case Layout::LAYOUT_ABSOLUTE:
             layout = AbsoluteLayout::create();
@@ -95,6 +80,15 @@ namespace gameplay
         form->_layout = layout;
         form->_theme = theme;
 
+        //Theme* theme = form->_theme;
+        const char* styleName = formProperties->getString("style");
+        form->initialize(theme->getStyle(styleName), formProperties);
+
+        // Add all the controls to the form.
+        form->addControls(theme, formProperties);
+
+        SAFE_DELETE(properties);
+
         __forms.push_back(form);
 
         return form;

gameplay/src/Form.h

@@ -37,13 +37,13 @@ public:
      *      size     = <width, height>      // Size of the form, measured in pixels.
      *   
      *      // All the controls within this form.
-     *      container{}
-     *      label{}
-     *      textBox{}
-     *      button{}
-     *      checkBox{}
-     *      radioButton{}
-     *      slider{}
+     *      container { }
+     *      label { }
+     *      textBox { }
+     *      button { }
+     *      checkBox { }
+     *      radioButton { }
+     *      slider { }
      * }
      *
      * @param path Path to the properties file to create a new form from.
@@ -105,13 +105,22 @@ public:
      */
     void draw();
 
-protected:
+private:
     
+    /**
+     * Constructor.
+     */
     Form();
 
-    virtual ~Form();
+    /**
+     * Constructor.
+     */
+    Form(const Form& copy);
 
-    static Form* create(const char* textureFile, Layout::Type type);
+    /**
+     * Destructor.
+     */
+    virtual ~Form();
 
     /**
      * Initialize a quad for this form in order to draw it in 3D.
@@ -145,10 +154,6 @@ protected:
     Node* _node;                // Node for transforming this Form in world-space.
     FrameBuffer* _frameBuffer;  // FBO the Form is rendered into for texturing the quad.
     Matrix _projectionMatrix;   // Orthographic projection matrix to be set on SpriteBatch objects when rendering into the FBO.
-
-private:
-
-    Form(const Form& copy);
 };
 
 }

gameplay/src/Label.cpp

@@ -18,14 +18,14 @@ namespace gameplay
     Label* Label::create(Theme::Style* style, Properties* properties)
     {
         Label* label = new Label();
-        label->init(style, properties);
+        label->initialize(style, properties);
 
         return label;
     }
 
-    void Label::init(Theme::Style* style, Properties* properties)
+    void Label::initialize(Theme::Style* style, Properties* properties)
     {
-        Control::init(style, properties);
+        Control::initialize(style, properties);
 
         const char* text = properties->getString("text");
         if (text)

gameplay/src/Label.h

@@ -25,6 +25,7 @@ class Label : public Control
     friend class Container;
 
 public:
+
     /**
      * Set the text for this label to display.
      *
@@ -52,7 +53,15 @@ public:
     virtual void addListener(Control::Listener* listener, int eventFlags);
 
 protected:
+
+    /**
+     * Constructor.
+     */
     Label();
+
+    /**
+     * Destructor.
+     */
     virtual ~Label();
 
     /**
@@ -68,7 +77,7 @@ protected:
     /**
      * Initialize this label.
      */
-    virtual void init(Theme::Style* style, Properties* properties);
+    virtual void initialize(Theme::Style* style, Properties* properties);
 
     /**
      * Draw this label's text.
@@ -80,6 +89,7 @@ protected:
     std::string _text;      // The text displayed by this label.
 
 private:
+
     Label(const Label& copy);
 };
 

gameplay/src/RadioButton.cpp

@@ -27,7 +27,7 @@ RadioButton::~RadioButton()
 RadioButton* RadioButton::create(Theme::Style* style, Properties* properties)
 {
     RadioButton* radioButton = new RadioButton();
-    radioButton->init(style, properties);
+    radioButton->initialize(style, properties);
 
     properties->getVector2("imageSize", &radioButton->_imageSize);
 

gameplay/src/RadioButton.h

@@ -66,7 +66,15 @@ public:
     virtual void addListener(Control::Listener* listener, int eventFlags);
 
 protected:
+
+    /**
+     * Constructor.
+     */
     RadioButton();
+
+    /**
+     * Destructor.
+     */
     virtual ~RadioButton();
 
     /**
@@ -79,13 +87,41 @@ protected:
      */
     static RadioButton* create(Theme::Style* style, Properties* properties);
 
+    /**
+     * Touch callback on touch events.  Controls return true if they consume the touch event.
+     *
+     * @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 the control.
+     *
+     * @see Touch::TouchEvent
+     */
     bool touchEvent(Touch::TouchEvent evt, int x, int y, unsigned int contactIndex);
 
+    /**
+     * Called when a control's properties change.  Updates this control's internal rendering
+     * properties, such as its text viewport.
+     *
+     * @param clip The clipping rectangle of this control's parent container.
+     */
     void update(const Rectangle& clip);
 
+    /**
+     * Draw the images associated with this control.
+     *
+     * @param spriteBatch The sprite batch containing this control's icons.
+     * @param clip The clipping rectangle of this control's parent container.
+     */
     void drawImages(SpriteBatch* spriteBatch, const Rectangle& clip);
 
-    // Clear the _selected flag of all radio buttons in the given group.
+    /**
+     * Clear the _selected flag of all radio buttons in the given group.
+     *
+     * @param groupID The group to clear.
+     */
     static void clearSelected(const std::string& groupId);
 
     std::string _groupId;
@@ -93,6 +129,7 @@ protected:
     Vector2 _imageSize;
 
 private:
+
     RadioButton(const RadioButton& copy);
 };
 

gameplay/src/Slider.cpp

@@ -14,7 +14,7 @@ Slider::~Slider()
 Slider* Slider::create(Theme::Style* style, Properties* properties)
 {
     Slider* slider = new Slider();
-    slider->init(style, properties);
+    slider->initialize(style, properties);
 
     slider->_min = properties->getFloat("min");
     slider->_max = properties->getFloat("max");

gameplay/src/Slider.h

@@ -32,6 +32,7 @@ class Slider : public Label
     friend class Container;
 
 public:
+
     /**
      * Set the minimum value that can be set on this slider.
      *
@@ -90,16 +91,60 @@ public:
      */
     float getValue();
 
+    /**
+     * Add a listener to be notified of specific events affecting
+     * this control.  Event types can be OR'ed together.
+     * E.g. To listen to touch-press and touch-release events,
+     * pass <code>Control::Listener::TOUCH | Control::Listener::RELEASE</code>
+     * as the second parameter.
+     *
+     * @param listener The listener to add.
+     * @param eventFlags The events to listen for.
+     */
     void addListener(Control::Listener* listener, int eventFlags);
 
 protected:
+
+    /**
+     * Constructor.
+     */
     Slider();
+
+    /**
+     * Destructor.
+     */
     ~Slider();
 
+    /**
+     * Create a slider with a given style and properties.
+     *
+     * @param style The style to apply to this slider.
+     * @param properties The properties to set on this slider.
+     *
+     * @return The new slider.
+     */
     static Slider* create(Theme::Style* style, Properties* properties);
 
+    /**
+     * Touch callback on touch events.  Controls return true if they consume the touch event.
+     *
+     * @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 the control.
+     *
+     * @see Touch::TouchEvent
+     */
     bool touchEvent(Touch::TouchEvent evt, int x, int y, unsigned int contactIndex);
 
+    /**
+     * Draw the images associated with this control.
+     *
+     * @param spriteBatch The sprite batch containing this control's icons.
+     * @param clip The clipping rectangle of this control's parent container.
+     */
     void drawImages(SpriteBatch* spriteBatch, const Rectangle& clip);
 
     float _min;
@@ -108,6 +153,7 @@ protected:
     float _value;
 
 private:
+
     Slider(const Slider& copy);
 };
 

gameplay/src/TextBox.cpp

@@ -19,7 +19,7 @@ TextBox::~TextBox()
 TextBox* TextBox::create(Theme::Style* style, Properties* properties)
 {
     TextBox* textBox = new TextBox();
-    textBox->init(style, properties);
+    textBox->initialize(style, properties);
 
     return textBox;
 }
@@ -29,15 +29,6 @@ int TextBox::getLastKeypress()
     return _lastKeypress;
 }
 
-void TextBox::setCursorLocation(int x, int y)
-{
-    Theme::Border border = getBorder(_state);
-    Theme::Padding padding = getPadding();
-
-    _cursorLocation.set(x - border.left - padding.left + _clip.x,
-                       y - border.top - padding.top + _clip.y);
-}
-
 void TextBox::addListener(Control::Listener* listener, int eventFlags)
 {
     if ((eventFlags & Listener::VALUE_CHANGED) == Listener::VALUE_CHANGED)
@@ -80,7 +71,7 @@ bool TextBox::touchEvent(Touch::TouchEvent evt, int x, int y, unsigned int conta
             x > 0 && x <= _clipBounds.width &&
             y > 0 && y <= _clipBounds.height)
         {
-            setCursorLocation(x, y);
+            setCaretLocation(x, y);
             _dirty = true;
             return _consumeTouchEvents;
         }
@@ -89,7 +80,7 @@ bool TextBox::touchEvent(Touch::TouchEvent evt, int x, int y, unsigned int conta
         if (x > 0 && x <= _clipBounds.width &&
             y > 0 && y <= _clipBounds.height)
         {
-            setCursorLocation(x, y);
+            setCaretLocation(x, y);
             _state = FOCUS;
             _dirty = true;
             return _consumeTouchEvents;
@@ -115,7 +106,7 @@ void TextBox::keyEvent(Keyboard::KeyEvent evt, int key)
                         // TODO: Move cursor to beginning of line.
                         // This only works for left alignment...
                         
-                        //_cursorLocation.x = _clip.x;
+                        //_caretLocation.x = _clip.x;
                         //_dirty = true;
                         break;
                     }
@@ -131,10 +122,10 @@ void TextBox::keyEvent(Keyboard::KeyEvent evt, int key)
                         Font::Justify textAlignment = getTextAlignment(_state);
                         bool rightToLeft = getTextRightToLeft(_state);
 
-                        unsigned int textIndex = font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _cursorLocation, &_cursorLocation,
+                        unsigned int textIndex = font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _caretLocation, &_caretLocation,
                             textAlignment, true, rightToLeft);
                         _text.erase(textIndex, 1);
-                        font->getLocationAtIndex(_text.c_str(), _clip, fontSize, &_cursorLocation, textIndex,
+                        font->getLocationAtIndex(_text.c_str(), _clip, fontSize, &_caretLocation, textIndex,
                             textAlignment, true, rightToLeft);
                         _dirty = true;
                         notifyListeners(Listener::TEXT_CHANGED);
@@ -147,9 +138,9 @@ void TextBox::keyEvent(Keyboard::KeyEvent evt, int key)
                         Font::Justify textAlignment = getTextAlignment(_state);
                         bool rightToLeft = getTextRightToLeft(_state);
 
-                        unsigned int textIndex = font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _cursorLocation, &_cursorLocation,
+                        unsigned int textIndex = font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _caretLocation, &_caretLocation,
                             textAlignment, true, rightToLeft);
-                        font->getLocationAtIndex(_text.c_str(), _clip, fontSize, &_cursorLocation, textIndex - 1,
+                        font->getLocationAtIndex(_text.c_str(), _clip, fontSize, &_caretLocation, textIndex - 1,
                             textAlignment, true, rightToLeft);
                         _dirty = true;
                         break;
@@ -161,9 +152,9 @@ void TextBox::keyEvent(Keyboard::KeyEvent evt, int key)
                         Font::Justify textAlignment = getTextAlignment(_state);
                         bool rightToLeft = getTextRightToLeft(_state);
 
-                        unsigned int textIndex = font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _cursorLocation, &_cursorLocation,
+                        unsigned int textIndex = font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _caretLocation, &_caretLocation,
                             textAlignment, true, rightToLeft);
-                        font->getLocationAtIndex(_text.c_str(), _clip, fontSize, &_cursorLocation, textIndex + 1,
+                        font->getLocationAtIndex(_text.c_str(), _clip, fontSize, &_caretLocation, textIndex + 1,
                             textAlignment, true, rightToLeft);
                         _dirty = true;
                         break;
@@ -175,8 +166,8 @@ void TextBox::keyEvent(Keyboard::KeyEvent evt, int key)
                         Font::Justify textAlignment = getTextAlignment(_state);
                         bool rightToLeft = getTextRightToLeft(_state);
 
-                        _cursorLocation.y -= fontSize;
-                        font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _cursorLocation, &_cursorLocation,
+                        _caretLocation.y -= fontSize;
+                        font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _caretLocation, &_caretLocation,
                             textAlignment, true, rightToLeft);
                         _dirty = true;
                         break;
@@ -188,8 +179,8 @@ void TextBox::keyEvent(Keyboard::KeyEvent evt, int key)
                         Font::Justify textAlignment = getTextAlignment(_state);
                         bool rightToLeft = getTextRightToLeft(_state);
 
-                        _cursorLocation.y += fontSize;
-                        font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _cursorLocation, &_cursorLocation,
+                        _caretLocation.y += fontSize;
+                        font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _caretLocation, &_caretLocation,
                             textAlignment, true, rightToLeft);
                         _dirty = true;
                         break;
@@ -205,7 +196,7 @@ void TextBox::keyEvent(Keyboard::KeyEvent evt, int key)
                 Font::Justify textAlignment = getTextAlignment(_state);
                 bool rightToLeft = getTextRightToLeft(_state);
 
-                unsigned int textIndex = font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _cursorLocation, &_cursorLocation,
+                unsigned int textIndex = font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _caretLocation, &_caretLocation,
                     textAlignment, true, rightToLeft);
 
                 switch (key)
@@ -216,7 +207,7 @@ void TextBox::keyEvent(Keyboard::KeyEvent evt, int key)
                         {
                             --textIndex;
                             _text.erase(textIndex, 1);
-                            font->getLocationAtIndex(_text.c_str(), _clip, fontSize, &_cursorLocation, textIndex,
+                            font->getLocationAtIndex(_text.c_str(), _clip, fontSize, &_caretLocation, textIndex,
                                 textAlignment, true, rightToLeft);
 
                             _dirty = true;
@@ -232,7 +223,7 @@ void TextBox::keyEvent(Keyboard::KeyEvent evt, int key)
                         _text.insert(textIndex, 1, (char)key);
 
                         // Get new location of cursor.
-                        font->getLocationAtIndex(_text.c_str(), _clip, fontSize, &_cursorLocation, textIndex + 1,
+                        font->getLocationAtIndex(_text.c_str(), _clip, fontSize, &_caretLocation, textIndex + 1,
                             textAlignment, true, rightToLeft);
                 
                         _dirty = true;
@@ -262,7 +253,7 @@ void TextBox::update(const Rectangle& clip)
         Font::Justify textAlignment = getTextAlignment(_state);
         bool rightToLeft = getTextRightToLeft(_state);
 
-        font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _cursorLocation, &_cursorLocation,
+        font->getIndexAtLocation(_text.c_str(), _clip, fontSize, _caretLocation, &_caretLocation,
             textAlignment, true, rightToLeft);
     }
 }
@@ -279,11 +270,20 @@ void TextBox::drawImages(SpriteBatch* spriteBatch, const Rectangle& clip)
             const Theme::UVs uvs = getImageUVs("textCaret", _state);
             unsigned int fontSize = getFontSize(_state);
 
-            spriteBatch->draw(_cursorLocation.x - (region.width / 2.0f), _cursorLocation.y, region.width, fontSize, uvs.u1, uvs.v1, uvs.u2, uvs.v2, color);
+            spriteBatch->draw(_caretLocation.x - (region.width / 2.0f), _caretLocation.y, region.width, fontSize, uvs.u1, uvs.v1, uvs.u2, uvs.v2, color);
         }
     }
 
     _dirty = false;
 }
 
+void TextBox::setCaretLocation(int x, int y)
+{
+    Theme::Border border = getBorder(_state);
+    Theme::Padding padding = getPadding();
+
+    _caretLocation.set(x - border.left - padding.left + _clip.x,
+                       y - border.top - padding.top + _clip.y);
+}
+
 }

gameplay/src/TextBox.h

@@ -31,6 +31,7 @@ class TextBox : public Label
     friend class Container;
 
 public:
+
     /**
      * Add a listener to be notified of specific events affecting
      * this control.  Event types can be OR'ed together.
@@ -43,31 +44,86 @@ public:
      */
     virtual void addListener(Control::Listener* listener, int eventFlags);
 
+    /**
+     * Get the last key pressed within this text box.
+     *
+     * @return The last key pressed within this text box.
+     */
     int getLastKeypress();
 
 protected:
+
+    /**
+     * Constructor.
+     */
     TextBox();
+
+    /**
+     * Destructor.
+     */
     ~TextBox();
 
+    /**
+     * Create a text box with a given style and properties.
+     *
+     * @param style The style to apply to this text box.
+     * @param properties The properties to set on this text box.
+     *
+     * @return The new text box.
+     */
     static TextBox* create(Theme::Style* style, Properties* properties);
 
-    void setCursorLocation(int x, int y);
-
+    /**
+     * Touch callback on touch events.  Controls return true if they consume the touch event.
+     *
+     * @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 the control.
+     *
+     * @see Touch::TouchEvent
+     */
     bool touchEvent(Touch::TouchEvent evt, int x, int y, unsigned int contactIndex);
 
+    /**
+     * Keyboard callback on key events.
+     *
+     * @param evt The key event that occured.
+     * @param key If evt is KEY_PRESS or KEY_RELEASE then key is the key code from Keyboard::Key.
+     *            If evt is KEY_CHAR then key is the unicode value of the character.
+     * 
+     * @see Keyboard::KeyEvent
+     * @see Keyboard::Key
+     */
     void keyEvent(Keyboard::KeyEvent evt, int key);
 
+    /**
+     * Called when a control's properties change.  Updates this control's internal rendering
+     * properties, such as its text viewport.
+     *
+     * @param clip The clipping rectangle of this control's parent container.
+     */
     void update(const Rectangle& clip);
 
-    // Draw the cursor.
+    /**
+     * Draw the images associated with this control.
+     *
+     * @param spriteBatch The sprite batch containing this control's icons.
+     * @param clip The clipping rectangle of this control's parent container.
+     */
     void drawImages(SpriteBatch* spriteBatch, const Rectangle& clip);
 
-    Vector2 _cursorLocation;
+    Vector2 _caretLocation;
     unsigned int textIndex;
     int _lastKeypress;
 
 private:
+
     TextBox(const TextBox& copy);
+
+    void setCaretLocation(int x, int y);
 };
 
 }

gameplay/src/Theme.h

@@ -14,103 +14,119 @@ namespace gameplay
 /**
  * A theme is created and stored as part of a form and represents its appearance.
  * Once loaded, the appearance properties can be retrieved from their style IDs and set on other
- * UI controls.  A Theme has one property, 'texture', which points to an image containing
- * all the Icon, Cursor, Slider, and Skin sprites used by the theme.  Each set of sprites within
- * the texture is described in its own namespace.  The rest of the Theme consists of Style namespaces.
- * A Style describes the border, margin, and padding of a Control, what icons and cursors (if any) are
- * associated with a Control, and Font properties to apply to a Control's text.
+ * UI controls.  A Theme has one property, 'texture', which points to a texture atlas containing
+ * all the images used by the theme.  Cursor images, skins, and lists of images used by controls
+ * are defined in their own namespaces.  The rest of the Theme consists of Style namespaces.
+ * A Style describes the border, margin, and padding of a Control, what images, skins, and cursors
+ * are associated with a Control, and Font properties to apply to a Control's text.
  *
  * Below is an explanation of the properties that can be set within themes:
  *
  * theme
  * {
- *    texture = <Path to texture>
- *
- *    // Describes the images used for CheckBox and RadioButton icons.
- *    icon <iconID>
- *    {
- *        size            =   <width, height>     // Size of this icon.
- *        offPosition     =   <x, y>              // Position of the unchecked / unselected image.
- *        onPosition      =   <x, y>              // Position of the checked / selected image.
- *        color           =   <#ffffffff>         // Tint to apply to icon.
- *    }
- *   
- *    cursor <cursorID>
- *    {
- *        region  =   <x, y, width, height>   // Region within the texture of cursor sprite.
- *        color   =   <#ffffffff>             // Tint to apply to cursor.
- *    }
- *   
- *    slider <sliderID>
- *    {
- *        minCapRegion    =   <x, y, width, height>   // Left / bottom slider cap.
- *        maxCapRegion    =   <x, y, width, height>   // Right / top slider cap.
- *        markerRegion    =   <x, y, width, height>   // Shows the slider's current position.
- *        trackRegion     =   <x, y, width, height>   // Track the marker slides along.
- *        color           =   <#ffffffff>             // Tint to apply to slider sprites.
- *    }
- *   
- *    // Defines the border and background of a Control.
- *    Skin <skinID>
- *    {
- *        // The corners and edges of the given region will be used as border sprites.
- *        border
- *        {
- *            top     =   <int>   // Height of top border, top corners.
- *            bottom  =   <int>   // Height of bottom border, bottom corners.
- *            left    =   <int>   // Width of left border, left corners.
- *            right   =   <int>   // Width of right border, right corners.
- *        }
- *       
- *        region  =   <x, y, width, height>   // Total Skin region including entire border.
- *        color   =   <#ffffffff>             // Tint to apply to Skin sprites.
- *    }
- *   
- *    style <styleID>
- *    {
- *        // Layouts may make use of a style's margin to put space between adjacent controls.
- *        margin
- *        {
- *            top     =   <int>
- *            bottom  =   <int>
- *            left    =   <int>
- *            right   =   <int>        
- *        }
- *       
- *        // Padding is the space between a control's border and its content.
- *        padding
- *        {
- *            top     =   <int>
- *            bottom  =   <int>
- *            left    =   <int>
- *            right   =   <int>        
- *        }
- *       
- *        // This overlay is used when a control is enabled but not active or focused.
- *        normal
- *        {
- *            Skin   =   <SkinID>               // Skin to use for border and background sprites.
- *            checkBox    =   <iconID>                    // Icon to use for checkbox sprites.
- *            radioButton =   <iconID>                    // Icon to use for radioButton sprites.
- *            slider      =   <sliderID>                  // Slider to use for slider sprites.
- *            mouseCursor =   <cursorID>                  // Cursor to use when the mouse is over this control.
- *            textCursor  =   <cursorID>                  // Cursor to use within a textBox.
- *            font        =   <Path to font>              // Font to use for rendering text.
- *            fontSize    =   <int>                       // Size of text.
- *            textColor   =   <#ffffffff>                 // Color of text.
- *            alignment   =   <Text alignment constant>   // Member of Font::Justify enum.
- *            rightToLeft =   <bool>                      // Whether to draw text from right to left.
- *        }
- *       
- *        // This overlay is used when the control is in focus.
- *        // If not specified, the 'normal' overlay will be used.
- *        focus{}
- *       
- *        // This overlay is used when the control is active.
- *        // (Touch or mouse is down within the control.)
- *        // If not specified, the 'normal' overlay will be used.
- *        active{}
- *    }
+ *     texture = <Path to texture>
+ * 
+ *     // Describes a single image, to be used as a cursor.
+ *     cursor <Cursor ID>
+ *     {
+ *         region = <x, y, width, height>
+ *         color = <#ffffffff>
+ *     }
+ * 
+ *     // Describes all the images used by a control for one or more states.
+ *     imageList <ImageList ID>
+ *     {
+ *         image checked
+ *         {
+ *             region = <x, y, width, height>
+ *         }
+ * 
+ *         image unchecked
+ *         {
+ *             region = <x, y, width, height>
+ *             color = <#fffffffff>            // Optionally override image-list color.
+ *         }
+ * 
+ *         color = <#fffffffff>    // Default blend color for images that don't specify their own.
+ *     }
+ *     
+ *     // Defines the border and background of a Control.
+ *     skin <Skin ID>
+ *     {
+ *         // The corners and edges of the given region will be used as border sprites.
+ *         border
+ *         {
+ *             top     =   <int>   // Height of top border, top corners.
+ *             bottom  =   <int>   // Height of bottom border, bottom corners.
+ *             left    =   <int>   // Width of left border, left corners.
+ *             right   =   <int>   // Width of right border, right corners.
+ *         }
+ *         
+ *         region  =   <x, y, width, height>   // Total container region including entire border.
+ *         color   =   <#ffffffff>             // Tint to apply to skin.
+ *     }
+ *     
+ *     style <Style ID>
+ *     {
+ *         // Layouts may make use of a style's margin to put space between adjacent controls.
+ *         margin
+ *         {
+ *             top     =   <int>
+ *             bottom  =   <int>
+ *             left    =   <int>
+ *             right   =   <int>        
+ *         }
+ *         
+ *         // Padding is the space between a control's border and its content.
+ *         padding
+ *         {
+ *             top     =   <int>
+ *             bottom  =   <int>
+ *             left    =   <int>
+ *             right   =   <int>        
+ *         }
+ *         
+ *         // Properties used when in control is in the normal state.
+ *         stateNormal
+ *         {
+ *             skin   =   <Skin ID>             // Skin to use for border and background sprites.
+ *             imageList = <ImageList ID>
+ * 
+ *             cursor      =   <Cursor ID>                 // Cursor to use when the mouse is over this control.
+ *             font        =   <Path to font>              // Font to use for rendering text.
+ *             fontSize    =   <int>                       // Size of text.
+ *             textColor   =   <#ffffffff>                 // Color of text.
+ *             alignment   =   <Text alignment constant>   // Member of Font::Justify enum.
+ *             rightToLeft =   <bool>                      // Whether to draw text from right to left.
+ *             opacity     =   <float>                     // Opacity to apply to all text/border/icon colors.
+ *         }
+ *         
+ *         // Properties used when in control is in the focus state
+ *         // If not specified, the 'normal' overlay will be used.
+ *         stateFocus
+ *         {
+ *             skin   =   <Skin ID>             // Skin to use for border and background sprites.
+ *             ...
+ *         }
+ *         
+ *         // Properties used when in control is in the focus. 
+ *         // This is when a touch/mouse is down within the control.
+ *         // If not specified, the 'normal' overlay will be used.
+ *         stateActive
+ *         {
+ *             skin   =   <Skin ID>             // Skin to use for border and background sprites.
+ *             ...
+ *         }
+ * 
+ *         // Properties used when in control is in the focus. 
+ *         // This is when a touch/mouse is down within the control.
+ *         // If not specified, the 'normal' overlay will be used.
+ *         state-disabled
+ *         {
+ *             skin   =   <Skin ID>             // Skin to use for border and background sprites.
+ *             ...        
+ *         }
+ *     }
  * }
  *
  */

gameplay/src/ThemeStyle.h

@@ -15,8 +15,8 @@ namespace gameplay
 /**
  * This class represents the appearance of a control.  A style can have padding and margin values,
  * as well as overlays for each of the control's states.  Each overlay in turn can reference
- * the above classes to determine the border, background, cursor, and icon settings to use for
- * a particular state.
+ * other theme classes to determine the border, background, cursor, and image settings to use for
+ * a particular state, as well as color and font settings, etcetera.
  */
 class Theme::Style
 {
@@ -159,6 +159,23 @@ private:
         float _opacity;
     };
 
+    /**
+     * Constructor.
+     */
+    Style(const char* id, float tw, float th,
+          const Theme::Margin& margin, const Theme::Padding& padding,
+          Overlay* normal, Overlay* focus, Overlay* active, Overlay* disabled);
+
+    /**
+     * Constructor.
+     */
+    Style(const Style& style);
+
+    /**
+     * Destructor.
+     */
+    ~Style();
+
     /**
      * Returns the Id of this Style.
      */
@@ -192,25 +209,6 @@ private:
      * The margin is used by Layouts other than AbsoluteLayout to put space between Controls.
      */
     void setMargin(float top, float bottom, float left, float right);
-
-private:
-
-    /**
-     * Constructor.
-     */
-    Style(const char* id, float tw, float th,
-          const Theme::Margin& margin, const Theme::Padding& padding,
-          Overlay* normal, Overlay* focus, Overlay* active, Overlay* disabled);
-
-    /**
-     * Constructor.
-     */
-    Style(const Style& style);
-
-    /**
-     * Destructor.
-     */
-    ~Style();
         
     std::string _id;
     float _tw;

gameplay/src/VerticalLayout.h

@@ -17,6 +17,7 @@ class VerticalLayout : public Layout
     friend class Container;
 
 public:
+
     /**
      * Set whether this layout will start laying out controls from the bottom of the container.
      * This setting defaults to 'false', meaning controls will start at the top.
@@ -40,16 +41,38 @@ public:
     Layout::Type getType();
 
 protected:
+
+    /**
+     * Constructor.
+     */
     VerticalLayout();
+
+    /**
+     * Destructor.
+     */
     virtual ~VerticalLayout();
 
+    /**
+     * Create a VerticalLayout.
+     *
+     * @return a VerticalLayout object.
+     */
     static VerticalLayout* create();
 
+    /**
+     * Update the controls contained by the specified container.
+     *
+     * Controls are placed next to one another vertically until
+     * the bottom-most edge of the container is reached.
+     *
+     * @param container The container to update.
+     */
     void update(const Container* container);
 
     bool _bottomToTop;
 
 private:
+
     VerticalLayout(const VerticalLayout& copy);
 };