CheckboxHistory interface

<?php
namespace app\system;
/**
* Maintain a list of checkboxes and the immidiate history
*
* Uses: array of  $key => $label
*
*   the key can be numbers or string the class works with keys
*
*   e.g.  $cbxHistory = new CheckboxHistory(array('key1' => 'label 1',
*                                                 'key2' => 'label 2',
*                                                 'key3' => 'label 3',
*                                                 ))
*
* It uses a string to hold whether each checkbox in the list currently is checked or not
*
*  e.g.   $cbxHistory->cbxStateString()
*
*         This will be stored in a hidden field $_POST and will become the $prvCheckedState
*
*
*
*  It generates all the details to
*     1) use in the checkbox HTML
*          'label' is for the html checkbox label
*          'value' is for the html checkbox value
*            note: the value is a position in the list not a key!
*
*     2) The state of the checkbox and whether is has just changed
*
*  e.g.  $cbxHistory->cbxDetails($key);
*
*        returns: array('label'       => $this->cbxLabel($key),
*                       'value'       => $this->cbxValue($key),
*                       'key'         => $key,
*
*                       'hasChanged'  => $this->hasChanged($key),
*                       'curChecked'  => $this->curChecked($key),
*                       'prvChecked'  => $this->prvChecked($key));
*
*  It uses a cbxStateString to know what the previous states of the checkbox
*
*    e.g.  $cbxHistory->setCbxCheckedState($oldCbxCheckedState);
*
*          This will normally be from the html 'hidden' cbxState field
*
*/

interface ICheckboxHistory {


   /**
   * The label value to be used in the html
   *
   * @param mixed $key
   *
   * @return label text
   */
   public function cbxLabel($key);

   /**
   * The value to be used for the checkbox in the html.
   *
   * It is actually the position of the lookup key in the list
   *
   * @param mixed $key
   *
   * @return integer
   */
   public function cbxValue($key);

   /**
   * The 'key' of the checkbox given the 'value' (position])
   *
   * It is actually the key at that position in the list
   *
   * @param integer $html value of the checkbox
   *
   * @return mixed $key
   */
   public function cbxKey($value);

   /**
   * This is the current state vector of all the checkboxes
   *
   * It is stored in a 'hidden' field on the form
   *
   * It is used in the  fromCbxStateString() method
   *
   * @return string
   */
   public function cbxStateString();


   /**
   * All the details (checkbox state) in one convenient list
   *
   * @param mixed $key
   *
   * @return array  ('label'       => cbxLabel(),
   *                 'value'       => $cbxValue(),
   *                 'key'         => $key,
   *                 'hasChanged'  => hasChanged(),
   *                 'curChecked'  => curChecked(),
   *                 'prvChecked'  => prvChecked(),
   *                )
   */
   public function cbxDetails($key);

   public function cbxDetailsByKey($key); // alias of cbxDetails

   /**
   * All the details (checkbox state) in one convenient list given a checkbox value
   *
   *
   * @param integer $position (html value of the checkbox)
   *
   * @return array
   */
   public function cbxDetailsByValue($position);


   /**
   * All the cbxDetails as an array
   *
   *   The key of the array is position  (cbxValue)
   *
   * @return array
   */
   public function cbxDetailsArray();

   public function getIterator();

   /**
   * set the curCheckedState from an array of values ($positions)
   *
   * @param array $positionList i.e. $_POST
   *
   * @return void
   */
   public function fromCheckedList(array $checkedPos);


  /**
   * This is the previous state of the all checkboxes
   *
   * It is obtained from the chechboxes 'hidden' field
   *
   * @param string $prvStateStr
   *
   * @return void
   */
   public function setCbxStateString($prvStateStr);



   /**
   * current state of a checkbox
   *
   * @param mixed $key
   *
   * @return boolean
   */
   public function curChecked($key);


   /**
   * previous state of a checkbox
   *
   * @param mixed $key
   *
   * @return booleam
   */
   public function prvChecked($key);

   /**
   * Has the checkbox changed state (user checked or unchecked it)
   *
   * @param mixed $key
   *
   * @return boolean
   */
   public function hasChanged($key);



   /**
   * Set or unset a checkbox by key value
   *
   * @param mixed   $key
   * @param boolean $checked
   *
   * @return void
   */
   public function setCheckbox($key, $checked = true);

}