/*****************************************************************
* Copyright (c) 2010, 2011 Texas Instruments 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:
* Patrick Chuong (Texas Instruments) - Pin and Clone Supports (331781)
* Patrick Chuong (Texas Instruments) - Add support for icon overlay in the debug view (Bug 334566)
*****************************************************************/
package org.eclipse.cdt.debug.ui;
import org.eclipse.jface.resource.ImageDescriptor;
import org.eclipse.jface.viewers.ISelection;
import org.eclipse.ui.IWorkbenchPart;
/**
* Debug element that wants to enable pin capability should be adaptable to this interface.
* <br><br>
* When the user presses the 'Pin' action in a view that supports debug context pinning, the
* DebugEventFilterService calls the <code>pin</code> method with the selected debug context.
* If more than one debug context is selected, the <code>pin</code> method is called multiple times.
* The <code>pin</code> method should return a handle for the pinned debug context and when
* there is a debug context change event generated by the debug context manager,
* <code>isPinnedTo</code> will be call by the DebugEventFilterService to determine whether the
* debug context in question is pinned to the handle returned by the <code>pin</code> method.
*
* @since 7.1
*/
public interface IPinProvider {
/**
* Pin element color descriptor.
*/
public interface IPinElementColorDescriptor {
/**
* Default number of color count.
*/
final int DEFAULT_COLOR_COUNT = 3;
/**
* An undefined color
*/
int UNDEFINED = -1;
/**
* Green color (Default)
*/
int GREEN = 0;
/**
* Red color
*/
int RED = 1;
/**
* Blue color
*/
int BLUE = 2;
/**
* Returns the overlay pin color. The overlay pin will be used to decorate the debug view for an element that
* is pinned to a view.
*
* @return one of the overlay colors
*/
int getOverlayColor();
/**
* Returns the toolbar pin action image description to use when the view is pinned, can be <code>null</code>.
* If <code>null</code>, then the default image description will be used.
*
* @return the icon descriptor
*/
ImageDescriptor getToolbarIconDescriptor();
}
/**
* Pin element handler interface.
*/
public interface IPinElementHandle {
/**
* Returns the debug context for this handle.
*
* @return the debug context
*/
Object getDebugContext();
/**
* Returns the label that will be used in the pinned view's description.
*
* @return the handle label
*/
String getLabel();
/**
* Returns color descriptor for this element.
*
* @return the color descriptor, can be <code>null</code>
*/
IPinElementColorDescriptor getPinElementColorDescriptor();
}
/**
* A callback interface that can be used by an IPinProvider to indicate
* that the model has changed for a pinned view and that the view must be
* refreshed.
*
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IPinModelListener {
/**
* Model changed handler that will cause the view to update.
*
* @param newSelection the new selection, if {@code null} the view will blank out.
*
*/
void modelChanged(ISelection newSelection);
}
/**
* Returns whether the debug context is pinnable.
*
* @param part the workbench part
* @param debugContext the debug context in question
* @return true if the debug context is pinnable
*/
boolean isPinnable(IWorkbenchPart part, Object debugContext);
/**
* Pin the debug context and returns a handle for the pinned debug context.
*
* @param part the workbench part
* @param debugContext the debug context to pin to
* @return a handle for the pinned debug context
*/
IPinElementHandle pin(IWorkbenchPart part, Object debugContext, IPinModelListener listener);
/**
* Unpin the debug context for the given pin handle.
*
* @param part the workbench part
* @param handle the handle for the pinned debug context
*/
void unpin(IWorkbenchPart part, IPinElementHandle handle);
/**
* Returns true if the debug context belongs to the handle. If returning true,
* then the debug context change event will be delegated to the view.
*
* @param debugContext the debug context in question
* @param handle an existing pinned debug context handle
* @return true to delegate debug context change event to the view
*/
boolean isPinnedTo(Object debugContext, IPinElementHandle handle);
}