ByteEdit/src/org/fife/ui/autocomplete/AutoCompleteDescWindow.java

/*
 * 12/21/2008
 * AutoCompleteDescWindow.java - A window containing a description of the
 * currently selected completion.
 * This library is distributed under a modified BSD license. See the included
 * AutoComplete.License.txt file for details.
 */
package org.fife.ui.autocomplete;

import java.awt.BorderLayout;
import java.awt.Component;
import java.awt.ComponentOrientation;
import java.awt.Graphics;
import java.awt.Insets;
import java.awt.Window;
import java.awt.event.ActionEvent;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.util.ArrayList;
import java.util.List;
import java.util.ResourceBundle;

import javax.swing.AbstractAction;
import javax.swing.Action;
import javax.swing.BorderFactory;
import javax.swing.Icon;
import javax.swing.ImageIcon;
import javax.swing.JButton;
import javax.swing.JEditorPane;
import javax.swing.JPanel;
import javax.swing.JScrollPane;
import javax.swing.JToolBar;
import javax.swing.JWindow;
import javax.swing.SwingUtilities;
import javax.swing.Timer;
import javax.swing.UIManager;
import javax.swing.border.AbstractBorder;
import javax.swing.border.Border;
import javax.swing.event.HyperlinkEvent;
import javax.swing.event.HyperlinkListener;

import org.fife.ui.rsyntaxtextarea.PopupWindowDecorator;

/**
 * The optional "description" window that describes the currently selected item
 * in the auto-completion window.
 *
 * @author Robert Futrell
 * @version 1.0
 */
class AutoCompleteDescWindow extends JWindow implements HyperlinkListener, DescWindowCallback {

	/**
	 * The parent AutoCompletion instance.
	 */
	private AutoCompletion ac;
	/**
	 * Renders the HTML description.
	 */
	private JEditorPane descArea;
	/**
	 * The scroll pane that {@link #descArea} is in.
	 */
	private JScrollPane scrollPane;
	/**
	 * The bottom panel, containing the toolbar and size grip.
	 */
	private JPanel bottomPanel;
	/**
	 * The toolbar with "back" and "forward" buttons.
	 */
	private JToolBar descWindowNavBar;
	/**
	 * Action that goes to the previous description displayed.
	 */
	private Action backAction;
	/**
	 * Action that goes to the next description displayed.
	 */
	private Action forwardAction;
	/**
	 * History of descriptions displayed.
	 */
	private List<HistoryEntry> history;
	/**
	 * The current position in {@link #history}.
	 */
	private int historyPos;
	/**
	 * Provides a slight delay between asking to set a description and actually
	 * displaying it, so that if the user is scrolling quickly through completions,
	 * those with slow-to-calculate summaries won't bog down the scrolling.
	 */
	private Timer timer;
	/**
	 * The action that listens for the timer to fire.
	 */
	private TimerAction timerAction;
	/**
	 * The resource bundle for this window.
	 */
	private ResourceBundle bundle;
	/**
	 * The amount of time to wait after the user changes the selected completion to
	 * refresh the description. This delay is in place to help performance for
	 * {@link Completion}s that may be slow to compute their summary text.
	 */
	private static final int INITIAL_TIMER_DELAY = 120;
	/**
	 * The resource bundle name.
	 */
	private static final String MSG = "org.fife.ui.autocomplete.AutoCompleteDescWindow";

