📝 Add documentation to Input, Label, Radio, Select and Slider UIObjects.

pandora/game_objects/ui_objects/Input.js

@@ -19,26 +19,70 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code Input} class represents an UIObject that holds and HTML input box.
+ * 
+ * ! All GameObjects need to be inside the tree to do anything (can be added as a child
+ * ! of another GameObject on the tree or as a root).
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class Input extends UIObject
 {
+    /**
+     * @constructor
+     * Initializes an empty Input with the given parameters.
+     * 
+     * @param {String} name     name for the Input GameObject.
+     * @param {String} value    default message inside the input box.
+     * @param {String} type     type of the input box (e.g: "text", "password"). 
+     */
     constructor(name, value = "", type = "text")
     {
         super(name);
 
-        this.P5Element = createInput(value, type);
-        this.setPosition(0, 0);
-        this.setStyle(STYLE.DEFAULT_STYLE);
-        this.size = new Vector2(200, 30);
+        this.P5Element = createInput(value, type); // This Button's HTML input.
+        this.setPosition(0, 0); // Set the position of the Input on the secondary buffer.
+        this.setSize(200, 30); // Set the size of the Input on the secondary buffer.
 
-        this.connectCallbacks();
-        this.P5Element.input(this.onInput);
-    }
-
-    _onInput()
-    {
+        this.setStyle(STYLE.DEFAULT_STYLE); // Set the default style of the UIObject.
 
+        this.connectCallbacks(); // Connect events of the p5.Element.
+        this.P5Element.input(this.onInput); // Connect the extra event inputs have.
     }
 
+    /**
+     * @override
+     * Defines default signals for UIObjects and serves as the caller to this UIObject's
+     * _initSignals() callbacks. Also adds the extra onChaged signal for CheckBoxes.
+     * 
+     * @signal mousePressed     emited once every time a mouse button is pressed over this
+     *                          UIObject.
+     * @signal doubleClicked    emited once every time a mouse button is pressed twice over
+     *                          this UIObject.
+     * @signal mouseWheel       emited once everty time a mouse wheel is scrolled over this
+     *                          UIObject. Passes one argument {event} that holds the deltaY
+     *                          property, that holds a number based on how much was vertically
+     *                          scrolled (up is positive) and the deltaX property, that holds a
+     *                          number based on how much was horizontaly scrolled (right is positive).
+     * @signal mouseReleased    emited once every time a mouse button is released over this
+     *                          UIObject.
+     * @signal mouseClicked     emited once every time a mouse button is pressed and released
+     *                          over this UIObject.
+     * @signal mouseMoved       emited once every time a mouse moves over this UIObject.
+     * @signal mouseOver        emited once every time a mouse moves onto this UIObject.
+     * @signal mouseOut         emited once every time a mouse moves out of this UIObject.
+     * @signal touchStarted     emited once every time a touch is regiestered over this UIObject.
+     * @signal touchMoved       emited once every time a touch move is regiestered over this
+     *                          UIObject.
+     * @signal touchEnded       emited once every time a touch is regiestered over this UIObject.
+     * @signal dragOver         emited once every time a file is dragged over this UIObject.
+     * @signal dragLeave        emited once every time a dragged file leaves this UIObject's area.
+     * 
+     * @signal input            emited once every time and input is dettected.
+     */
     initSignals()
     {
         this.addSignal("mousePressed");
@@ -59,9 +103,25 @@ class Input extends UIObject
         this._initSignals();
     }
 
+    /**
+     * Called once everty this this UIObject's input is triggered i.e typing.
+     * Connectec to the input event from this UIObject's p5.Element.
+     * Serves as an emitter to the input signal and calls the _onInput()
+     * callback.
+     */
     onInput()
     {
         this.pandoraObject.emitSignal("input");
         this.pandoraObject._onInput();
     }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once everty this this UIObject's input is triggered i.e typing.
+     */
+    _onInput()
+    {
+
+    }
 }

pandora/game_objects/ui_objects/Label.js

