documentation for core ui kinds

enyojs · Feb 29, 2012 · 248e1a4 · 248e1a4
1 parent a0c1c3c
commit 248e1a4
Show file tree

Hide file tree

Showing 9 changed files with 65 additions and 21 deletions.
diff --git a/source/ui/Button.js b/source/ui/Button.js
@@ -1,10 +1,16 @@
+/**
+	Implements an HTML button, with support for grouping
+*/
 enyo.kind({
 	name: "enyo.Button",
+	//* @protected
 	kind: enyo.ToolDecorator,
 	tag: "Button",
+	//* @public
 	published: {
 		disabled: false
 	},
+	//* @protected
 	create: function() {
 		this.inherited(arguments);
 		this.disabledChanged();

diff --git a/source/ui/Checkbox.js b/source/ui/Checkbox.js
@@ -1,16 +1,24 @@
+/**
+	Implements an HTML checkbox input, with support for grouping
+*/
 enyo.kind({
 	name: "enyo.Checkbox",
+	//* @protected
 	kind: enyo.Input,
 	attributes: {
 		type: "checkbox"
 	},
 	events: {
 		onActivate: ""
 	},
+	//* @public
 	published: {
+		//* Value of the checkbox
 		checked: false,
+		//* Group API requirement for determining selected item
 		active: false
 	},
+	//* @protected
 	handlers: {
 		onchange: "change",
 		onclick: "click"

diff --git a/source/ui/Group.js b/source/ui/Group.js
@@ -1,15 +1,18 @@
+/**
+	Provides a wrapper around multiple elements. Enables creation of radio groups from arbitrary components supporting the [GroupItem](#enyo.GroupItem) api.
+*/
 enyo.kind({
 	name: "enyo.Group",
 	published: {
+		//* Can there be only one?
 		highlander: true,
+		//* The control that is selected
 		active: null
 	},
+	//* @protected
 	handlers: {
 		onActivate: "activate"
 	},
-	create: function() {
-		this.inherited(arguments);
-	},
 	activate: function(inSender, inEvent) {
 		if (this.highlander) {
 			// deactivation messages are ignored unless it's an attempt
@@ -35,4 +38,4 @@ enyo.kind({
 			this.active.addClass("active");
 		}
 	}
-});
+});
diff --git a/source/ui/GroupItem.js b/source/ui/GroupItem.js
@@ -1,13 +1,15 @@
+//* Base kind for the Grouping api
 enyo.kind({
 	name: "enyo.GroupItem",
 	published: {
 		active: false
 	},
+	//* @protected
 	create: function() {
 		this.inherited(arguments);
 		this.activeChanged();
 	},
 	activeChanged: function() {
 		this.bubble("onActivate");
 	}
-});
+});
diff --git a/source/ui/Image.js b/source/ui/Image.js
@@ -1,5 +1,9 @@
+/**
+	Implements an HTML img element, and bubbles the onload, and onerror events
+*/
 enyo.kind({
 	name: "Image",
+	//* @protected
 	tag: "img",
 	attributes: {
 		onload: enyo.bubbler,

diff --git a/source/ui/Input.js b/source/ui/Input.js
@@ -1,14 +1,22 @@
+/**
+	Implements an HTML input element with cross platform support for change events
+*/
 enyo.kind({
 	name: "enyo.Input",
 	published: {
+		//* Default value of the input
 		value: "",
+		//* Text to display when the input is empty
 		placeholder: "",
 		disabled: false
 	},
 	events: {
+		//* Sent when the input's value has changed, support for IE included.
 		onInputChange: "",
+		//* Sent when the input's is disabled or enabled.
 		onDisabledChange: ""
 	},
+	//* @protected
 	tag: "input",
 	classes: "enyo-input",
 	attributes: {

diff --git a/source/ui/NoDom.js b/source/ui/NoDom.js
@@ -1,6 +1,9 @@
+/**
+	A control that returns as its components HTML as its own.
+*/
 enyo.kind({
 	name: "enyo.NoDom",
 	generateOuterHtml: function(inHtml) {
 		return inHtml;
 	}
-});
+});
diff --git a/source/ui/Repeater.js b/source/ui/Repeater.js
@@ -1,37 +1,45 @@
-enyo.kind({
+/**
+	A simple control for making lists of items.
+
+	Components of Repeater are copied for each row created, wrapped in a control keeping state of the row index.
+
+	Example:
+
+		{kind: "Repeater", rows: 2, onSetupRow: "setImageSource", components: [
+			{kind: "Image"}
+		]}
+
+		setImageSource: function(inSender, inEvent) {
+			var index = inEvent.index;
+			var rowControl = inEvent.row;
+			rowControl.$.image.setSrc(this.imageSources[index]);
+		}
+*/
+enyo.kind({
 	name: "enyo.Repeater",
 	kind: enyo.Control,
 	published: {
+		//* How many rows to render
 		rows: 0
 	},
 	events: {
+		//* Sends the row index, and the row control, for decoration
 		onSetupRow: ""
 	},
+	//* @protected
 	initComponents: function() {
 		this.rowComponents = this.components;
 		this.components = null;
 		this.inherited(arguments);
 	},
-	//* @protected
+	//* @public
-	generateInnerHtml: function() {
+	//* Render the list
-		//this.build();
-		return this.inherited(arguments);
-	},
 	build: function() {
 		this.destroyClientControls();
 		for (var i=0; i<this.rows; i++) {
 			var c = this.createComponent({kind: "NoDom", rowIndex: i});
 			c.createComponents(this.rowComponents);
 			this.doSetupRow({index: i, row: c});
 		}
-	},
-	XdispatchEvent: function(inEventName, inEvent, inSender) {
-		if (inSender && inSender.owner == this) {
-			var delegate = inEvent.originator[inEventName];
-			if (delegate && this.dispatch(this.owner, delegate, inEvent, inSender)) {
-				return true;
-			}
-		}
-		return this.inherited(arguments);
 	}
 });
diff --git a/source/ui/ToolDecorator.js b/source/ui/ToolDecorator.js
@@ -1,5 +1,7 @@
+//* Lines up components in a row, centered vertically
 enyo.kind({
 	name: "enyo.ToolDecorator",
+	//* @protected
 	kind: enyo.GroupItem,
 	classes: "enyo-tool-decorator"
 });