Ox.Element: update documentation

This commit is contained in:
rlx 2014-09-24 12:17:46 +02:00
parent 02aeb4ea0c
commit 8018ba499f

View file

@ -364,11 +364,11 @@
/*@
bindEvent <f> Adds event handler(s)
(callback) -> <o> This element
(callback) -> <o> This element object
Adds a catch-all handler
(event, callback) -> <o> This element
(event, callback) -> <o> This element object
Adds a handler for a single event
({event: callback, ...}) -> <o> This element
({event: callback, ...}) -> <o> This element object
Adds handlers for one or more events
callback <f> Callback function
data <o> event data (key/value pairs)
@ -401,16 +401,16 @@
};
/*@
bindMessage <f> Adds message handlers (if the element is an iframe)
(callback) -> <o> This element
bindMessage <f> Adds message handler(s) (if the element is an iframe)
(callback) -> <o> This element object
Adds a catch-all handler
(event, callback) -> <o> This element
Adds a handler for a single event
({event: callback, ...}) -> <o> This element
Adds handlers for on or more events
(message, callback) -> <o> This element object
Adds a handler for a single message
({message: callback, ...}) -> <o> This element object
Adds handlers for one or more messages
callback <f> Callback function
data <o> event data (key/value pairs)
event <s> Event name
data <o> Message data (key/value pairs)
message <s> Message name
@*/
Ox.Element.prototype.bindMessage = Ox.Element.prototype.onMessage = function bindMessage() {
var self = this.self(_);
@ -420,6 +420,18 @@
return this;
};
/*@
bindMessageOnce <f> Adds message handler(s) that run only once
(callback) -> <o> This element object
Adds a catch-all handler
(message, callback) -> <o> This element object
Adds a handler for a single message
({message: callback, ...}) -> <o> This element object
Adds handlers for one or more messages
callback <f> Callback function
data <o> Message data (key/value pairs)
event <s> Message name
@*/
Ox.Element.prototype.bindMessageOnce = Ox.Element.prototype.onMessageOnce = function bindMessageOnce() {
var self = this.self(_);
if (self.options.element == '<iframe>') {
@ -430,6 +442,10 @@
return this;
};
/*@
childrenElements <f> Gets all direct children element objects
() -> <[o]> Array of element objects
@*/
Ox.Element.prototype.childrenElements = function childrenElements() {
return Ox.slice(this.children())
.filter(Ox.isOxElement)
@ -465,13 +481,17 @@
return this;
};
/*@
findElements <f> Gets all descendant element objects
() -> <[o]> Array of element objects
@*/
Ox.Element.prototype.findElements = function findElements() {
return Ox.slice(this.find('.OxElement')).map(Ox.getOxElement);
};
/*@
gainFocus <function> Makes an element object gain focus
() -> <obj> This element object
() -> <obj> This element object
@*/
Ox.Element.prototype.gainFocus = function gainFocus() {
Ox.Focus.gainFocus(this);
@ -480,7 +500,7 @@
/*@
hasFocus <function> Returns true if an element object has focus
() -> <boolean> True if the element has focus
() -> <boolean> True if the element has focus
@*/
Ox.Element.prototype.hasFocus = function hasFocus() {
return Ox.Focus.focusedElement() === this;
@ -497,17 +517,25 @@
/*@
loseFocus <function> Makes an element object lose focus
() -> <object> This element object
() -> <object> This element object
@*/
Ox.Element.prototype.loseFocus = function loseFocus() {
Ox.Focus.loseFocus(this);
return this;
};
/*@
nextElement <f> Gets the closest following sibling element object
() -> <o> Element object
@*/
Ox.Element.prototype.nextElement = function nextElement() {
return this.nextElements()[0];
};
/*@
nextElements <f> Gets all following sibling element objects
() -> <[o]> Array of element objects
@*/
Ox.Element.prototype.nextElements = function nextElements() {
return this.nextAll().filter(Ox.isOxElement).map(Ox.getOxElement);
};
@ -530,10 +558,18 @@
return Ox.getset(self.options, arguments, self.update, this);
};
/*@
parentElement <f> Gets the closest parent element object
() -> <o> Element object
@*/
Ox.Element.prototype.parentElement = function parentElement() {
return Ox.last(this.parentElements());
};
/*@
parentElements <f> Gets all parent element objects
() -> <[o]> Array of element objects
@*/
Ox.Element.prototype.parentElements = function parentElements() {
return Ox.slice(this.parents())
.filter(Ox.isOxElement)
@ -542,7 +578,7 @@
/*@
postMessage <f> Sends a message (if the element is an iframe)
(event, data) -> This element
(event, data) -> This element object
event <s> Event name
data <o> Event data
@*/
@ -553,10 +589,18 @@
return this;
};
/*@
prevElement <f> Gets the closest preceding sibling element object
() -> <[o]> Array of element objects
@*/
Ox.Element.prototype.prevElement = function prevElement() {
return Ox.last(this.prevElements());
};
/*@
prevElements <f> Gets all preceding sibling element objects
() -> <[o]> Array of element objects
@*/
Ox.Element.prototype.prevElements = function prevElements() {
return this.prevAll().filter(Ox.isOxElement).map(Ox.getOxElement);
};
@ -568,6 +612,10 @@
return this;
};
/*@
removeElement <f> Clean up after removal from DOM
This gets invoked on .remove()
@*/
Ox.Element.prototype.removeElement = function removeElement(includeChildren) {
if (includeChildren !== false) {
this.findElements().forEach(function($element) {
@ -596,8 +644,10 @@
};
/*@
setElement <f> set $element
($element) -> <o> This element
setElement <f> Sets the element to the element of another element object
This is useful if an element has specific options, but uses another
generic element as its DOM representation
($element) -> <o> This element object
@*/
Ox.Element.prototype.setElement = function setElement($element) {
$element.addClass('OxElement').data({oxid: this.oxid});
@ -610,6 +660,10 @@
return this;
};
/*@
siblingElements <f> Gets all sibling element objects
() -> <[o]> Array of element objects
@*/
Ox.Element.prototype.siblingElements = function siblingElements() {
return Ox.slice(this.siblings())
.filter(Ox.isOxElement)
@ -627,7 +681,7 @@
/*@
toggleOption <f> Toggle boolean option(s)
(key[, key[, ...]]) -> <o> This element
(key[, key[, ...]]) -> <o> This element object
@*/
Ox.Element.prototype.toggleOption = function toggleOption() {
var options = {}, self = this.self(_);
@ -645,8 +699,8 @@
Triggers an event with data
({event: data, ...}) -> <o> This element object
Triggers one or more events with data
event <string> Event name
data <object> Event data (key/value pairs)
event <s> Event name
data <o> Event data (key/value pairs)
@*/
Ox.Element.prototype.triggerEvent = function triggerEvent() {
Ox.Event.trigger.apply(
@ -655,6 +709,17 @@
return this;
};
/*@
triggerMessage <f> Triggers one or more messages
(message) -> <o> This element object
Triggers an event
(message, data) -> <o> This element object
Triggers a message with data
({message: data, ...}) -> <o> This element object
Triggers one or more messages with data
message <s> Message name
data <o> Message data (key/value pairs)
@*/
Ox.Element.prototype.triggerMessage = function triggerMessage() {
var self = this.self(_);
if (self.options.element == '<iframe>') {
@ -665,16 +730,16 @@
/*@
unbindEvent <f> Removes event handler(s)
() -> <o> This element
() -> <o> This element object
Removes all handlers.
(callback) -> <o> This element
(callback) -> <o> This element object
Removes a specific catch-all handler
(event) -> <o> This element
(event) -> <o> This element object
Removes all handlers for a single event (to remove all catch-all
handlers, pass '*' as event)
(event, callback) -> <o> This element
(event, callback) -> <o> This element object
Removes a specific handler for a single event
({event: callback}, ...) -> <o> This element
({event: callback}, ...) -> <o> This element object
Removes specific handlers for one or more events
event <string> Event name
@*/
@ -683,6 +748,21 @@
return this;
};
/*@
unbindMessage <f> Removes message handler(s)
() -> <o> This element
Removes all handlers.
(callback) -> <o> This element object
Removes a specific catch-all handler
(message) -> <o> This element object
Removes all handlers for a single message (to remove all catch-all
handlers, pass '*' as message)
(message, callback) -> <o> This element object
Removes a specific handler for a single event
({message: callback}, ...) -> <o> This element object
Removes specific handlers for one or more messages
message <string> Message name
@*/
Ox.Element.prototype.unbindMessage = function unbindMessage() {
var self = this.self(_);
if (self.options.element == '<iframe>') {
@ -693,9 +773,9 @@
/*@
update <f> Adds one or more handlers for options updates
(callback) -> <o> that
(key, callback) -> <o> that
({key: callback, ...}) -> <o> that
(callback) -> <o> This element object
(key, callback) -> <o> This element object
({key: callback, ...}) -> <o> This element object
@*/
Ox.Element.prototype.update = function update() {
var callbacks, self = this.self(_);
@ -714,6 +794,9 @@
/*@
value <f> Shortcut to get or set self.options.value
() -> <*> Value
(value) -> <o> This element object
value <*> Value
@*/
Ox.Element.prototype.value = function value() {
return this.options(