From 709501acc76be4cddbe88c5cb9ab52e998fda90d Mon Sep 17 00:00:00 2001 From: xue <> Date: Wed, 4 Jan 2006 14:42:29 +0000 Subject: Added documentation. --- framework/Web/UI/WebControls/TBulletedList.php | 120 ++++++++++++++++++++++++- 1 file changed, 117 insertions(+), 3 deletions(-) (limited to 'framework/Web/UI/WebControls/TBulletedList.php') 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 * @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 + * @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; -- cgit v1.2.3