From: stronk7 Date: Mon, 14 Apr 2008 23:03:05 +0000 (+0000) Subject: Cleanup of phpdoc + some clarifications when specifying colors. MDL-14354 ; merged... X-Git-Url: http://git.mjollnir.org/gw?a=commitdiff_plain;h=6d5b31e1198fe305c0f1d7f99662c5d00239d78b;p=moodle.git Cleanup of phpdoc + some clarifications when specifying colors. MDL-14354 ; merged from 19_STABLE --- diff --git a/lib/excellib.class.php b/lib/excellib.class.php index 241bc9ea46..ae5bcbe623 100644 --- a/lib/excellib.class.php +++ b/lib/excellib.class.php @@ -7,7 +7,7 @@ // Moodle - Modular Object-Oriented Dynamic Learning Environment // // http://moodle.com // // // -// Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com // +// Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com // // (C) 2001-3001 Eloy Lafuente (stronk7) http://contiento.com // // // // This program is free software; you can redistribute it and/or modify // @@ -29,7 +29,7 @@ require_once 'Spreadsheet/Excel/Writer.php'; /** * Define and operate over one Moodle Workbook. -* +* * A big part of this class acts as a wrapper over the PEAR * Spreadsheet_Excel_Writer_Workbook and OLE libraries * maintaining Moodle functions isolated from underlying code. @@ -39,7 +39,9 @@ class MoodleExcelWorkbook { var $pear_excel_workbook; var $latin_output; - /* Constructs one Moodle Workbook. + /** + * Constructs one Moodle Workbook. + * * @param string $filename The name of the file */ function MoodleExcelWorkbook($filename) { @@ -58,7 +60,9 @@ class MoodleExcelWorkbook { $this->pear_excel_workbook->setTempDir($CFG->dataroot.'/temp/excel'); } - /* Create one Moodle Worksheet + /** + * Create one Moodle Worksheet + * * @param string $name Name of the sheet */ function &add_worksheet($name = '') { @@ -67,7 +71,9 @@ class MoodleExcelWorkbook { return $ws; } - /* Create one Moodle Format + /** + * Create one Moodle Format + * * @param array $properties array of properties [name]=value; * valid names are set_XXXX existing * functions without the set_ part @@ -79,13 +85,16 @@ class MoodleExcelWorkbook { return $ft; } - /* Close the Moodle Workbook + /** + * Close the Moodle Workbook */ function close() { $this->pear_excel_workbook->close(); } - /* Write the correct HTTP headers + /** + * Write the correct HTTP headers + * * @param string $name Name of the downloaded file */ function send($filename) { @@ -95,7 +104,7 @@ class MoodleExcelWorkbook { /** * Define and operate over one Worksheet. -* +* * A big part of this class acts as a wrapper over the PEAR * Spreadsheet_Excel_Writer_Workbook and OLE libraries * maintaining Moodle functions isolated from underlying code. @@ -105,7 +114,9 @@ class MoodleExcelWorksheet { var $pear_excel_worksheet; var $latin_output; - /* Constructs one Moodle Worksheet. + /** + * Constructs one Moodle Worksheet. + * * @param string $filename The name of the file * @param object $workbook The internal PEAR Workbook onject we are creating */ @@ -120,7 +131,9 @@ class MoodleExcelWorksheet { } } - /* Write one string somewhere in the worksheet + /** + * Write one string somewhere in the worksheet + * * @param integer $row Zero indexed row * @param integer $col Zero indexed column * @param string $str The string to write @@ -141,7 +154,9 @@ class MoodleExcelWorksheet { $this->pear_excel_worksheet->writeString($row, $col, $str, $format); } - /* Write one number somewhere in the worksheet + /** + * Write one number somewhere in the worksheet + * * @param integer $row Zero indexed row * @param integer $col Zero indexed column * @param float $num The number to write @@ -154,7 +169,9 @@ class MoodleExcelWorksheet { $this->pear_excel_worksheet->writeNumber($row, $col, $num, $format); } - /* Write one url somewhere in the worksheet + /** + * Write one url somewhere in the worksheet + * * @param integer $row Zero indexed row * @param integer $col Zero indexed column * @param string $url The url to write @@ -167,7 +184,9 @@ class MoodleExcelWorksheet { $this->pear_excel_worksheet->writeUrl($row, $col, $url, $format); } - /* Write one formula somewhere in the worksheet + /** + * Write one formula somewhere in the worksheet + * * @param integer $row Zero indexed row * @param integer $col Zero indexed column * @param string $formula The formula to write @@ -180,7 +199,9 @@ class MoodleExcelWorksheet { $this->pear_excel_worksheet->writeFormula($row, $col, $formula, $format); } - /* Write one blanck somewhere in the worksheet + /** + * Write one blanck somewhere in the worksheet + * * @param integer $row Zero indexed row * @param integer $col Zero indexed column * @param mixed $format The XF format for the cell @@ -192,8 +213,10 @@ class MoodleExcelWorksheet { $this->pear_excel_worksheet->writeBlank($row, $col, $format); } - /* Write anything somewhere in the worksheet + /** + * Write anything somewhere in the worksheet * Type will be automatically detected + * * @param integer $row Zero indexed row * @param integer $col Zero indexed column * @param mixed $token What we are writing @@ -229,7 +252,9 @@ class MoodleExcelWorksheet { } } - /* Sets the height (and other settings) of one row + /** + * Sets the height (and other settings) of one row + * * @param integer $row The row to set * @param integer $height Height we are giving to the row (null to set just format withouth setting the height) * @param mixed $format The optional XF format we are giving to the row @@ -243,7 +268,9 @@ class MoodleExcelWorksheet { $this->pear_excel_worksheet->setRow($row, $height, $format, $hidden, $level); } - /* Sets the width (and other settings) of one column + /** + * Sets the width (and other settings) of one column + * * @param integer $firstcol first column on the range * @param integer $lastcol last column on the range * @param integer $width width to set @@ -308,8 +335,10 @@ class MoodleExcelWorksheet { /// Merge cells safely to the PEAR Worksheet $this->pear_excel_worksheet->mergeCells($first_row, $first_col, $last_row, $last_col); } - - /* Returns the PEAR Excel Format for one Moodle Excel Format + + /** + * Returns the PEAR Excel Format for one Moodle Excel Format + * * @param mixed MoodleExcelFormat object * @return mixed PEAR Excel Format object */ @@ -325,7 +354,7 @@ class MoodleExcelWorksheet { /** * Define and operate over one Format. -* +* * A big part of this class acts as a wrapper over the PEAR * Spreadsheet_Excel_Writer_Workbook and OLE libraries * maintaining Moodle functions isolated from underlying code. @@ -334,7 +363,9 @@ class MoodleExcelFormat { var $pear_excel_format; - /* Constructs one Moodle Format. + /** + * Constructs one Moodle Format. + * * @param object $workbook The internal PEAR Workbook onject we are creating */ function MoodleExcelFormat(&$workbook, $properties = array()) { @@ -352,6 +383,7 @@ class MoodleExcelFormat { /** * Set the size of the text in the format (in pixels). * By default all texts in generated sheets are 10px. + * * @param integer $size Size of the text (in pixels) */ function set_size($size) { @@ -359,7 +391,9 @@ class MoodleExcelFormat { $this->pear_excel_format->setSize($size); } - /* Set weight of the format + /** + * Set weight of the format + * * @param integer $weight Weight for the text, 0 maps to 400 (normal text), * 1 maps to 700 (bold text). Valid range is: 100-1000. * It's Optional, default is 1 (bold). @@ -369,7 +403,9 @@ class MoodleExcelFormat { $this->pear_excel_format->setBold($weight); } - /* Set underline of the format + /** + * Set underline of the format + * * @param integer $underline The value for underline. Possible values are: * 1 => underline, 2 => double underline */ @@ -378,35 +414,41 @@ class MoodleExcelFormat { $this->pear_excel_format->setUnderline($underline); } - /* Set italic of the format + /** + * Set italic of the format */ function set_italic() { /// Set the italic safely to the PEAR Format $this->pear_excel_format->setItalic(); } - /* Set strikeout of the format + /** + * Set strikeout of the format */ function set_strikeout() { /// Set the strikeout safely to the PEAR Format $this->pear_excel_format->setStrikeOut(); } - /* Set outlining of the format + /** + * Set outlining of the format */ function set_outline() { /// Set the outlining safely to the PEAR Format $this->pear_excel_format->setOutLine(); } - /* Set shadow of the format + /** + * Set shadow of the format */ function set_shadow() { /// Set the shadow safely to the PEAR Format $this->pear_excel_format->setShadow(); } - /* Set the script of the text + /** + * Set the script of the text + * * @param integer $script The value for script type. Possible values are: * 1 => superscript, 2 => subscript */ @@ -415,7 +457,9 @@ class MoodleExcelFormat { $this->pear_excel_format->setScript($script); } - /* Set color of the format + /** + * Set color of the format. Used to specify the color of the text to be formatted. + * * @param mixed $color either a string (like 'blue'), or an integer (range is [8...63]) */ function set_color($color) { @@ -423,7 +467,12 @@ class MoodleExcelFormat { $this->pear_excel_format->setColor($color); } - /* Set foreground color of the format + /** + * Set foreground color (top layer) of the format. About formatting colors note that cells backgrounds + * have TWO layers, in order to support patterns and paint them with two diferent colors. + * This method set the color of the TOP layer of the background format. So, when filling + * cells with plain colors (no patterns) this is the method to use. + * * @param mixed $color either a string (like 'blue'), or an integer (range is [8...63]) */ function set_fg_color($color) { @@ -431,7 +480,13 @@ class MoodleExcelFormat { $this->pear_excel_format->setFgColor($color); } - /* Set background color of the format + /** + * Set background color (bottom layer) of the format. About formatting colors note that cells backgrounds + * have TWO layers, in order to support patterns and paint them with two diferent colors. + * This method set the color of the BOTTOM layer of the background format. So, the color + * specified here only will be visible if using patterns. Use set_fg_color() to fill + * cells with plain colors (no patterns). + * * @param mixed $color either a string (like 'blue'), or an integer (range is [8...63]) */ function set_bg_color($color) { @@ -439,7 +494,8 @@ class MoodleExcelFormat { $this->pear_excel_format->setBgColor($color); } - /* Set the fill pattern of the format + /** + * Set the fill pattern of the format * @param integer Optional. Defaults to 1. Meaningful values are: 0-18 * 0 meaning no background. */ @@ -448,14 +504,17 @@ class MoodleExcelFormat { $this->pear_excel_format->setPattern($pattern); } - /* Set text wrap of the format + /** + * Set text wrap of the format */ function set_text_wrap() { /// Set the shadow safely to the PEAR Format $this->pear_excel_format->setTextWrap(); } - /* Set the cell alignment of the format + /** + * Set the cell alignment of the format + * * @param string $location alignment for the cell ('left', 'right', etc...) */ function set_align($location) { @@ -463,7 +522,9 @@ class MoodleExcelFormat { $this->pear_excel_format->setAlign($location); } - /* Set the cell horizontal alignment of the format + /** + * Set the cell horizontal alignment of the format + * * @param string $location alignment for the cell ('left', 'right', etc...) */ function set_h_align($location) { @@ -471,7 +532,9 @@ class MoodleExcelFormat { $this->pear_excel_format->setHAlign($location); } - /* Set the cell vertical alignment of the format + /** + * Set the cell vertical alignment of the format + * * @param string $location alignment for the cell ('top', 'vleft', etc...) */ function set_v_align($location) { @@ -479,7 +542,9 @@ class MoodleExcelFormat { $this->pear_excel_format->setVAlign($location); } - /* Set the top border of the format + /** + * Set the top border of the format + * * @param integer $style style for the cell. 1 => thin, 2 => thick */ function set_top($style) { @@ -487,7 +552,9 @@ class MoodleExcelFormat { $this->pear_excel_format->setTop($style); } - /* Set the bottom border of the format + /** + * Set the bottom border of the format + * * @param integer $style style for the cell. 1 => thin, 2 => thick */ function set_bottom($style) { @@ -495,7 +562,9 @@ class MoodleExcelFormat { $this->pear_excel_format->setBottom($style); } - /* Set the left border of the format + /** + * Set the left border of the format + * * @param integer $style style for the cell. 1 => thin, 2 => thick */ function set_left($style) { @@ -503,7 +572,9 @@ class MoodleExcelFormat { $this->pear_excel_format->setLeft($style); } - /* Set the right border of the format + /** + * Set the right border of the format + * * @param integer $style style for the cell. 1 => thin, 2 => thick */ function set_right($style) { @@ -513,6 +584,7 @@ class MoodleExcelFormat { /** * Set cells borders to the same style + * * @param integer $style style to apply for all cell borders. 1 => thin, 2 => thick. */ function set_border($style) { @@ -520,10 +592,10 @@ class MoodleExcelFormat { $this->pear_excel_format->setBorder($style); } - /* Set the numerical format of the format - * It can be date, time, currency, etc... - /* Set the numerical format of the format + /** + * Set the numerical format of the format * It can be date, time, currency, etc... + * * @param integer $num_format The numeric format */ function set_num_format($num_format) {