	/**
	 * Constructor.
	 *
	 * @param owner The parent window.
	 * @param ac    The parent auto-completion.
	 */
	public AutoCompleteDescWindow(Window owner, AutoCompletion ac) {
		super(owner);
		this.ac = ac;
		ComponentOrientation o = ac.getTextComponentOrientation();
		JPanel cp = new JPanel(new BorderLayout());
		cp.setBorder(TipUtil.getToolTipBorder());
		descArea = new JEditorPane("text/html", null);
		TipUtil.tweakTipEditorPane(descArea);
		descArea.addHyperlinkListener(this);
		scrollPane = new JScrollPane(descArea);
		Border b = BorderFactory.createEmptyBorder();
		scrollPane.setBorder(b);
		scrollPane.setViewportBorder(b);
		scrollPane.setBackground(descArea.getBackground());
		scrollPane.getViewport().setBackground(descArea.getBackground());
		cp.add(scrollPane);
		descWindowNavBar = new JToolBar();
		backAction = new ToolBarBackAction(o.isLeftToRight());
		forwardAction = new ToolBarForwardAction(o.isLeftToRight());
		descWindowNavBar.setFloatable(false);
		descWindowNavBar.add(new JButton(backAction));
		descWindowNavBar.add(new JButton(forwardAction));
		bottomPanel = new JPanel(new BorderLayout());
		b = new AbstractBorder() {

			@Override
			public Insets getBorderInsets(Component c) {
				return new Insets(1, 0, 0, 0);
			}

			@Override
			public void paintBorder(Component c, Graphics g, int x, int y, int w, int h) {
				g.setColor(UIManager.getColor("controlDkShadow"));
				g.drawLine(x, y, x + w - 1, y);
			}
		};
		bottomPanel.setBorder(b);
		SizeGrip rp = new SizeGrip();
		bottomPanel.add(descWindowNavBar, BorderLayout.LINE_START);
		bottomPanel.add(rp, BorderLayout.LINE_END);
		cp.add(bottomPanel, BorderLayout.SOUTH);
		setContentPane(cp);
		applyComponentOrientation(o);
		setFocusableWindowState(false);
		// Give apps a chance to decorate us with drop shadows, etc.
		if (Util.getShouldAllowDecoratingMainAutoCompleteWindows()) {
			PopupWindowDecorator decorator = PopupWindowDecorator.get();
			if (decorator != null) {
				decorator.decorate(this);
			}
		}
		history = new ArrayList<HistoryEntry>(1); // Usually small
		historyPos = -1;
		timerAction = new TimerAction();
		timer = new Timer(INITIAL_TIMER_DELAY, timerAction);
		timer.setRepeats(false);
	}

	/**
	 * Sets the currently displayed description and updates the history.
	 *
	 * @param historyItem The item to add to the history.
	 */
	private void addToHistory(HistoryEntry historyItem) {
		history.add(++historyPos, historyItem);
		clearHistoryAfterCurrentPos();
		setActionStates();
	}

	/**
	 * Clears the history of viewed descriptions.
	 */
	private void clearHistory() {
		history.clear(); // Try to free some memory.
		historyPos = -1;
		if (descWindowNavBar != null) {
			setActionStates();
		}
	}

	/**
	 * Makes the current history page the last one in the history.
	 */
	private void clearHistoryAfterCurrentPos() {
		for (int i = history.size() - 1; i > historyPos; i--) {
			history.remove(i);
		}
		setActionStates();
	}

	/**
	 * Copies from the description text area, if it is visible and there is a
	 * selection.
	 *
	 * @return Whether a copy occurred.
	 */
	public boolean copy() {
		if (isVisible() && descArea.getSelectionStart() != descArea.getSelectionEnd()) {
			descArea.copy();
			return true;
		}
		return false;
	}

	/**
	 * Returns the localized message for the specified key.
	 *
	 * @param key The key.
	 * @return The localized message.
	 */
	private String getString(String key) {
		if (bundle == null) {
			bundle = ResourceBundle.getBundle(MSG);
		}
		return bundle.getString(key);
	}