@@ -19,23 +19,57 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code Lagel} class represents an UIObject that holds and HTML label.
+ * 
+ * ! All GameObjects need to be inside the tree to do anything (can be added as a child
+ * ! of another GameObject on the tree or as a root).
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class Label extends UIObject
 {
+    /**
+     * @constructor
+     * Initializes and empty Label with the specified parameters.
+     * 
+     * @param {String} name name for the Label GameObject. 
+     * @param {String} text inner HTML text of the label.
+     */
     constructor(name, text = "Label")
     {
         super(name);
-        this.text = text;
-        this.P5Element = createDiv(text);
-        this.size = new Vector2(200, 50);
 
-        this.setStyle(STYLE.DEFAULT_STYLE);
+        this.text = text; // This Label's inner HTML text.
+        this.P5Element = createDiv(text); // This Label's HTML label.
+        this.setPosition(0, 0); // Set the position of the Label on the secondary buffer.
+        this.setSize(200, 50); // Set the size of the Label on the secondary buffer.
 
-        this.connectCallbacks();
+        this.setStyle(STYLE.DEFAULT_STYLE); // Set the default style of the UIObject.
+
+        this.connectCallbacks(); // Connect events of the p5.Element.
     }
 
+    /**
+     * Sets the text inside this Label's HTML label.
+     * 
+     * @param {String} t    new text for the label.
+     */
     setText(t)
     {
         this.P5Element.html(t);
         this.text = t;
     }
+
+    /**
+     * Returns this Label's HTML label's text.
+     * 
+     * @returns {String}    HTML label's text.
+     */
+    getText()
+    {
+        return this.text;
+    }
 }

pandora/game_objects/ui_objects/Radio.js

