File: TextFit.doc.txt

TextFit class                                                 v1.1.3 2012-12-05
===============================================================================
http://tweezy.net.au/TextFit.html


TextFit is a simple PHP5 class that does a couple of things:

1. Shorten a text string
------------------------
Strings can be shortened to fit within a specific number of characters.
Two methods are available for this - shortenText() trims excess characters 
from the end of the string, and shortenFilename() trims excess characters from 
the middle, keeping the file extension.


2. Display text in columns
--------------------------
Text values can be displayed in columns, somewhat like a table (for use with 
fixed-width fonts, eg in a plain-text email). The principal methods for this 
are fitTextRow() which produces a row of strings from an array in fixed-width 
columns, and fitTextLine() which produces a horizontal line spanning all columns.

Example output:

Name              | Age | Country      |     Amount
===================================================
Nguyen Thi Anh    | 40  | Vietnam      |   2,108.50
S. Baldrick       | 36  | England      |      14.75
Michael Bruce     | 28  | Australia    |     648.15
Buck Gregson      | 48  | USA          |   4,444.44
---------------------------------------------------

(note that a fixed-width font must be used to line up the columns properly)


===============================================================================

The remainder of this document is a complete reference for the TextFit class. 
FOR A QUICK START, see examples.php

===============================================================================



I N S T A N T I A T I O N
-------------------------
The TextFit class can be instantiated with one or more of the parameters 
listed below. If any of these is missing or null, a default value will be used.
The values for these can also be changed individually after instantiation, by 
calling the appropriate set-- method.

    $Columns ....... for info see setColumns() method
    $WrapText ...... (default=false) for info see setWrap() method
    $AddExtraRow ... (default=false) for info see setAddRow() method


C L A S S   M E T H O D S
-------------------------
_____________________________________________________________________________________________

For simple text or filename shortening, use shortenText or shortenFilename.
These methods do not required class instantiation - that is, they may be called 
statically. For example:
    $s = TextFit::shortenText('Here is some quite long string', 15);
_____________________________________________________________________________________________

    shortenText($text, $chars, $ForceCutoff, $UseEllipsis)
    ------------------------------------------------------
        Trims excess characters from the end of a string.
    
        $text ......... the string to be shortened if necessary (no default - must be supplied)
        $chars ........ (default=40) The maximum number of characters desired. If $text is longer 
                        than this it will be shortened to fit into $chars characters
        $ForceCutoff .. (default=false) If true, $text will be shortened to exactly $chars characters 
                        without regard for word boundaries. If false, the text will try to keep whole 
                        words intact, and as a result will often shorten the text to slightly 
                        less that $chars characters.
        $UseEllipsis .. (default=false) If true, shortened text will be appended with an ellipsis 
                        character. If false, three dots are used.
        
    
    shortenFilename($text, $chars, $UseEllipsis)
    --------------------------------------------
        Trims excess characters from the middle of a filename, keeping the file extension.
    
        $text ......... Text containing the filename to be shortened if necessary, which must 
                        end with a file extension (eg .doc)
        $chars ........ (default=40) Maximum number of characters desired. If $text is longer 
                        than this, excess characters will be removed from the middle of the 
                        string, keeping the file extension
        $UseEllipsis .. (default=false) If true, omitted text will be replaced by an ellipsis 
                        character. If false, three dots are used.

_____________________________________________________________________________________________

The other methods are concerned with displaying fixed-width text in columns, and can only be 
called after instantiating the class.
_____________________________________________________________________________________________
    
    fitTextRow($RowValues, $PadChar)
    --------------------------------
        Produces a row of strings in fixed-width columns
        $RowValues .. an array of strings, one for each column
        $PadChar .... the character use to expand short strings to the correct width 
                      (default=space, or the character previously set by setPadChar)
        See also: setRowChar()
        
    fitTextLine($Char, $ColSpan)
    ----------------------------
        Produces a line that spans all columns, using the $Char character (default '-'). 
        If $ColSpan is specified, only spans that number of columns - this is 
        NOT recommended if you are using setLineChar() or setRowChar().
        See also: setLineChar()
        
    fitTextBlank($PadChar)
    ----------------------
        Essentially the same as fitTextRow, but with empty strings to create a blank line.
        $PadChar is the character use to expand each column to the correct width 
                    (default=space, or the character previously set by setPadChar)

    fitTextRows($RowValues, $AddHeading, $LineChar)
    -----------------------------------------------
        Produces multiple rows of strings from a multi-row array, with an optional heading row.
        $RowValues .... multi-row array (see examples.php)
        $AddHeading ... (default=false) If true, a heading row is generated from the subarray indexes
        $LineChar ..... (default=true) If AddHeading is true, $LineChar can set a line above and/or 
                        below the heading. $LineChar can be boolean, or a 1 or 2 character string
                            1 char: adds lines above and below using that char
                            2 char: adds line above with 1st char, line below with 2nd char
                                - use N for no line; so 'N=' means no line above, line of '=' below
                            true: adds lines of '=' above and below (same as '=' or '==')
                            false: no lines (same as 'N' or 'NN')


    fitTextList($List, $FillDown, $AutoWidth)
    -----------------------------------------
        Produces multiple rows from a simple array of strings
        $List ......... A simple array of strings (see examples.php)
        $FillDown ..... (default=true) If true, values are listed down the first column, then 
                        the second, etc. If false, values are listed row by row.
        $AutoWidth .... (default=false) If true, the widths set with setColumns() are ignored, 
                        and all columns will be the size of the longest string in $List (no word 
                        wrapping!). Any column 'align' and/or 'case' settings will still be used.
                        $AutoWidth can also be an integer specifying the number of columns 
                        to use; in this case you don't need to call setColumns() at all 
                        (and if you do, it will be ignored).
    
