/*
 This file is part of the software framework JStatCom, 
 a library for building applications for data based analysis.

 Copyright (C) 2000-2005 Alexander Benkwitz, Markus Kraetzig

 This library is free software; you can redistribute it and/or modify
 it under the terms of the GNU Lesser General Public License as
 published by the Free Software Foundation; either version 2.1 of the
 License, or (at your option) any later version.

 This library 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
 Lesser General Public License for more details.

 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
 USA
 */

package com.jstatcom.component;

import java.awt.Component;

import javax.swing.JComponent;

/**
 * An alternative to CardPanel that can be used in conjunction
 * with CardPanelAction to display components on demand as well
 * as to notify them when they are either shown or hidden. The notification is
 * done by invoking firePropertyChange on the respective
 * component.
 * 

 * The easiest way to receive notification about CARD_DISPLAYED
 * events is if the component implements Card and overrides the
 * shown method.
 * 

 * Another way for the respective component to react to
 * CARD_DISPLAYED events is to call
 * addPropertyChangeListener(this) on initialization as well as
 * to override the propertyChange method. Of course it can also
 * register other clients to this event.
 * 
 * @author A. Benkwitz, M. Kraetzig 
 * @see com.jstatcom.component.CardPanelAction
 */
public final class CardDisplayPanel extends CardPanel {
    /**
     * Name of the property that is thrown when a "card" component is either
     * displayed or hidden.
     */
    public final static String CARD_DISPLAYED = "CARD_DISPLAYED";

    /**
     * Creates a CardDisplayPanel.
     */
    public CardDisplayPanel() {
        super();
    }

    /**
     * Reimplements the super method and fires property change events. Execution
     * is in the following order:
     * 

     * 
if card is already displayed, nothing happens
     * 
the component that is hidden calls
     * firePropertyChange(CARD_DISPLAYED, true, false) and
     * shown(false) if it implements Card
     * 
afterwards the new component is shown and this component calls
     * firePropertyChange(CARD_DISPLAYED, false, true) and
     * shown(true) if it implements Card
     * 
     * 
     * @param card
     *            the component to be shown, must be a JComponent
     * 
     * @throws IllegalArgumentException
     *             if (!(card instanceof JComponent))
     */
    public void showCard(Component card) {

        if (!(card instanceof JComponent))
            throw new IllegalArgumentException("Argument not a JComponent.");

        int index = getVisibleChildIndex();

        // Card is already displayed.
        if (index != -1 && getComponent(index).equals(card))
            return;

        // Add new component, do not show yet.
        JComponent toFront = (JComponent) card;
        if (toFront.getParent() != this) {
            toFront.setVisible(false);
            add(toFront);
        }

        JComponent toBack = null;
        if (index != -1)
            toBack = (JComponent) getComponent(index);

        // Hide previous, fire property change.
        if (toBack != null) {
            toBack.setVisible(false);
            toBack.firePropertyChange(CARD_DISPLAYED, true, false);
            if (toBack instanceof Card)
                ((Card) toBack).shown(false);
        }

        // Finally bring card to top, fire property change.
        toFront.setVisible(true);
        toFront.firePropertyChange(CARD_DISPLAYED, false, true);
        if (toFront instanceof Card)
            ((Card) toFront).shown(true);
        repaint();
    }
}