class.extras.md

一款开源强大的javascript控件

Class: Chain {#Chain}
=====================

提供链式执行一组函数的工具类. 该类中的方法可以通过[Class:implement][]来实现到其他的[Class][]中.

在本框架中,已实现该工具类的类有[Fx][]和[Request][]. 比如在[Fx][]中,它被用来实现自定义的复杂动画特效.



Chain 方法: constructor {#Chain:constructor}
----------------------------------------------


### 语法:

#### 实现到其他新建类中:

	var MyClass = new Class({ 
		Implements: Chain 
	});

#### 实现到已有类中:

	MyClass.implement(Chain);

#### 独立使用

	var myChain = new Chain;

### 示例:

		var Todo = new Class({
			Implements: Chain,
			initialize: function(){
				this.chain.apply(this, arguments);
			}
		});

		var myTodoList = new Todo(
			function(){ alert('get groceries');	},
			function(){ alert('go workout'); },
			function(){ alert('code mootools documentation until eyes close involuntarily'); },
			function(){ alert('sleep');	}
		);

### 另参考:

- [Class][]



Chain 方法: chain {#Chain:chain}
----------------------------------

向调用链末端添加新的被调函数.

### 语法:

	myClass.chain(fn[, fn2[, fn3[, ...]]]);

### 参数:

1. 任意数量的函数

### 返回值:

* (*object*) 当前的类实例

### 示例:

	//Fx.Tween已经实现了Chain类,因为它继承了Fx类
	var myFx = new Fx.Tween('myElement', {
		property: 'opacity'
	});
	
	myFx.start(1,0).chain(
		//注意: "this"引用了主调对象(此处即myFx对象).
		function(){ this.start(0,1); },
		function(){ this.start(1,0); },
		function(){ this.start(0,1); }
	); 

### 另参考:

- [Fx][], [Fx.Tween][]



Chain 方法: callChain {#Chain:callChain}
------------------------------------------

执行并删除调用链顶端的一个被调函数(原先调用链上第二位函数将提升为第一位)

### 语法:

	myClass.callChain([any arguments]);

### 参数:

1. 任意参数(这些参数将传递给当前将被调用的函数)

### 返回值:

* (*object*) 主调类实例

### 示例:

	var myChain = new Chain();
	myChain.chain(
		function(){ alert('do dishes'); },
		function(){ alert('put away clean dishes'); }
	);
	myChain.callChain(); //显示 'do dishes'.
	myChain.callChain(); //显示 'put away clean dishes'.



Chain 方法: clearChain {#Chain:clearChain}
--------------------------------------------

清空调用链

### 语法:

	myClass.clearChain();

### 返回值:

* (*object*) 类实例

### 示例:

	var myFx = Fx.Tween('myElement', 'color'); //Fx.Tween继承了Fx对Chain类的实现.
	myFx.chain(function(){ 
		while(true) {
			alert("D'oh!");
		} 
	});
	myFx.clearChain(); //清空调用链,链上将无被调函数

### 另参考:

- [Fx][], [Fx.Tween][]



Class: Events {#Events}
=======================

事件相关的工具类. 该类中的方法可以通过[Class:implement][]实现到其他的[Class][]中.

比如在[Fx][]类中, 它被用于提供向Fx中添加任意多个事件的能力, 如: 'complete', 'start', 以及 'cancel'.

实现[Events](#Events)的类必须通过使用option的方式或调用addEvent方法来添加事件, 不能直接通过 .options.onEventName 的方式来进行.

### 语法:

#### 实现到新建类中:

	var MyClass = new Class({ Implements: Events });

#### 实现到已有类中:

	MyClass.implement(Events);

### 实现说明:

- 该类可以被实现到其他的类中以提供给目标类它的事件处理功能
- Events被设计成和[Options](#Options)类有效协作的, 当option中的属性名以'on'开头,并紧接大写字母开头的单词时, 这个属性将被认为是一个事件而自动进行处理(例如: 'onComplete'将被处理为'complete'事件).

### 示例:

	var Widget = new Class({
		Implements: Events,
		initialize: function(element){
			// ...
		},
		complete: function(){
			this.fireEvent('complete');
		}
	});

	var myWidget = new Widget();
	myWidget.addEvent('complete', myFunction);


### 另参考:

- [Class][], [Options](#Options)



Events 方法: addEvent {#Events:addEvent}
------------------------------------------

向类实例的事件栈中添加一个事件

### 语法:

	myClass.addEvent(type, fn[, internal]);

### 参数:

1. type     - (*string*)   事件类型 (如: 'complete')
2. fn       - (*function*) 事件监听函数
3. internal - (*boolean*, 可选) 设置为true时, 可防止该事件被清除

### 返回值:

* (*object*) 类实例

### 示例:

	var myFx = new Fx.Tween('element', 'opacity');
	myFx.addEvent('start', myStartFunction);


Events 方法: addEvents {#Events:addEvents}
------------------------------------------

和[addEvent](#addEvent)功能类似, 区别之处在于可一次添加多个事件

### 语法:

	myClass.addEvents(events);

### 参数:

1. events - (*object*) 一个键值对对象: 键代表事件名(如: 'start'), 值代表事件触发时执行的函数

### 返回值:

* (*object*) 类实例

### 示例:

	var myFx = new Fx.Tween('element', 'opacity');
	
	myFx.addEvents({
		'start': myStartFunction,
		'complete': function() {
			alert('Done.');
		}
	});



Events 方法: fireEvent {#Events:fireEvent}
--------------------------------------------

触发指定事件类型的下所有监听函数

### 语法:

	myClass.fireEvent(type[, args[, delay]]);

### 参数:

1. type  - (*string*) 事件类型 (如: 'complete')
2. args  - (*mixed*, 可选) 传递给监听函数的参数. 如果参数大于一个,请使用数组
3. delay - (*number*, 可选) 执行事件前的延迟时间(毫秒)(默认值为0)

### 返回值:

* (*object*) 类实例

### 示例:

	var Widget = new Class({
		Implements: Events,
		initialize: function(arg1, arg2){
			//...
			this.fireEvent("initialize", [arg1, arg2], 50);
		}
	});



Events 方法: removeEvent {#Events:removeEvent}
------------------------------------------------

删除指定类型事件下的指定监听函数

### 语法:

	myClass.removeEvent(type, fn);

### 参数:

1. type - (*string*) 事件类型 (如: 'complete')
2. fn   - (*function*) 目标函数

### 返回值:

* (*object*) 类实例

### 备注:

- 如果监听函数被设置了internal属性并值为true, 则该监听函数无法被删除


Events 方法: removeEvents {#Events:removeEvents}
--------------------------------------------------

删除指定类型事件下的所有监听函数. 如果未指定事件类型,则删除全部类型下的所有监听函数.

### 语法:

	myClass.removeEvents([type]);

### 参数:

1. type - (*string*, 可选) 事件类型 (如: 'complete'). 如果未指定,则删除全部类型下的所有监听函数

### 返回值:

* (*object*) 类实例

### 示例:

	var myFx = new Fx.Tween('myElement', 'opacity');
	myFx.removeEvents('complete');


### 备注:

- removeEvents不会删除设置了internal为true的监听函数. 参看[Events:removeEvent][]



Class: Options {#Options}
=========================

可选项配置相关的工具类. 该类中的方法可以通过[Class:implement][]实现到其他的[Class][]中.

用于提供自动化设置类实例的可选项.

和[Events](#Events)类协作时,当可选项属性名以'on'开头并且紧接大写字母开头的单词时,这个属性将被认为是一个事件而自动进行处理(例如: 'onComplete'将被处理为'complete'事件)

### 语法:

#### 实现到其他新建类中:

	var MyClass = new Class({Implements: Options});

#### 实现到已有类中:

	MyClass.implement(Options);



Options 方法: setOptions {#Options:setOptions}
------------------------------------------------

将类的默认可选项和参数中传入的可选项进行合并

### 语法:

	myClass.setOptions([options]);

### 参数:

1. options - (*object*, 可选) 用户指定的可选项

### 返回值:

* (*object*) 类实例

### 示例:

	var Widget = new Class({
		Implements: Options,
		options: {
			color: '#fff',
			size: {
				width: 100,
				height: 100
			}
		},
		initialize: function(options){
			this.setOptions(options);
		}
	});

	var myWidget = new Widget({
		color: '#f00',
		size: {
			width: 200
		}
	});

	/** 
	 *	myWidget.options当前为: 
	 *	{
	 *		color: #f00, 
	 *		size: {
	 *			width: 200, 
	 *			height: 100
	 *		}
	 *	}
	 */

### 备注:

- 依赖于一个类中已定义的作为默认可选项的类属性: options
- 如果一个类实现了[Events](#Events), 则任何名称以'on'开头并紧接大写字母开头的单词的可选项(如: 'onComplete')将变为类实例的一个事件,并限定了该可选项的值必须为一个函数


[Class]: /Class/Class
[Class:implement]: /Class/Class/#Class:implement
[Fx]: /Fx/Fx
[Fx.Tween]: /Fx/Fx.Tween
[Request]: /Request/Request
[Request.HTML]: /Request/Request.HTML
[Events:removeEvent]: /Element/Element.Event/#Element:removeEvent