/*
 * @(#)HTable.java    2.5.0   16 May 2006
 *
 * Copyright 2006
 * College of Computer and Information Science
 * Northeastern University
 * Boston, MA  02115
 *
 * The Java Power Tools software may be used for educational
 * purposes as long as this copyright notice is retained intact
 * at the top of all source files.
 *
 * To discuss possible commercial use of this software, 
 * contact Richard Rasala at Northeastern University, 
 * College of Computer and Information Science,
 * 617-373-2462 or rasala@ccs.neu.edu.
 *
 * The Java Power Tools software has been designed and built
 * in collaboration with Viera Proulx and Jeff Raab.
 *
 * Should this software be modified, the words "Modified from 
 * Original" must be included as a comment below this notice.
 *
 * All publication rights are retained.  This software or its 
 * documentation may not be published in any media either
 * in whole or in part without explicit permission.
 *
 * This software was created with support from Northeastern 
 * University and from NSF grant DUE-9950829.
 */

package edu.neu.ccs.gui;

import edu.neu.ccs.util.*;

import java.awt.*;
import javax.swing.*;

/**
 * <p>Class <code>HTable</code> extends <code>TablePanel</code>
 * to constrain the table to be <code>HORIZONTAL</code>, that is,
 * to have just one column.</p>
 * 
 * <p>The <a href="http://www-cs-faculty.stanford.edu/~eroberts/jtf/"><i>ACM Java Task Force</i></a>
 * introduced classes <code>TableLayout</code> and <code>TablePanel</code>
 * that resemble the corresponding JPT classes to a certain degree.
 * The <i>ACM Java Task Force</i> also introduced simple derived
 * classes of <code>TablePanel</code> called <code>HPanel</code> and
 * <code>VPanel</code> to specialize for the situation of one row or
 * one column.  Since this seemed to be a good idea, we introduced
 * similar derived classes into JPT as of 2.5.0 but used the names
 * <code>HTable</code> and <code>VTable</code>.  The implementation
 * of the JPT classes is independent of that of the
 * <i>ACM Java Task Force</i> classes.</p>
 *  
 * @author  Richard Rasala
 * @version 2.5.0
 * @since   2.5.0
 */
