org.eclipse.e4.ui.internal.workbench

Class ModelServiceImpl

java.lang.Object

org.eclipse.e4.ui.internal.workbench.ModelServiceImpl

All Implemented Interfaces:

EModelService

public class ModelServiceImpl
extends java.lang.Object
implements EModelService

Field Summary

Fields inherited from interface org.eclipse.e4.ui.workbench.modeling.EModelService

ABOVE, ANYWHERE, BELOW, CLONED_FROM_KEY, GLOBAL, IN_ACTIVE_PERSPECTIVE, IN_ANY_PERSPECTIVE, IN_MAIN_MENU, IN_PART, IN_SHARED_AREA, IN_TRIM, LEFT_OF, NOT_IN_UI, OUTSIDE_PERSPECTIVE, PRESENTATION, RIGHT_OF

Constructor Summary

Constructors

Constructor and Description
ModelServiceImpl(IEclipseContext appContext) This is a singleton service.

Method Summary

Modifier and Type	Method and Description
void	bringToTop(MUIElement element) Brings the specified element to the top of its containment structure.
MUIElement	cloneElement(MUIElement element, MSnippetContainer snippetContainer) Clones the element, creating a deep copy of its structure.
MUIElement	cloneSnippet(MSnippetContainer snippetContainer, java.lang.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.
int	countRenderableChildren(MUIElement element) Return the count of the children whose 'toBeRendered' flag is true
<T extends MApplicationElement> T	createModelElement(java.lang.Class<T> elementType) Creates instances of model elements.
MPart	createPart(MPartDescriptor descriptor) Creates a new part from the given descriptor.
void	detach(MPartSashContainerElement element, int x, int y, int width, int height) Created a separate (detached) window containing the given element.
MUIElement	find(java.lang.String id, MUIElement searchRoot) Returns the first element, recursively searching under the specified search root (inclusive)
<T> java.util.List<T>	findElements(MApplicationElement searchRoot, java.lang.Class<T> clazz, int searchFlags, Selector matcher) Return a list of any elements that match the given search criteria.
<T> java.util.List<T>	findElements(MUIElement searchRoot, java.lang.String id, java.lang.Class<T> clazz, java.util.List<java.lang.String> tagsToMatch) This is a convenience method that forwards the parameters on to EModelService.findElements(MUIElement, String, Class, List, int), passing EModelService.ANYWHERE as the 'searchFlags'.
<T> java.util.List<T>	findElements(MUIElement searchRoot, java.lang.String id, java.lang.Class<T> clazz, java.util.List<java.lang.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 EModelService.findElements(MApplicationElement, Class, int, Selector).
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)
MUIElement	findSnippet(MSnippetContainer snippetContainer, java.lang.String id) Convenience method to find a snippet by id in a particular container
MPerspective	getActivePerspective(MWindow window) Return the active perspective for the given window.
MUIElement	getContainer(MUIElement element) Get the container of the given element.
IEclipseContext	getContainingContext(MUIElement element) Locate the context that is closest to the given element in the parent hierarchy.
int	getElementLocation(MUIElement element) Given an element this method responds with information about where the element exists within the current UI Model.
java.util.List<MPlaceholder>	getNullRefPlaceHolders(MUIElement element, MWindow refWin)
MPartDescriptor	getPartDescriptor(java.lang.String id) Returns the descriptor for the given part id.
MPerspective	getPerspectiveFor(MUIElement element)
MWindow	getTopLevelWindowFor(MUIElement element) Get the top-level window containing this UI element.
MTrimBar	getTrim(MTrimmedWindow window, SideValue sv) Returns the window's MTrimBar for the specified side.
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.
void	hostElement(MUIElement element, MWindow hostWindow, java.lang.Object uiContainer, IEclipseContext hostContext) Allows an element to be rendered in an arbitrary UI container (I.e.
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.
boolean	isHostedElement(MUIElement element, MWindow hostWindow) Tests whether the given element is being 'hosted'.
boolean	isLastEditorStack(MUIElement stack) Returns true iff the supplied element represents the single visible element in the shared area.
<T extends MUIElement> void	move(T element, <any> newParent) Move the element to a new location.
<T extends MUIElement> void	move(T element, <any> newParent, boolean leavePlaceholder) Move the element to a new location.
<T extends MUIElement> void	move(T element, <any> newParent, int index) Move the element to a new location.
<T extends MUIElement> void	move(T element, <any> newParent, int index, boolean leavePlaceholder) Move the element to a new location.
void	removePerspectiveModel(MPerspective persp, MWindow window) Remove the given perspective completely from the model.
void	resetPerspectiveModel(MPerspective persp, MWindow window) This is a convenience method that will clean the model of all traces of a given perspective.
int	toBeRenderedCount(<any> container) Count the number of 'toBeRendered' children

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ModelServiceImpl

public ModelServiceImpl(IEclipseContext appContext)

This is a singleton service. One instance is used throughout the running application

Parameters:

appContext - The applicationContext to get the eventBroker from

Throws:

java.lang.NullPointerException - if the given appContext is null

Method Detail

createModelElement

public final <T extends MApplicationElement> T createModelElement(java.lang.Class<T> elementType)

Description copied from interface: EModelService

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.

Specified by:

createModelElement in interface EModelService

Parameters:

elementType - the class to instantiate. Cannot be null

Returns:

a new instance

findElements

public <T> java.util.List<T> findElements(MUIElement searchRoot,
                                          java.lang.String id,
                                          java.lang.Class<T> clazz,
                                          java.util.List<java.lang.String> tagsToMatch)

Description copied from interface: EModelService

This is a convenience method that forwards the parameters on to EModelService.findElements(MUIElement, String, Class, List, int), passing EModelService.ANYWHERE as the 'searchFlags'.

Specified by:

findElements in interface EModelService

findElements

public <T> java.util.List<T> findElements(MUIElement searchRoot,
                                          java.lang.String id,
                                          java.lang.Class<T> clazz,
                                          java.util.List<java.lang.String> tagsToMatch,
                                          int searchFlags)

Description copied from interface: EModelService

This is a convenience method that constructs a new Selector based on ElementMatcher and forwards the call on to the base API EModelService.findElements(MApplicationElement, Class, int, Selector).

Specified by:

findElements in interface EModelService

See Also:

EModelService.findElements(MApplicationElement, Class, int, Selector)

findElements

public <T> java.util.List<T> findElements(MApplicationElement searchRoot,
                                          java.lang.Class<T> clazz,
                                          int searchFlags,
                                          Selector matcher)

Description copied from interface: EModelService

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.

Specified by:

findElements in interface EModelService

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.

find

public MUIElement find(java.lang.String id,
                       MUIElement searchRoot)

Description copied from interface: EModelService

Returns the first element, recursively searching under the specified search root (inclusive)

Specified by:

find in interface EModelService

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

countRenderableChildren

public int countRenderableChildren(MUIElement element)

Description copied from interface: EModelService

Return the count of the children whose 'toBeRendered' flag is true

Specified by:

countRenderableChildren in interface EModelService

Parameters:

element - The element to test

Returns:

the number of children with 'toBeRendered' == true

getContainingContext

public IEclipseContext getContainingContext(MUIElement element)

Description copied from interface: EModelService

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

Specified by:

getContainingContext in interface EModelService

Parameters:

element - the element to locate parent context for

Returns:

the containing context for this element

cloneElement

public MUIElement cloneElement(MUIElement element,
                               MSnippetContainer snippetContainer)

Description copied from interface: EModelService

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.

Specified by:

cloneElement in interface EModelService

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

public MUIElement cloneSnippet(MSnippetContainer snippetContainer,
                               java.lang.String snippetId,
                               MWindow refWin)

Description copied from interface: EModelService

If a snippet with the given id exists a clone is created and returned. returns null if no snippet can be found.

Specified by:

cloneSnippet in interface EModelService

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

getNullRefPlaceHolders

public java.util.List<MPlaceholder> getNullRefPlaceHolders(MUIElement element,
                                                           MWindow refWin)

Parameters:

element -

refWin -

Returns:

list of null referencing place holders

findSnippet

public MUIElement findSnippet(MSnippetContainer snippetContainer,
                              java.lang.String id)

Description copied from interface: EModelService

Convenience method to find a snippet by id in a particular container

Specified by:

findSnippet in interface EModelService

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

bringToTop

public void bringToTop(MUIElement element)

Description copied from interface: EModelService

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.

Specified by:

bringToTop in interface EModelService

Parameters:

element - The element to bring to the top

findPlaceholderFor

public MPlaceholder findPlaceholderFor(MWindow window,
                                       MUIElement element)

Description copied from interface: EModelService

Given a containing MWindow find the MPlaceholder that is currently being used to host the given element (if any)

Specified by:

findPlaceholderFor in interface EModelService

Parameters:

window - The containing window

element - The element to find the MPlaceholder for

Returns:

the MPlaceholder or null if none is found

move

public <T extends MUIElement> void move(T element,
                                        <any> newParent)

Description copied from interface: EModelService

Move the element to a new location. The element will be placed at the end of the new parent's list of children.

Specified by:

move in interface EModelService

Parameters:

element - The element to move

newParent - The new parent for the element.

move

public <T extends MUIElement> void move(T element,
                                        <any> newParent,
                                        boolean leavePlaceholder)

Description copied from interface: EModelService

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.

Specified by:

move in interface EModelService

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

public <T extends MUIElement> void move(T element,
                                        <any> newParent,
                                        int index)

Description copied from interface: EModelService

Move the element to a new location. The element will be placed at the specified index in the new parent's list of children.

Specified by:

move in interface EModelService

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

public <T extends MUIElement> void move(T element,
                                        <any> newParent,
                                        int index,
                                        boolean leavePlaceholder)

Description copied from interface: EModelService

Move the element to a new location. The element will be placed at the end of the new parent's list of children.

Specified by:

move in interface EModelService

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

public void insert(MPartSashContainerElement toInsert,
                   MPartSashContainerElement relTo,
                   int where,
                   float ratio)

Description copied from interface: EModelService

Inserts the given element into the UI Model by either creating a new sash or augmenting an existing sash if the orientation permits.

Specified by:

insert in interface EModelService

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: EModelService.LEFT_OF, EModelService.RIGHT_OF, EModelService.ABOVE, EModelService.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

public void detach(MPartSashContainerElement element,
                   int x,
                   int y,
                   int width,
                   int height)

Description copied from interface: EModelService

Created a separate (detached) window containing the given element.

Specified by:

detach in interface EModelService

Parameters:

element - 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

getTrim

public MTrimBar getTrim(MTrimmedWindow window,
                        SideValue sv)

Description copied from interface: EModelService

Returns the window's MTrimBar for the specified side. If necessary the bar will be created.

Specified by:

getTrim in interface EModelService

Parameters:

window - The window to get the trim bar for

sv - The value for the specified side

Returns:

The appropriate trim bar

getTopLevelWindowFor

public MWindow getTopLevelWindowFor(MUIElement element)

Description copied from interface: EModelService

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

Specified by:

getTopLevelWindowFor in interface EModelService

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

public MPerspective getPerspectiveFor(MUIElement element)

Specified by:

getPerspectiveFor in interface EModelService

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

resetPerspectiveModel

public void resetPerspectiveModel(MPerspective persp,
                                  MWindow window)

Description copied from interface: EModelService

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.

Specified by:

resetPerspectiveModel in interface EModelService

Parameters:

persp - the perspective to remove

window - the window to remove it from

removePerspectiveModel

public void removePerspectiveModel(MPerspective persp,
                                   MWindow window)

Description copied from interface: EModelService

Remove the given perspective completely from the model.

Specified by:

removePerspectiveModel in interface EModelService

Parameters:

persp - the perspective to remove

window - the window to remove it from

getActivePerspective

public MPerspective getActivePerspective(MWindow window)

Description copied from interface: EModelService

Return the active perspective for the given window. This is a convenience method that just returns the MPerspectiveStack's selectedElement.

Specified by:

getActivePerspective in interface EModelService

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.

toBeRenderedCount

public int toBeRenderedCount(<any> container)

Description copied from interface: EModelService

Count the number of 'toBeRendered' children

Specified by:

toBeRenderedCount in interface EModelService

Parameters:

container - The container to check

Returns:

The number of children whose toBeRendered flag is true

getContainer

public MUIElement getContainer(MUIElement element)

Description copied from interface: EModelService

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

Specified by:

getContainer in interface EModelService

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

public int getElementLocation(MUIElement element)

Description copied from interface: EModelService

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.

Specified by:

getElementLocation in interface EModelService

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

public MPartDescriptor getPartDescriptor(java.lang.String id)

Description copied from interface: EModelService

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

Specified by:

getPartDescriptor in interface EModelService

Parameters:

id - The id of the descriptor to return

Returns:

The descriptor matching the id or null if none exists

createPart

public MPart createPart(MPartDescriptor descriptor)

Description copied from interface: EModelService

Creates a new part from the given descriptor.

Specified by:

createPart in interface EModelService

Parameters:

descriptor - a part descriptor, must not be null

Returns:

a new part

See Also:

EPartService.createPart(String)

hideLocalPlaceholders

public void hideLocalPlaceholders(MWindow window,
                                  MPerspective perspective)

Description copied from interface: EModelService

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.

Specified by:

hideLocalPlaceholders in interface EModelService

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

public boolean isLastEditorStack(MUIElement stack)

Description copied from interface: EModelService

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.

Specified by:

isLastEditorStack in interface EModelService

Parameters:

stack - The element to test

Returns:

true iff the element is the last visible stack

hostElement

public void hostElement(MUIElement element,
                        MWindow hostWindow,
                        java.lang.Object uiContainer,
                        IEclipseContext hostContext)

Description copied from interface: EModelService

Allows an element to be rendered in an arbitrary UI container (I.e. SWT Composite).

Specified by:

hostElement in interface EModelService

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

public boolean isHostedElement(MUIElement element,
                               MWindow hostWindow)

Description copied from interface: EModelService

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.

Specified by:

isHostedElement in interface EModelService

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.