@@ -19,34 +19,63 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code Radio} class represents an UIObject that holds and HTML radio button.
+ * 
+ * ! All GameObjects need to be inside the tree to do anything (can be added as a child
+ * ! of another GameObject on the tree or as a root).
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class Radio extends UIObject
 {
+    /**
+     * @constructor
+     * Initializes an empty Radio.
+     * 
+     * @param {String} name name for the Radio GameObject. 
+     */
     constructor(name)
     {
         super(name);
 
-        this.P5Element = createRadio();
-        this.setPosition(10, 10);
-        this.setStyle(STYLE.DEFAULT_STYLE);
-        this.multiLine = false;
+        this.P5Element = createRadio(); // This Radio's HTML radio.
+        this.setPosition(10, 10); // Set this position of the Radio on the secondary buffer.
+        this.multiLine = false; // Should the different radio buttons be shown on separate lines?
 
-        this.connectCallbacks();
-        this.P5Element.changed(this.onChanged);
+        this.setStyle(STYLE.DEFAULT_STYLE); // Set the default style of the UIObject.
+
+        this.connectCallbacks(); // Connect events of the p5.Element.
+        this.P5Element.changed(this.onChanged); // Connect the extra event radios have.
     }
 
-    // Setters
+    /**
+     * Sets the selected option on this Radio's HTML radio button based on its value.
+     * 
+     * @param {String} value    value of the radio button to be selected.
+     */
     setSelected(value)
     {
         this.P5Element.selected(value);
     }
 
-    // Getters
+    /**
+     * Returns the value of the selected option from this Radio's HTML radio button.
+     * 
+     * @returns {String}    the value of the selected option.
+     */
     getSelected()
     {
         return this.P5Element.selected();
     }
 
-    // Methods
+    /**
+     * Inserts a new option on this Radio's HTML radio button with the given value.
+     * 
+     * @param {String} value    value for the new option.
+     */
     addOption(value)
     {
         this.P5Element.option(value);
@@ -61,6 +90,10 @@ class Radio extends UIObject
     //     this.P5Element.remove(value);
     // }
 
+    /**
+     * This fucntion creates separete HTML divs for each option on this Radio's HTML radio button ]
+     * in order to make them appear on different lines.
+     */
     makeMultiline()
     {
         this.multiLine = true;
@@ -74,6 +107,9 @@ class Radio extends UIObject
         this.fixRadioDivElement();
     }
 
+    /**
+     * Fixes de div elements after the call to makeMultiLine().
+     */
     fixRadioDivElement()
     {
         this.P5Element._getInputChildrenArray = function()
@@ -82,12 +118,36 @@ class Radio extends UIObject
         }
     }
 
-    // Callbacks
-    _onChanged()
-    {
-        console.log(this.getSelected());
-    }
-
+    /**
+     * @override
+     * Defines default signals for UIObjects and serves as the caller to this UIObject's
+     * _initSignals() callbacks. Also adds the extra onChaged signal for CheckBoxes.
+     * 
+     * @signal mousePressed     emited once every time a mouse button is pressed over this
+     *                          UIObject.
+     * @signal doubleClicked    emited once every time a mouse button is pressed twice over
+     *                          this UIObject.
+     * @signal mouseWheel       emited once everty time a mouse wheel is scrolled over this
+     *                          UIObject. Passes one argument {event} that holds the deltaY
+     *                          property, that holds a number based on how much was vertically
+     *                          scrolled (up is positive) and the deltaX property, that holds a
+     *                          number based on how much was horizontaly scrolled (right is positive).
+     * @signal mouseReleased    emited once every time a mouse button is released over this
+     *                          UIObject.
+     * @signal mouseClicked     emited once every time a mouse button is pressed and released
+     *                          over this UIObject.
+     * @signal mouseMoved       emited once every time a mouse moves over this UIObject.
+     * @signal mouseOver        emited once every time a mouse moves onto this UIObject.
+     * @signal mouseOut         emited once every time a mouse moves out of this UIObject.
+     * @signal touchStarted     emited once every time a touch is regiestered over this UIObject.
+     * @signal touchMoved       emited once every time a touch move is regiestered over this
+     *                          UIObject.
+     * @signal touchEnded       emited once every time a touch is regiestered over this UIObject.
+     * @signal dragOver         emited once every time a file is dragged over this UIObject.
+     * @signal dragLeave        emited once every time a dragged file leaves this UIObject's area.
+     * 
+     * @signal changed          emited once every time this UIObject's radio button's value is changed.
+     */
     initSignals()
     {
         this.addSignal("mousePressed");
@@ -108,9 +168,25 @@ class Radio extends UIObject
         this._initSignals();
     }
 
+    /**
+     * Called once every time this UIObject's radio buttons's value is changed.
+     * Connected to the changed event from this UIObject's p5.Element.
+     * Serves as an emiter to the changed signal and calls the _onChanged()
+     * callback.
+     */
     onChanged()
     {
         this.pandoraObject.emitSignal("changed");
         this.pandoraObject._onChanged();
     }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time this UIObject's radio button's value is changed.
+     */
+    _onChanged()
+    {
+        console.log(this.getSelected());
+    }
 }

pandora/game_objects/ui_objects/Select.js