	/**
	 * Called when a hyperlink is clicked.
	 *
	 * @param e The event.
	 */
	@Override
	public void hyperlinkUpdate(HyperlinkEvent e) {
		HyperlinkEvent.EventType type = e.getEventType();
		if (!type.equals(HyperlinkEvent.EventType.ACTIVATED)) {
			return;
		}
		// Users can redirect URL's, perhaps to a local copy of documentation.
		URL url = e.getURL();
		if (url != null) {
			LinkRedirector redirector = AutoCompletion.getLinkRedirector();
			if (redirector != null) {
				URL newUrl = redirector.possiblyRedirect(url);
				if (newUrl != null && newUrl != url) {
					url = newUrl;
					e = new HyperlinkEvent(e.getSource(), e.getEventType(), newUrl, e.getDescription(),
							e.getSourceElement());
				}
			}
		}
		// Custom hyperlink handler for this completion type
		ExternalURLHandler handler = ac.getExternalURLHandler();
		if (handler != null) {
			HistoryEntry current = history.get(historyPos);
			handler.urlClicked(e, current.completion, this);
			return;
		}
		// No custom handler...
		if (url != null) {
			// Try loading in external browser (Java 6+ only).
			try {
				Util.browse(new URI(url.toString()));
			} catch (/* IO */URISyntaxException ioe) {
				UIManager.getLookAndFeel().provideErrorFeedback(descArea);
				ioe.printStackTrace();
			}
		} else { // Assume simple function name text, like in c.xml
					// FIXME: This is really a hack, and we assume we can find
					// the
					// linked-to item in the same CompletionProvider.
			AutoCompletePopupWindow parent = (AutoCompletePopupWindow) getParent();
			CompletionProvider p = parent.getSelection().getProvider();
			if (p instanceof AbstractCompletionProvider) {
				String name = e.getDescription();
				List<Completion> l = ((AbstractCompletionProvider) p).getCompletionByInputText(name);
				if (l != null && !l.isEmpty()) {
					// Just use the 1st one if there's more than 1
					Completion c = l.get(0);
					setDescriptionFor(c, true);
				} else {
					UIManager.getLookAndFeel().provideErrorFeedback(descArea);
				}
			}
		}
	}

	/**
	 * Enables or disables the back and forward actions as appropriate.
	 */
	private void setActionStates() {
		// TODO: Localize this text!
		String desc = null;
		if (historyPos > 0) {
			backAction.setEnabled(true);
			desc = "Back to " + history.get(historyPos - 1);
		} else {
			backAction.setEnabled(false);
		}
		backAction.putValue(Action.SHORT_DESCRIPTION, desc);
		if (historyPos > -1 && historyPos < history.size() - 1) {
			forwardAction.setEnabled(true);
			desc = "Forward to " + history.get(historyPos + 1);
		} else {
			forwardAction.setEnabled(false);
			desc = null;
		}
		forwardAction.putValue(Action.SHORT_DESCRIPTION, desc);
	}

	/**
	 * Sets the description displayed in this window. This clears the history.
	 *
	 * @param item The item whose description you want to display.
	 */
	public void setDescriptionFor(Completion item) {
		setDescriptionFor(item, false);
	}

	/**
	 * Sets the description displayed in this window.
	 *
	 * @param item         The item whose description you want to display.
	 * @param addToHistory Whether to add this page to the page history (as opposed
	 *                     to clearing it and starting anew).
	 */
	protected void setDescriptionFor(Completion item, boolean addToHistory) {
		setDescriptionFor(item, null, addToHistory);
	}

	/**
	 * Sets the description displayed in this window.
	 *
	 * @param item The item whose description you want to display.
	 * @parma anchor The anchor to jump to, or <code>null</code> if none.
	 * @param addToHistory Whether to add this page to the page history (as opposed
	 *                     to clearing it and starting anew).
	 */
	protected void setDescriptionFor(Completion item, String anchor, boolean addToHistory) {
		timer.stop();
		timerAction.setCompletion(item, anchor, addToHistory);
		timer.start();
	}

	private void setDisplayedDesc(Completion completion, final String anchor, boolean addToHistory) {
		String desc = completion == null ? null : completion.getSummary();
		if (desc == null) {
			desc = "<html><em>" + getString("NoDescAvailable") + "</em>";
		}
		descArea.setText(desc);
		if (anchor != null) {
			SwingUtilities.invokeLater(new Runnable() {

				@Override
				public void run() {
					descArea.scrollToReference(anchor);
				}
			});
		} else {
			descArea.setCaretPosition(0); // In case of scrolling
		}
		if (!addToHistory) {
			// Remove everything first if this is going to be the only
			// thing in history.
			clearHistory();
		}
		addToHistory(new HistoryEntry(completion, desc, null));
	}

