package com.onaro.sanscreen.client.help;

import java.awt.Component;

import javax.help.HelpSetException;
import javax.swing.AbstractButton;

public interface IHelpManager {
    /**
     * Adds a HelpModule. Merges it with the existing set of HelpModules. This is used to load HelpModules dynamically.
     * 
     * @param loader
     *            the class loader we'll use to find the help resources
     * @param path
     *            the path to the root of the help directory containing the IHelpModule
     * @return the IHelpModule we added.
     */
    public IHelpModule addHelpModule(ClassLoader loader, String path) throws HelpSetException;
    
    /**
     * Removes a help module.
     * 
     * @param path
     *            the path to the root of the help directory containing the IHelpModule
     */
    public void removeHelp(String path);

    /**
     * Enables F1 on the given component.
     * 
     * @param comp
     *            the component that will enable F1 help processing.
     * @param context
     *            the help context to show when F1 is pressed.
     */
    public void enableHelpKey(Component comp, String context);

    /**
     * Sets the help context string for the component. When help is invoked on this component the given context will be
     * used to display context-sensitive help.
     * 
     * @param comp
     *            the component whose help context is set
     * @param context
     *            the help context to set for the component
     */
    public void setHelpContext(Component comp, String context);

    /**
     * Registers the given button component to invoke help. Typically, the help invoker will be a menu item or toolbar
     * button component.
     * 
     * @param comp
     *            the component that will invoke help when pressed.
     */
    public void registerHelpInvoker(AbstractButton comp);

    /**
     * Unregisters the given button component to invoke help. Typically, the help invoker will be a menu item or toolbar
     * button component.  Removes a listener from the component.
     * 
     * @param comp
     *            the component that will no longer invoke help when pressed.
     */
    public void unregisterHelpInvoker(AbstractButton comp);

    /**
     * Registers the given button component to invoke help after tracking. Typically, the help invoker will be a menu
     * item or toolbar button component. Help after tracking functionality is the ability to enter into a mode where the
     * user clicks on a UI component and gets help on it.
     * 
     * @param comp
     *            the component that will invoke help after tracking when pressed.
     * 
     * @param comp
     */
    public void registerTrackerHelpInvoker(AbstractButton comp);

    /**
     * Unregisters the given button component that was registered to invoke help after tracking. Typically, the help invoker will be a menu
     * item or toolbar button component. Help after tracking functionality is the ability to enter into a mode where the
     * user clicks on a UI component and gets help on it.
     * 
     * @param comp
     *            the component that will no longer invoke help after tracking when pressed.
     * 
     * @param comp
     */
    public void unregisterTrackerHelpInvoker(AbstractButton comp);
}