@@ -19,41 +19,69 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code Select} class represents an UIObject that holds and HTML select.
+ * 
+ * ! All GameObjects need to be inside the tree to do anything (can be added as a child
+ * ! of another GameObject on the tree or as a root).
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class Select extends UIObject
 {
+    /**
+     * @constructor
+     * Intializes an empty Select.
+     * 
+     * @param {String} name name for the Select GameObject.
+     */
     constructor(name)
     {
         super(name);
 
-        this.P5Element = createSelect();
-        this.setPosition(0, 0);
-        this.setSize(100, 20);
-        this.setStyle(STYLE.DEFAULT_STYLE);
+        this.P5Element = createSelect(); // This Select's HTML select.
+        this.setPosition(0, 0); // Set this Select's position on the secondary buffer.
+        this.setSize(100, 20); // Set this Select's size on the secondary buffer.
 
-        this.connectCallbacks();
-        this.P5Element.changed(this.onChanged);
+        this.setStyle(STYLE.DEFAULT_STYLE); // Set this UIObject's default style.
+
+        this.connectCallbacks(); // Connect the events of the p5.Element.
+        this.P5Element.changed(this.onChanged); // Connect the extra event selects have.
     }
 
-    // Setters
+    /**
+     * Set this Select's selected option based on the option's value.
+     * 
+     * @param {String} value    value of the option to be selected.
+     */
     setSelected(value)
     {
         this.P5Element.selected(value);
     }
 
-    // Getters
+    /**
+     * Returns the selecte option's value.
+     * 
+     * @returns {String}
+     */
     getSelected()
     {
         return this.P5Element.selected();
     }
 
-    // Methods
+    /**
+     * Add a new option to this Select's HTML select with the given value.
+     * 
+     * @param {String} value    value for the new option.
+     */
     addOption(value)
     {
         this.P5Element.option(value);
     }
 
-    // TODO confirm if disable methods really dont exist or if
-    // something is fucky wooky.
+    // TODO confirm if disable methods really dont exist or if something is broken.
 
     // disableAll()
     // {
@@ -65,12 +93,36 @@ class Select extends UIObject
     //     this.P5Element.disable(value);
     // }
 
-    // Callbacks
-    _onChanged()
-    {
-
-    }
-
+    /**
+     * @override
+     * Defines default signals for UIObjects and serves as the caller to this UIObject's
+     * _initSignals() callbacks. Also adds the extra onChaged signal for CheckBoxes.
+     * 
+     * @signal mousePressed     emited once every time a mouse button is pressed over this
+     *                          UIObject.
+     * @signal doubleClicked    emited once every time a mouse button is pressed twice over
+     *                          this UIObject.
+     * @signal mouseWheel       emited once everty time a mouse wheel is scrolled over this
+     *                          UIObject. Passes one argument {event} that holds the deltaY
+     *                          property, that holds a number based on how much was vertically
+     *                          scrolled (up is positive) and the deltaX property, that holds a
+     *                          number based on how much was horizontaly scrolled (right is positive).
+     * @signal mouseReleased    emited once every time a mouse button is released over this
+     *                          UIObject.
+     * @signal mouseClicked     emited once every time a mouse button is pressed and released
+     *                          over this UIObject.
+     * @signal mouseMoved       emited once every time a mouse moves over this UIObject.
+     * @signal mouseOver        emited once every time a mouse moves onto this UIObject.
+     * @signal mouseOut         emited once every time a mouse moves out of this UIObject.
+     * @signal touchStarted     emited once every time a touch is regiestered over this UIObject.
+     * @signal touchMoved       emited once every time a touch move is regiestered over this
+     *                          UIObject.
+     * @signal touchEnded       emited once every time a touch is regiestered over this UIObject.
+     * @signal dragOver         emited once every time a file is dragged over this UIObject.
+     * @signal dragLeave        emited once every time a dragged file leaves this UIObject's area.
+     * 
+     * @signal changed          emited once every time this UIObject's select's value is changed.
+     */
     initSignals()
     {
         this.addSignal("mousePressed");
@@ -91,9 +143,25 @@ class Select extends UIObject
         this._initSignals();
     }
 
+    /**
+     * Called once every time this UIObject's select's value is changed.
+     * Connected to the changed event from this UIObject's p5.Element.
+     * Serves as an emiter to the changed signal and calls the _onChanged()
+     * callback.
+     */
     onChanged()
     {
         this.pandoraObject.emitSignal("changed");
         this.pandoraObject._onChanged();
     }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time this UIObject's select's value is changed.
+     */
+    _onChanged()
+    {
+
+    }
 }

pandora/game_objects/ui_objects/Slider.js

@@ -19,25 +19,72 @@
  * along with Pandora.  If not, see <https://www.gnu.org/licenses/>.
  *************************************************************************/
 
