/*
    * Copyright (c) 2003-2008 by Cosylab d. d.
    *
    * This file is part of CosyBeans-Common.
    *
    * CosyBeans-Common is free software: you can redistribute it and/or modify
    * it under the terms of the GNU General Public License as published by
    * the Free Software Foundation, either version 3 of the License, or
    * (at your option) any later version.
   *
   * CosyBeans-Common is distributed in the hope that it will be useful,
   * but WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   * GNU General Public License for more details.
   *
   * You should have received a copy of the GNU General Public License
   * along with CosyBeans-Common.  If not, see <http://www.gnu.org/licenses/>.
   */
  
  package com.cosylab.gui.components.ledder;
  
  import java.awt.Color;
  
  import java.beans.PropertyChangeListener;
  import java.beans.PropertyChangeSupport;
  
  import java.io.Serializable;
  
  
  /**
   * This is generic class providing access to the <code>BitDescriptor</code>. In
   * most cases this implementation should provide all neccessary access to the
   * model. This class is designed for convenient access and minimal overhead.
   *
   * @author <a href="mailto:ales.pucelj@cosylab.com">Ales Pucelj</a>
   * @version $id$
   */
  public class BitmaskField implements Serializable
  {
  	// Model holding individual led information.
  	private BitDescriptor bitDescriptor;
  
  	// Value holding the mask value
  	private long mask = 0;
  
  	// Value holding the bit pattern.
  	private long bits = 0;
  
  	// When used as mask, the mask will be ignored completely.
  
  	/** DOCUMENT ME! */
  	public static final int IGNORE_MASK = -1;
  
  	// Cache variable used when calling getBitCount to prevent unnecessary mask
  	// parsing. Negative value indicates that mask will be parsed on next call, 
  	// nonnegative indicates valid bit count.
  	private transient int lastBitCount = -1;
  
  	// Support class to handle firing of property change events.
  	private final PropertyChangeSupport changes = new PropertyChangeSupport(this);
  
  	/**
  	 * Default constructor for BitmaskField.
  	 */
  	public BitmaskField()
  	{
  		this(null);
  	}
  
  	/**
  	 * Constructor for BitmaskField that also initialized the values to the
  	 * specified model.
  	 *
  	 * @param ledModel BitDescriptor Initial model to use.
  	 */
  	public BitmaskField(BitDescriptor ledModel)
  	{
  		super();
  		setBitDescriptor(ledModel);
  	}
  
  	/**
  	 * Creates default model. Override this method to create a different
  	 * implementation of BitDescriptor by default. This method will be called
  	 * whenever it is neccessary to create a new model ensuring the model
  	 * always exists.
  	 *
  	 * @return BitDescriptor
  	 */
  	protected BitDescriptor createDefaultModel()
  	{
  		return new DefaultBitDescriptor();
  	}
  
  	/**
  	 * Returns current model used to represent the bit values.
  	 *
  	 * @return BitDescriptor
  	 */
 	public BitDescriptor getBitDescriptor()
 	{
 		if (bitDescriptor == null) {
 			bitDescriptor = new DefaultBitDescriptor();
 		}
 
 		return bitDescriptor;
 	}
 
 	/**
 	 * DOCUMENT ME!
 	 *
 	 * @return
 	 */
 	private int size()
 	{
 		long tmpMask = getMask();
 		int size = 0;
 		boolean done = false;
 
 		while (!done) {
 			if (tmpMask % 2 == 1) {
 				size++;
 			}
 
 			tmpMask = tmpMask >> 1;
 
 			if (tmpMask == 0) {
 				done = true;
 			}
 		}
 
 		return size;
 	}
 
 	/**
 	 * Sets the model to represent bit values. If the new model is null,
 	 * default model will be used as created by
 	 * <code>createDefaultModel()</code>  method. Also, setting the same
 	 * instance of the model multiple times will not  cause any change to
 	 * occur. If the new model is null, a new instance of model will be
 	 * created using <code>createDefaultModel()</code> method.
 	 *
 	 * @param newModel BitDescriptor
 	 */
 	public void setBitDescriptor(BitDescriptor newModel)
 	{
 		if (bitDescriptor == newModel) {
 			return;
 		}
 
 		BitDescriptor oldValue = bitDescriptor;
 
 		// Remove the listener from the old model.
 		if (oldValue != null) {
 			//TODO	oldValue.removeLedModelListener(ledModelListener);
 		}
 
 		bitDescriptor = newModel;
 
 		// Ensure the new model is not null.
 		if (bitDescriptor == null) {
 			bitDescriptor = createDefaultModel();
 		}
 
 		// Register listener on the new model.
 		//TODO bitDescriptor.addLedModelListener(ledModelListener);
 		changes.firePropertyChange("model", oldValue, newModel);
 	}
 
 	/**
 	 * Returns number of bits defined by mask. Counts each bit in mask and
 	 * increases the counter for each value of 1.
 	 * 
 	 * <p>
 	 * If the mask is defined as 0010110111, getBitCount returns 6.
 	 * </p>
 	 * 
 	 * <p>
 	 * Always returns non-negative integer.
 	 * </p>
 	 * 
 	 * <p>
 	 * This method may be used to discover the number of leds to display. If
 	 * the mask is not defined, the return value will be the number of leds in
 	 * the model. Value of leds is cached to avoid calculation each time the
 	 * method is called and will be changed whenever the model changes.
 	 * </p>
 	 *
 	 * @return int Number of leds
 	 */
 	public int getBitCount()
 	{
 		//			if (lastBitCount >= 0) {
 		//			return lastBitCount;
 		//		}
 		if (mask == IGNORE_MASK) {
 			// We ignore the mask and return number of elements in the model.
 			lastBitCount = size();
 		} else {
 			synchronized (this) {
 				long m = mask;
 
 				// Scan the mask bitwise and increment the counter for each bit
 				// value of 1 encountered.
 				while (m > 0) {
 					lastBitCount += m & 1;
 					m >>= 1;
 				}
 
 				lastBitCount = size();
 			}
 		}
 
 		return lastBitCount;
 	}
 
 	/**
 	 * Resets the cache for the <code>getBitCount()</code> method. This should
 	 * be called whenever the number of leds changes.
 	 */
 	protected final void flushBitCount()
 	{
 		lastBitCount = -1;
 	}
 
 	/**
 	 * Sets the new bit pattern. To avoid unneccesary updates, the property
 	 * change event will only be fired if the actual value has changed.
 	 *
 	 * @param value long New bit pattern.
 	 */
 	public void setBits(long value)
 	{
 		if (bits == value) {
 			return;
 		}
 
 		long oldValue = bits;
 
 		bits = value;
 
 		firePropertyChange("bits", oldValue, value);
 	}
 
 	/**
 	 * Returns the bit pattern currently set.
 	 *
 	 * @return long Bit pattern.
 	 */
 	public long getBits()
 	{
 		return bits;
 	}
 
 	/**
 	 * Sets the mask to use. This may be bitwise specification of which bits in
 	 * the bit pattern are valid or IGNORE_MASK constant. In the latter case
 	 * mask parameter will be ignored entirely.
 	 *
 	 * @param value long New mask.
 	 */
 	public void setMask(long value)
 	{
 		if (mask == value) {
 			return;
 		}
 
 		long oldValue = mask;
 
 		mask = value;
 
 		flushBitCount();
 
 		firePropertyChange("mask", oldValue, value);
 	}
 
 	/**
 	 * Returns the mask. The return value will be bitwise pattern indicating
 	 * active bits or IGNORE_MASK constant.
 	 *
 	 * @return long Current mask.
 	 */
 	public long getMask()
 	{
 		return mask;
 	}
 
 	/**
 	 * Returns array containing descriptions for the leds. This is a
 	 * convenience method. To avoid creation of new String array, query the
 	 * BitDescriptor  directly.
 	 *
 	 * @return String[] Descriptions of the leds.
 	 */
 	public String[] getDescriptions()
 	{
 		synchronized (this) {
 			BitDescriptor lm = getBitDescriptor();
 
 			final String[] descriptions = new String[size()];
 
 			for (int i = 0; i < size(); i++) {
 				descriptions[i] = lm.getDescription(i);
 			}
 
 			return descriptions;
 		}
 	}
 
 	/**
 	 * Returns array of colors to be used for rendering the individual led's ON
 	 * state. This is a convenience method. To avoid creation of new Color
 	 * array, query the BitDescriptor directly.
 	 *
 	 * @return Color[] Colors indicating the ON state.
 	 */
 	public Color[] getColorsWhenOn()
 	{
 		synchronized (this) {
 			BitDescriptor lm = getBitDescriptor();
 
 			Color[] colors = new Color[size()];
 
 			for (int i = 0; i < size(); i++) {
 				colors[i] = lm.getColorWhenOn(i);
 			}
 
 			return colors;
 		}
 	}
 
 	/**
 	 * Returns array of colors to be used for rendering the individual led's
 	 * OFF state. This is a convenience method. To avoid creation of new Color
 	 * array, query the BitDescriptor directly.
 	 *
 	 * @return Color[] Colors indicating the OFF state.
 	 */
 	public Color[] getColorsWhenOff()
 	{
 		synchronized (this) {
 			BitDescriptor lm = getBitDescriptor();
 
 			Color[] colors = new Color[size()];
 
 			for (int i = 0; i < size(); i++) {
 				colors[i] = lm.getColorWhenOff(i);
 			}
 
 			return colors;
 		}
 	}
 
 	/**
 	 * Returns array of colors corresponding to current state of bit pattern.
 	 * This is a convenience method. To avoid creation of new Color array,
 	 * query the BitDescriptor directly.
 	 *
 	 * @return Color[]
 	 */
 	public Color[] toColor()
 	{
 		int i = 0;
 		long m = mask;
 		long v = bits;
 
 		int n = getBitCount();
 		final Color[] colors = new Color[n];
 
 		synchronized (this) {
 			final BitDescriptor lm = getBitDescriptor();
 
 			while (m > 0) {
 				if ((m & 1) == 1) {
 					colors[i++] = ((v & 1) == 1) ? lm.getColorWhenOn(i)
 						: lm.getColorWhenOff(i);
 				}
 
 				m >>= 1;
 				v >>= 1;
 			}
 		}
 
 		return colors;
 	}
 
 	/**
 	 * Returns bit pattern by ignoring all zeros in the mask. If mask is set to
 	 * IGNORE_MASK, return value is equal to bits parameter.
 	 * 
 	 * <p>
 	 * Example: <br>
 	 * <code> mask = XX10101 bits = XX10010 getCompactValue() = XXXXX100
 	 * </code>
 	 * </p>
 	 *
 	 * @return long Compact representation of the bit pattern.
 	 */
 	public long getCompactValue()
 	{
 		if (mask == IGNORE_MASK) {
 			return bits;
 		}
 
 		long m = mask;
 		long v = bits;
 		long vi = 0;
 		long newBits = 0;
 
 		while (m > 0) {
 			if ((m & 1) == 1) {
 				newBits += ((v & 1) << vi++);
 			}
 
 			m >>= 1;
 			v >>= 1;
 		}
 
 		return newBits;
 	}
 
 	/**
 	 * Convenience method that fires property change event with long
 	 * parameters. To avoid unneccesary creation of <code>Long</code> objects
 	 * the event is only fired if any listeners have been registered.
 	 *
 	 * @param property String
 	 * @param old long
 	 * @param now long
 	 */
 	protected void firePropertyChange(String property, long old, long now)
 	{
 		if (changes.hasListeners(property)) {
 			changes.firePropertyChange(property, new Long(old), new Long(now));
 		}
 	}
 
 	/**
 	 * Adds property change listener.
 	 *
 	 * @param listener PropertyChangeListener
 	 */
 	public void addPropertyChangeListener(PropertyChangeListener listener)
 	{
 		changes.addPropertyChangeListener(listener);
 	}
 
 	/**
 	 * Removes property change listener.
 	 *
 	 * @param listener PropertyChangeListener
 	 */
 	public void removePropertyChangeListener(PropertyChangeListener listener)
 	{
 		changes.removePropertyChangeListener(listener);
 	}
 }
 
 /* __oOo__ */