// DashboardPanel.java
//
//    Created: September 2005
//
// This file is a component of the BioMoby project.
// Copyright Martin Senger (martin.senger@gmail.com).
//

package org.biomoby.service.dashboard;

import javax.swing.JLabel;
import javax.swing.Icon;
import javax.swing.JComponent;
import java.net.URL;

/**
 * An interface that must be implemented by each panel that wants to
 * sit on a dashboard. <p>
 *
 * @author <A HREF="mailto:martin.senger@gmail.com">Martin Senger</A>
 * @version $Id: DashboardPanel.java,v 1.9 2005/12/13 15:01:29 senger Exp $
 */

public interface DashboardPanel {

    /**************************************************************************
     * Return a graphical representation of this panel. <p>
     *
     * @param propertyChannel is a shared storage for properties
     * @return a GUI representing this panel
     **************************************************************************/
    JComponent getComponent (PropertyChannel propertyChannel);

    /**************************************************************************
     * A name identifies a panel in the dashboard's tabs. It should be
     * relatively short, without newlines, or any other special
     * characters. <p>
     *
     * @see #getTitle
     **************************************************************************/
    String getName();

    /**************************************************************************
     * A title is a more-detailed description of a panel, possibly
     * including an image. The dashboard will display it above this
     * panel.<p>
     *
     *
     * @return a panel (possibly rich) title, or an empty label (but not null)
     * @see #getName
     **************************************************************************/
    JLabel getTitle();

    /**************************************************************************
     * The help system is centralized in Dashboard itself. The panels
     * are not supposed to have a Help button. The main panel help is
     * provided by this method. Which, however, does not preclude to
     * use help tool-tips, or some ways of context-sensitive help,
     * directly in panels. <p>
     *
     * The returned string will be treated as an HTML document (will
     * be displayed with "text/html" mime type). <p>
     *
     * TBD: we may change this later and use JavaHelp mechanism. <p>
     *
     * @return the main help document describing features provided by
     * a panel
     **************************************************************************/
    String getHelp();

    /**************************************************************************
     * Return a URL of this panel's help page. Usually it is a link to
     * a local file, the same one that is often used by the {@link
     * #getHelp} method. This URL (instead of direct help text) is
     * used in the dashboard summary page. <p>
     *
     * @return a URL of the panel help page, or null
     **************************************************************************/
    URL getHelpURL();

    /**************************************************************************
     * Return a short description (few lines only) of this panel. It
     * may be used in some Dashboard summary, or in panel selection
     * settings. <p>
     *
     * @return a panel short description
     **************************************************************************/
    String getDescription();

    /**************************************************************************
     * Return an icon decorating this panel. The icon should be small
     * - it will be used in the panel tab (together with the name
     * returned by {@link #getName}). A dashboard may ignore too large
     * icons. <p>
     *
     * @return a panel icon, or null
     **************************************************************************/
    Icon getIcon();

    /**************************************************************************
     * Return a URL of this panel's icon. Usually it is the same icon
     * as returned by the {@link #getIcon}. This URL (instead of
     * directly the icon) is used in the dashboard summary page. <p>
     *
     * @return a URL (usualy pointing to a local file) of the panel
     * icon, or null
     **************************************************************************/
    URL getIconURL();

    /**************************************************************************
     * Some panels can be selected by users as not-needed - so they do
     * not show at the start-up. But some panels cannot be removed
     * because their functionality is crucial also for other
     * panels. <p>
     *
     * @return true if this panel should be always shown in the dashboard
     **************************************************************************/
    boolean isMandatory();

    /**************************************************************************
     * Some panels are less important for most users (e.g. debugging
     * panels) so they are shown only when a user specifically selects
     * them. <p>
     *
     * @return true if this panel should not be loaded by deafult
     **************************************************************************/
    boolean loadOnlyOnDemand();

//     /**************************************************************************
//      * Return a number of sub-components that will be loaded when this
//      * panel is loaded. This is purely for the benefit of a loading
//      * progress bar. By default, the whole panel is considered a one
//      * component - so any value returned by this method that is
//      * smaller than 2 is considered as 1. <p>
//      *
//      * If you decide, however, to return number higher than 1 then you
//      * should also fire the same number of events... TBD
//      *
//      * @return number of sub-components of this panel that are worth
//      * to fire a loading progress bar event about them
//      **************************************************************************/
//     int progressItemsCount();
}