0x2620/oxjs
2
0
Fork 1
Code Issues 172 Pull requests Releases Wiki Activity

Ox.Element: update documentation

Browse source
This commit is contained in:
rlx 2014-09-24 12:17:46 +02:00
parent 02aeb4ea0c
commit 8018ba499f
1 changed files with 111 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

139
source/Ox.UI/js/Core/Element.js
View file

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