| /********************************************************************* |
| * Copyright (c) 2005, 2019 SAP SE and others |
| * |
| * This program and the accompanying materials are made |
| * available under the terms of the Eclipse Public License 2.0 |
| * which is available at https://www.eclipse.org/legal/epl-2.0/ |
| * |
| * Contributors: |
| * SAP SE - 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 |
| * |
| * SPDX-License-Identifier: EPL-2.0 |
| **********************************************************************/ |
| 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, "Verdana", 9, true, false); |
| * </pre> |
| * |
| * </blockquote> |
| * <p> |
| * Inside the <em>getRichToolTip</em>:<blockquote> |
| * |
| * <pre> |
| * Font font = manageFont(getDiagramTypeProvider().getDiagram(), "Verdana", 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); |
| } |