sanj/oxjs
1
0
Fork 0
forked from 0x2620/oxjs
Code Pull requests Activity

various documentation-related changes

Browse source
This commit is contained in:
rolux 2011-05-05 20:02:56 +02:00
commit a6ed310087
13 changed files with 880 additions and 301 deletions
Download patch file Download diff file Expand all files Collapse all files

30
source/Ox.UI/js/Calendar/Ox.Calendar.js
View file

@ -1,4 +1,28 @@
// vim: et:ts=4:sw=4:sts=4:ft=js
/*@
Ox.Calendar <f> Basic calendar object
() -> <f> Calendar object
(options) -> <f> Calendar object
(options, self) -> <f> Calendar object
options <o> Options object
date <d|new Date()> UTC Date on which the calendar is centered
dates <[o]|[]> Date objects to be displayed
end <s> End of the event (UTC Date, as string)
name <s> Name of the event
start <s> Start of the event (UTC Date, as string)
type <s> Type of the event (like "person")
height <n|256> Height in px
range <[n]|[100, 5101]> Start and end year of the calendar
width <n|256> Width in px
zoom <n|8> Initial zoom level
self <o> Shared private variable
@*/
// Fixme: switch to UTC
// Fixme: in options.dates, replace "stop" with "end"
// Fixme: create a variable-resolution date type (with end that is _inclusive_)
Ox.Calendar = function(options, self) {
self = self || {};
@ -6,9 +30,9 @@ Ox.Calendar = function(options, self) {
.defaults({
date: new Date(),
dates: [],
height: 512,
range: [100, 5101],
width: 512,
height: 256,
range: [1000, 3000],
width: 256,
zoom: 8
})
.options(options || {})

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

@ -1,11 +1,67 @@
// vim: et:ts=4:sw=4:sts=4:ft=js
// check out http://ejohn.org/apps/learn/#36 (-#38, making fns work w/o new)
Ox.Element = function() {
/*@
Ox.Element <function:Ox.JQueryElement> Basic UI element object
# Usage --------------------------------------------------------------------
([options[, self]]) -> <object> UI element
# Arguments ----------------------------------------------------------------
options <object> the options of the element
# Properties
element <string> tagname or CSS selector
tooltip <object> tooltip (not implemented)
options <string> tagname or CSS selector
self <object> shared private variable
# Properties ---------------------------------------------------------------
$element <object> jQuery DOM object
bindEvent <function> binds an event to a function, once
# Usage
(event, callback) -> <object> this element
({event: callback, ...}) -> <object> this element
# Arguments
event <string> event name
callback <function> callback function
data <object> event data
bindEventOnce <function> binds an event to a function
defaults <function> sets the default options
options <function> sets the options
triggerEvent <function> triggers an event
unbindEvent <function> unbinds an event
# Events -------------------------------------------------------------------
anyclick <event> anyclick
fires on mouseup, but not on any subsequent mouseup within 250 ms
* <*> original event properties
doubleclick <event> doubleclick
fires on the second mousedown within 250 ms
* <*> original event properties
drag <event> drag
fires on mousemove after dragstart, stops firing on mouseup
clientDX <number> horizontal drag delta in px
clientDY <number> vertical drag delta in px
* <*> original event properties
dragend <event> dragpause
Fires on mouseup after dragstart
clientDX <number> horizontal drag delta in px
clientDY <number> vertical drag delta in px
* <*> original event properties
dragpause <event> dragpause
Fires once when the mouse doesn't move for 250 ms after drag
clientDX <number> horizontal drag delta in px
clientDY <number> vertical drag delta in px
* <*> original event properties
dragstart <event> dragstart
fires when the mouse is down for 250 ms
* <*> original event properties
mouserepeat <event> mouserepeat
fires every 50 ms after the mouse was down for 250 ms, stops firing on
mouseleave or mouseup
* <*> original event properties
singleclick <event> singleclick
fires 250 ms after mouseup, if there was no subsequent mousedown
* <*> original event properties
@*/
/***
Basic element object
***/
Ox.Element = function() {
/*
tooltip option can be any of the following:
@ -137,7 +193,7 @@ Ox.Element = function() {
that.triggerEvent('mouserepeat');
}
function mouseup(e) {
// only trigger on firse mouseup
// only trigger on first mouseup
if (!self.mouseup) {
that.triggerEvent('anyclick', e);
self.mouseup = true;
@ -173,19 +229,29 @@ Ox.Element = function() {
that._self = self; // fixme: remove
/*@
bindEvent <function> Binds a function to an event
(event, callback) -> <f> This element
({event: callback, ...}) -> <f> This element
callback <f> Callback function
data <o> event data (key/value pairs)
event <s> Event name (can be namespaced, like "click.foo")
@*/
that.bindEvent = function() {
/***
binds a function to an event triggered by this object
Usage
bindEvent(event, fn)
bindEvent({eventA: fnA, eventB: fnB, ...})
***/
Ox.forEach(Ox.makeObject(arguments), function(fn, event) {
bind('bind', event, fn);
});
return that;
}
/*@
bindEventOnce <function> Binds a function to an event, once
(event, callback) -> <f> This element
({event: callback, ...}) -> <f> This element
callback <f> Callback function
data <o> event data (key/value pairs)
event <s> Event name (can be namespaced, like "click.foo")
@*/
that.bindEventOnce = function() {
Ox.forEach(Ox.makeObject(arguments), function(fn, event) {
bind('one', event, fn);
@ -193,6 +259,13 @@ Ox.Element = function() {
return that;
};
/*@
Sets the default options for an element object
({key: value, ...}) -> <f>
key <str> the name of the default option
that <obj> the element object
value <val> the value of the default option
@*/
that.defaults = function(defaults) {
// sets the default options
self.defaults = defaults;
@ -200,43 +273,54 @@ Ox.Element = function() {
return that;
};
/*@
Makes an element object gain focus
() -> that
that <obj> the element object
@*/
that.gainFocus = function() {
/***
make this object gain focus
***/
Ox.Focus.focus(that.id);
return that;
};
/*@
Returns true if an element object has focus
() -> hasFocus
hasFocus <boolean> true if the element has focus
@*/
that.hasFocus = function() {
/***
returns true if this object has focus
***/
return Ox.Focus.focused() == that.id;
};
/*@
Makes an element object lose focus
() -> that
that <object> the element object
@*/
that.loseFocus = function() {
/***
make this object lose focus
***/
Ox.Focus.blur(that.id);
return that;
};
/*@
.options()
Gets or sets the options of an element object
# Usage
() -> <obj> all options
(key) -> <val> the value of option[key]
(key, value) -> <obj> this element
sets options[key] to value and calls self.setOption(key, value)
if the key/value pair was added or modified
({key: value, ...}) -> <obj> this element
sets multiple options and calls self.setOption(key, value)
for every key/value pair that was added or modified
# Arguments
key <str> the name of the option
value <val> the value of the option
@*/
that.options = function() {
/*
that.options()
returns self.options
that.options(key)
returns self.options.key
that.options(key, val)
sets self.options.key to val, calls self.setOption(key, val)
if the key has been added or its val has changed, returns that
that.options({keyA: valA, keyB: valB})
sets self.options.keyA to valA and self.options.keyB to valB,
calls self.setOptions(key, val) for every key/value pair
that has been added or modified, returns that
*/
return Ox.getset(self.options, arguments, self.setOption, that);
};

16
source/Ox.UI/js/Core/Ox.JQueryElement.js
View file

@ -1,13 +1,20 @@
// vim: et:ts=4:sw=4:sts=4:ft=js
/***
Basic jQuery element
***/
/*@
Ox.JQueryElement <function> Wrapper for jQuery
# Usage
($element) -> <object> Wrapped jQuery DOM element
# Arguments
$element <object> jQuery DOM Element
@*/
Ox.JQueryElement = function($element) {
var that = this;
//@ Ox.JQueryElement.id <number> Unique id
that.id = Ox.uid();
//@ Ox.JQueryElement.ox <string> OxJS version
that.ox = Ox.VERSION;
//@ Ox.JQueryElement.$element <object> The jQuery DOM element
that.$element = $element.data({
oxid: that.id
});
@ -15,6 +22,7 @@ Ox.JQueryElement = function($element) {
return that;
};
// add all jQuery functions to the prototype of Ox.JQueryElement
Ox.forEach($('<div>'), function(val, key) {
if (Ox.isFunction(val)) {
Ox.JQueryElement.prototype[key] = function() {
@ -31,7 +39,7 @@ Ox.forEach($('<div>'), function(val, key) {
// if the $element of an ox object was returned
// then return the ox object instead
// so that we can do oxObj.jqFn().oxFn()
return ret.jquery && Ox.UI.elements[id = ret.data('oxid')] ?
return ret && ret.jquery && Ox.UI.elements[id = ret.data('oxid')] ?
Ox.UI.elements[id] : ret;
};
}

89
source/Ox.UI/js/Core/Ox.Keyboard.js
View file

@ -5,46 +5,7 @@
(function() {
var buffer = '',
// the dot notation ('0.numpad') makes the keyboard event ('key_0.numpad')
// namespaced, so that binding to 'key_0' will catch 'key_0.numpad' too
keyNames = {
0: 'section', 8: 'backspace', 9: 'tab', 12: 'clear', 13: 'enter',
16: 'shift', 17: 'control', 18: 'alt', 20: 'capslock', 27: 'escape',
32: 'space', 33: 'pageup', 34: 'pagedown', 35: 'end', 36: 'home',
37: 'left', 38: 'up', 39: 'right', 40: 'down',
45: 'insert', 46: 'delete', 47: 'help',
48: '0', 49: '1', 50: '2', 51: '3', 52: '4',
53: '5', 54: '6', 55: '7', 56: '8', 57: '9',
65: 'a', 66: 'b', 67: 'c', 68: 'd', 69: 'e',
70: 'f', 71: 'g', 72: 'h', 73: 'i', 74: 'j',
75: 'k', 76: 'l', 77: 'm', 78: 'n', 79: 'o',
80: 'p', 81: 'q', 82: 'r', 83: 's', 84: 't',
85: 'u', 86: 'v', 87: 'w', 88: 'x', 89: 'y', 90: 'z',
// fixme: this is usually 91: window.left, 92: window.right, 93: select
91: 'meta.left', 92: 'meta.right', 93: 'meta.right',
96: '0.numpad', 97: '1.numpad', 98: '2.numpad', 99: '3.numpad',
100: '4.numpad', 101: '5.numpad', 102: '6.numpad', 103: '7.numpad',
104: '8.numpad', 105: '9.numpad', 106: 'asterisk.numpad', 107: 'plus.numpad',
109: 'minus.numpad', 108: 'enter.numpad', 110: 'dot.numpad', 111: 'slash.numpad',
112: 'f1', 113: 'f2', 114: 'f3', 115: 'f4', 116: 'f5',
117: 'f6', 118: 'f7', 119: 'f8', 120: 'f9', 121: 'f10',
122: 'f11', 123: 'f12', 124: 'f13', 125: 'f14', 126: 'f15', 127: 'f16',
144: 'numlock', 145: 'scrolllock',
186: 'semicolon', 187: 'equal', 188: 'comma', 189: 'minus',
190: 'dot', 191: 'slash', 192: 'backtick', 219: 'openbracket',
220: 'backslash', 221: 'closebracket', 222: 'quote', 224: 'meta'
// see dojo, for ex.
},
// meta comes last so that we can differentiate between
// alt_control_shift_meta.left and alt_control_shift_meta.right
modifierNames = {
altKey: 'alt', // Mac: option
ctrlKey: 'control',
shiftKey: 'shift',
metaKey: 'meta', // Mac: command
},
resetTimeout, triggerTimeout;
var buffer = '', resetTimeout, triggerTimeout;
/*
Ox.UI.ready(function() {
@ -59,10 +20,10 @@
if ($element.length) {
if (
(
keyNames[event.keyCode] == 'up' &&
Ox.KEYS[event.keyCode] == 'up' &&
$element[0].selectionStart + $element[0].selectionEnd == 0
) || (
keyNames[event.keyCode] == 'down' &&
Ox.KEYS[event.keyCode] == 'down' &&
$element[0].selectionStart == $element.val().length &&
$element[0].selectionEnd == $element.val().length
)
@ -82,27 +43,41 @@
});
function keydown(event) {
var focused = Ox.Focus.focused(),
key,
keyName = keyNames[event.keyCode] || '',
keyName = Ox.KEYS[event.keyCode] || '',
keyNames = keyName ? [keyName] : [],
keyBasename = keyName.split('.')[0],
keys = keyName ? [keyName] : [];
Ox.forEach(modifierNames, function(v, k) {
ret = true;
Ox.forEach(Ox.MODIFIER_KEYS, function(v, k) {
// avoid pushing modifier twice
if (event[k] && keyBasename != v) {
keys.splice(-1, 0, v);
keyNames.splice(-1, 0, v);
}
});
key = keys.join('_');
if (/^(shift_)?[a-z]$|^\d(\.numpad)?$|space/.test(key)) {
key = keyNames.join('_');
if (focused !== null) {
Ox.UI.elements[focused].triggerEvent('key_' + key);
// prevent Chrome from going back in history, or scrolling
if (
[
'backspace', 'down', 'left', 'right', 'space', 'up'
].indexOf(keyBasename) > -1 &&
!Ox.UI.elements[focused].hasClass('OxInput')
) {
ret = false;
}
}
if (/^[\w\d](\.numpad)?$|space/.test(key)) {
// don't register leading spaces or trailing double spaces
if (!(keyName == 'space' && (buffer == '' || / $/.test(buffer)))) {
buffer += keyName == 'space' ? ' ' : keyBasename;
Ox.print('buffer', buffer)
// clear the trigger timeout only if the key went into the buffer
clearTimeout(triggerTimeout);
triggerTimeout = setTimeout(function() {
Ox.print('buffer', buffer)
focused !== null && Ox.UI.elements[focused].triggerEvent('keys', {
keys: buffer
});
@ -114,16 +89,10 @@
resetTimeout = setTimeout(function() {
buffer = '';
}, 1000);
if (focused !== null) {
Ox.UI.elements[focused].triggerEvent('key_' + key);
// prevent Chrome from going back in history, or scrolling
if (
['backspace', 'down', 'left', 'right', 'space', 'up'].indexOf(key) > -1 &&
!Ox.UI.elements[focused].hasClass('OxInput')
) {
return false;
}
}
Ox.print(ret)
return ret;
}
})();

17
source/Ox.UI/js/Core/Ox.SyntaxHighlighter.js
View file

@ -39,12 +39,11 @@ Ox.SyntaxHighlighter = function(options, self) {
self.source = '';
self.tokens = Ox.tokenize(self.options.source);
self.tokens.forEach(function(token, i) {
var classNames, tokenString;
var classNames;
if (
!(self.options.stripComments && token.type == 'comment')
) {
classNames = 'Ox' + Ox.toTitleCase(token.type);
tokenString = self.options.source.substr(self.cursor, token.length);
if (token.type == 'whitespace') {
if (isAfterLinebreak() && hasIrregularSpaces()) {
classNames += ' OxLeading'
@ -53,7 +52,7 @@ Ox.SyntaxHighlighter = function(options, self) {
}
}
self.source += '<span class="' + classNames + '">' +
encodeToken(tokenString, token.type) + '</span>';
encodeToken(token.source, token.type) + '</span>';
}
self.cursor += token.length;
function isAfterLinebreak() {
@ -65,7 +64,7 @@ Ox.SyntaxHighlighter = function(options, self) {
self.tokens[i + 1].type == 'linebreak';
}
function hasIrregularSpaces() {
return tokenString.split('').reduce(function(prev, curr) {
return token.source.split('').reduce(function(prev, curr) {
return prev + (curr == ' ' ? 1 : 0);
}, 0) % self.options.tabLength;
}
@ -108,24 +107,24 @@ Ox.SyntaxHighlighter = function(options, self) {
.html(self.source)
.appendTo(that);
function encodeToken(str, type) {
function encodeToken(source, type) {
var linebreak = '<br/>',
tab = Ox.repeat('&nbsp;', self.options.tabLength);
if (self.options.showLinebreaks) {
if (type == 'linebreak') {
linebreak = '' + linebreak;
linebreak = '\u21A9' + linebreak;
} else {
linebreak = '<span class="OxLinebreak"></span>' + linebreak;
linebreak = '<span class="OxLinebreak">\u21A9</span>' + linebreak;
}
}
if (self.options.showTabs) {
tab = '<span class="OxTab">\u2192' + tab.substr(6) + '</span>';
}
str = Ox.encodeHTML(str)
source = Ox.encodeHTML(source)
.replace(/ /g, '&nbsp;')
.replace(/\t/g, tab)
.replace(/\n/g, linebreak);
return str;
return source;
}
self.setOption = function() {

47
source/Ox.UI/js/List/Ox.List.js
View file

@ -1,4 +1,14 @@
// vim: et:ts=4:sw=4:sts=4:ft=js
/*@
Basic list object
(options) -> that
(options, self) -> that
options <obj> the list's options
self <obj> shared private variable
@*/
Ox.List = function(options, self) {
/***
@ -17,23 +27,26 @@ Ox.List = function(options, self) {
var self = self || {},
that = new Ox.Container({}, self)
.defaults({
centered: false,
construct: null,
draggable: false,
format: [],
itemHeight: 16,
items: null,
itemWidth: 16,
keys: [],
max: -1,
min: 0,
orientation: 'vertical',
pageLength: 100,
selected: [],
sort: [],
sortable: false,
type: 'text',
unique: ''
centered: false, //@ <boo> if true, and orientation is 'horizontal',
//@ then keep the selected item centered
construct: null, //@ <fun> (data) returns the list item HTML
draggable: false, //@ <boo> true if the items can be reordered
format: [], //@ <arr> ???
itemHeight: 16, //@ <num> item height
items: null, //@ <arr> list items
//@ <fun> (data) returns {items, size, ...}
//@ (data, callback) returns [items]
itemWidth: 16, //@ <num> item width
keys: [], //@ <arr> keys of the list items
max: -1, //@ <num> max number of items that can be selected
min: 0, //@ <num> min number of items that must be selected
orientation: 'vertical', //@ <str> 'horizontal' or 'vertical'
pageLength: 100, //@ <num> number of items per page
selected: [], //@ <arr> ids of the selected elements
sort: [], //@ <arr>
sortable: false, //@ <boo>
type: 'text', //@ <str>
unique: '' //@ <str> name of the key that acts as unique id
})
.options(options || {})
.scroll(scroll);

84
source/Ox.UI/js/Map/Ox.Map.js
View file

@ -1,5 +1,89 @@
// vim: et:ts=4:sw=4:sts=4:ft=js
/*@
Ox.Map <function> Basic map object
# DESCRIPTION --------------------------------------------------------------
<code>Ox.Map</code> is a wrapper around the
<a href="http://code.google.com/apis/maps/documentation/javascript/">Google
Maps API</a>.
# USAGE --------------------------------------------------------------------
() -> <f> Map object
(options) -> <f> Map object
(options, self) -> <f> Map object
# ARGUMENTS ----------------------------------------------------------------
options <o|{}> options
clickable <b|false> If true, clicking on the map finds a place
editable <b|false> If true, places are editable
findPlaceholder <s|"Find"> Placeholder text for the find input element
labels <b|false> If true, show labels on the map
markers <n|100> Maximum number of markers to be displayed
places <[o]|[]> Array of place objects
countryCode <s> ISO 3166 country code
east <n> Longitude of the eastern boundary in degrees
editable <b|false> If true, the place is editable
geoname <s> Geoname (like "Paris, Île-de-France, France")
lat <n> Latitude in degrees
lng <n> Longitude in degrees
markerColor <s|"red"> CSS color of the place marker
markerSize <n|16> size of the place marker in px
name <s> Name (like "Paris")
north <n> Latitude of the northern boundary in degrees
south <n> Latitude of the southern boundary in degrees
type <s> Type (like "city" or "country")
west <n> Longitude of the western boundary in degrees
selected <s|""> Id of the selected place
statusbar <b|false> If true, the map has a statusbar
toolbar <b|false> If true, the map has a toolbar
self <o|{}> Shared private variable
# EVENTS -------------------------------------------------------------------
addplace <!> Fires when a place has been added
place <o> Place object
editplace <!> Fires when a place has been edited
place <o> Place object
geocode <!> Fires when a google geocode request returns
latLng <o|u> Query coordinates, or undefined
lat <n> latitude
lng <n> longitude
address <s|u> Query string, or undefined
results <[o]> Google Maps geocode results
address_components <[o]> Address components
long_name <s> Long name
short_name <s> Short name
types <[s]> Types (like "country" or "political")
formatted_address <s> Formatted address
geometry <o> Geometry
bounds <o> Bounds
northEast <o> North-east corner
lat <n> Latitude
lng <n> Longitude
southWest <o> South-west corner
lat <n> Latitude
lng <n> Longitude
location <o> Location
lat <n> Latitude
lng <n> Longitude
location_type <s> Location type (like "APPROXIMATE")
viewport <o> Viewport
northEast <o> North-east corner
lat <n> Latitude
lng <n> Longitude
southWest <o> South-west corner
lat <n> Latitude
lng <n> Longitude
types <[s]> Types (like "country" or "political")
# EXAMPLES -----------------------------------------------------------------
<script>
// simple
Ox.load('UI', function() {
Ox.Map().appendTo(Ox.UI.$body);
});
</script>
> Ox.Map() === true
false
> Ox.Map() === false
false
@*/
Ox.Map = function(options, self) {
self = self || {};