plugins/org.eclipse.graphiti/src/org/eclipse/graphiti/tb/IToolBehaviorProvider.java

/*******************************************************************************
 * <copyright>
 *
 * Copyright (c) 2005, 2019 SAP AG.
 * 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:
 *    SAP AG - initial API, implementation and documentation
 *    mwenz - Bug 341224: Allow to hide the selection and marquee tools in the palette
 *    mwenz - Bug 363796 - Make setting of selection width of connections public
 *    mgorning - Bug 363186 - Allow modification of selection and hover state also for anchors
 *    mgorning - Bug 391523 - Revise getSelectionInfo...() in IToolBehaviorProvider
 *    fvelasco - Bug 323349 - Enable external invocation of features
 *    mwenz - Bug 428068 - Automatically unselect a tool entry in palette like 'connection creation' after execution
 *    mwenz - Bug 434458 - Connections don't support Color decorators
 *    mwenz - Bug 520392 - Hard coded error message when entering an empty string in direct editing
 *    Hubert Guerard, mwenz - Bug 543847 - Add capability to select several PictogramElement from a selection of PictogramElement
 * </copyright>
 *
 *******************************************************************************/
package org.eclipse.graphiti.tb;

import java.awt.Polygon;

import org.eclipse.graphiti.DiagramScrollingBehavior;
import org.eclipse.graphiti.IExecutionInfo;
import org.eclipse.graphiti.features.IDirectEditingFeature;
import org.eclipse.graphiti.features.context.ICustomContext;
import org.eclipse.graphiti.features.context.IDirectEditingContext;
import org.eclipse.graphiti.features.context.IDoubleClickContext;
import org.eclipse.graphiti.features.context.IPictogramElementContext;
import org.eclipse.graphiti.features.context.ISingleClickContext;
import org.eclipse.graphiti.features.context.impl.CustomContext;
import org.eclipse.graphiti.features.custom.ICustomFeature;
import org.eclipse.graphiti.features.impl.IIndependenceSolver;
import org.eclipse.graphiti.mm.algorithms.AbstractText;
import org.eclipse.graphiti.mm.algorithms.GraphicsAlgorithm;
import org.eclipse.graphiti.mm.algorithms.Polyline;
import org.eclipse.graphiti.mm.algorithms.styles.Color;
import org.eclipse.graphiti.mm.algorithms.styles.Font;
import org.eclipse.graphiti.mm.algorithms.styles.TextStyle;
import org.eclipse.graphiti.mm.pictograms.Anchor;
import org.eclipse.graphiti.mm.pictograms.Connection;
import org.eclipse.graphiti.mm.pictograms.ContainerShape;
import org.eclipse.graphiti.mm.pictograms.PictogramElement;
import org.eclipse.graphiti.mm.pictograms.Shape;
import org.eclipse.graphiti.palette.IConnectionCreationToolEntry;
import org.eclipse.graphiti.palette.IPaletteCompartmentEntry;
import org.eclipse.graphiti.util.ILocationInfo;

/**
 * The Interface IToolBehaviorProvider.
 * 
 * @noimplement This interface is not intended to be implemented by clients,
 *              extend {@link DefaultToolBehaviorProvider} instead
 * @noextend This interface is not intended to be extended by clients.
 */
public interface IToolBehaviorProvider {

	/**
	 * Returns the context button pad data for the given pictogram element
	 * context. The context button pad data defines, which context buttons to
	 * show for a given pictogram element. Can return null, if no there is no
	 * context button pad for the given pictogram element.
	 * 
	 * @param context
	 *            The pictogram element context, for which to return the context
	 *            button pad data.
	 * @return The context button pad data for the given pictogram element
	 *         context.
	 */
	IContextButtonPadData getContextButtonPad(IPictogramElementContext context);

	/**
	 * Returns the context menu for the current mouse location.
	 * 
	 * @param context
	 *            the custom context which contains the info about the location
	 *            where the context menu appears.
	 * @return the context menu
	 */
	IContextMenuEntry[] getContextMenu(ICustomContext context);

	/**
	 * Return the palette entries for the palette of the graphical editor.
	 * Typically these entries are a subset of CreateFeatures and
	 * CreateConnectionFeatures which are provided by the feature provider.
	 * 
	 * @return the palette entries
	 */
	IPaletteCompartmentEntry[] getPalette();