	/**
	 * {@inheritDoc}
	 */
	@Override
	public void setVisible(boolean visible) {
		if (!visible) {
			clearHistory();
		}
		super.setVisible(visible);
	}

	/**
	 * Callback for custom <code>ExternalURLHandler</code>s.
	 *
	 * @param completion The completion to display.
	 * @param anchor     The anchor in the HTML to jump to, or <code>null</code> if
	 *                   none.
	 */
	@Override
	public void showSummaryFor(Completion completion, String anchor) {
		setDescriptionFor(completion, anchor, true);
	}

	/**
	 * Called by the parent completion popup window the LookAndFeel is updated.
	 */
	public void updateUI() {
		SwingUtilities.updateComponentTreeUI(this);
		// Update editor pane for new font, bg, selection colors, etc.
		TipUtil.tweakTipEditorPane(descArea);
		scrollPane.setBackground(descArea.getBackground());
		scrollPane.getViewport().setBackground(descArea.getBackground());
		((JPanel) getContentPane()).setBorder(TipUtil.getToolTipBorder());
	}

	/**
	 * A completion and its cached summary text.
	 */
	private static class HistoryEntry {

		public Completion completion;
		public String summary;
		public String anchor;

		public HistoryEntry(Completion completion, String summary, String anchor) {
			this.completion = completion;
			this.summary = summary;
			this.anchor = anchor;
		}

		/**
		 * Overridden to display a short name for the completion, since it's used in the
		 * tool tips for the "back" and "forward" buttons.
		 *
		 * @return A string representation of this history entry.
		 */
		@Override
		public String toString() {
			return completion.getInputText();
		}
	}

	/**
	 * Action that actually updates the summary text displayed.
	 */
	private class TimerAction extends AbstractAction {

		private Completion completion;
		private String anchor;
		private boolean addToHistory;

		/**
		 * Called when the timer is fired.
		 */
		@Override
		public void actionPerformed(ActionEvent e) {
			setDisplayedDesc(completion, anchor, addToHistory);
		}

		public void setCompletion(Completion c, String anchor, boolean addToHistory) {
			this.completion = c;
			this.anchor = anchor;
			this.addToHistory = addToHistory;
		}
	}

	/**
	 * Action that moves to the previous description displayed.
	 */
	class ToolBarBackAction extends AbstractAction {

		public ToolBarBackAction(boolean ltr) {
			String img = "org/fife/ui/autocomplete/arrow_" + (ltr ? "left.png" : "right.png");
			ClassLoader cl = getClass().getClassLoader();
			Icon icon = new ImageIcon(cl.getResource(img));
			putValue(Action.SMALL_ICON, icon);
		}

		@Override
		public void actionPerformed(ActionEvent e) {
			if (historyPos > 0) {
				HistoryEntry pair = history.get(--historyPos);
				descArea.setText(pair.summary);
				if (pair.anchor != null) {
					// System.out.println("Scrolling to: " + pair.anchor);
					descArea.scrollToReference(pair.anchor);
				} else {
					descArea.setCaretPosition(0);
				}
				setActionStates();
			}
		}
	}

	/**
	 * Action that moves to the previous description displayed.
	 */
	class ToolBarForwardAction extends AbstractAction {

		public ToolBarForwardAction(boolean ltr) {
			String img = "org/fife/ui/autocomplete/arrow_" + (ltr ? "right.png" : "left.png");
			ClassLoader cl = getClass().getClassLoader();
			Icon icon = new ImageIcon(cl.getResource(img));
			putValue(Action.SMALL_ICON, icon);
		}

		@Override
		public void actionPerformed(ActionEvent e) {
			if (history != null && historyPos < history.size() - 1) {
				HistoryEntry pair = history.get(++historyPos);
				descArea.setText(pair.summary);
				if (pair.anchor != null) {
					// System.out.println("Scrolling to: " + pair.anchor);
					descArea.scrollToReference(pair.anchor);
				} else {
					descArea.setCaretPosition(0);
				}
				setActionStates();
			}
		}
	}
}