path: root/bundles/org.eclipse.ui.workbench/Eclipse UI/org/eclipse/ui/part/DrillDownAdapter.java

/*******************************************************************************
 * Copyright (c) 2000, 2006 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.ui.part;

import java.util.Arrays;
import java.util.List;

import org.eclipse.jface.action.Action;
import org.eclipse.jface.action.IMenuManager;
import org.eclipse.jface.action.IToolBarManager;
import org.eclipse.jface.viewers.ISelectionChangedListener;
import org.eclipse.jface.viewers.IStructuredSelection;
import org.eclipse.jface.viewers.SelectionChangedEvent;
import org.eclipse.jface.viewers.StructuredSelection;
import org.eclipse.jface.viewers.TreeViewer;
import org.eclipse.ui.ISharedImages;
import org.eclipse.ui.PlatformUI;
import org.eclipse.ui.internal.WorkbenchImages;
import org.eclipse.ui.internal.WorkbenchMessages;

/**
 * Implements a simple web style navigation metaphor for a <code>TreeViewer</code>.  
 * Home, back, and "drill into" functions are supported for the viewer,
 * <p>
 * To use the <code>DrillDownAdapter</code> ..
 * </p>
 * <ul>
 * <li>Create an instance of <code>TreeViewer</code>. </li>
 * <li>Create a <code>DrillDownAdapter</code> for the viewer. </li>
 * <li>Create a container for your viewer with a toolbar or a popup menu.
 *		Add actions for "goBack", "goHome", and "goInto" to either one by calling
 *		</code>addNavigationActions</code> with the popup menu or toolbar.</li>
 * </ol>
 * <p>
 * If the input for the underlying viewer is changed by something other than the 
 * adapter the <code>reset</code> method should be called.  This will clear
 * the drill stack and update the navigation buttons to reflect the new 
 * state of the underlying viewer.
 * </p>
 * </p>
 */
public class DrillDownAdapter implements ISelectionChangedListener {
    private TreeViewer fChildTree;

    private DrillStack fDrillStack;

    private Action homeAction;

    private Action backAction;

    private Action forwardAction;

    /**
     * Allocates a new DrillDownTreePart.
     *
     * @param tree the target tree for refocusing
     */
    public DrillDownAdapter(TreeViewer tree) {
        fDrillStack = new DrillStack();
        fChildTree = tree;
    }

    /**
     * Adds actions for "go back", "go home", and "go into" to a menu manager.
     *
     * @param manager is the target manager to update
     */
    public void addNavigationActions(IMenuManager manager) {
        createActions();
        manager.add(homeAction);
        manager.add(backAction);
        manager.add(forwardAction);
        updateNavigationButtons();
    }

    /**
     * Adds actions for "go back", "go home", and "go into" to a tool bar manager.
     *
     * @param toolBar is the target manager to update
     */
    public void addNavigationActions(IToolBarManager toolBar) {
        createActions();
        toolBar.add(homeAction);
        toolBar.add(backAction);
        toolBar.add(forwardAction);
        updateNavigationButtons();
    }

    /**
     * Returns whether expansion is possible for the current selection.  This
     * will only be true if it has children.
     *
     * @param element the object to test for expansion
     * @return <code>true</code> if expansion is possible; otherwise 
     *		return <code>false</code
     */
    public boolean canExpand(Object element) {
        return fChildTree.isExpandable(element);
    }

    /**
     * Returns whether "go back" is possible for child tree.  This is only possible 
     * if the client has performed one or more drilling operations.
     *
     * @return <code>true</code> if "go back" is possible; <code>false</code> otherwise
     */
    public boolean canGoBack() {
        return fDrillStack.canGoBack();
    }

    /**
     * Returns whether "go home" is possible for child tree.  This is only possible 
     * if the client has performed one or more drilling operations.
     *
     * @return <code>true</code> if "go home" is possible; <code>false</code> otherwise
     */
    public boolean canGoHome() {
        return fDrillStack.canGoHome();
    }

    /**
     * Returns whether "go into" is possible for child tree.  This is only possible 
     * if the current selection in the client has one item and it has children.
     *
     * @return <code>true</code> if "go into" is possible; <code>false</code> otherwise
     */
    public boolean canGoInto() {
        IStructuredSelection oSelection = (IStructuredSelection) fChildTree
                .getSelection();
        if (oSelection == null || oSelection.size() != 1) {
			return false;
		}
        Object anElement = oSelection.getFirstElement();
        return canExpand(anElement);
    }

