/*******************************************************************************
* Copyright (c) 2010, 2015 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
* Manumitting Technologies Inc - Bug 380609
******************************************************************************/
package org.eclipse.e4.ui.workbench.modeling;
import java.util.List;
import org.eclipse.e4.core.contexts.IEclipseContext;
import org.eclipse.e4.ui.model.application.MApplicationElement;
import org.eclipse.e4.ui.model.application.descriptor.basic.MPartDescriptor;
import org.eclipse.e4.ui.model.application.ui.MElementContainer;
import org.eclipse.e4.ui.model.application.ui.MSnippetContainer;
import org.eclipse.e4.ui.model.application.ui.MUIElement;
import org.eclipse.e4.ui.model.application.ui.SideValue;
import org.eclipse.e4.ui.model.application.ui.advanced.MPerspective;
import org.eclipse.e4.ui.model.application.ui.advanced.MPlaceholder;
import org.eclipse.e4.ui.model.application.ui.basic.MPart;
import org.eclipse.e4.ui.model.application.ui.basic.MPartSashContainerElement;
import org.eclipse.e4.ui.model.application.ui.basic.MTrimBar;
import org.eclipse.e4.ui.model.application.ui.basic.MTrimmedWindow;
import org.eclipse.e4.ui.model.application.ui.basic.MWindow;
import org.eclipse.e4.ui.workbench.Selector;
/**
* This service is used to find, create and handle model elements
*
* @since 1.0
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface EModelService {
// Insertion constants
/** Insert the new element above the existing one */
public static final int ABOVE = 0;
/** Insert the new element below the existing one */
public static final int BELOW = 1;
/** Insert the new element to the left of the existing one */
public static final int LEFT_OF = 2;
/** Insert the new element to the right of the existing one */
public static final int RIGHT_OF = 3;
// Search modifiers / Location Constants
/** Returned Location if the element's parent chain does not relate to the MApplication's model */
public static final int NOT_IN_UI = 0x00;
/** Returned Location if the element is in the UI but not in an MPerspective */
public static final int OUTSIDE_PERSPECTIVE = 0x01;
/** Returned Location if the element is in the currently active perspective */
public static final int IN_ACTIVE_PERSPECTIVE = 0x02;
/** Returned Location if the element is in a non-active perspective */
public static final int IN_ANY_PERSPECTIVE = 0x04;
/** Returned Location if the element is contained in an MArea */
public static final int IN_SHARED_AREA = 0x08;
/** Returned Location if the element is in an MTrimBar */
public static final int IN_TRIM = 0x10;
/**
* Returned Location if the element is in a main menu of an MWindow
*
* @since 1.1
*/
public static final int IN_MAIN_MENU = 0x20;
/**
* Returned Location if the element is in an MPart
*
* @since 1.1
*/
public static final int IN_PART = 0x40;
// 'Standard' searches
/** Searches for elements in the UI that the user is currently seeing (excluding trim) */
public static final int PRESENTATION = OUTSIDE_PERSPECTIVE | IN_ACTIVE_PERSPECTIVE
| IN_SHARED_AREA;
/** Searches for elements in the UI presentation, including all perspectives */
public static final int ANYWHERE = OUTSIDE_PERSPECTIVE | IN_ANY_PERSPECTIVE | IN_SHARED_AREA
| IN_TRIM;
/**
* Searches for elements in the UI that the user is currently seeing that are OUTSIDE the
* perspective (i.e. visible regardless of the current perspective)
*/
public static final int GLOBAL = OUTSIDE_PERSPECTIVE | IN_SHARED_AREA;
/**
* When invoking the 'cloneElement' method the newly cloned element's 'transientData' map will
* contain a reference to the original element using this as a key.
*
* @since 1.1
*/
public static String CLONED_FROM_KEY = "Cloned From"; //$NON-NLS-1$
/**
* Creates instances of model elements. The method supports any type extending
* {@link MApplicationElement}, both in the standard e4 UI model and in an extension models.
*
* <p>
* <b>Caution:</b> To create model element instances of extension models you need to register
* them with the <code>the org.eclipse.e4.workbench.model.definition.enrichment</code>
* ExtensionPoint.
* </p>
*
* @param elementType
* the class to instantiate. Cannot be <code>null</code>
* @return a new instance
* @throws NullPointerException
* if the passed class is <code>null</code>
* @throws IllegalArgumentException
* if the passed class is not supported.
*/
public <T extends MApplicationElement> T createModelElement(Class<T> elementType);
/**
* This is a convenience method that constructs a new Selector based on {@link ElementMatcher}
* and forwards the call on to the base API
* {@link EModelService#findElements(MApplicationElement, Class, int, Selector)}.
*
* @see EModelService#findElements(MApplicationElement, Class, int, Selector)
*/
public <T> List<T> findElements(MUIElement searchRoot, String id, Class<T> clazz,
List<String> tagsToMatch, int searchFlags);
/**
* This is a convenience method that forwards the parameters on to
* {@link EModelService#findElements(MUIElement, String, Class, List, int)}, passing
* {@link EModelService#ANYWHERE} as the 'searchFlags'.
*
*/
public <T> List<T> findElements(MUIElement searchRoot, String id, Class<T> clazz,
List<String> tagsToMatch);
/**
* Return a list of any elements that match the given search criteria. The search is recursive
* and includes the specified search root. Any of the search parameters may be specified as
* <code>null</code> in which case that field will always 'match'.
* <p>
* NOTE: This is a generically typed method with the List's generic type expected to be the
* value of the 'clazz' parameter. If the 'clazz' parameter is null then the returned list is
* untyped.
* </p>
*
* @param <T>
* The generic type of the returned list
* @param searchRoot
* The element at which to start the search. This element must be non-null and is
* included in the search.
* @param clazz
* The type of element to be searched for. If non-null this also defines the return
* type of the List.
* @param searchFlags
* A bitwise combination of the following constants:
* <ul>
* <li><b>OUTSIDE_PERSPECTIVE</b> Include the elements in the window's model that are
* not in a perspective</;i>
* <li><b>IN_ANY_PERSPECTIVE</b> Include the elements in all perspectives</;i>
* <li><b>IN_ACTIVE_PERSPECTIVE</b> Include the elements in the currently active
* perspective only</;i>
* <li><b>IN_MAIN_MENU</b> Include elements in an MWindow's main menu</;i>
* <li><b>IN_PART</b> Include MMenu and MToolbar elements owned by parts</;i>
* <li><b>IN_ACTIVE_PERSPECTIVE</b> Include the elements in the currently active
* perspective only</;i>
* <li><b>IN_SHARED_AREA</b> Include the elements in the shared area</;i>
* <li><b>IN_TRIM</b> Include the elements in the window's trim</;i>
* </ul>
* Note that you may omit both perspective flags but still define
* <b>IN_SHARED_AREA</b>; the flags <b>OUTSIDE_PERSPECTIVE | IN_SHARED_AREA</b> for
* example will search the presentation <i>excluding</i> the elements in perspective
* stacks.
* @param matcher
* An implementation of a Selector that will return true for elements that it wants
* in the returned list.
* @return The generically typed list of matching elements.
*
* @since 1.1
*/
public <T> List<T> findElements(MApplicationElement searchRoot, Class<T> clazz,
int searchFlags, Selector matcher);
/**
* Returns the first element, recursively searching under the specified search root (inclusive)
*
* @param id
* The id to search for, must not be null
* @param searchRoot
* The element at which to start the search, must not be null
* @return The first element with a matching id or <code>null</code> if one is not found
*/
public MUIElement find(String id, MUIElement searchRoot);
/**
* Locate the context that is closest to the given element in the parent hierarchy. It does not
* include the context of the supplied element (should it have one).
*
* @param element
* the element to locate parent context for
* @return the containing context for this element
*/
public IEclipseContext getContainingContext(MUIElement element);
/**
* Brings the specified element to the top of its containment structure. If the specified
* element is a top-level window, then it will be selected as the application's currently active
* window. Otherwise, the element may merely be brought up to be seen by the user but not
* necessarily have its containing window become the application's active window.
*
* @param element
* The element to bring to the top
*/
public void bringToTop(MUIElement element);
/**
* Clones the element, creating a deep copy of its structure.
*
* NOTE: The cloned element gets the original element added into its 'transientData' map using
* the CLONED_FROM_KEY key. This is useful in cases where there may be other information the
* newly cloned element needs from the original.
*
* @param element
* The element to clone
* @param snippetContainer
* An optional MUIElement where the cloned snippet is to be saved. null if the clone
* need not be saved
* @return The newly cloned element
*/
public MUIElement cloneElement(MUIElement element, MSnippetContainer snippetContainer);
/**
* If a snippet with the given id exists a clone is created and returned. returns
* <code>null</code> if no snippet can be found.
*
* @param snippetContainer
* The container of the snippet to clone used
* @param snippetId
* The element id of the snippet to clone
* @param refWin
* The window that Placeholder references should be resolved using
*
* @return The cloned snippet or <code>null</code> if no snippet with the given id can be found
*/
public MUIElement cloneSnippet(MSnippetContainer snippetContainer, String snippetId,
MWindow refWin);
/**
* Convenience method to find a snippet by id in a particular container
*
* @param snippetContainer
* The container to look in
* @param id
* The id of the root element of the snippet
* @return The root element of the snippet or <code>null</code> if none is found
*/
public MUIElement findSnippet(MSnippetContainer snippetContainer, String id);
/**
* Return the count of the children whose 'toBeRendered' flag is true
*
* @param element
* The element to test
* @return the number of children with 'toBeRendered' == true
*/
public int countRenderableChildren(MUIElement element);
/**
* Given a containing MWindow find the MPlaceholder that is currently being used to host the
* given element (if any)
*
* @param window
* The containing window
* @param element
* The element to find the MPlaceholder for
* @return the MPlaceholder or null if none is found
*/
public MPlaceholder findPlaceholderFor(MWindow window, MUIElement element);
/**
* Move the element to a new location. The element will be placed at the end of the new parent's
* list of children.
*
* @param element
* The element to move
* @param newParent
* The new parent for the element.
*/
public <T extends MUIElement> void move(T element, MElementContainer<? super T> newParent);
/**
* Move the element to a new location. The element will be placed at the end of the new parent's
* list of children. If 'leavePlaceholder is true then an instance of MPlaceholder will be
* inserted into the model at the element's original location.
*
* @param element
* The element to move
* @param newParent
* The new parent for the element.
* @param leavePlaceholder
* true if a placeholder for the element should be added
*/
public <T extends MUIElement> void move(T element, MElementContainer<? super T> newParent,
boolean leavePlaceholder);
/**
* Move the element to a new location. The element will be placed at the specified index in the
* new parent's list of children.
*
* @param element
* The element to move
* @param newParent
* The new parent for the element.
* @param index
* The index to insert the element at; -1 means at the end
*/
public <T extends MUIElement> void move(T element, MElementContainer<? super T> newParent, int index);
/**
* Move the element to a new location. The element will be placed at the end of the new parent's
* list of children.
*
* @param element
* The element to move
* @param newParent
* The new parent for the element.
* @param index
* The index to insert the element at; -1 means at the end
* @param leavePlaceholder
* true if a placeholder for the element should be added
*/
public <T extends MUIElement> void move(T element, MElementContainer<? super T> newParent, int index,
boolean leavePlaceholder);
/**
* Inserts the given element into the UI Model by either creating a new sash
* or augmenting an existing sash if the orientation permits.
*
* @param toInsert
* The element to insert
* @param relTo
* The element that the new one is to be relative to
* @param where
* Indication of where the inserted element should be placed:
* {@link #LEFT_OF}, {@link #RIGHT_OF}, {@link #ABOVE},
* {@link #BELOW}.
* @param ratio
* The percentage of the area to be occupied by the inserted
* element; should be a number greater than 0 and less than 1
*/
public void insert(MPartSashContainerElement toInsert, MPartSashContainerElement relTo,
int where, float ratio);
/**
* Created a separate (detached) window containing the given element.
*
* @param mPartSashContainerElement
* The element to detach
* @param x
* The X position of the new window
* @param y
* The Y position of the new window
* @param width
* The Width of the new window
* @param height
* The Height of the new window
*/
public void detach(MPartSashContainerElement mPartSashContainerElement, int x, int y, int width, int height);
/**
* Get the top-level window containing this UI element. A <code>null</code> return value
* indicates that the element is not directly contained in the UI model (but may, for example,
* be a model snippet hosted in a Dialog...)
*
* @param element
* The element to get the window for
*
* @return the top-level window containing this UI element. A <code>null</code> return value
* indicates that the element is not directly contained in the UI model (but may, for
* example, be a model snippet hosted in a Dialog...)
*/
public MWindow getTopLevelWindowFor(MUIElement element);
/**
* @param element
* The element to get the perspective for
* @return The MPerspective containing this element or <code>null</code> if the element is not
* in a perspective
*/
public MPerspective getPerspectiveFor(MUIElement element);
/**
* Returns the window's MTrimBar for the specified side. If necessary the bar will be created.
*
* @param window
* The window to get the trim bar for
* @param sv
* The value for the specified side
*
* @return The appropriate trim bar
*/
public MTrimBar getTrim(MTrimmedWindow window, SideValue sv);
/**
* Return the active perspective for the given window. This is a convenience method that just
* returns the MPerspectiveStack's selectedElement.
*
* @param window
* The window to determine the active perspective for.
*
* @return The active perspective or <code>null</code> if there is no MPerspectiveStack, it's
* empty or has no selected element.
*/
public MPerspective getActivePerspective(MWindow window);
/**
* This is a convenience method that will clean the model of all traces of a given perspective.
* There may be elements (i.e. minimized stacks...) in the window's trim that are associated
* with a perspective as well as the need to properly clean up any detached windows associated
* with the perspective.
*
* @param persp
* the perspective to remove
* @param window
* the window to remove it from
*/
public void resetPerspectiveModel(MPerspective persp, MWindow window);
/**
* Remove the given perspective completely from the model.
*
* @param persp
* the perspective to remove
* @param window
* the window to remove it from
*/
public void removePerspectiveModel(MPerspective persp, MWindow window);
/**
* Count the number of 'toBeRendered' children
*
* @param container
* The container to check
* @return The number of children whose toBeRendered flag is <code>true</code>
*
*/
public int toBeRenderedCount(MElementContainer<?> container);
/**
* Get the container of the given element. This is a convenience method that will always return
* the actual container for the element, even where the element's 'getParent' might return null
* (trim, detached windows...)
*
* @param element
* The element to get the container for
* @return The element's container. This may be <code>null</code> if the element being checked
* is a snippet unattached to the UI Model itself.
*/
public MUIElement getContainer(MUIElement element);
/**
* Given an element this method responds with information about where the element exists within
* the current UI Model. This is used in cases where it is necessary to know if an element is in
* the 'shared area' or outside of any perspective.
*
* @param element
* @return The location of the element in the UI, will be one of:
* <ul>
* <li><b>NOT_IN_UI:</b> The element is not in the UI model at all</li>
* <li><b>OUTSIDE_PERSPECTIVE:</b> The element not within a perspective stack</li>
* <li><b>IN_ACTIVE_PERSPECTIVE:</b> The element is within the currently active
* perspective</li>
* <li><b>IN_ANY_PERSPECTIVE:</b> The element is within a perspective but not the active
* one</li>
* <li><b>IN_SHARED_AREA:</b> The element is within an area that is shared between
* different perspectives</li>
* </ul>
*/
public int getElementLocation(MUIElement element);
/**
* Returns the descriptor for the given part id.
* <p>
* <b>NOTE:</b> In order to support multiple instance parts there is a convention where the
* part's id may be in the form 'partId:secondaryId'. If the given id contains a ':' then only
* the substring before the ':' will be used to find the descriptor.
* </p>
* <p>
* In order to support this convention it's required that no descriptor contain a ':' in its id
* </p>
*
* @param id
* The id of the descriptor to return
* @return The descriptor matching the id or <code>null</code> if none exists
*/
public MPartDescriptor getPartDescriptor(String id);
/**
* Creates a new part from the given descriptor.
*
* @param descriptor
* a part descriptor, must not be <code>null</code>
* @return a new part
* @see EPartService#createPart(String)
* @since 1.5
*/
public MPart createPart(MPartDescriptor descriptor);
/**
* This method ensures that there will never be two placeholders for the same referenced element
* visible in the presentation at the same time. It does this by hiding placeholders which are
* contained in any MPerspective if there is a placeholder for the element in any 'shared' area
* (i.e. visible regardless of which perspective is visible) by setting its 'toBeRendered' state
* to <code>false</code>.
*
* @param window
* The window to modify
* @param perspective
* if non-null specifies the specific perspective to modify, otherwise all
* perspectives in the window are checked
*/
public void hideLocalPlaceholders(MWindow window, MPerspective perspective);
/**
* Returns <code>true</code> iff the supplied element represents the single visible element in
* the shared area. This method is used to test for this condition since (by convention) there
* must be at least one stack in the shared area at all times.
*
* @param stack
* The element to test
* @return <code>true</code> iff the element is the last visible stack
*/
public boolean isLastEditorStack(MUIElement stack);
/**
* Allows an element to be rendered in an arbitrary UI container (I.e. SWT Composite).
*
* @param element
* The element to be rendered.
* @param hostWindow
* The MWindow the element is being hosted under. Must be non-nulland rendered.
* @param uiContainer
* The UI container acting as the rendered element's parent. Must be non-null.
* @param hostContext
* The IEclipseContext to use for hosting the element. Must be non-null.
*/
public void hostElement(MUIElement element, MWindow hostWindow, Object uiContainer,
IEclipseContext hostContext);
/**
* Tests whether the given element is being 'hosted'. This method is used to allow UI Elements
* to act as if they are contained within a given MWindow even though the element is not
* actually structurally contained in that window's UI Model.
*
* @param element
* The element to test. Must be non-null.
* @param hostWindow
* The window to test the element against. Must be non-null.
*
* @return <code>true</code> iff the given element or one of its ancestors is currently being
* hosted in the given MWindow.
*/
public boolean isHostedElement(MUIElement element, MWindow hostWindow);
}