path: root/org.eclipse.debug.ui/ui/org/eclipse/debug/internal/ui/viewers/model/provisional/ITreeModelViewer.java

/*******************************************************************************
 * Copyright (c) 2011, 2015 Wind River Systems 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:
 *     Wind River Systems - initial API and implementation
 *     IBM Corporation - ongoing bug fixes and enhancements
 *******************************************************************************/
package org.eclipse.debug.internal.ui.viewers.model.provisional;

import org.eclipse.debug.internal.ui.viewers.model.ILabelUpdateListener;
import org.eclipse.jface.viewers.ISelection;
import org.eclipse.jface.viewers.ISelectionProvider;
import org.eclipse.jface.viewers.TreePath;
import org.eclipse.jface.viewers.ViewerFilter;
import org.eclipse.jface.viewers.ViewerLabel;
import org.eclipse.swt.widgets.Display;

/**
 * Interface of an tree model viewer.  It declares the common methods for the
 * JFace-based {@link TreeModelViewer} and the UI-less 
 * {@link VirtualTreeModelViewer}.
 *
 * @since 3.8
 */
public interface ITreeModelViewer extends ISelectionProvider {

    /**
     * Constant indicating that all levels of the tree should be expanded or
     * collapsed.
     *
     * @see #setAutoExpandLevel(int)
     * @see #getAutoExpandLevel()
     */
    public static final int ALL_LEVELS = -1;

    /**
     * Returns the Display object that this viewer is in.  The
     * display object can be used by clients to access the display thread
     * to call the viewer methods.
     * 
     * @return The display.
     */
    public Display getDisplay();

    /**
     * Returns this viewer's presentation context.
     * 
     * @return presentation context
     */
    public IPresentationContext getPresentationContext();

    /**
     * Returns the current input of this viewer, or <code>null</code>
     * if none. The viewer's input provides the "model" for the viewer's
     * content.
     * 
     * @return Input object
     */
    public Object getInput();

    /**
     * Sets the input of this viewer.  Setting the input resets the 
     * viewer's contents and triggers an update starting at the input
     * element.
     * 
     * @param object Input element, or <code>null</code> if none.
     */
    public void setInput(Object object);
    
    /**
     * Returns the current selection in viewer.
     * 
     * @return selection object
     */
    @Override
	public ISelection getSelection();

    /**
     * Sets a new selection for this viewer and optionally makes it visible.
     * The selection is not set if the model selection policy overrides the
     * attempt to set the selection.
     * 
     * @param selection the new selection
     * @param reveal <code>true</code> if the selection is to be made
     *   visible, and <code>false</code> otherwise
     * @param force <code>true</code> if the selection should override the 
     *   model selection policy
     */
    public void setSelection(ISelection selection, boolean reveal, boolean force);
    
    /**
     * Attempts to set the selection for this viewer and optionally makes it visible.
     * The selection is not set if the model selection policy overrides the
     * attempt to set the selection.
     * 
     * @param selection the new selection
     * @param reveal whether to make the selection visible after successfully setting
     *  the selection
     * @param force whether to force the selection (override the model selection policy)
     * @return <code>true</code> if the selection was set and <code>false</code> if the
     *  model selection policy overrides the selection attempt
     */
    public boolean trySelection(ISelection selection, boolean reveal, boolean force);

    /**
     * Returns the auto-expand level.
     *
     * @return non-negative level, or <code>ALL_LEVELS</code> if all levels of
     *         the tree are expanded automatically
     * @see #setAutoExpandLevel
     */    
    public int getAutoExpandLevel();

    /**
     * Sets the auto-expand level to be used when the input of the viewer is set
     * using {@link #setInput(Object)}. The value 0 means that there is no
     * auto-expand; 1 means that the invisible root element is expanded (since
     * most concrete implementations do not show the root element, there is usually
     * no practical difference between using the values 0 and 1); 2 means that
     * top-level elements are expanded, but not their children; 3 means that
     * top-level elements are expanded, and their children, but not
     * grandchildren; and so on.
     * <p>
     * The value <code>ALL_LEVELS</code> means that all subtrees should be
     * expanded.
     * </p>
     * 
     * @param level
     *            non-negative level, or <code>ALL_LEVELS</code> to expand all
     *            levels of the tree
     */
    public void setAutoExpandLevel(int level);
        
