From 76bcfd0d0d7e5747e543e47ff4ba2d3b05007731 Mon Sep 17 00:00:00 2001
From: Qiang Xue <qiang.xue@gmail.com>
Date: Sun, 17 Jul 2011 00:34:24 -0400
Subject: [PATCH] finished behavior and event.

---
 framework/base/Behavior.php | 82 ++++++++++++++++++++++++++++-----------------
 framework/base/Event.php    |  2 +-
 2 files changed, 52 insertions(+), 32 deletions(-)

diff --git a/framework/base/Behavior.php b/framework/base/Behavior.php
index 8062138..288b132 100644
--- a/framework/base/Behavior.php
+++ b/framework/base/Behavior.php
@@ -10,18 +10,34 @@
 
 namespace yii\base;
 
+/**
+ * Behavior is the base class for all behavior classes.
+ *
+ * A behavior can be used to enhance the functionality of an existing component.
+ * In particular, it can "inject" its own properties and events into the component
+ * and make them directly accessible via the component.
+ *
+ * @author Qiang Xue <qiang.xue@gmail.com>
+ * @since 2.0
+ */
 class Behavior extends Component
 {
 	private $_enabled;
 	private $_owner;
 
 	/**
-	 * Declares events and the corresponding event handler methods.
-	 * The events are defined by the {@link owner} component, while the handler
-	 * methods by the behavior class. The handlers will be attached to the corresponding
-	 * events when the behavior is attached to the {@link owner} component; and they
-	 * will be detached from the events when the behavior is detached from the component.
-	 * @return array events (array keys) and the corresponding event handler methods (array values).
+	 * Declares event handlers for the [[owner]]'s events.
+	 *
+	 * Child classes may override this method to declare which methods in this behavior
+	 * should be attached to which events of the [[owner]] component.
+	 * The methods will be attached to the [[owner]]'s events when the behavior is
+	 * attached to the owner; and they will be detached from the events when
+	 * the behavior is detached from the component.
+	 *
+	 * The method should return an array whose keys are the names of the owner's events
+	 * and values are the names of the behavior methods.
+	 *
+	 * @return array events (keys) and the corresponding behavior method names (values).
 	 */
 	public function events()
 	{
@@ -30,34 +46,37 @@ class Behavior extends Component
 
 	/**
 	 * Attaches the behavior object to the component.
-	 * The default implementation will set the {@link owner} property
-	 * and attach event handlers as declared in {@link events}.
+	 * The default implementation will set the [[owner]] property
+	 * and attach event handlers as declared in [[events]].
 	 * Make sure you call the parent implementation if you override this method.
-	 * @param CComponent $owner the component that this behavior is to be attached to.
+	 * @param Component $owner the component that this behavior is to be attached to.
 	 */
 	public function attach($owner)
 	{
-		$this->_owner=$owner;
-		foreach($this->events() as $event=>$handler)
-			$owner->attachEventHandler($event,array($this,$handler));
+		$this->_owner = $owner;
+		foreach($this->events() as $event=>$handler) {
+			$owner->attachEventHandler($event, array($this, $handler));
+		}
 	}
 
 	/**
 	 * Detaches the behavior object from the component.
-	 * The default implementation will unset the {@link owner} property
-	 * and detach event handlers declared in {@link events}.
+	 * The default implementation will unset the [[owner]] property
+	 * and detach event handlers declared in [[events]].
 	 * Make sure you call the parent implementation if you override this method.
-	 * @param CComponent $owner the component that this behavior is to be detached from.
+	 * @param Component $owner the component that this behavior is to be detached from.
 	 */
 	public function detach($owner)
 	{
-		foreach($this->events() as $event=>$handler)
-			$owner->detachEventHandler($event,array($this,$handler));
-		$this->_owner=null;
+		foreach($this->events() as $event=>$handler) {
+			$owner->detachEventHandler($event, array($this, $handler));
+		}
+		$this->_owner = null;
 	}
 
 	/**
-	 * @return CComponent the owner component that this behavior is attached to.
+	 * Returns the owner component that this behavior is attached to.
+	 * @return Component the owner component that this behavior is attached to.
 	 */
 	public function getOwner()
 	{
@@ -65,6 +84,7 @@ class Behavior extends Component
 	}
 
 	/**
+	 * Returns a value indicating whether this behavior is enabled.
 	 * @return boolean whether this behavior is enabled
 	 */
 	public function getEnabled()
@@ -73,23 +93,23 @@ class Behavior extends Component
 	}
 
 	/**
-	 * @param boolean $value whether this behavior is enabled
+	 * Enables or disables the behavior.
+	 * @param boolean $value whether this behavior should be enabled.
 	 */
 	public function setEnabled($value)
 	{
-		if($this->_enabled!=$value && $this->_owner)
-		{
-			if($value)
-			{
-				foreach($this->events() as $event=>$handler)
-					$this->_owner->attachEventHandler($event,array($this,$handler));
+		if($this->_enabled!=$value && $this->_owner) {
+			if($value) {
+				foreach($this->events() as $event=>$handler) {
+					$this->_owner->attachEventHandler($event, array($this, $handler));
+				}
 			}
-			else
-			{
-				foreach($this->events() as $event=>$handler)
-					$this->_owner->detachEventHandler($event,array($this,$handler));
+			else {
+				foreach($this->events() as $event=>$handler) {
+					$this->_owner->detachEventHandler($event, array($this, $handler));
+				}
 			}
 		}
-		$this->_enabled=$value;
+		$this->_enabled = $value;
 	}
 }
diff --git a/framework/base/Event.php b/framework/base/Event.php
index 4a1b3b8..2e9837d 100644
--- a/framework/base/Event.php
+++ b/framework/base/Event.php
@@ -32,7 +32,7 @@ class Event extends Component
 	 * @var boolean whether the event is handled. Defaults to false.
 	 * When a handler sets this to be true, the rest of the uninvoked event handlers will be canceled.
 	 */
-	public $handled=false;
+	public $handled = false;
 
 	/**
 	 * Constructor.