+/**
+ * The {@code Slider} class represents an UIObject that holds and HTML slider.
+ * 
+ * ! All GameObjects need to be inside the tree to do anything (can be added as a child
+ * ! of another GameObject on the tree or as a root).
+ * 
+ * @author Pedro Schneider
+ * 
+ * @class
+ */
 class Slider extends UIObject
 {
+    /**
+     * @constructor
+     * Initializes a Slider with the specified parameters.
+     * 
+     * @param {String} name     name for the Slider GameObject. 
+     * @param {number} min      minimum value on the slider.
+     * @param {number} max      maximum value on the slider.
+     * @param {number} value    initial value for the slider.
+     * @param {number} step     step value for the slider.
+     */
     constructor(name, min = 0, max = 100, value = 0, step = 0)
     {
         super(name);
-        this.P5Element = createSlider(min, max, value, step);
-        this.setPosition(0, 0);
-        this.setSize(200, 25);
-        this.setStyle(STYLE.DEFAULT_STYLE);
 
-        this.connectCallbacks();
-        this.P5Element.changed(this.onChanged);
-    }
+        this.P5Element = createSlider(min, max, value, step); // This Slider's HTML slider.
+        this.setPosition(0, 0); // Set this Slider's position on the secondary buffer.
+        this.setSize(200, 25); // Set this Slider's size on the secondary buffer.
 
-    _onChanged()
-    {
+        this.setStyle(STYLE.DEFAULT_STYLE); // Set this UIObject's default style.
 
+        this.connectCallbacks(); // Connect the events of the p5.Element.
+        this.P5Element.changed(this.onChanged); // Connect the extra event sliders have.
     }
 
+    /**
+     * @override
+     * Defines default signals for UIObjects and serves as the caller to this UIObject's
+     * _initSignals() callbacks. Also adds the extra onChaged signal for CheckBoxes.
+     * 
+     * @signal mousePressed     emited once every time a mouse button is pressed over this
+     *                          UIObject.
+     * @signal doubleClicked    emited once every time a mouse button is pressed twice over
+     *                          this UIObject.
+     * @signal mouseWheel       emited once everty time a mouse wheel is scrolled over this
+     *                          UIObject. Passes one argument {event} that holds the deltaY
+     *                          property, that holds a number based on how much was vertically
+     *                          scrolled (up is positive) and the deltaX property, that holds a
+     *                          number based on how much was horizontaly scrolled (right is positive).
+     * @signal mouseReleased    emited once every time a mouse button is released over this
+     *                          UIObject.
+     * @signal mouseClicked     emited once every time a mouse button is pressed and released
+     *                          over this UIObject.
+     * @signal mouseMoved       emited once every time a mouse moves over this UIObject.
+     * @signal mouseOver        emited once every time a mouse moves onto this UIObject.
+     * @signal mouseOut         emited once every time a mouse moves out of this UIObject.
+     * @signal touchStarted     emited once every time a touch is regiestered over this UIObject.
+     * @signal touchMoved       emited once every time a touch move is regiestered over this
+     *                          UIObject.
+     * @signal touchEnded       emited once every time a touch is regiestered over this UIObject.
+     * @signal dragOver         emited once every time a file is dragged over this UIObject.
+     * @signal dragLeave        emited once every time a dragged file leaves this UIObject's area.
+     * 
+     * @signal changed          emited once every time this UIObject's slider's value is changed.
+     */
     initSignals()
     {
         this.addSignal("mousePressed");
@@ -58,9 +105,25 @@ class Slider extends UIObject
         this._initSignals();
     }
 
+    /**
+     * Called once every time this UIObject's slider's value is changed.
+     * Connected to the changed event from this UIObject's p5.Element.
+     * Serves as an emiter to the changed signal and calls the _onChanged()
+     * callback.
+     */
     onChanged()
     {
         this.pandoraObject.emitSignal("changed");
         this.pandoraObject._onChanged();
     }
+
+    /**
+     * @callback
+     * ! This function should be overriden, it provides no default functionality.
+     * Called once every time this UIObject's slider's value is changed.
+     */
+    _onChanged()
+    {
+
+    }
 }