	/**
	 * Returns a feature which will be executed at at double click. For that
	 * purpose a custom feature is used, because custom features appear in the
	 * context menu and the double click feature should also appear in the
	 * context menu (usual UI guideline).
	 * 
	 * @param context
	 *            contains information where the double click gesture has
	 *            happened
	 * @return the feature to execute
	 */
	ICustomFeature getDoubleClickFeature(IDoubleClickContext context);

	/**
	 * Returns a feature which will be executed at at a single click on an
	 * already selected shape. If the feature provider already returned a direct
	 * editing feature for that single click, then this method will not be
	 * called.
	 * 
	 * @param context
	 *            contains information where the single click gesture has
	 *            happened
	 * @return the feature to execute
	 * @since 0.10
	 */
	ICustomFeature getSingleClickFeature(ISingleClickContext context);

	/**
	 * Command features can do anything, but they are tied to an external
	 * command. They can be invoked through a keybinding, a menu action or a
	 * toolbar item.
	 * 
	 * @param context
	 *            the context
	 * @param hint
	 *            the hint specified in the command binding
	 * 
	 * @return the feature
	 * @since 0.10
	 */
	ICustomFeature getCommandFeature(CustomContext context, String hint);

	/**
	 * Returns decorators which will be used at rendering time to decorate the
	 * graphical representation of the given pictogram element. Adding or
	 * removing decorators will not make the diagram dirty.<br>
	 * Decorators of type {@link IImageDecorator}, {@link IColorDecorator} and
	 * {@link IBorderDecorator} are supported for {@link Shape}s; for
	 * {@link Connection}s only {@link IColorDecorator}s are supported and they
	 * can only be used to change the foreground color of the {@link Connection}
	 * .
	 * 
	 * @param pe
	 *            the pictogram element
	 * @return the decorators
	 */
	IDecorator[] getDecorators(PictogramElement pe);

	/**
	 * Returns the adapter for the specified key. This method will be called in
	 * the getAdapter() method of the graphical editor.
	 * 
	 * @param type
	 *            the type
	 * @return the adapter
	 */
	Object getAdapter(Class<?> type);

	/**
	 * Override this method if you want to change the default selection on mouse
	 * click.
	 * 
	 * @param originalPe
	 *            the original pictogram element
	 * @param oldSelection
	 *            the old selection
	 * @return an active pictogram element to be selected instead; return
	 *         <code>null</code> if there should not be a special selection
	 *         behavior; if there should not be a selection simply return the
	 *         diagram
	 */
	PictogramElement getSelection(PictogramElement originalPe, PictogramElement[] oldSelection);

	/**
	 * @since 0.16
	 */
	PictogramElement[] getSelections(PictogramElement selection);

	/**
	 * Override this method if you want to change the default scrolling behavior
	 * of the diagram. The default is DiagramScrollingBehavior.GEF_DEFAULT: the
	 * empty diagram comes up without scroll bars. The scroll bars start to
	 * appear when objects are moved to the outside of the currently visible
	 * area. For permanently visible scroll bars, return the value
	 * DiagramScrollingBehavior.SCROLLBARS_PERMANENTLY_VISIBLE.
	 * 
	 * @return The DiagramScrollingBehavior
	 * @deprecated Scroll bar based infinite canvas is a workaround for GEF
	 *             limitations.
	 * 
	 * @see DefaultToolBehaviorProvider#getDiagramScrollingBehavior()
	 */
	@Deprecated
	DiagramScrollingBehavior getDiagramScrollingBehavior();

	/**
	 * Gets the zoom levels.
	 * 
	 * @return the zoom levels
	 */
	double[] getZoomLevels();

	/**
	 * Dispose.
	 */
	void dispose();

	/**
	 * Return the selection info for the given shape.
	 * 
	 * @param shape
	 *            the shape
	 * @return the shape selection info
	 * @since 0.10
	 */
	IShapeSelectionInfo getSelectionInfoForShape(Shape shape);

	/**
	 * Return the selection info for the given anchor.
	 * 
	 * @param anchor
	 *            the anchor
	 * @return the anchor selection info
	 * @since 0.10
	 */
	IAnchorSelectionInfo getSelectionInfoForAnchor(Anchor anchor);

	/**
	 * Return the selection info for the given connection.
	 * 
	 * @param connection
	 *            the connection
	 * @return the connection selection info
	 * @since 0.10
	 */
	IConnectionSelectionInfo getSelectionInfoForConnection(Connection connection);

