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 Detail

      • ABOVE

        static final int ABOVE
        Insert the new element above the existing one
        See Also:
        Constant Field Values
      • BELOW

        static final int BELOW
        Insert the new element below the existing one
        See Also:
        Constant Field Values
      • LEFT_OF

        static final int LEFT_OF
        Insert the new element to the left of the existing one
        See Also:
        Constant Field Values
      • RIGHT_OF

        static final int RIGHT_OF
        Insert the new element to the right of the existing one
        See Also:
        Constant Field Values
      • 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:
        Constant Field Values
      • OUTSIDE_PERSPECTIVE

        static final int OUTSIDE_PERSPECTIVE
        Returned Location if the element is in the UI but not in an MPerspective
        See Also:
        Constant Field Values
      • IN_ACTIVE_PERSPECTIVE

        static final int IN_ACTIVE_PERSPECTIVE
        Returned Location if the element is in the currently active perspective
        See Also:
        Constant Field Values
      • IN_ANY_PERSPECTIVE

        static final int IN_ANY_PERSPECTIVE
        Returned Location if the element is in a non-active perspective
        See Also:
        Constant Field Values
      • IN_SHARED_AREA

        static final int IN_SHARED_AREA
        Returned Location if the element is contained in an MArea
        See Also:
        Constant Field Values
      • IN_TRIM

        static final int IN_TRIM
        Returned Location if the element is in an MTrimBar
        See Also:
        Constant Field Values
      • 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:
        Constant Field Values
      • IN_PART

        static final int IN_PART
        Returned Location if the element is in an MPart
        Since:
        1.1
        See Also:
        Constant Field Values
      • PRESENTATION

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

        static final int ANYWHERE
        Searches for elements in the UI presentation, including all perspectives
        See Also:
        Constant Field Values
      • 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:
        Constant Field Values
      • 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:
        Constant Field Values
    • Method Detail

      • 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)
        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
        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 -
        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
      • 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.