Added documentation.

1 files changed, 117 insertions, 3 deletions

diff --git a/framework/Web/UI/WebControls/TBulletedList.php b/framework/Web/UI/WebControls/TBulletedList.php
index 8190f9ec..67c380bc 100644
--- a/framework/Web/UI/WebControls/TBulletedList.php
+++ b/framework/Web/UI/WebControls/TBulletedList.php
@@ -13,6 +13,20 @@
 /**

  * TBulletedList class

  *

+ * TBulletedList displays items in a bullet format.

+ * The bullet style is specified by {@link setBulletStyle BulletStyle}. When

+ * the style is 'CustomImage', the {@link setBackImageUrl BulletImageUrl}

+ * specifies the image used as bullets.

+ *

+ * TBulletedList displays the item texts in three different modes, specified

+ * via {@link setDisplayMode DisplayMode}. When the mode is 'Text', the item texts

+ * are displayed as static texts; When the mode is 'HyperLink', each item

+ * is displayed as a hyperlink whose URL is given by the item value, and the

+ * {@link setTarget Target} property can be used to specify the target browser window;

+ * When the mode is 'LinkButton', each item is displayed as a link button which

+ * posts back to the page if a user clicks on that and the event {@link onClick Click}

+ * will be raised under such a circumstance.

+ *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

  * @package System.Web.UI.WebControls

@@ -20,9 +34,24 @@
  */

 class TBulletedList extends TListControl implements IPostBackEventHandler

 {

+	/**

+	 * @var boolean cached property value of Enabled

+	 */

 	private $_isEnabled;

+	/**

+	 * @var TPostBackOptions postback options

+	 */

 	private $_postBackOptions;

 

+	/**

+	 * Raises the postback event.

+	 * This method is required by {@link IPostBackEventHandler} interface.

+	 * If {@link getCausesValidation CausesValidation} is true, it will

+	 * invoke the page's {@link TPage::validate validate} method first.

+	 * It will raise {@link onClick Click} events.

+	 * This method is mainly used by framework and control developers.

+	 * @param TEventParameter the event parameter

+	 */

 	public function raisePostBackEvent($param)

 	{

 		if($this->getCausesValidation())

@@ -30,6 +59,9 @@ class TBulletedList extends TListControl implements IPostBackEventHandler
 		$this->onClick(new TBulletedListEventParameter((int)$param));

 	}

 

+	/**

+	 * @return string tag name of the bulleted list

+	 */

 	protected function getTagName()

 	{

 		switch($this->getBulletStyle())

@@ -44,6 +76,11 @@ class TBulletedList extends TListControl implements IPostBackEventHandler
 		return 'ul';

 	}

 

+	/**

+	 * Adds attribute name-value pairs to renderer.

+	 * This overrides the parent implementation with additional bulleted list specific attributes.

+	 * @param THtmlWriter the writer used for the rendering purpose

+	 */

 	protected function addAttributesToRender($writer)

 	{

 		$needStart=false;

@@ -88,53 +125,90 @@ class TBulletedList extends TListControl implements IPostBackEventHandler
 		parent::addAttributesToRender($writer);

 	}

 

+	/**

+	 * @return string image URL used for bullets when {@link getBulletStyle BulletStyle} is 'CustomImage'.

+	 */

 	public function getBulletImageUrl()

 	{

 		return $this->getViewState('BulletImageUrl','');

 	}

 

+	/**

+	 * @param string image URL used for bullets when {@link getBulletStyle BulletStyle} is 'CustomImage'.

+	 */

 	public function setBulletImageUrl($value)

 	{

 		$this->setViewState('BulletImageUrl',$value,'');

 	}

 

+	/**

+	 * @return string style of bullets. Defaults to 'NotSet'.

+	 */

 	public function getBulletStyle()

 	{

 		return $this->getViewState('BulletStyle','NotSet');

 	}

 

+	/**

+	 * @return string style of bullets. Valid values include

+	 * 'NotSet','Numbered','LowerAlpha','UpperAlpha','LowerRoman','UpperRoman','Disc','Circle','Square','CustomImage'

+	 */

 	public function setBulletStyle($value)

 	{

 		$this->setViewState('BulletStyle',TPropertyValue::ensureEnum($value,'NotSet','Numbered','LowerAlpha','UpperAlpha','LowerRoman','UpperRoman','Disc','Circle','Square','CustomImage'),'NotSet');

 	}

 

+	/**

+	 * @param string display mode of the list. Defaults to 'Text'.

+	 */

 	public function getDisplayMode()

 	{

 		return $this->getViewState('DisplayMode','Text');

 	}

 

+	/**

+	 * @return string display mode of the list. Valid values include

+	 * 'Text', 'HyperLink', 'LinkButton'.

+	 */

 	public function setDisplayMode($value)

 	{

 		$this->setViewState('DisplayMode',TPropertyValue::ensureEnum($value,'Text','HyperLink','LinkButton'),'Text');

 	}

 

+	/**

+	 * @return integer starting index when {@link getBulletStyle BulletStyle} is one of

+	 * the following: 'Numbered', 'LowerAlpha', 'UpperAlpha', 'LowerRoman', 'UpperRoman'.

+	 * Defaults to 1.

+	 */

 	public function getFirstBulletNumber()

 	{

 		return $this->getViewState('FirstBulletNumber',1);

 	}

 

+	/**

+	 * @param integer starting index when {@link getBulletStyle BulletStyle} is one of

+	 * the following: 'Numbered', 'LowerAlpha', 'UpperAlpha', 'LowerRoman', 'UpperRoman'.

+	 */

 	public function setFirstBulletNumber($value)

 	{

 		$this->setViewState('FirstBulletNumber',TPropertyValue::ensureInteger($value),1);

 	}

 

+	/**

+	 * Raises 'Click' event.

+	 * This method is invoked when the {@link getDisplayMode DisplayMode} is 'LinkButton'

+	 * and end-users click on one of the buttons.

+	 * @param TBulletedListEventParameter event parameter.

+	 */

 	public function onClick($param)

 	{

 		$this->raiseEvent('Click',$this,$param);

 	}

 

 	/**

-	 * @return string the target window or frame to display the Web page content linked to when the THyperLink component is clicked.

+	 * @return string the target window or frame to display the Web page content

+	 * linked to when {@link getDisplayMode DisplayMode} is 'HyperLink' and one of

+	 * the hyperlinks is clicked.

 	 */

 	public function getTarget()

 	{

@@ -142,20 +216,29 @@ class TBulletedList extends TListControl implements IPostBackEventHandler
 	}

 

 	/**

-	 * Sets the target window or frame to display the Web page content linked to when the THyperLink component is clicked.

-	 * @param string the target window, valid values include '_blank', '_parent', '_self', '_top' and empty string.

+	 * @param string the target window or frame to display the Web page content

+	 * linked to when {@link getDisplayMode DisplayMode} is 'HyperLink' and one of

+	 * the hyperlinks is clicked.

 	 */

 	public function setTarget($value)

 	{

 		$this->setViewState('Target',$value,'');

 	}

 

+	/**

+	 * Renders the control.

+	 * @param THtmlWriter the writer for the rendering purpose.

+	 */

 	protected function render($writer)

 	{

 		if($this->getHasItems())

 			parent::render($writer);

 	}

 

+	/**

+	 * Renders the body contents.

+	 * @param THtmlWriter the writer for the rendering purpose.

+	 */

 	protected function renderContents($writer)

 	{

 		$this->_isEnabled=$this->getEnabled(true);

@@ -175,6 +258,12 @@ class TBulletedList extends TListControl implements IPostBackEventHandler
 		}

 	}

 

