/*
 * File    : TableCell.java
 * Created : 29 nov. 2003
 * By      : Olivier
 * Adapted to MyTorrents by TuxPaper 2004/02/16
 *
 * Azureus - a Java Bittorrent client
 *
 * This program 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 2 of the License.
 *
 * This program 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 ( see the LICENSE file ).
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */
 
package org.gudy.azureus2.plugins.ui.tables;

import org.gudy.azureus2.plugins.ui.Graphic;

/** This interface provides access to an Azureus table cell.
 *
 * @see TableManager
 *
 * @author Oliver (Original PeerTableItem Code)
 * @author TuxPaper (Generic-izing)
 *
 * @since 2.0.8.5
 */
// Modified from MyTorrentsTableItem/PeerTableItem
public interface TableCell {
  
  /** Retrieve the data object associated with the current table row and cell.
   * The results of this method MUST NOT BE CACHED.
   * The link between a table cell and a DataSource is not persistent and can 
   * change from call to call (for example when the table is re-ordered, the 
   * link may be modified)
   *
   * @return The return type is dependent upon which table the cell is for:<br>
   *   TABLE_MYTORRENTS_*: {@link org.gudy.azureus2.plugins.download.Download}
   *                       object for the current row<br>
   *   TABLE_TORRENT_PEERS: {@link org.gudy.azureus2.plugins.peers.Peer} 
   *                        object for the current row<br>
   *   TABLE_TORRENT_FILES: {@link org.gudy.azureus2.plugins.disk.DiskManagerFileInfo}
   *                        object for the current row<br>
   *   TABLE_MYTRACKER: {@link org.gudy.azureus2.plugins.tracker.TrackerTorrent}
   *                    object for the current row<br>
   *   TABLE_MYSHARES: {@link org.gudy.azureus2.plugins.sharing.ShareResource}
   *                    object for the current row<br>
   *   remaining TABLE_* constants: undefined or null<br>
   */
  Object getDataSource();
  
  /** Retreive the TableColumn that this cell belongs to
   *
   * @return this cell's TableColumn
   */
  TableColumn getTableColumn();
  
  /** Retrieve the TableRow that this cell belongs to
   *
   * @return this cell's TableRow
   */
  TableRow getTableRow();
  
  /** Returns which table the cell is being displayed in.
   *
   * @return {@link TableManager}.TABLE_* constant
   */
  String getTableID();
  
  /**
   * This method is called to set the cell's text.
   * Caching is done, so that if same text is used several times,
   * there won't be any 'flickering' effect. Ie the text is only updated if
   * it's different from current value.
   * <p>
   * This function must be called from the same thread that the GUI is running
   * under.  Listeners like {@link TableCellAddedListener} do not always get
   * called on the GUI thread.
   * <p>
   * If you wish to set the text and not worry about changing to the GUI thread,
   * use {@link #invalidate()}, and set the text in the 
   * {@link TableCellRefreshListener}
   *
   * @param text the text to be set
   * @return True - the text was updated.<br>
   *         False - the text was the same and not modified.
   */
  boolean setText(String text);

  /** Retrieve the Cell's text
   *
   * @return Cell's text
   */
  String getText();

  /** Change the cell's foreground color.
   * <p>
   * pass -1 to return color back to default
   *
   * @param red red value (0 - 255)
   * @param green green value (0 - 255)
   * @param blue blue value (0 - 255)
   * @return True - Color changed. <br>
   *         False - Color was already set.
   */
  boolean setForeground(int red, int green, int blue);

  /**
   * Change the cell's foreground color
   * 
   * @param rgb int array containing red, green, and blue values, respectively.
   *            null to return color back to default
   * @return
   *
   * @since 3.0.4.3
   */
  boolean setForeground(int[] rgb);
  
  /**
   * Change the cell's foreground color to the user's defined "error" color.
   * 
   * @since 3.0.3.5
   * @return True - Color changed. <br>
   *         False - Color was already set.
   */
  boolean setForegroundToErrorColor();
  