public class HTable
    extends TablePanel
{
    
    /** The IllegalArgumentException error message. */
    private final String errormessage =
        "In HTable.addObject, the row argument must be zero";
    
    
    /**
     * Constructs a default horizontal table panel.
     */
    public HTable() {
        super.setOrientation(HORIZONTAL);
    }
    
    
    /**
     * Constructs a horizontal table panel with 
     * the given number of columns.
     *
     * @param cols the number of columns in the table
     */
    public HTable(int cols) {
        super(1, cols);
        super.setOrientation(HORIZONTAL);
    }
    
    
    /**
     * Constructs a horizontal table panel with
     * the given number of columns
     * and the given cell alignment.
     *
     * @param cols the number of columns in the table
     * @param align the alignment of a component within a table cell
     */
    public HTable(int cols, int align) {
        super(1, cols, align);
        super.setOrientation(HORIZONTAL);
    }
    
    
    /**
     * <p>Constructs a horizontal table panel with
     * the given number of columns
     * and the given horizontal and vertical gaps between cells.<p>
     * 
     * <p>Although the <code>vgap</code> parameter does not affect
     * the internals of the table since there is only one row,
     * it is used by the method <code>autoEmptyBorder</code> that
     * is inherited from <code>TablePanel</code>.</p>
     *
     * @param cols the number of columns in the table
     * @param hgap the horizontal gap between rows
     * @param vgap the vertical gap between cols
     */
    public HTable(int cols, int hgap, int vgap) {
        super(1, cols, hgap, vgap);
        super.setOrientation(HORIZONTAL);
    }
    
    
    /**
     * <p>Constructs a horizontal table panel with
     * the given number of columns,
     * the given horizontal and vertical gaps between cells,
     * and the given cell alignment.</p>
     *
     * <p>Although the <code>vgap</code> parameter does not affect
     * the internals of the table since there is only one row,
     * it is used by the method <code>autoEmptyBorder</code> that
     * is inherited from <code>TablePanel</code>.</p>
     *
     * @param cols the number of columns in the table
     * @param hgap the horizontal gap between rows
     * @param vgap the vertical gap between cols
     * @param align the alignment of a component within a table cell
     */
    public HTable(int cols, int hgap, int vgap, int align) {
        super(1, cols, hgap, vgap, align);
        super.setOrientation(HORIZONTAL);
    }
    
    
    /**
     * Constructs a horizontal table panel
     * containing the given objects.
     *
     * @param contents the array of contents to be used to fill the table
     */
    public HTable(Object[] contents) {
        super(contents, HORIZONTAL);
    }
    
    
    /**
     * Constructs a horizontal table panel
     * containing the given objects
     * with the given cell alignment.
     *
     * @param contents the array of contents to be used to fill the table
     * @param align the alignment of a component within a table cell
     */
    public HTable(Object[] contents, int align) {
        super(contents, HORIZONTAL, align);
    }
    
    
    /**
     * <p>Constructs a horizontal table panel
     * containing the given objects
     * with the given horizontal and vertical gaps between cells.</p>
     *
     * <p>Although the <code>vgap</code> parameter does not affect
     * the internals of the table since there is only one row,
     * it is used by the method <code>autoEmptyBorder</code> that
     * is inherited from <code>TablePanel</code>.</p>
     *
     * @param contents the array of contents to be used to fill the table
     * @param hgap the horizontal gap between rows
     * @param vgap the vertical gap between cols
     */
    public HTable(Object[] contents, int hgap, int vgap) {
        super(contents, HORIZONTAL, hgap, vgap);
    }
    
    
    /**
     * <p>Constructs a horizontal table panel
     * containing the given objects
     * with the given horizontal and vertical gaps between cells
     * and the given cell alignment.
     *
     * <p>Although the <code>vgap</code> parameter does not affect
     * the internals of the table since there is only one row,
     * it is used by the method <code>autoEmptyBorder</code> that
     * is inherited from <code>TablePanel</code>.</p>
     *
     * @param contents the array of contents to be used to fill the table
     * @param hgap the horizontal gap between rows
     * @param vgap the vertical gap between cols
     * @param align the alignment of a component within a table cell
     */
    public HTable(Object[] contents, int hgap, int vgap, int align) {
        super(contents, HORIZONTAL, hgap, vgap, align);
    }
    
    
    /**
     * <p>Add the given object to this <CODE>HTable</CODE>
     * at the position specified by the col
     * after applying the transformation of the method
     * <CODE>makeComponent</CODE>.</p>
     *
     * <p>If a component is already installed at the given position,
     * then this component is removed.</p>
     *
     * @param object the object to be transformed and added to the table
     * @param col the column in the table
     * @return the component obtained by transforming the object
     */
    public Component addObject(Object object, int col) {
        return super.addObject
            (object, new CellPosition(0, col));
    }
    
    
    /**
     * <p>Calls the inherited method from <code>TablePanel</code>
     * provided that the <code>row</code> argument is zero.</p>
     * 
     * <p>Otherwise throws <code>IllegalArgumentException</code>.</p>
     * 
     * @param object the object to be transformed and added to the table
     * @param row the row in the table which must be zero
     * @param col the column in the table
     * @return the component obtained by transforming the object
     */
    public Component addObject(Object object, int row, int col) {
        if (row == 0)
            return super.addObject
                (object, new CellPosition(0, col));
        
        throw new IllegalArgumentException(errormessage);
    }
    
    
    /**
     * <p>Calls the inherited method from <code>TablePanel</code>
     * provided that the <code>position</code> argument is either
     * <code>null</code> or has its <code>row</code> set to zero.</p>
     * 
     * <p>Otherwise throws <code>IllegalArgumentException</code>.</p>
     * 
     * @param object the object to be transformed and added to the table
     * @param position the position in the table
     * @return the component obtained by transforming the object
     */
    public Component addObject(Object object, CellPosition position) {
        if ((position == null) || (position.row == 0))
            return super.addObject(object, position);
        
        throw new IllegalArgumentException(errormessage);
    }
    
    
    /**
     * Returns the component at the col in the table
     * or <code>null</code> if no such component exists.
     *
     * @param col the column position of the component
     */
    public Component getTableEntry(int col) {
        return getTableEntry(0, col);
    }
    
    
    /**
     * Overrides the inherited method to ignore the given
     * rows and set the number of rows to 1.
     * 
     * @param rows ignored
     */
    public void setRows(int rows) {
        super.setRows(1);
    }
    
    
    /**
     * Overrides the inherited method to ignore the given
     * orientation and to set the orientation to HORIZONTAL.
     *
     * @param orientation ignored
     */
    public void setOrientation(int orientation) {
        super.setOrientation(HORIZONTAL);
    }
}