*******************************
 The HTML_Progress2_Lite Class
*******************************

--------------------
 User Documentation
--------------------

:Author:        Laurent Laville
:Contact:       pear@laurent-laville.org
:Date:          $Date: 2005/06/23 14:32:01 $
:Revision:      $Revision: 1.1 $


Table of contents

1. Intended audience
2. Introduction
3. Installation
4. A simple tutorial
5. Quick API tutorial
6. Attributes reference

*******************************

1. Intended audience
====================

If you want to have a class without any dependencies, and don't want to
install/use the PEAR framework, then HTML_Progress2_Lite is the easy solution
to produces progress meter (as its big brother PEAR::HTML_Progress2).


2. Introduction
===============

HTML_Progress2_Lite is a class that produces quickly and easily a vertical
or horizontal progress bar. Each progress bar may be filled in both way
(from up/down, from left,right).

Comparative HTML_Progress2 vs HTML_Progress2_Lite
-------------------------------------------------

A quickly features comparative between the two classes (solutions) :

+-------------------------------------+----------------+---------------------+
| Features \ Classes                  | HTML_Progress2 | HTML_Progress2_Lite |
+=====================================+================+=====================+
| Horizontal progress meter           |     yes        |        yes          |
+-------------------------------------+----------------+---------------------+
| Vertical progress meter             |     yes        |        yes          |
+-------------------------------------+----------------+---------------------+
| Polygonal progress meter            |     yes        |        no           |
+-------------------------------------+----------------+---------------------+
| Ellipse/Circle progress meter       |     yes        |        no           |
+-------------------------------------+----------------+---------------------+
| API error management                |     yes        |        no           |
+-------------------------------------+----------------+---------------------+
| multiple progress bar on same page  |     yes        |        yes          |
+-------------------------------------+----------------+---------------------+
| multiple labels system              |     yes        |        yes          |
+-------------------------------------+----------------+---------------------+
| full bar progress meter rendering   |     yes        |        yes          |
+-------------------------------------+----------------+---------------------+
| progress meter with cells rendering |     yes        |        no           |
+-------------------------------------+----------------+---------------------+
| progress meter with cells rendering |     yes        |        no           |
+-------------------------------------+----------------+---------------------+
| may use external stylesheet         |     yes        |        no           |
+-------------------------------------+----------------+---------------------+
| may use external javascript         |     yes        |        no           |
+-------------------------------------+----------------+---------------------+
| implements Observer design pattern  |     yes        |        no           |
+-------------------------------------+----------------+---------------------+