+	/**

+	 * Renders each item

+	 * @param THtmlWriter writer for the rendering purpose

+	 * @param TListItem item to be rendered

+	 * @param integer index of the item being rendered

+	 */

 	protected function renderBulletText($writer,$item,$index)

 	{

 		switch($this->getDisplayMode())

@@ -216,6 +305,9 @@ class TBulletedList extends TListControl implements IPostBackEventHandler
 		$writer->renderEndTag();

 	}

 

+	/**

+	 * @return TPostBackOptions postback options used for linkbuttons.

+	 */

 	protected function getPostBackOptions()

 	{

 		$option=new TPostBackOptions();

@@ -232,14 +324,36 @@ class TBulletedList extends TListControl implements IPostBackEventHandler
 	}

 }

 

+/**

+ * TBulletedListEventParameter

+ * Event parameter for {@link TBulletedList::onClick Click} event of the

+ * bulleted list. The {@link getIndex Index} gives the zero-based index

+ * of the item that is currently being clicked.

+ *

+ * @author Qiang Xue <qiang.xue@gmail.com>

+ * @version $Revision: $  $Date: $

+ * @package System.Web.UI.WebControls

+ * @since 3.0

+ */

 class TBulletedListEventParameter extends TEventParameter

 {

+	/**

+	 * @var integer index of the item clicked

+	 */

 	private $_index;

+

+	/**

+	 * Constructor.

+	 * @param integer index of the item clicked

+	 */

 	public function __construct($index)

 	{

 		$this->_index=$index;

 	}

 

+	/**

+	 * @return integer zero-based index of the item (rendered as a link button) that is clicked

+	 */

 	public function getIndex()

 	{

 		return $this->_index;