    /**
     * Create the actions for navigation.
     *
     */
    private void createActions() {
        // Only do this once.
        if (homeAction != null) {
			return;
		}

        // Home.	
        homeAction = new Action(WorkbenchMessages.GoHome_text) {
            public void run() {
                goHome();
            }
        };
        homeAction
                .setToolTipText(WorkbenchMessages.GoHome_toolTip);
        homeAction
                .setImageDescriptor(WorkbenchImages
                        .getImageDescriptor(ISharedImages.IMG_ETOOL_HOME_NAV));

        // Back.
        ISharedImages images = PlatformUI.getWorkbench().getSharedImages();
        backAction = new Action(WorkbenchMessages.GoBack_text) {
            public void run() {
                goBack();
            }
        };
        backAction
                .setToolTipText(WorkbenchMessages.GoBack_toolTip); 
        backAction.setImageDescriptor(images
                .getImageDescriptor(ISharedImages.IMG_TOOL_BACK));
        backAction.setDisabledImageDescriptor(images
                .getImageDescriptor(ISharedImages.IMG_TOOL_BACK_DISABLED));

        // Forward.
        forwardAction = new Action(WorkbenchMessages.GoInto_text) { 
            public void run() {
                goInto();
            }
        };
        forwardAction.setToolTipText(WorkbenchMessages.GoInto_toolTip); 
        forwardAction.setImageDescriptor(images
                .getImageDescriptor(ISharedImages.IMG_TOOL_FORWARD));
        forwardAction.setDisabledImageDescriptor(images
                .getImageDescriptor(ISharedImages.IMG_TOOL_FORWARD_DISABLED));

        // Update the buttons when a selection change occurs.
        fChildTree.addSelectionChangedListener(this);
        updateNavigationButtons();
    }

    /**
     * Expands the given items in the tree.  The list of items passed should be
     * derived by calling <code>getExpanded</code>.
     *
     * @param items is a list of items within the tree which should be expanded
     */
    private void expand(List items) {
        fChildTree.setExpandedElements(items.toArray());
    }

    /**
     * Returns a list of elements corresponding to expanded nodes in 
     * child tree.
     *
     * @return a list of expandd elements
     */
    private List getExpanded() {
        return Arrays.asList(fChildTree.getExpandedElements());
    }

    /**
     * Reverts the input for the tree back to the state when <code>goInto</code>
     * was last called.
     * <p>
     * A frame is removed from the drill stack.  Then that frame is used to reset the
     * input and expansion state for the child tree.
     * </p>
     */
    public void goBack() {
        Object currentInput = fChildTree.getInput();
        DrillFrame oFrame = fDrillStack.goBack();
        Object input = oFrame.getElement();
        fChildTree.setInput(input);
        expand(oFrame.getExpansion());
        // if there was a selection, it should have been preserved,
        // but if not, select the element that was drilled into
        if (fChildTree.getSelection().isEmpty()) {
			fChildTree
                    .setSelection(new StructuredSelection(currentInput), true);
		}
        updateNavigationButtons();
    }

    /**
     * Reverts the input for the tree back to the state when the adapter was
     * created.
     * <p>
     * All of the frames are removed from the drill stack.  Then the oldest frame is 
     * used to reset the input and expansion state for the child tree.
     * </p>
     */
    public void goHome() {
        Object currentInput = fChildTree.getInput();
        DrillFrame oFrame = fDrillStack.goHome();
        Object input = oFrame.getElement();
        fChildTree.setInput(input);
        expand(oFrame.getExpansion());
        // if there was a selection, it should have been preserved,
        // but if not, select the element that was last drilled into
        if (fChildTree.getSelection().isEmpty()) {
			fChildTree
                    .setSelection(new StructuredSelection(currentInput), true);
		}
        updateNavigationButtons();
    }

    /**
     * Sets the input for the tree to the current selection.
     * <p>
     * The current input and expansion state are saved in a frame and added to the 
     * drill stack.  Then the input for the tree is changed to be the current selection.  
     * The expansion state for the tree is maintained during the operation.
     * </p><p>
     * On return the client may revert back to the previous state by invoking 
     * <code>goBack</code> or <code>goHome</code>.
     * </p>
     */
    public void goInto() {
        IStructuredSelection sel = (IStructuredSelection) fChildTree
                .getSelection();
        Object element = sel.getFirstElement();
        goInto(element);
    }

    /**
     * Sets the input for the tree to a particular item in the tree.
     * <p>
     * The current input and expansion state are saved in a frame and added to the 
     * drill stack.  Then the input for the tree is changed to be <code>newInput</code>.  
     * The expansion state for the tree is maintained during the operation.
     * </p><p>
     * On return the client may revert back to the previous state by invoking 
     * <code>goBack</code> or <code>goHome</code>.
     * </p>
     *
     * @param newInput the new input element
     */
    public void goInto(Object newInput) {
        // If we can drill ..
        if (canExpand(newInput)) {
            // Save the old state.
            Object oldInput = fChildTree.getInput();
            List expandedList = getExpanded();
            fDrillStack.add(new DrillFrame(oldInput, "null", expandedList));//$NON-NLS-1$

            // Install the new state.
            fChildTree.setInput(newInput);
            expand(expandedList);
            updateNavigationButtons();
        }
    }

    /**
     * Resets the drill down adapter. 
     * <p>
     * This method is typically called when the input for the underlying view
     * is reset by something other than the adapter.
     * On return the drill stack has been cleared and the navigation buttons
     * reflect the new state of the underlying viewer.
     * </p>
     */
    public void reset() {
        fDrillStack.reset();
        updateNavigationButtons();
    }

    /**
     * Updates the navigation buttons when a selection change occurs
     * in the tree.
     */
    public void selectionChanged(SelectionChangedEvent event) {
        updateNavigationButtons();
    }

    /**
     * Updates the enabled state for each navigation button.  
     */
    protected void updateNavigationButtons() {
        if (homeAction != null) {
            homeAction.setEnabled(canGoHome());
            backAction.setEnabled(canGoBack());
            forwardAction.setEnabled(canGoInto());
        }
    }
}