Package org.eclipse.e4.ui.workbench.modeling

Interface EModelService

public interface EModelService
This service is used to find, create and handle model elements
Since:
1.0
Restriction:
This interface is not intended to be implemented by clients.

  • Field Details

    • ABOVE

      static final int ABOVE
      Insert the new element above the existing one
      See Also:

    • BELOW

      static final int BELOW
      Insert the new element below the existing one
      See Also:

    • LEFT_OF

      static final int LEFT_OF
      Insert the new element to the left of the existing one
      See Also:

    • RIGHT_OF

      static final int RIGHT_OF
      Insert the new element to the right of the existing one
      See Also:

    • NOT_IN_UI

      static final int NOT_IN_UI
      Returned Location if the element's parent chain does not relate to the MApplication's model
      See Also:

    • OUTSIDE_PERSPECTIVE

      static final int OUTSIDE_PERSPECTIVE
      Returned Location if the element is in the UI but not in an MPerspective
      See Also:

    • IN_ACTIVE_PERSPECTIVE

      static final int IN_ACTIVE_PERSPECTIVE
      Returned Location if the element is in the currently active perspective
      See Also:

    • IN_ANY_PERSPECTIVE

      static final int IN_ANY_PERSPECTIVE
      Returned Location if the element is in a non-active perspective
      See Also:

    • IN_SHARED_AREA

      static final int IN_SHARED_AREA
      Returned Location if the element is contained in an MArea
      See Also:

    • IN_TRIM

      static final int IN_TRIM
      Returned Location if the element is in an MTrimBar
      See Also:

    • IN_MAIN_MENU

      static final int IN_MAIN_MENU
      Returned Location if the element is in a main menu of an MWindow
      Since:
      1.1
      See Also:

    • IN_PART

      static final int IN_PART
      Returned Location if the element is in an MPart
      Since:
      1.1
      See Also:

    • IN_SHARED_ELEMENTS

      static final int IN_SHARED_ELEMENTS
      Returned Location if the element is in SharedElements
      Since:
      1.11
      See Also:

    • PRESENTATION

      static final int PRESENTATION
      Searches for elements in the UI that the user is currently seeing (excluding trim)
      See Also:

    • ANYWHERE

      static final int ANYWHERE
      Searches for elements in the UI presentation, including all perspectives
      See Also:

    • GLOBAL

      static final int GLOBAL
      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)
      See Also:

    • CLONED_FROM_KEY

      static final String CLONED_FROM_KEY
      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
      See Also:

  • Method Details

    • createModelElement

      <T extends MApplicationElement> T createModelElement(Class<T> elementType)
      Creates instances of model elements. The method supports any type extending MApplicationElement, both in the standard e4 UI model and in an extension models.

      Caution: To create model element instances of extension models you need to register them with the the org.eclipse.e4.workbench.model.definition.enrichment ExtensionPoint.

      Parameters:
      elementType - the class to instantiate. Cannot be null
      Returns:
      a new instance
      Throws:
      NullPointerException - if the passed class is null
      IllegalArgumentException - if the passed class is not supported.

    • deleteModelElement

      void deleteModelElement(MUIElement element)
      Removes a visual model element from the application model by calling MUIElement.setToBeRendered(boolean) with false and by removing the model element from its parent.
      Parameters:
      element - - model
      Since:
      1.9

    • findElements

      <T> List<T> findElements(MUIElement searchRoot, String id, Class<T> clazz, List<String> tagsToMatch, int searchFlags)
      This is a convenience method that constructs a new Selector based on ElementMatcher and forwards the call on to the base API findElements(MApplicationElement, Class, int, Selector).
      Parameters:
      searchRoot - The element at which to start the search. This element must be non-null and is included in the search.
      id - The id of the element search for, can be null
      clazz - The type of element to be searched for. If non-null this also defines the return type of the List.
      tagsToMatch - List of tags that needs to match.
      searchFlags - A bitwise combination of the following constants:
      • OUTSIDE_PERSPECTIVE Include the elements in the window's model that are not in a perspective
      • IN_ANY_PERSPECTIVE Include the elements in all perspectives
      • IN_ACTIVE_PERSPECTIVE Include the elements in the currently active perspective only
      • IN_MAIN_MENU Include elements in an MWindow's main menu
      • IN_PART Include MMenu and MToolbar elements owned by parts
      • IN_ACTIVE_PERSPECTIVE Include the elements in the currently active perspective only
      • IN_SHARED_AREA Include the elements in the shared area
      • IN_TRIM Include the elements in the window's trim
      • IN_SHARED_ELEMENTS Include the elements in the window's Shared Elements
      Note that you may omit both perspective flags but still define IN_SHARED_AREA; the flags OUTSIDE_PERSPECTIVE | IN_SHARED_AREA for example will search the presentation excluding the elements in perspective stacks.
      Returns:
      The generically typed list of matching elements.
      See Also:

    • findElements

      <T> List<T> findElements(MUIElement searchRoot, String id, Class<T> clazz, List<String> tagsToMatch)
      This is a convenience method that forwards the parameters on to findElements(MUIElement, String, Class, List, int), passing ANYWHERE as the 'searchFlags'.
      Parameters:
      searchRoot - The element at which to start the search. This element must be non-null and is included in the search.
      id - The id of the element search for, can be null
      clazz - The type of element to be searched for. If non-null this also defines the return type of the List.
      tagsToMatch - List of tags that needs to match.
      Returns:
      The generically typed list of matching elements.

    • findElements

      <T> List<T> findElements(MUIElement searchRoot, String id, Class<T> clazz)
      This is a convenience method that forwards the parameters on to findElements(MUIElement, String, Class, List), passing null as 'tagsToMatch'.
      Parameters:
      searchRoot - The element at which to start the search. This element must be non-null and is included in the search.
      id - The id of the element search for, can be null
      clazz - The type of element to be searched for. If non-null this also defines the return type of the List.
      Returns:
      The generically typed list of matching elements.
      Since:
      1.8

    • findElements

      <T> List<T> findElements(MApplicationElement searchRoot, Class<T> clazz, int searchFlags, Selector matcher)
      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 null in which case that field will always 'match'.

      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.

      Type Parameters:
      T - The generic type of the returned list
      Parameters:
      searchRoot - The element at which to start the search. This element must be non-null and is included in the search.
      clazz - The type of element to be searched for. If non-null this also defines the return type of the List.
      searchFlags - A bitwise combination of the following constants:
      • OUTSIDE_PERSPECTIVE Include the elements in the window's model that are not in a perspective
      • IN_ANY_PERSPECTIVE Include the elements in all perspectives
      • IN_ACTIVE_PERSPECTIVE Include the elements in the currently active perspective only
      • IN_MAIN_MENU Include elements in an MWindow's main menu
      • IN_PART Include MMenu and MToolbar elements owned by parts
      • IN_ACTIVE_PERSPECTIVE Include the elements in the currently active perspective only
      • IN_SHARED_AREA Include the elements in the shared area
      • IN_TRIM Include the elements in the window's trim
      • IN_SHARED_ELEMENTS Include the elements in the window's Shared Elements
      Note that you may omit both perspective flags but still define IN_SHARED_AREA; the flags OUTSIDE_PERSPECTIVE | IN_SHARED_AREA for example will search the presentation excluding the elements in perspective stacks.
      matcher - An implementation of a Selector that will return true for elements that it wants in the returned list.
      Returns:
      The generically typed list of matching elements.
      Since:
      1.1

    • find

      MUIElement find(String id, MUIElement searchRoot)
      Returns the first element, recursively searching under the specified search root (inclusive)
      Parameters:
      id - The id to search for, must not be null
      searchRoot - The element at which to start the search, must not be null
      Returns:
      The first element with a matching id or null if one is not found

    • getContainingContext

      IEclipseContext getContainingContext(MUIElement element)
      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).
      Parameters:
      element - the element to locate parent context for
      Returns:
      the containing context for this element

    • bringToTop

      void bringToTop(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.
      Parameters:
      element - The element to bring to the top

    • cloneElement

      MUIElement cloneElement(MUIElement element, MSnippetContainer snippetContainer)
      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.
      Parameters:
      element - The element to clone
      snippetContainer - An optional MUIElement where the cloned snippet is to be saved. null if the clone need not be saved
      Returns:
      The newly cloned element

    • cloneSnippet

      MUIElement cloneSnippet(MSnippetContainer snippetContainer, String snippetId, MWindow refWin)
      If a snippet with the given id exists a clone is created and returned. returns null if no snippet can be found.
      Parameters:
      snippetContainer - The container of the snippet to clone used
      snippetId - The element id of the snippet to clone
      refWin - The window that Placeholder references should be resolved using
      Returns:
      The cloned snippet or null if no snippet with the given id can be found

    • findSnippet

      MUIElement findSnippet(MSnippetContainer snippetContainer, String id)
      Convenience method to find a snippet by id in a particular container
      Parameters:
      snippetContainer - The container to look in
      id - The id of the root element of the snippet
      Returns:
      The root element of the snippet or null if none is found

    • countRenderableChildren

      int countRenderableChildren(MUIElement element)
      Return the count of the children whose 'toBeRendered' flag is true
      Parameters:
      element - The element to test
      Returns:
      the number of children with 'toBeRendered' == true

    • findPlaceholderFor

      MPlaceholder findPlaceholderFor(MWindow window, MUIElement element)
      Given a containing MWindow find the MPlaceholder that is currently being used to host the given element (if any)
      Parameters:
      window - The containing window
      element - The element to find the MPlaceholder for
      Returns:
      the MPlaceholder or null if none is found

    • move

      <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.
      Parameters:
      element - The element to move
      newParent - The new parent for the element.

    • move

      <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 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.
      Parameters:
      element - The element to move
      newParent - The new parent for the element.
      leavePlaceholder - true if a placeholder for the element should be added

    • move

      <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 specified index in the new parent's list of children.
      Parameters:
      element - The element to move
      newParent - The new parent for the element.
      index - The index to insert the element at; -1 means at the end

    • move

      <T extends MUIElement> void move(T element, MElementContainer<? super T> newParent, int index, boolean leavePlaceholder)
      Move the element to a new location. The element will be placed at the end of the new parent's list of children.
      Parameters:
      element - The element to move
      newParent - The new parent for the element.
      index - The index to insert the element at; -1 means at the end
      leavePlaceholder - true if a placeholder for the element should be added

    • insert

      void insert(MPartSashContainerElement toInsert, MPartSashContainerElement relTo, int where, float ratio)
      Inserts the given element into the UI Model by either creating a new sash or augmenting an existing sash if the orientation permits.
      Parameters:
      toInsert - The element to insert
      relTo - The element that the new one is to be relative to
      where - Indication of where the inserted element should be placed: LEFT_OF, RIGHT_OF, ABOVE, BELOW.
      ratio - The percentage of the area to be occupied by the inserted element; should be a number greater than 0 and less than 1

    • detach

      void detach(MPartSashContainerElement mPartSashContainerElement, int x, int y, int width, int height)
      Created a separate (detached) window containing the given element.
      Parameters:
      mPartSashContainerElement - The element to detach
      x - The X position of the new window
      y - The Y position of the new window
      width - The Width of the new window
      height - The Height of the new window

    • getTopLevelWindowFor

      MWindow getTopLevelWindowFor(MUIElement element)
      Get the top-level window containing this UI element. A null 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...)
      Parameters:
      element - The element to get the window for
      Returns:
      the top-level window containing this UI element. A null 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...)

    • getPerspectiveFor

      MPerspective getPerspectiveFor(MUIElement element)
      Parameters:
      element - The element to get the perspective for
      Returns:
      The MPerspective containing this element or null if the element is not in a perspective

    • getTrim

      MTrimBar getTrim(MTrimmedWindow window, SideValue sv)
      Returns the window's MTrimBar for the specified side. If necessary the bar will be created.
      Parameters:
      window - The window to get the trim bar for
      sv - The value for the specified side
      Returns:
      The appropriate trim bar

    • getActivePerspective

      MPerspective getActivePerspective(MWindow window)
      Return the active perspective for the given window. This is a convenience method that just returns the MPerspectiveStack's selectedElement.
      Parameters:
      window - The window to determine the active perspective for.
      Returns:
      The active perspective or null if there is no MPerspectiveStack, it's empty or has no selected element.

    • resetPerspectiveModel

      void resetPerspectiveModel(MPerspective persp, 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.
      Parameters:
      persp - the perspective to remove
      window - the window to remove it from

    • removePerspectiveModel

      void removePerspectiveModel(MPerspective persp, MWindow window)
      Remove the given perspective completely from the model.
      Parameters:
      persp - the perspective to remove
      window - the window to remove it from

    • toBeRenderedCount

      int toBeRenderedCount(MElementContainer<?> container)
      Count the number of 'toBeRendered' children
      Parameters:
      container - The container to check
      Returns:
      The number of children whose toBeRendered flag is true

    • getContainer

      MUIElement getContainer(MUIElement element)
      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...)
      Parameters:
      element - The element to get the container for
      Returns:
      The element's container. This may be null if the element being checked is a snippet unattached to the UI Model itself.

    • getElementLocation

      int getElementLocation(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.
      Parameters:
      element - the element of interest
      Returns:
      The location of the element in the UI, will be one of:
      • NOT_IN_UI: The element is not in the UI model at all
      • OUTSIDE_PERSPECTIVE: The element not within a perspective stack
      • IN_ACTIVE_PERSPECTIVE: The element is within the currently active perspective
      • IN_ANY_PERSPECTIVE: The element is within a perspective but not the active one
      • IN_SHARED_AREA: The element is within an area that is shared between different perspectives

    • getPartDescriptor

      MPartDescriptor getPartDescriptor(String id)
      Returns the descriptor for the given part id.

      NOTE: 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.

      In order to support this convention it's required that no descriptor contain a ':' in its id

      Parameters:
      id - The id of the descriptor to return
      Returns:
      The descriptor matching the id or null if none exists

    • createPart

      MPart createPart(MPartDescriptor descriptor)
      Creates a new part from the given descriptor.
      Parameters:
      descriptor - a part descriptor, must not be null
      Returns:
      a new part
      Since:
      1.5
      See Also:

    • hideLocalPlaceholders

      void hideLocalPlaceholders(MWindow window, MPerspective perspective)
      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 false.
      Parameters:
      window - The window to modify
      perspective - if non-null specifies the specific perspective to modify, otherwise all perspectives in the window are checked

    • isLastEditorStack

      boolean isLastEditorStack(MUIElement stack)
      Returns true 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.
      Parameters:
      stack - The element to test
      Returns:
      true iff the element is the last visible stack

    • hostElement

      void hostElement(MUIElement element, MWindow hostWindow, Object uiContainer, IEclipseContext hostContext)
      Allows an element to be rendered in an arbitrary UI container (I.e. SWT Composite).
      Parameters:
      element - The element to be rendered.
      hostWindow - The MWindow the element is being hosted under. Must be non-nulland rendered.
      uiContainer - The UI container acting as the rendered element's parent. Must be non-null.
      hostContext - The IEclipseContext to use for hosting the element. Must be non-null.

    • isHostedElement

      boolean isHostedElement(MUIElement element, MWindow hostWindow)
      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.
      Parameters:
      element - The element to test. Must be non-null.
      hostWindow - The window to test the element against. Must be non-null.
      Returns:
      true iff the given element or one of its ancestors is currently being hosted in the given MWindow.