	/**
	 * Returns the location info which will be used for direct editing if the
	 * framework cannot decide this. E.g. a shape is selected and the user
	 * presses F2 but the mouse is outside the shape.
	 * 
	 * @param pe
	 *            the active and selected pictogram element
	 * @param currentLocationInfo
	 *            the current location info determined by the framework
	 * @return the location info for the given selected pictogram element
	 */
	ILocationInfo getLocationInfo(PictogramElement pe, ILocationInfo currentLocationInfo);

	/**
	 * Called before execution on stack. Overriding this method can be necessary
	 * if any additional actions have to be processed before the stack will be
	 * executed.
	 * 
	 * @param executionInfo
	 *            info about content to be executed
	 */
	void preExecute(IExecutionInfo executionInfo);

	/**
	 * Called after execution on stack. Overriding this method can be necessary
	 * if any additional actions have to be processed after the stack will be
	 * executed. As example a tool could process an automatic layout of the
	 * diagram after each diagram modification.
	 * 
	 * @param executionInfo
	 *            info about content to be executed
	 */
	void postExecute(IExecutionInfo executionInfo);

	/**
	 * Returns the tooltip to be attached to the graphical representation of the
	 * given graphics algorithm. <br>
	 * <p>
	 * It can either be a String, creating a simple tooltip, or an AbstractText.
	 * In the latter case, a rich text label would be created, respecting the
	 * contained {@link TextStyle}s.
	 * 
	 * <p>
	 * Since the pictogram element doesn't belong to the diagram, you have to be
	 * careful with the {@link Color}s and {@link Font}s used in the
	 * {@link TextStyle}s within the {@link AbstractText}. <strong>They should
	 * be created and added to the diagram beforehand</strong>, preferably in
	 * the add feature that created the given graphicsAlgorithm, i.e.:
	 * <p>
	 * Somewhere in the <em>add</em> method of the <em>addFeature</em>
	 * :<blockquote>
	 * 
	 * <pre>
	 * manageFont(diagram, &quot;Verdana&quot;, 9, true, false);
	 * </pre>
	 * 
	 * </blockquote>
	 * <p>
	 * Inside the <em>getRichToolTip</em>:<blockquote>
	 * 
	 * <pre>
	 * Font font = manageFont(getDiagramTypeProvider().getDiagram(), &quot;Verdana&quot;, 9, true, false);
	 * textStyle.setFont(font);
	 * </pre>
	 * 
	 * </blockquote>
	 * <p>
	 * This will ensure resource management for both fonts and colors, and
	 * prevent transaction read-only errors if trying to add a font o a color to
	 * the diagram without a write transaction.
	 * <p>
	 * <strong>Note</strong>: Be extremely careful when adding rich text
	 * tooltips to an previously existing diagram. Since the pictograms may have
	 * already been added to the diagram, the tooltip may cause an
	 * {@link IllegalStateException} if trying to use a resource that was not
	 * previously added to the diagram.
	 * 
	 * @param graphicsAlgorithm
	 *            the graphics algorithm
	 * @return the tooltip
	 * @since 0.10
	 */
	Object getToolTip(GraphicsAlgorithm graphicsAlgorithm);

	/**
	 * The returned graphics algorithm defines the selection border and the
	 * rectangle where the context buttons appear at.
	 * 
	 * @param pe
	 *            the pictogram element
	 * @return the graphics algorithm which defines the selection border
	 */
	GraphicsAlgorithm getSelectionBorder(PictogramElement pe);

	/**
	 * The returned graphics algorithm defines the technical container for
	 * active children. Currently implementers have to secure to deliver a
	 * (Rounded)Rectangle. Does not make sense for other types of graphics
	 * algorithm.
	 * 
	 * @param cs
	 *            the container shape
	 * @return the graphics algorithm acting as technical container
	 */
	GraphicsAlgorithm getContentArea(ContainerShape cs);

	/**
	 * The returned graphics algorithm's define the area where the user can
	 * click to select the shape.
	 * 
	 * @param pe
	 *            the pictogram element
	 * @return the click area
	 */
	GraphicsAlgorithm[] getClickArea(PictogramElement pe);