_____________________________________________________________________________________________

The methods starting with "set" are used to change various preferences (some of which 
can be set at instantiation). The "set" methods are listed here in alphabetical order.
_____________________________________________________________________________________________

    setAddRow($AddExtraRow)
    -----------------------
        If $AddExtraRow is boolean true, a blank line will be added after each text row. 
        If $AddExtraRow is a string, fitTextLine will be added using that character. 
        This method is especially useful for spacing rows when $WrapText is true - see 
        setWrap() method.

    setColumns($Columns)
    --------------------
        Defines the width, and optionally alignment and letter case of each column. 
        In its simplest form $Columns can be a positive integer, which will set the 
        default width for all columns. The caveat with this is that all columns will 
        be left-aligned, and you must call fitTextRow (which confirms the number of 
        columns) before calling fitTextLine.
        
        EXAMPLE 1: setColumns(30);
            
        For more control, $Columns can be an array of column attributes; one array element 
        per column. Each element in the array may be an integer (width of the column), or 
        a subarray with one or more of these indexes:
            width ... width in characters (int) 
            align ... left|right|centre|center (string) 
            case .... upper|lower|proper|keep (string) 
            
        EXAMPLE 2: setColumns( array(20, 5, 30) )
        EXAMPLE 3: setColumns( array(10, array( 'width'=>10, 'align'=>'right' )) )
        
        Example 3 will set two columns of width 10 characters, the second being right aligned

    setDefaultWidth($DefaultWidth)
    ------------------------------
        Sets the width of any columns that don't have a width specified (default=20)

    setEchoOn($EchoOn)
    ------------------
        If $EchoOn is true the fitText__ methods will echo their result. If false, they 
        will return it as a string, and the calling script is responsible for any output. 
        The default value for the $EchoOn parameter is true, however if you don't call 
        setEchoOn at all, the default value for $EchoOn is false.

    setEOL($EOL)
    ------------
        Sets the character/s to append to the end of each line (default \r\n)

    setIndent($Indent)
    ------------------
        Indents the "table" by prepending $Indent spaces to each row.

    setLineChar($Separator, $LeftChar, $RightChar)
    ----------------------------------------------
        Sets an optional column separator character, and/or left and right border of lines.
        For more information see setRowChar().
        This method does NOT specify the character used for drawing lines - see fitTextLine()
        
    setPadChar($PadChar)
    --------------------
        Sets the character used to pad each column to make it a fixed width.
        The default is space, which very rarely needs to be changed.
        If you're not calling fitTextLine(), $PadChar can be more than one 
        character (eg multiple spaces); this is useful to add extra padding 
        when using fitTextList() with AutoWidth.
        

    setRowChar($Separator, $LeftChar, $RightChar)
    ---------------------------------------------
        Sets an optional column separator character, and/or left and right border 
        for text rows. See also: setLineChar().
        
        $Separator .. if not specified or empty, a single space is used
        $LeftChar ... if not specified or empty, no character is used
        $RightChar .. if not specified, same as $LeftChar
        
        Example: To generate a table like below, you would call 
            setRowChar('|', '|');
            setLineChar('+', '+');
            
            +----------+----------------+
            | Column 1 | Column 2       |
            +----------+----------------+
            | Text     | More text      |
            +----------+----------------+
            | Text     | More text      |
            +----------+----------------+
            | Text     | More text      |
            +----------+----------------+
            
        
    setWrap($WrapText, $MaxLines)
    -----------------------------
        If $WrapText is true, long text is wrapped within each column. If false (default), 
        long text is shortened to fit on one line in each column. If you call setWrap(true), 
        you should also consider calling setAddRow(true).