  /**
   * Get the foreground color of the cell
   * 
   * @return array containing red, green, and blue color
   * 
   * @since 2.5.0.1
   */
  int[] getForeground();

	/**
	 * Get the background color of the cell
	 * 
	 * @return array containing red, green, and blue color.  Might be null
	 *
	 * @since 3.0.3.5
	 */
	int[] getBackground();
	  
  /** Sets a Comparable object that column sorting will act on.  If you never 
   * call setSortValue, your column will be sorted by the cell's text.
   *
   * @param valueToSort the object that will be used when the column cell's
   *                    are compared to each other
   * @return True - Sort Value changed. <br>
   *         False - Sort Value was already set to object supplied.
   */
  public boolean setSortValue(Comparable valueToSort);

  /** Sets a long value that the column sorting will act on. 
   *
   * @param valueToSort sorting value.
   * @return True - Sort Value changed. <br>
   *         False - Sort Value was already set to value supplied.
   */
  public boolean setSortValue(long valueToSort);
  
  /**
   * Sets a float value that the column sorting will act upon.
   * @param valueToSort float sort value
   * @return true if sort value changed, or false if sort value already set to value supplied
   */
  public boolean setSortValue( float valueToSort );
  

  /** Retrieves the sorting value
   *
   * @return Object that will be sorted on
   */
  public Comparable getSortValue();

  /** Determines if the user has chosen to display the cell
   *
   * @return True - User has chosen to display cell
   */
  boolean isShown();

  /** Validility of the cell's text.
   *
   * @return True - Text is the same as last call.  You do not need to update
   *                unless you have new text to display. <br>
   *         False - Cell-to-Datasource link has changed, and the text is
   *                 definitely not valid.
   */
  boolean isValid();

  /** Sets the cell to invalid. This will result in a refresh on the next 
   * scheduled interval.
   *
   * @since 2.3.0.7
   */
  public void invalidate();

  /**
   * Set the cell's tooltip display.
   * 
   * 
   * @param tooltip Object to display.  Currently, only String is supported
   * 
   * @see #addToolTipListener(TableCellToolTipListener)
   * @since 2.1.0.2
   */
  public void setToolTip(Object tooltip);
  /**
   * Retrieve the tooltip object assigned to this cell
   * 
   * @return tooltip object
   * 
   * @see #addToolTipListener(TableCellToolTipListener)
   * @since 2.1.0.2
   */
  public Object getToolTip();

  
  /**
   * Retrieve whether the cell has been disposed.  This will return true after
   * the {@link TableCellDisposeListener} is triggered.
   * 
   * @return disposal state
   * @since 2.3.0.7
   */
  public boolean isDisposed();
  
  /**
   * Retrieves the number of lines available for setting text
   * 
   * @return # of lines available, -1 if unknown
   *
   * @since 3.0.1.1
   */
  public int getMaxLines();

  //////////////////////////////////
  // Start TYPE_GRAPHIC functions //
  //////////////////////////////////

  /** Retrieve the width of the cell's drawing area (excluding any margin) for
   * TableColumn objects of TYPE_GRAPHIC only.
   *
   * @return if you are filling the cell, this is the width your image should be
   */
  public int getWidth();

  /** Retrieve the height of the cell's drawing area (excluding any margin) for
   * TableColumn objects of TYPE_GRAPHIC only.
   *
   * @return if you are filling the cell, this is the height your image should be
   */
  public int getHeight();
  
  /** Sets the image to be drawn.
   * <p>
   * From 3.0.1.1, setting the graphic to the same Graphic object will not
   * redraw the image.  You need to {@link #invalidate()} the cell if you
   * know the image bits have changed (or you could pass a new Graphic object
   * in each time a new image is generated)
   * <p>  
   * Previously, setting the graphic to the same object resulted in a repaint.
   * Plugins were naughty and would do this on every refresh, causing horrible
   * repaint slowdowns.
   *
   * @param img image to be stored & drawn
   * @return true - image was changed.<br>
   *         false = image was the same
   */
  public boolean setGraphic(Graphic img);