	/**
	 * Provides the graphics algorithm that defines the outline for the given
	 * pictogram element's chopbox Anchor.
	 * 
	 * @param pe
	 *            the given pictogram element
	 * @return the graphics algorithm that defines the outline for connections
	 *         from or to the shape's chopbox anchor
	 */
	GraphicsAlgorithm getChopboxAnchorArea(PictogramElement pe);

	/**
	 * Returns a tooltip for the workbench titlebar.
	 * 
	 * @return a tooltip or <code>null</code> to indicate that the default from
	 *         the graphics framework will be used
	 */
	String getTitleToolTip();

	/**
	 * Indicates whether guides will be shown or not.
	 * 
	 * @return <code>true</code>, if guides should be shown
	 */
	boolean isShowGuides();

	/**
	 * Indicates whether flyout palette will be shown or not.
	 * 
	 * @return <code>true</code>, if flyout palette should be shown
	 * @since 0.9
	 */
	boolean isShowFlyoutPalette();

	/**
	 * Indicates whether the selection tool shall be added to the palette or not
	 * 
	 * @return <code>true</code>, if the selection tool shall be added,
	 *         <code>false</code> otherwise
	 * 
	 * @since 0.9
	 */
	boolean isShowSelectionTool();

	/**
	 * Indicates whether the marquee tool shall be added to the palette or not
	 * 
	 * @return <code>true</code>, if the marquee tool shall be added,
	 *         <code>false</code> otherwise
	 * 
	 * @since 0.9
	 */
	boolean isShowMarqueeTool();

	/**
	 * Indicates if the selection of multiple elements is enabled. Override this
	 * method and return <code>false</code> if an editor with single selection
	 * behavior is needed.
	 * 
	 * @return <code>false</code>, if single selection is enforced
	 */
	boolean isMultiSelectionEnabled();

	/**
	 * Indicates if the selection of connections is enabled.
	 * 
	 * @return <code>true</code>, if selection of connections is enabled
	 */
	boolean isConnectionSelectionEnabled();

	/**
	 * Returns the contributor ID for the tabbed property sheet page.
	 * 
	 * @return the contributor ID for the tabbed property sheet page.
	 */
	public String getContributorId();

	/**
	 * Decides if business objects are equal. The framework uses this method
	 * only for EMF business objects. For the non-EMF case,
	 * {@link IIndependenceSolver} is responsible.
	 * 
	 * @return true if the business objects are deemed equal, false otherwise.
	 * @since 0.8
	 */
	public boolean equalsBusinessObjects(Object o1, Object o2);

	/**
	 * Is asked to return the selection width (the tolerance area a user can
	 * click to still select) a lathy object (e.g. {@link Polyline} or
	 * {@link Polygon} for {@link Shape}s and {@link Connection}s) in the
	 * diagram. The method is called when a new object is drawn for the first
	 * time onto a diagram (on creation of the object or on opening the
	 * diagram).
	 * 
	 * @param polyline
	 *            the {@link Polyline} object to get the selection width for
	 * @return an int representing the allowed tolerance for clicking in pixels
	 * 
	 * @since 0.9
	 */
	public int getLineSelectionWidth(Polyline polyline);

	/**
	 * Defines if the tool created for the given
	 * {@link IConnectionCreationToolEntry} stays active after a connection has
	 * been created or not. The default behavior in the GEF framework is
	 * <code>true</code>, which is also the return value of the default
	 * implementation in
	 * {@link DefaultToolBehaviorProvider#isStayActiveAfterExecution(IConnectionCreationToolEntry)}
	 * . This method is queried by the framework when the tool is created from
	 * the palette entry.
	 * 
	 * @return <code>true</code> in case the tool should stay active after
	 *         execution, <code>false</code> otherwise.
	 * 
	 * @since 0.11
	 */
	public boolean isStayActiveAfterExecution(IConnectionCreationToolEntry connectionCreationToolEntry);

	/**
	 * Returns the title of the popup that appears when a user provides an
	 * invalid input for direct editing. The default implementation returns 'Can
	 * not edit value'.
	 * 
	 * @param feature
	 *            The {@link IDirectEditingFeature} that was invoked
	 * @param context
	 *            The {@link IDirectEditingContext} that was used.
	 * @return A {@link String} representing the title of the popup to present
	 *         to the user.
	 * @since 0.15
	 */
	public String getDirectEditingInvalidNotificationTitle(IDirectEditingFeature feature,
			IDirectEditingContext context);
}