From 4ab3e2865788db181a0d4d6d3b459123df43d2b5 Mon Sep 17 00:00:00 2001 From: xue <> Date: Wed, 4 Jan 2006 22:54:41 +0000 Subject: Added documentation. --- framework/Web/UI/WebControls/TTable.php | 412 +++++++++++++++++++++++--------- 1 file changed, 300 insertions(+), 112 deletions(-) (limited to 'framework/Web/UI/WebControls') diff --git a/framework/Web/UI/WebControls/TTable.php b/framework/Web/UI/WebControls/TTable.php index 4f93f8f1..66485399 100644 --- a/framework/Web/UI/WebControls/TTable.php +++ b/framework/Web/UI/WebControls/TTable.php @@ -1,25 +1,106 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ + +/** + * TTable class + * + * TTable displays an HTML table on a Web page. + * + * A table may have {@link setCaption Caption}, whose alignment is specified + * via {@link setCaptionAlign CaptionAlign}. The table cellpadding and cellspacing + * are specified via {@link setCellPadding CellPadding} and {@link setCellSpacing CellSpacing} + * properties, respectively. The {@link setGridLines GridLines} specifies how + * the table should display its borders. The horizontal alignment of the table + * content can be specified via {@link setHorizontalAlign HorizontalAlign}, + * and {@link setBackImageUrl BackImageUrl} can assign a background image to the table. + * + * A TTable maintains a list of {@link TTableRow} controls in its + * {@link getRows Rows} property. Each {@link TTableRow} represents + * an HTML table row. + * + * To populate the table {@link getRows Rows}, you may either use control template + * or dynamically create {@link TTableRow} in code. + * In template, do as follows to create the table rows and cells, + * + * <com:TTable> + * <com:TTableRow> + * <com:TTableCell Text="content" /> + * <com:TTableCell Text="content" /> + * </com:TTableRow> + * <com:TTableRow> + * <com:TTableCell Text="content" /> + * <com:TTableCell Text="content" /> + * </com:TTableRow> + * <com:TTable> + * + * The above can also be accomplished in code as follows, + * + * $table=new TTable; + * $row=new TTableRow; + * $cell=new TTableCell; $cell->Text="content"; $row->Cells->add($cell); + * $cell=new TTableCell; $cell->Text="content"; $row->Cells->add($cell); + * $table->Rows->add($row); + * $row=new TTableRow; + * $cell=new TTableCell; $cell->Text="content"; $row->Cells->add($cell); + * $cell=new TTableCell; $cell->Text="content"; $row->Cells->add($cell); + * $table->Rows->add($row); + * + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TTable extends TWebControl { + /** + * @var TTableRowCollection row collection + */ private $_rows=null; + /** + * @return string tag name for the table + */ protected function getTagName() { return 'table'; } + /** + * Adds object parsed from template to the control. + * This method adds only {@link TTableRow} objects into the {@link getRows Rows} collection. + * All other objects are ignored. + * @param mixed object parsed from template + */ public function addParsedObject($object) { if($object instanceof TTableRow) $this->getRows()->add($object); } + /** + * Creates a style object for the control. + * This method creates a {@link TTableStyle} to be used by the table. + * @return TStyle control style to be used + */ protected function createStyle() { return new TTableStyle; } + /** + * Adds attributes to renderer. + * @param THtmlWriter the renderer + */ protected function addAttributesToRender($writer) { parent::addAttributesToRender($writer); @@ -38,37 +119,50 @@ class TTable extends TWebControl } /** - * @return array list of TTableRow components + * @return TTableRowCollection list of {@link TTableRow} controls */ public function getRows() { if(!$this->_rows) - $this->_rows=new TTableRowCollection($this); + $this->_rows=new TTableRowCollection(); return $this->_rows; } + /** + * @return string table caption + */ public function getCaption() { return $this->getViewState('Caption',''); } + /** + * @param string table caption + */ public function setCaption($value) { $this->setViewState('Caption',$value,''); } + /** + * @return string table caption alignment. Defaults to 'NotSet'. + */ public function getCaptionAlign() { - return $this->getViewState('CaptionAlign',''); + return $this->getViewState('CaptionAlign','NotSet'); } + /** + * @param string table caption alignment. Valid values include + * 'NotSet','Top','Bottom','Left','Right'. + */ public function setCaptionAlign($value) { $this->setViewState('CaptionAlign',TPropertyValue::ensureEnum($value,'NotSet','Top','Bottom','Left','Right'),'NotSet'); } /** - * @return integer the cellspacing for the table keeping the checkbox list. Defaults to -1, meaning not set. + * @return integer the cellspacing for the table. Defaults to -1, meaning not set. */ public function getCellSpacing() { @@ -79,8 +173,7 @@ class TTable extends TWebControl } /** - * Sets the cellspacing for the table keeping the checkbox list. - * @param integer the cellspacing for the table keeping the checkbox list. + * @param integer the cellspacing for the table. Defaults to -1, meaning not set. */ public function setCellSpacing($value) { @@ -88,7 +181,7 @@ class TTable extends TWebControl } /** - * @return integer the cellpadding for the table keeping the checkbox list. Defaults to -1, meaning not set. + * @return integer the cellpadding for the table. Defaults to -1, meaning not set. */ public function getCellPadding() { @@ -99,14 +192,16 @@ class TTable extends TWebControl } /** - * Sets the cellpadding for the table keeping the checkbox list. - * @param integer the cellpadding for the table keeping the checkbox list. + * @param integer the cellpadding for the table. Defaults to -1, meaning not set. */ public function setCellPadding($value) { $this->getStyle()->setCellPadding($value); } + /** + * @return string the horizontal alignment of the table content. Defaults to 'NotSet'. + */ public function getHorizontalAlign() { if($this->getHasStyle()) @@ -115,11 +210,18 @@ class TTable extends TWebControl return 'NotSet'; } + /** + * @param string the horizontal alignment of the table content. + * Valid values include 'NotSet', 'Justify', 'Left', 'Right', 'Center'. + */ public function setHorizontalAlign($value) { $this->getStyle()->setHorizontalAlign($value); } + /** + * @return string the grid line setting of the table. Defaults to 'None'. + */ public function getGridLines() { if($this->getHasStyle()) @@ -128,24 +230,40 @@ class TTable extends TWebControl return 'None'; } + /** + * Sets the grid line style of the table. + * Valid values include 'None', 'Horizontal', 'Vertical', 'Both'. + * @param string the grid line setting of the table + */ public function setGridLines($value) { $this->getStyle()->setGridLines($value); } + /** + * @return string the URL of the background image for the table + */ public function getBackImageUrl() { if($this->getHasStyle()) return $this->getStyle()->getBackImageUrl(); else - return 'None'; + return ''; } + /** + * Sets the URL of the background image for the table + * @param string the URL + */ public function setBackImageUrl($value) { $this->getStyle()->setBackImageUrl($value); } + /** + * Renders the openning tag for the table control which will render table caption if present. + * @param THtmlWriter the writer used for the rendering purpose + */ public function renderBeginTag($writer) { parent::renderBeginTag($writer); @@ -159,6 +277,10 @@ class TTable extends TWebControl } } + /** + * Renders body contents of the table. + * @param THtmlWriter the writer used for the rendering purpose. + */ protected function renderContents($writer) { if($this->_rows) @@ -174,33 +296,69 @@ class TTable extends TWebControl } +/** + * TTableRow class. + * + * TTableRow displays a table row. The table cells in the row can be accessed + * via {@link getCells Cells}. The horizontal and vertical alignments of the row + * are specified via {@link setHorizontalAlign HorizontalAlign} and + * {@link setVerticalAlign VerticalAlign} properties, respectively. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TTableRow extends TWebControl { + /** + * @var TTableCellCollection cell collection + */ private $_cells=null; + /** + * @return string tag name for the table + */ protected function getTagName() { return 'tr'; } + /** + * Adds object parsed from template to the control. + * This method adds only {@link TTableCell} objects into the {@link getCells Cells} collection. + * All other objects are ignored. + * @param mixed object parsed from template + */ public function addParsedObject($object) { if($object instanceof TTableCell) $this->getCells()->add($object); } + /** + * Creates a style object for the control. + * This method creates a {@link TTableItemStyle} to be used by the table row. + * @return TStyle control style to be used + */ protected function createStyle() { return new TTableItemStyle; } + /** + * @return TTableCellCollection list of {@link TTableCell} controls + */ public function getCells() { if(!$this->_cells) - $this->_cells=new TTableCellCollection($this); + $this->_cells=new TTableCellCollection(); return $this->_cells; } + /** + * @return string the horizontal alignment of the contents within the table item, defaults to 'NotSet'. + */ public function getHorizontalAlign() { if($this->getHasStyle()) @@ -209,11 +367,19 @@ class TTableRow extends TWebControl return 'NotSet'; } + /** + * Sets the horizontal alignment of the contents within the table item. + * Valid values include 'NotSet', 'Justify', 'Left', 'Right', 'Center' + * @param string the horizontal alignment + */ public function setHorizontalAlign($value) { $this->getStyle()->setHorizontalAlign($value); } + /** + * @return string the vertical alignment of the contents within the table item, defaults to 'NotSet'. + */ public function getVerticalAlign() { if($this->getHasStyle()) @@ -222,11 +388,20 @@ class TTableRow extends TWebControl return 'NotSet'; } + /** + * Sets the vertical alignment of the contents within the table item. + * Valid values include 'NotSet','Top','Bottom','Middel' + * @param string the horizontal alignment + */ public function setVerticalAlign($value) { $this->getStyle()->setVerticalAlign($value); } + /** + * Renders body contents of the table row + * @param THtmlWriter writer for the rendering purpose + */ protected function renderContents($writer) { if($this->_cells) @@ -242,18 +417,51 @@ class TTableRow extends TWebControl } +/** + * TTableCell class. + * + * TTableCell displays a table cell on a Web page. Content of the table cell + * is specified by the {@link setText Text} property. If {@link setText Text} + * is empty, the body contents enclosed by the table cell component tag are rendered. + * Note, {@link setText Text} is not HTML-encoded when displayed. So make sure + * it does not contain dangerous characters. + * + * The horizontal and vertical alignments of the contents in the cell + * are specified via {@link setHorizontalAlign HorizontalAlign} and + * {@link setVerticalAlign VerticalAlign} properties, respectively. + * + * The colspan and rowspan of the cell are specified via {@link setColumnSpan ColumnSpan} + * and {@link setRowSpan RowSpan} properties. And the {@link setWrap Wrap} property + * indicates whether the contents in the cell should be wrapped. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TTableCell extends TWebControl { + /** + * @return string tag name for the table cell + */ protected function getTagName() { return 'td'; } + /** + * Creates a style object for the control. + * This method creates a {@link TTableItemStyle} to be used by the table cell. + * @return TStyle control style to be used + */ protected function createStyle() { return new TTableItemStyle; } + /** + * @return string the horizontal alignment of the contents within the table item, defaults to 'NotSet'. + */ public function getHorizontalAlign() { if($this->getHasStyle()) @@ -262,11 +470,19 @@ class TTableCell extends TWebControl return 'NotSet'; } + /** + * Sets the horizontal alignment of the contents within the table item. + * Valid values include 'NotSet', 'Justify', 'Left', 'Right', 'Center' + * @param string the horizontal alignment + */ public function setHorizontalAlign($value) { $this->getStyle()->setHorizontalAlign($value); } + /** + * @return string the vertical alignment of the contents within the table item, defaults to 'NotSet'. + */ public function getVerticalAlign() { if($this->getHasStyle()) @@ -275,6 +491,11 @@ class TTableCell extends TWebControl return 'NotSet'; } + /** + * Sets the vertical alignment of the contents within the table item. + * Valid values include 'NotSet','Top','Bottom','Middel' + * @param string the horizontal alignment + */ public function setVerticalAlign($value) { $this->getStyle()->setVerticalAlign($value); @@ -315,7 +536,7 @@ class TTableCell extends TWebControl } /** - * @return boolean whether the text content wraps within a table cell. + * @return boolean whether the text content wraps within a table cell. Defaults to true. */ public function getWrap() { @@ -344,6 +565,7 @@ class TTableCell extends TWebControl /** * Sets the text content of the table cell. + * If the text content is empty, body content (child controls) of the cell will be rendered. * @param string the text content */ public function setText($value) @@ -351,6 +573,10 @@ class TTableCell extends TWebControl $this->setViewState('Text',$value,''); } + /** + * Adds attributes to renderer. + * @param THtmlWriter the renderer + */ protected function addAttributesToRender($writer) { parent::addAttributesToRender($writer); @@ -360,6 +586,10 @@ class TTableCell extends TWebControl $writer->addAttribute('rowspan',"$rowspan"); } + /** + * Renders body contents of the table cell. + * @param THtmlWriter the writer used for the rendering purpose. + */ protected function renderContents($writer) { if(($text=$this->getText())==='') @@ -367,29 +597,32 @@ class TTableCell extends TWebControl else $writer->write($text); } - - /** - * Renders the body content of this cell. - * @return string the rendering result - */ - protected function renderBody() - { - $text=$this->getText(); - if($text!=='') - return $text; - else - return parent::renderBody(); - } } - +/** + * TTableHeaderCell class. + * + * TTableHeaderCell displays a table header cell on a Web page. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TTableHeaderCell extends TTableCell { + /** + * @return string tag name for the table header cell + */ protected function getTagName() { return 'th'; } + /** + * Adds attributes to renderer. + * @param THtmlWriter the renderer + */ protected function addAttributesToRender($writer) { parent::addAttributesToRender($writer); @@ -401,31 +634,50 @@ class TTableHeaderCell extends TTableCell $writer->addAttribute('axis',$text); } + /** + * @return string the scope of the cells that the header cell applies to. Defaults to 'NotSet'. + */ public function getScope() { return $this->getViewState('Scope','NotSet'); } + /** + * @param string the scope of the cells that the header cell applies to. + * Valid values include 'NotSet','Row','Column'. + */ public function setScope($value) { $this->setViewState('Scope',TPropertyValue::ensureEnum($value,'NotSet','Row','Column'),'NotSet'); } + /** + * @return string the abbr attribute of the HTML th element + */ public function getAbbreviatedText() { return $this->getViewState('AbbreviatedText',''); } + /** + * @param string the abbr attribute of the HTML th element + */ public function setAbbreviatedText($value) { $this->setViewState('AbbreviatedText',$value,''); } + /** + * @return string the axis attribute of the HTML th element + */ public function getCategoryText() { return $this->getViewState('CategoryText',''); } + /** + * @param string the axis attribute of the HTML th element + */ public function setCategoryText($value) { $this->setViewState('CategoryText',$value,''); @@ -433,50 +685,18 @@ class TTableHeaderCell extends TTableCell } +/** + * TTableRowCollection class. + * + * TTableRowCollection is used to maintain a list of rows belong to a table. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TTableRowCollection extends TList { - /** - * the table that owns this collection. - * @var TTable - */ - private $_o; - - /** - * Constructor. - * @param TTable the table that owns this collection. - */ - public function __construct(TTable $owner) - { - parent::__construct(); - $this->_o=$owner; - } - - /** - * @return TTable the table that owns this collection. - */ - protected function getOwner() - { - return $this->_o; - } - - /** - * Overrides the parent implementation with customized processing of the newly added item. - * @param mixed the newly added item - */ - protected function addedItem($item) - { - $this->_o->addedControl($item); - } - - /** - * Overrides the parent implementation with customized processing of the removed item. - * @param mixed the removed item - */ - protected function removedItem($item) - { - $this->_o->removedControl($item); - } - /** * Only string or instance of TControl can be added into collection. * @param mixed the item to be added @@ -488,52 +708,20 @@ class TTableRowCollection extends TList } +/** + * TTableCellCollection class. + * + * TTableCellCollection is used to maintain a list of cells belong to a table row. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TTableCellCollection extends TList { /** - * the table row that owns this collection. - * @var TTableRow - */ - private $_o; - - /** - * Constructor. - * @param TTableRow the table row that owns this collection. - */ - public function __construct(TTableRow $owner) - { - parent::__construct(); - $this->_o=$owner; - } - - /** - * @return TTableRow the table row that owns this collection. - */ - protected function getOwner() - { - return $this->_o; - } - - /** - * Overrides the parent implementation with customized processing of the newly added item. - * @param mixed the newly added item - */ - protected function addedItem($item) - { - $this->_o->addedControl($item); - } - - /** - * Overrides the parent implementation with customized processing of the removed item. - * @param mixed the removed item - */ - protected function removedItem($item) - { - $this->_o->removedControl($item); - } - - /** - * Only string or instance of TControl can be added into collection. + * Only string or instance of TTableCell can be added into collection. * @param mixed the item to be added */ protected function canAddItem($item) -- cgit v1.2.3