    /**
     * Returns the label data for the given element and for the given column, 
     * Returns <code>null</code> if the given element is not found or is not 
     * materialized in the virtual viewer.  Clients may listen to label update 
     * events to be notified when element labels are updated.
     * 
     * @param path Path of the element.
     * @param columnId ID of the column for which to return the label data.
     * @return Label object containing the label information.  Can be 
     * <code>null</code> if the given element is not found or is not 
     * materialized in the virtual viewer.
     */
    public ViewerLabel getElementLabel(TreePath path, String columnId);
    
    /**
     * Registers the specified listener for view update notifications.
     * 
     * @param listener Listener to add
     */
    public void addViewerUpdateListener(IViewerUpdateListener listener);
    
    /**
     * Removes the specified listener from update notifications.
     * 
     * @param listener Listener to remove
     */
    public void removeViewerUpdateListener(IViewerUpdateListener listener);
    
    /**
     * Registers the specified listener for state update notifications.
     * 
     * @param listener Listener to add
     */
    public void addStateUpdateListener(IStateUpdateListener listener);
    
    /**
     * Removes the specified listener from state update notifications.
     * 
     * @param listener Listener to remove
     */
    public void removeStateUpdateListener(IStateUpdateListener listener);
    
    /**
     * Registers the specified listener for view label update notifications.
     * 
     * @param listener Listener to add
     */
    public void addLabelUpdateListener(ILabelUpdateListener listener);
    
    /**
     * Removes the specified listener from view label update notifications.
     * 
     * @param listener Listener to remove
     */
    public void removeLabelUpdateListener(ILabelUpdateListener listener);
    
    /**
     * Registers the given listener for model delta notification.
     * This listener is called immediately after the viewer processes
     * the delta.
     * 
     * @param listener Listener to add
     */
    public void addModelChangedListener(IModelChangedListener listener);
    
    /**
     * Removes the given listener from model delta notification.
     * 
     * @param listener Listener to remove
     */
    public void removeModelChangedListener(IModelChangedListener listener);
    
    /**
     * Writes state information into a delta for the sub-tree at the given
     * path.  It adds delta nodes and IModelDelta.EXPAND and IModelDelta.SELECT 
     * as it parses the sub-tree.
     * 
     * @param path Path where to start saving the state.
     * @param delta The delta where the state is to be saved.
     * @param flagsToSave The flags to preserve during the state save.  The 
     * supported flags are <code>IModelDelta.SELECT</code>, 
     * <code>IModelDelta.EXPAND</code>, <code>IModelDelta.COLLAPSE</code>.
     * @return Returns whether the state was saved for the given path.  Will 
     * return <code>false</code> if an element at the given path cannot 
     * be found.
     */
    public boolean saveElementState(TreePath path, ModelDelta delta, int flagsToSave);
    
    /**
     * Causes the viewer to process the given delta as if it came from a
     * model proxy.  This method is intended to be used to restore state
     * saved using {@link #saveElementState(TreePath, ModelDelta, int)}.
     * 
     * @param delta Delta to process.
     */
    public void updateViewer(IModelDelta delta);
    
    /**
     * Triggers an update of the given element and its children.  If 
     * multiple instances of the given element are found in the tree, 
     * they will all be updated.
     * 
     * @param element Element to update.
     */
    public void refresh(Object element);

    /**
     * Triggers a full update of all the elements in the tree.
     */
    public void refresh();

    /**
     * Returns the paths at which the given element is found realized in viewer
     * or an empty array if not found.
     * 
     * @param element Element to find.
     * @return Array of paths for given element.
     */
    public TreePath[] getElementPaths(Object element);

    /**
     * Returns filters currently configured in viewer.
     * 
     * @return filter array in viewer.
     */
    public ViewerFilter[] getFilters();
    
    /**
     * Add a new filter to use in viewer.
     * 
     * @param filter Filter to add.
     */
    public void addFilter(ViewerFilter filter);
    
    /**
     * Sets viewer filters to the filters in array.
     * 
     * @param filters New filter array to use.
     */
	public void setFilters(ViewerFilter... filters);

 }