  /** Retrieve the SWT graphic related to this table item for
   * TableColumn objects of TYPE_GRAPHIC only.
   *
   * @return the Image that is draw in the cell, or null if there is none.
   */
  public Graphic getGraphic();
  
  /** TODO:
  /** Sets the image to be drawn to the file specified for
   * TableColumn objects of TYPE_GRAPHIC only.
   * 
   * @param imageLocation URI of image
   * @return true - image was changed.<br>
   *         false = image was the same
   *
  public boolean setGraphic(String imageLocation);
  */

  
  /** Sets whether the graphic fills the whole cell for
   * TableColumn objects of TYPE_GRAPHIC only. This may effect how often
   * a refresh of the cell is needed, and effects alignment.
   *
   * @param bFillCell true - the whole cell is filled by the graphic
   */
  public void setFillCell(boolean bFillCell);

	/**
	 * @return
	 *
	 * @since 3.0.5.3
	 */
	int getMarginHeight();

  /**
   * Specifies the number of pixels of vertical margin that will
   * be placed along the top and bottom edges of the layout for
   * TableColumn objects of TYPE_GRAPHIC only.
   * <p>
   * The default is 1.
   *
   * @param height new margin height
   */
  public void setMarginHeight(int height);

	/**
	 * @return
	 *
	 * @since 3.0.5.3
	 */
	int getMarginWidth();

  /**
   * Specifies the number of pixels of horizontal margin that will
   * be placed along the left and right edges of the layout for
   * TableColumn object of TYPE_GRAPHIC only.
   * <p>
   * The default is 1.
   *
   * @param width new margin width
   */
  public void setMarginWidth(int width);
  
  // End TYPE_GRAPHIC functions
  
  /** Adds a listener that triggers when the TableCell needs refreshing
   *
   * @param listener Listener Object to be called when refresh is needed.
   */
  public void addRefreshListener(TableCellRefreshListener listener);
  /** Remove a previously added TableCellRefreshListener
   *
   * @param listener Previously added listener
   */
  public void removeRefreshListener(TableCellRefreshListener listener);

  /** Adds a listener that triggers when the TableCell has been disposed
   *
   * @param listener listener object to be called
   */
  public void addDisposeListener(TableCellDisposeListener listener);
  /** Remove a previously added TableCellDisposeListener
   *
   * @param listener Previously added listener
   */
  public void removeDisposeListener(TableCellDisposeListener listener);

  /** Adds a listener related to tooltip actions
   *
   * @param listener listener object to be called
   */
  public void addToolTipListener(TableCellToolTipListener listener);
  /** Remove a previously added TableCellToolTipListener
   *
   * @param listener Previously added listener
   */
  public void removeToolTipListener(TableCellToolTipListener listener);
  
  /**
   * Adds a listener that triggers when a TableCell that belongs to this column
   * has a mouse event.
   * 
   * @param listener
   * 
   * @since 2.3.0.7
   */
  public void addMouseListener(TableCellMouseListener listener);
  /** Remove a previously added TableCellMouseListener
  *
  * @param listener Previously added listener
   * @since 2.3.0.7
  */
  public void removeMouseListener(TableCellMouseListener listener);
  
  /**
   * A listener is added for every type of cell listener the supplied object 
   * implements
   *  
   * @param listenerObject Object implementing some cell listeneters
   */
  public void addListeners(Object listenerObject);

  /**
   * Returns a Graphic of what's behind the cell  
   * 
   * @return
   *
   * @since 3.0.3.5
   */
  public Graphic getBackgroundGraphic();

	/**
	 * Return the position of the mouse relative to the cell.
	 *  
	 * @return array of 2 containing x and y position position relative to cell. 
	 * 				null if cell doesn't have mouse.
	 *
	 * @since 3.0.4.3
	 */
	public int[] getMouseOffset();

	/**
	 * Returns text that's meant for the clipboard
	 * 
	 * @since 4.3.1.5
	 */
	public String getClipboardText();
}