Software license:
-----------------
HTML_Progress2_Lite is released under PHP License 3.0
(http://www.php.net/license/3_0.txt)

Specifications:
---------------
Supported Platforms
  Operating System independent.

Supported Browsers
  * Internet Explorer 6.x
  * Mozilla 1.7.x
  * Mozilla Firebird 1.x
  * Opera 7.x

System Requirements:
--------------------
Mandatory resources:
  * Webserver Apache 1.3.x or IIS (recommended: 1.3.33)
  * PHP 4.2.0 or newer (recommended: 4.3.11 or 5.0.4)


3. Installation
===============

Copy the file (Progress2_Lite.php) to a directory that is in your PHP
include_path. If none is yet defined, you should then edit your php.ini

If you do not have access to the php.ini file, you can change non-server
settings (such as your include_path) with the ini_set() command.
example: ini_set("include_path",".:/usr/local/lib/php");


4. A simple tutorial
====================

As example below is only a demo and process nothing, i've added a wait
function. Take care that the basic PHP function usleep()
(http://www.php.net/manual/en/function.usleep.php) did not work on Windows
systems until PHP 5.0.0
So i've defined a custom _sleep() function, that allows this script to
have a smooth animation and run on all platforms.

::
    <?php
    require_once 'Progress2_Lite.php';

    function _sleep($usecs)
    {
        if ((substr(PHP_OS, 0, 3) == 'WIN') && (substr(PHP_VERSION,0,1) < '5') ){
            for ($i=0; $i<$usecs; $i++) { }
        } else {
            usleep($usecs);
        }
    }

    // Creates a new progress bar 300 pixels width and 30 pixels height
    // at position 50:80 of your browser screen
    $pbl = new HTML_Progress2_Lite(array('top' => 80, 'left' => 50, 'height' => 30));

    // Adds additional text label
    $pbl->addLabel('text','txt1','Progress2 Lite - Simple Example');

    // Show the progress bar
    $pbl->display();

    // Processes
    for($i=1; $i<=100; $i++) {
        $pbl->moveStep($i);
        _sleep(100000);
    }
    ?>
::


5. Quick API tutorial
=====================

* setDirection() _ defines the progress bar fill way and shape
  horizontal bar
  - from left to right (= right)
  - from right to left (= left)
  vertical bar
  - from down to up (= up)
  - from up to down (= down)

  default: horizontal bar filled from left to right

* addLabel() _ add a new label to the progress bar
  = > see also  removeLabel() to remove an existing label, and chapter 6

* addButton() _ add a new button to the progress bar
  = > see also  removeButton() to remove an existing button, and chapter 6

   ::
    <?php
    require_once 'Progress2_Lite.php';

    $pbl = new HTML_Progress2_Lite(array('padding' => 2, 'position' => 'relative'));

    // Adds stop button as label 'btn2' with action 'stop=1'
    $pbl->addButton('btn1','Stop',$_SERVER['PHP_SELF'].'?stop=1');

    // ...
    ?>
   ::

* setFrameAttributes() _ build a frame around the progress bar.
  => see chapter 6 for styles quick card reference

* setLabelAttributes() _ defines style of a progress bar label.
  => see chapter 6 for styles quick card reference

   ::
    <?php
    require_once 'Progress2_Lite.php';

    $pbl = new HTML_Progress2_Lite(array('padding' => 2, 'position' => 'relative'));

    // Adds restart button as label 'btn1' with action 'restart=1'
    $pbl->addButton('btn1','Restart',$_SERVER['PHP_SELF'].'?restart=1');
    // Adds stop button as label 'btn2' with action 'stop=1'
    $pbl->addButton('btn2','Stop',$_SERVER['PHP_SELF'].'?stop=1');
    // and make it right aligned with restart button (shift left 80 pixels)
    $pbl->setLabelAttributes('btn2', array('left' => 80));

    // ...
    ?>
   ::

* moveNext(), moveStep() _ changes the value of the progress bar and refresh display

* moveMin() _ API to restart at beginning a progress bar

* display() _ send progress bar renders to browser

* hide() _ hide the progress bar on display

* show() _ show a progress bar hidden on display


6. Attributes reference
=======================

Position and size
-----------------
The main look and feel of the progress bar can be set with first parameter
of the class constructor. The '$options' parameter is expected a hash of
style declarations.
Here are the default values applied if nothing overload it:

   +-----------------------------------------------+------------------------+
   | Attributes                                    |    Default values      |
   +===============================================+========================+
   | position                                      |        absolute        |
   +-----------------------------------------------+------------------------+
   | left                                          |        10              |
   +-----------------------------------------------+------------------------+
   | top                                           |        25              |
   +-----------------------------------------------+------------------------+
   | width                                         |        300             |
   +-----------------------------------------------+------------------------+
   | height                                        |        25              |
   +-----------------------------------------------+------------------------+
   | padding                                       |        0               |
   +-----------------------------------------------+------------------------+
   | min                                           |        0               |
   +-----------------------------------------------+------------------------+
   | max                                           |        100             |
   +-----------------------------------------------+------------------------+

All these properties means that we will create, by default, a standard
progress bar 300 pixels width, 25 pixels height, at position 10,25 of
your browser screen.

Colors
------
The colors are defined by setBarAttributes() method, which accepted a hash
of style declarations, with defaults :

   +-----------------------------------------------+------------------------+
   | Attributes                                    |    Default values      |
   +===============================================+========================+
   | border-style                                  |      solid             |
   +-----------------------------------------------+------------------------+
   | border-width                                  |      1                 |
   +-----------------------------------------------+------------------------+
   | border-color                                  |      #000000           |
   +-----------------------------------------------+------------------------+
   | background-color                              |      #C0C0C0           |
   +-----------------------------------------------+------------------------+
   | color                                         |      #0033FF           |
   +-----------------------------------------------+------------------------+

Frame
-----
Allows to build a frame (windows style) around the progress bar

   +-----------------------------------------------+------------------------+
   | Attributes                                    |    Default values      |
   +===============================================+========================+
   | show                                          |        true            |
   +-----------------------------------------------+------------------------+
   | left                                          |        200             |
   +-----------------------------------------------+------------------------+
   | top                                           |        100             |
   +-----------------------------------------------+------------------------+
   | width                                         |        320             |
   +-----------------------------------------------+------------------------+
   | height                                        |        90              |
   +-----------------------------------------------+------------------------+
   | color                                         |        #C0C0C0         |
   +-----------------------------------------------+------------------------+
   | border                                        |        2               |
   +-----------------------------------------------+------------------------+
   | border-style                                  |        solid           |
   +-----------------------------------------------+------------------------+
   | border-color                                  |    #DFDFDF #404040     |
   |                                               |    #404040 #DFDFDF     |
   +-----------------------------------------------+------------------------+

Labels
------
Five types are available: text, button, step, percent, crossbar

   +-----------------------------------------------+------------------------+
   | TEXT label attributes                         |    Default values      |
   +===============================================+========================+
   | left  (1)                                     |       left             |
   +-----------------------------------------------+------------------------+
   | top   (1)                                     |       top - 16         |
   +-----------------------------------------------+------------------------+
   | width   (2)                                   |        0               |
   +-----------------------------------------------+------------------------+
   | height  (2)                                   |        0               |
   +-----------------------------------------------+------------------------+
   | align  (left, center, right)                  |        left            |
   +-----------------------------------------------+------------------------+
   | background-color                              |                        |
   +-----------------------------------------------+------------------------+
   | font-size                                     |        11              |
   +-----------------------------------------------+------------------------+
   | font-family                                   | Verdana, Tahoma, Arial |
   +-----------------------------------------------+------------------------+
   | font-weight                                   |        normal          |
   +-----------------------------------------------+------------------------+
   | color                                         |        #000000         |
   +-----------------------------------------------+------------------------+

   +-----------------------------------------------+------------------------+
   | BUTTON label attributes                       |    Default values      |
   +===============================================+========================+
   | action                                        |                        |
   +-----------------------------------------------+------------------------+
   | target                                        |       self             |
   +-----------------------------------------------+------------------------+
   | left  (1)                                     |       left             |
   +-----------------------------------------------+------------------------+
   | top   (1)                                     |   top + height + 10    |
   +-----------------------------------------------+------------------------+
   | width                                         |        0               |
   +-----------------------------------------------+------------------------+
   | height                                        |        0               |
   +-----------------------------------------------+------------------------+
   | align  (left, center, right)                  |        center          |
   +-----------------------------------------------+------------------------+
   | background-color                              |                        |
   +-----------------------------------------------+------------------------+
   | font-size                                     |        11              |
   +-----------------------------------------------+------------------------+
   | font-family                                   | Verdana, Tahoma, Arial |
   +-----------------------------------------------+------------------------+
   | font-weight                                   |        normal          |
   +-----------------------------------------------+------------------------+
   | color                                         |        #000000         |
   +-----------------------------------------------+------------------------+

   +-----------------------------------------------+------------------------+
   | STEP label attributes                         |    Default values      |
   +===============================================+========================+
   | left  (1)                                     |       left + 5         |
   +-----------------------------------------------+------------------------+
   | top   (1)                                     |       top + 5          |
   +-----------------------------------------------+------------------------+
   | width                                         |        10              |
   +-----------------------------------------------+------------------------+
   | height                                        |        0               |
   +-----------------------------------------------+------------------------+
   | align  (left, center, right)                  |        right           |
   +-----------------------------------------------+------------------------+
   | background-color                              |                        |
   +-----------------------------------------------+------------------------+
   | font-size                                     |        11              |
   +-----------------------------------------------+------------------------+
   | font-family                                   | Verdana, Tahoma, Arial |
   +-----------------------------------------------+------------------------+
   | font-weight                                   |        normal          |
   +-----------------------------------------------+------------------------+
   | color                                         |        #000000         |
   +-----------------------------------------------+------------------------+

   +-----------------------------------------------+------------------------+
   | PERCENT label attributes                      |    Default values      |
   +===============================================+========================+
   | left  (1)                                     |  left + width - 50     |
   +-----------------------------------------------+------------------------+
   | top   (1)                                     |       top - 16         |
   +-----------------------------------------------+------------------------+
   | width                                         |        50              |
   +-----------------------------------------------+------------------------+
   | height                                        |        0               |
   +-----------------------------------------------+------------------------+
   | align  (left, center, right)                  |        right           |
   +-----------------------------------------------+------------------------+
   | background-color                              |                        |
   +-----------------------------------------------+------------------------+
   | font-size                                     |        11              |
   +-----------------------------------------------+------------------------+
   | font-family                                   | Verdana, Tahoma, Arial |
   +-----------------------------------------------+------------------------+
   | font-weight                                   |        normal          |
   +-----------------------------------------------+------------------------+
   | color                                         |        #000000         |
   +-----------------------------------------------+------------------------+

   +-----------------------------------------------+------------------------+
   | CROSSBAR label attributes                     |    Default values      |
   +===============================================+========================+
   | left  (1)                                     |  left + (width / 2)    |
   +-----------------------------------------------+------------------------+
   | top   (1)                                     |       top - 16         |
   +-----------------------------------------------+------------------------+
   | width                                         |        10              |
   +-----------------------------------------------+------------------------+
   | height                                        |        0               |
   +-----------------------------------------------+------------------------+
   | align  (left, center, right)                  |        center          |
   +-----------------------------------------------+------------------------+
   | background-color                              |                        |
   +-----------------------------------------------+------------------------+
   | font-size                                     |        11              |
   +-----------------------------------------------+------------------------+
   | font-family                                   | Verdana, Tahoma, Arial |
   +-----------------------------------------------+------------------------+
   | font-weight                                   |        normal          |
   +-----------------------------------------------+------------------------+
   | color                                         |        #000000         |
   +-----------------------------------------------+------------------------+

   Note (1): position/size are relative to progress bar itself.
             That means the default text label is on top side
             of the progress bar.
   Note (2): width or height sets to zero means there is no size restriction
             (== auto-size)

