From 502f34922f324437030a76742252b37f5f82567d Mon Sep 17 00:00:00 2001
From: xue <>
Date: Thu, 12 Jan 2006 16:41:25 +0000
Subject: Added documentation.

---
 framework/Web/UI/WebControls/TTextHighlighter.php | 76 +++++++++++++++++++----
 1 file changed, 63 insertions(+), 13 deletions(-)

(limited to 'framework')

diff --git a/framework/Web/UI/WebControls/TTextHighlighter.php b/framework/Web/UI/WebControls/TTextHighlighter.php
index ec21b344..800d5246 100644
--- a/framework/Web/UI/WebControls/TTextHighlighter.php
+++ b/framework/Web/UI/WebControls/TTextHighlighter.php
@@ -1,16 +1,36 @@
 <?php
+/**
+ * TTextHighlighter class file
+ *
+ * @author Wei Zhuo<weizhuo[at]gmail[dot]com>
+ * @link http://www.pradosoft.com/
+ * @copyright Copyright &copy; 2005 Wei Zhuo
+ * @license http://www.pradosoft.com/license/
+ * @version $Revision: $  $Date: $
+ * @package System.Web.UI.WebControls
+ */
 
+/**
+ * Using GeSHi and TTextWriter classes
+ */
 Prado::using('System.Web.UI.WebControls.Highlighter.geshi');
 Prado::using('System.IO.TTextWriter');
 
 /**
- * ${classname}
+ * TTextHighlighter class.
  *
- * ${description}
+ * TTextHighlighter does syntax highlighting its body content, including
+ * static text and rendering results of child controls.
+ * You can set {@link setLanguage Language} to specify what kind of syntax
+ * the body content is. Currently, TTextHighlighter supports the following
+ * languages: 'php','prado','css','html','javascript' and 'xml', where 'prado'
+ * refers to PRADO template syntax. By setting {@link setShowLineNumbers ShowLineNumbers}
+ * to true, the highlighted result may be shown with line numbers.
  *
  * @author Wei Zhuo<weizhuo[at]gmail[dot]com>
- * @version $Revision: 1.66 $  $Date: ${DATE} ${TIME} $
- * @package ${package}
+ * @version $Revision: $  $Date: $
+ * @package System.Web.UI.WebControls
+ * @since 3.0
  */
 class TTextHighlighter extends TWebControl
 {
@@ -22,32 +42,55 @@ class TTextHighlighter extends TWebControl
 		return 'div';
 	}
 
+	/**
+	 * @return string language whose syntax is to be used for highlighting. Defaults to 'php'.
+	 */
 	public function getLanguage()
 	{
 		return $this->getViewState('Language', 'php');
 	}
 
+	/**
+	 * @param string language whose syntax is to be used for highlighting.
+	 * Valid values include 'php','prado','css','html','javascript','xml'.
+	 */
 	public function setLanguage($value)
 	{
-		$this->setViewState('Language', $value, 'php');
+		$this->setViewState('Language', TPropertyValue::ensureEnum($value,'php','prado','css','html','javascript','xml'), 'php');
 	}
 
-	public function setShowLineNumbers($value)
+	/**
+	 * @return boolean whether to show line numbers in the highlighted result.
+	 */
+	public function getShowLineNumbers()
 	{
-		$this->setViewState('ShowLineNumbers', TPropertyValue::ensureBoolean($value), false);
+		return $this->getViewState('ShowLineNumbers', false);
 	}
 
-	public function getShowLineNumbers()
+	/**
+	 * @param boolean whether to show line numbers in the highlighted result.
+	 */
+	public function setShowLineNumbers($value)
 	{
-		return $this->getViewState('ShowLineNumbers', false);
+		$this->setViewState('ShowLineNumbers', TPropertyValue::ensureBoolean($value), false);
 	}
 
+	/**
+	 * Registers css style for the highlighted result.
+	 * This method overrides parent implementation.
+	 * @param THtmlWriter writer
+	 */
 	protected function onPreRender($writer)
 	{
 		parent::onPreRender($writer);
-		$this->registerTextHighlightStyleSheet();
+		$this->registerHighlightStyleSheet();
 	}
 
+	/**
+	 * HTML-decodes static text.
+	 * This method overrides parent implementation.
+	 * @param mixed object to be added as body content
+	 */
 	public function addParsedObject($object)
 	{
 		if(is_string($object))
@@ -55,6 +98,12 @@ class TTextHighlighter extends TWebControl
 		parent::addParsedObject($object);
 	}
 
+	/**
+	 * Renders body content.
+	 * This method overrides parent implementation by replacing
+	 * the body content with syntax highlighted result.
+	 * @param THtmlWriter writer
+	 */
 	protected function renderContents($writer)
 	{
 		$textWriter=new TTextWriter;
@@ -65,13 +114,14 @@ class TTextHighlighter extends TWebControl
 	/**
 	 * Register CSS style sheet file.
 	 */
-	protected function registerTextHighlightStyleSheet()
+	protected function registerHighlightStyleSheet()
 	{
 		$cs = $this->getPage()->getClientScript();
-		if(!$cs->isStyleSheetFileRegistered(get_class($this)))
+		$cssKey='prado:TTextHighlighter';
+		if(!$cs->isStyleSheetFileRegistered($cssKey))
 		{
 			$styleSheet = $this->getAsset('Highlighter/code_highlight.css');
-			$cs->registerStyleSheetFile(get_class($this), $styleSheet);
+			$cs->registerStyleSheetFile($cssKey, $styleSheet);
 		}
 	}
 
-- 
cgit v1.2.3