source: trunk/gli/src/org/greenstone/gatherer/gui/browser/HTMLViewPane.java@ 4366

/**
 *#########################################################################
 *
 * A component of the Gatherer application, part of the Greenstone digital
 * library suite from the New Zealand Digital Library Project at the
 * University of Waikato, New Zealand.
 *
 * <BR><BR>
 *
 * Author: John Thompson, Greenstone Digital Library, University of Waikato
 *
 * <BR><BR>
 *
 * Copyright (C) 1999 New Zealand Digital Library Project
 *
 * <BR><BR>
 *
 * 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, or
 * (at your option) any later version.
 *
 * <BR><BR>
 *
 * 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.
 *
 * <BR><BR>
 *
 * 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., 675 Mass Ave, Cambridge, MA 02139, USA.
 *########################################################################
 */

 




package org.greenstone.gatherer.gui.browser;
/**
 *  @date:        23/11/01
 */
import java.awt.Component;
import java.awt.Dimension;
import java.awt.image.BufferedImage;
import java.net.URL;
import javax.swing.ImageIcon;
import javax.swing.JProgressBar;
import org.greenstone.gatherer.gui.browser.GBrowserListener;
import org.greenstone.gatherer.util.GURL;
/** HTMLViewPane provides the interface that all implementations must adhere to. The methods shown are used by Gatherer to interact with the rendered HTML pane, and in turn recieve messages back. */
public interface HTMLViewPane {
    /** Add a GBrowserListener to this browser. 
     * @param listener an object which implements the GBrowserListener interface.
      */
    public void addGBrowserListener(GBrowserListener listener);

    public void afterDisplay();

  /**
    * Back tells the browser to display a previous page if there is one. All
    * implementations of HTMLViewPane should remember pages visited within this
    * session, and react appropriately to calls to this function. Any caller of
    * back should then immediately call canBack to determine if the function
    * should be enabled.
    * @return value - whether or not the operation was successful
    */
    public boolean back();
    /**
    * CanBack is used to determine if there are further pages to 'back' to, and
    * based on the result whether the functionality should be available
    */
    public boolean canBack();
    /**
    * CanForward performs approximately the same duty as canBack except, of
    * course, in the opposite direction.
    */
    public boolean canForward();
    /** 
      * CanStop determines whether the stop functionality is available. In general
      * you have to be doing something before you can stop it!
      */
    public boolean canStop();
    /**
   * Capture is used to grab a buffered image of the current graphics context of
   * the HTML pane. Note that this may not actually be feasible in embedded
   * applications such as Mozilla, as the apllication has a seperate graphics
   * buffer.
   * @return img - a buffered image containing a clipped section of the HTML
   * panes graphics buffer.
   */
    public BufferedImage capture();
    /**
   * When called this method returns the URL of the resource currently being
   * displayed (or rendered). If no resource has been requested the return URL
   * is null. The URL can point to local files, web-based resources etc.
   * @return url - the GURL of the currently displayed resource.
   */
    public GURL current();
    /**
   * This method is used to tell the HTML pane whether it should attempt to
   * follow hyperlinks when a user clicks them. Whether this is set or not the
   * fetch method should still be called by the HTML pane implementation apon
   * a hyperlink click.
   * @param on - whether followHyperlinks is; on (= true) or off.
   */
    public void followHyperlinks(boolean value);
    /**
    * Forward is a call for the HTMLViewPane implementation to move forward one
    * page in its browser history. It should react appropriately to calls to this
    * method and should retain a history of forward pages.
    * @return value - whether of not the operation was successfull
    */
    public boolean forward();
    /** In order to add the class that implements this interface to a component hierarchy you require some way to get at the component. This is that way.
      * @return a component reference of this class (as compared to the interface one you started with).
      */  
    public Component getContent();
    /**
   * If called, getProgressBar should return a reference to a JProgress bar. The
   * HTML pane is then resposible for updating the progress bar for its lifetime
   * whereapon the caller will dispose of it. If no page is currently being
   * downloaded/rendered then the call should return null.
   * @return progress - a JProgressBar indicating the HTML panes progress
   * towards displaying a url or null.
   */
    public JProgressBar getProgress();
    /** Before attempting to issue futher instructions to the HTML pane, Gatherer must first ensure that its ready. A pane should always be responsive but there are foreseeable times when an interrupt to go to a new page may cause the renderer to become unstable, or perhaps a user is filling out a form and thus shouldn't be pre-empted.
   * @return <i>true</i> if the pane is ready for further instructions, <i>false</i> if not.
   */
    public boolean isReady();
    /**
   * SetEnabled is used to temporarily prevent further user interaction with the
   * pane. This may be caused by certain user requests in other parts of Gatherer
   * or is called when a modal dialogue is opened by the Gatherer application.
   * Any implementation of setEnabled should in turn call an equivent method
   * within its subcomponents and update its appearance to indicate its current
   * state (ie greyed out boxes or background, wait cursor).
   * @param on - what state the component should be in; on (= true) or off.
   */
    public void setEnabled(boolean value);
    /** Remove a GBrowserListener from this browser. 
      * @param listener an object which implements the GBrowserListener interface.
      */
    public void removeGBrowserListener(GBrowserListener listener);
    /**
   * Show, in both of its forms, allows Gatherer to display a certain URL or file
   * in the HTML pane.
   * @param filename a string representing a valid local file path.
    * @param update whether this action should update the history queues.
   * @return whether a page has been queued to be rendered.
   */
    public boolean show(String filename);
    /**
   * Show, in both of its forms, allows Gatherer to display a certain URL or file
   * in the HTML pane.
   * @param url a url representing a valid URI.
    * @param update whether this action should update the history queues.
   * @return whether a page has been queued to be rendered.
   */
    public boolean show(GURL url);
    /**
   * Stop() kills the current rendering.
   * @return whether the rendering was successfully killed.
   */
    public boolean stop();
}