/**
 * How to use :
 *
 * 1) in header, put
 *   <SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript" SRC="[...]/gui.js">
 *   </SCRIPT>
 *   <SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript">
 *     <!--
 *       var ih = createImageHandler ();
 *       ih.setImagePath      ("http://myserver/mypath/");  // "./"   by default
 *       ih.setImageFormat    (".gif");                     // ".gif" by default
 *       ih.setImageOnSuffix  ("_on");                      // ""     by default
 *       ih.setImageOffSuffix ("_off");                     // "_s"   by default
 *       ih.loadImageArray    (['myField', ...]);           // coma separated list of field names
 *     // -->
 *   </SCRIPT>
 *
 *   Note that, according to the upper settings, the files :
 *     - 'http://myserver/mypath/myField.gif'     = path + fieldName +  onSuffix + format
 *     - 'http://myserver/mypath/myField_s.gif'   = path + fieldName + offSuffix + format
 *   must exist and be accessible from the web.
 *
 *
 * 2) then for each field,
 *   <A HREF="whatever.html"
 *     onMouseOver = "return ih.  select ('myField');"
 *     onMouseOut  = "return ih.unselect ('myField');">
 *     <IMG 
 *       NAME   = "myField"                                 // watch out ! this is the field name !
 *       ALT    = "my field"
 *       BORDER = "0"
 *       SRC    = "./pics/mf.gif"
 *       WIDTH  = "100"
 *       HEIGHT = "100" >
 *   </A>
 */





  /**
   * Constructs and returns a new ImageHandler object.
   * all variables are set to the following default values :
   *   - imagesPath      : "./"
   *   - imagesFormat    : ".gif"
   *   - imagesOnSuffix  : "_s";
   *   - imagesOffSuffix : "";
   *
   * Always returns the newly created ImageHandler.
   */
  function createImageHandler ( ) {
    ih = new Object ();

    // -- OBJECT VARIABLES
    ih.path               = "./";    // default value for URL to image folder
    ih.format             = ".gif";  // default images format 
    ih.onSuffix           = "_s";    // default "on mouse over" image name suffix
    ih.offSuffix          = "";      // default "on mouse out" image name suffix

    ih.dynamicImage       = "menu.php?text=" // default dynamic image producer
    ih.dynamicOnSuffix    = "&on=true";  // default "on mouse over" dynamic image suffix
    ih.dynamicOffSuffix   = "&on=false"; // default "on mouse over" dynamic image suffix

    ih.ON                 = "asdfas";   // *script* suffix for "on mouse over" image name
    ih.OFF                = "fubasd";   // *script* suffix for "on mouse out" image name

    // -- OBJECT METHODS 
    ih.setImagesPath      = imageHandler_setImagesPath;
    ih.setImagesFormat    = imageHandler_setImagesFormat;
    ih.setImagesOnSuffix  = imageHandler_setImagesOnSuffix;
    ih.setImagesOffSuffix = imageHandler_setImagesOffSuffix;
    ih.setDynamicImage    = imageHandler_setDynamicImage;
    ih.setDynamicImagesOnSuffix  = imageHandler_setDynamicImagesOnSuffix;
    ih.setDynamicImagesOffSuffix = imageHandler_setDynamicImagesOffSuffix;
    ih.select             = imageHandler_select;
    ih.unselect           = imageHandler_unselect;
    ih.loadImage          = imageHandler_loadImage;
    ih.loadImageArray     = imageHandler_loadImageArray;
    ih.loadDynamicImage   = imageHandler_loadDynamicImage;

    return ih;
  }

  /**
   * Set the URL of image folder where all images :
   *   - path + field + onSuffix  + format
   *   - path + field + offSuffix + format
   * are available from the web, for each 'field'.
   *
   * Always returns 'true'
   */
  function imageHandler_setImagesPath ( imgPath ) {
    path = imgPath;
    return true;
  }

  /**
   * Set format of the images.
   * Will most probably be one of : 
   * ".gif", ".jpg", ".jpeg", ".png"
   * 
   * Note that, for each 'field', files :
   *   - path + field + onSuffix  + format
   *   - path + field + offSuffix + format
   * must be accessible from the web.
   *
   * Always returns 'true'
   */
  function imageHandler_setImagesFormat ( imgFormat ) {
    format = imgFormat;
    return true;
  }

  /**
   * Sets the image suffix for selected images.
   * Note that, for each 'field', file :
   *   - path + field + onSuffix + format
   * must be accessible from the web.
   * 
   * Always returns 'true'.
   */
  function imageHandler_setImagesOnSuffix ( imgSuffix ) {
    onSuffix = imgSuffix;
    return true;
  }

  /**
   * Sets the image suffix for unselected images.
   * Note that, for each 'field', file :
   *   - path + field + offSuffix + format
   * must be accessible from the web.
   * 
   * Always returns 'true'.
   */
  function imageHandler_setImagesOffSuffix ( imgSuffix ) {
    offSuffix = imgSuffix;
    return true;
  }

  /**
   * Set the name of the dynamic script that generates the images.
   * Note that, for each 'field', file :
   *   - path + dynamicImage + field + dynamic*Suffix
   * must be accessible from the web.
   *
   * Always returns 'true'.
   */
  function imageHandler_setDynamicImage ( image ) {
    dynamicImage = image;
    return true;
  }

  /**
   * Sets dynamic image suffix for selected images.
   * Note that, for each 'field', file :
   *   - path + dynamicImage + field + dynamicOnSuffix
   * must be accessible from the web.
   * 
   * Always returns 'true'.
   */
  function imageHandler_setDynamicImagesOnSuffix ( imgSuffix ) {
    dynamicOnSuffix = imgSuffix;
    return true;
  }

  /**
   * Sets dynamic image suffix for unselected images.
   * Note that, for each 'field', file :
   *   - path + dynamicImage + field + dynamicOffSuffix
   * must be accessible from the web.
   * 
   * Always returns 'true'.
   */
  function imageHandler_setDynamicImagesOffSuffix ( imgSuffix ) {
    dynamicOffSuffix = imgSuffix;
    return true;
  }







  /**
   * Loads the necessary images for the field 
   * provided as a parameter to this function.
   *
   * Note that the following images must be 
   * accessible from the web :
   *   - path + field + onSuffix  + format
   *   - path + field + offSuffix + format
   *
   * Only call this function after setting all 
   * other parameters (path, format, suffixes).
   * 
   * Always returns 'true'.
   */
  function imageHandler_loadImage ( field ) {
    document[field + this.ON ] = createImage (path + field + onSuffix  + format);
    document[field + this.OFF] = createImage (path + field + offSuffix + format);
    return true;
  }


  /**
   * Loads the necessary images for the fields 
   * provided as a coma separated list, eg.
   * ['field1', 'field2', 'field3'].
   *
   * Note that the following images must be 
   * accessible from the web :
   *   - path + field + onSuffix  + format
   *   - path + field + offSuffix + format
   * and that for each 'field' in the list.
   *
   * Only call this function after setting all 
   * other parameters (path, format, suffixes).
   * 
   * Always returns 'true'.
   */
  function imageHandler_loadImageArray ( fields ) {
    for ( index = 0;
	  index < fields.length;
          index ++ ) {
      loadImage(fields[index]);
    }
    return true;
  }


  /**
   * Loads the necessary images for the field 
   * provided as a parameter to this function.
   *
   * Note that the following images must be 
   * accessible from the web :
   *   - path + dynamicImage + field + dynamicOnSuffix
   *   - path + dynamicImage + field + dynamicOffSuffix
   *
   * Only call this function after setting all 
   * other parameters (path, dynamicImage, suffixes).
   * 
   * Always returns 'true'.
   */
  function imageHandler_loadDynamicImage ( field ) {
    document[field + this.ON ] = createImage (path + dynamicImage + field + dynamicOnSuffix );
    document[field + this.OFF] = createImage (path + dynamicImage + field + dynamicOffSuffix);
    return true;
  }


  /**
   * Sets the 'document.field' image to the 
   * selected image version.
   * 
   * Always returns 'true'.
   */
  function imageHandler_select ( field ) {
    setImageSource ( field, field + this.ON );
    return true;
  }


  /**
   * Sets the 'document.field' image to the 
   * unselected image version.
   * 
   * Always returns 'true'.
   */
  function imageHandler_unselect ( field ) {
    setImageSource ( field, field + this.OFF );
    return true;
  }


  /**
   * Creates and returns a new image that will 
   * will display the contents of the 'source' 
   * file.
   * 
   * Returns the created image.
   */
  function createImage ( source ) {
      img     = new Image ();
      img.src = source;
      return img;
  }


  /**
   * Checks if : 
   *   - document[from], 
   *   - document[from].src and 
   *   - document[to]
   * exist, in which case, it sets 
   * document[to].src to document[from].src, 
   * that is, if document[to] is an image, 
   * then it will now show the same as 
   * document[from].
   * 
   * Returns 'true' if the source could be changed, 
   * returns 'false' else.
   */
  function setImageSource ( to, from ) {
    if ( document[to]       != null  &&
         document[from]     != null  &&
         document[from].src != null ) {
      document[to].src = document[from].src;
      return true;
    }
    return false;
  }