|
Eclipse Platform Release 3.3 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Manages content extensions for extensible viewers and provides reusable
services for filters, sorting, the activation of content extensions, and DND.
The service can locate the appropriate providers (for contents or labels) for
an element and provide a ready-to-go ITreeContentProvider
and
ILabelProvider
for viewers that wish to take advantage of the
org.eclipse.ui.navigator.navigatorContent extensions defined for a
particular viewerId.
Clients should create instances of the this class using the factory (NavigatorContentServiceFactory
).
Clients may contribute logical extensions using org.eclipse.ui.navigator.navigatorContent. Each extension has three states which determine whether the extension is used by the content service:
INavigatorActivationService.activateExtensions(String[], boolean)
or
INavigatorActivationService.deactivateExtensions(String[], boolean)
from the Activation Service
A new instance of the content service should be created for each viewer.
Clients should use createCommonContentProvider()
and
createCommonLabelProvider()
for the viewer. Each content service
tracks the viewer it is attached to. Clients may create the content service
with a viewer using (NavigatorContentServiceFactory.createContentService(String)
).
Alternatively, when the content provider is created and set on a viewer,
IContentProvider.inputChanged(org.eclipse.jface.viewers.Viewer, Object, Object)
will be called and the content provider will update the viewer used by its
backing content service. Therefore, only each content service has exactly one
content provider and one label provider.
Extensions may also coordinate their behavior through a
state model
. The state model holds properties
and supports property change listeners. Actions can toggle the setting of
properties and the corresponding content/label providers will respond to
property change event. Each navigatorContent extension has its own
contained state model keyed off of the content extension id.
Clients may respond when content extensions are loaded by attaching a
INavigatorContentServiceListener
to the content service.
Some extensions may provide content or label providers which implement
IMemento
. Clients must call restoreState(IMemento)
and
saveState(IMemento)
at the appropriate times for these extensions to
prepare themselves with the memento.
This interface is not intended to be implemented by clients.
Method Summary | |
---|---|
void |
addListener(INavigatorContentServiceListener aListener)
Add a listener to be notified whenever an extension is loaded. |
INavigatorContentDescriptor[] |
bindExtensions(String[] extensionIds,
boolean isRoot)
Bind the set of given extensions to this content service. |
ITreeContentProvider |
createCommonContentProvider()
Create a Content Provider which will use an enhanced delegation model to locate extension content providers using this content service for each element in the tree. |
IDescriptionProvider |
createCommonDescriptionProvider()
|
ILabelProvider |
createCommonLabelProvider()
Create a Label Provider which will use an enhanced delegation model to locate extension label providers using this content service for each element in the tree. |
void |
dispose()
Release any acquired resources and instantiated content extensions. |
Set |
findContentExtensionsByTriggerPoint(Object anElement)
Search for extensions that declare the given element in their triggerPoints expression. |
Set |
findContentExtensionsWithPossibleChild(Object anElement)
Search for extensions that declare the given element in their possibleChildren expression. |
Set |
findRootContentExtensions(Object anElement)
Search for extensions that declare the given element in their triggerPoints expression or that indicate they should be bound as a root extension. |
IExtensionStateModel |
findStateModel(String anExtensionId)
The state model stores properties associated with the extension. |
INavigatorActivationService |
getActivationService()
The activation service is used to toggle whether certain extensions have the opportunity to contribute content and/or actions. |
INavigatorContentDescriptor |
getContentDescriptorById(String anExtensionId)
Return the content extension for the given id. |
INavigatorContentExtension |
getContentExtensionById(String anExtensionId)
Return the content extension for the given id. |
INavigatorDnDService |
getDnDService()
The DND Service provides instances of CommonDragAdapterAssistant
and CommonDropAdapterAssistant for this content service. |
INavigatorFilterService |
getFilterService()
The filter service can provide the available filters for the viewer, and manage which filters are active. |
INavigatorPipelineService |
getPipelineService()
The pipeline service calculates the appropriate viewer modification or refresh that should be applied for viewers that wish to take advantage of the model pipelining that some extensions use to massage or reshape contents in the viewer. |
INavigatorSaveablesService |
getSaveablesService()
The saveable service helps implementing ISaveablesSource . |
INavigatorSorterService |
getSorterService()
The sorter service provides the appropriate sorter based on the current items being sorted. |
INavigatorViewerDescriptor |
getViewerDescriptor()
The viewer descriptor provides some basic information about the abstract viewer that uses this content service. |
String |
getViewerId()
The viewer id is used to locate matching viewerContentBindings. |
String[] |
getVisibleExtensionIds()
Return the set of visible extension ids for this content service, which includes those that are bound through viewerContentBindings and those that are bound through bindExtensions(String[], boolean) . |
INavigatorContentDescriptor[] |
getVisibleExtensions()
Return the set of visible content descriptors for this content service, which includes those that are bound through viewerContentBindings and those that are bound through bindExtensions(String[], boolean) . |
boolean |
isActive(String anExtensionId)
See above for the definition of active. |
boolean |
isVisible(String anExtensionId)
See above for the definition of visible. |
void |
removeListener(INavigatorContentServiceListener aListener)
Remove a listener (by identity) from the set of listeners. |
void |
restoreState(IMemento aMemento)
Restore the state associated with the memento. |
void |
saveState(IMemento aMemento)
Persist any session-to-session state with the memento. |
void |
update()
The root content providers are recalculated by this method. |
Method Detail |
public ITreeContentProvider createCommonContentProvider()
The content provider returned will populate the root of the viewer in one of two ways.
In the first approach, the content provider will seek out content
extensions which are bound using a viewerContentBinding. If any
of the found viewerContentBindings declare the isRoot
attribute on as true, then that set of extensions will be consulted for
the root elements of the tree. The input of the viewer will be supplied
to each of their IStructuredContentProvider.getElements(Object)
methods and aggregate the results for the root of the viewer.
In the second approach, if no viewerContentBindings declare
isRoot as true, then all matching extensions are consulted based
on their triggerPoints expression in the navigatorContent
extension. Any matching extensions are then consulted via their
IStructuredContentProvider.getElements(Object)
methods and the
results are aggregated into the root.
After the root is populated, the children of each root element are determined by consulting the source extension and all extension which describe the element in their triggerPoints expression.
If clients wish to use a viewer other than the CommonViewer, then they are responsible for creating the content provider, and setting it on their viewer.
public ILabelProvider createCommonLabelProvider()
The label of each element is determined by consulting the source of the element. If the source chooses to return null, then other extensions which declare the element in their triggerPoints extension are consulted. The first non-null value is used (including the empty label).
If clients wish to use a viewer other than the CommonViewer, then they are responsible for creating the label provider, and setting it on their viewer.
public IDescriptionProvider createCommonDescriptionProvider()
public IExtensionStateModel findStateModel(String anExtensionId)
IExtensionStateModel.addPropertyChangeListener(org.eclipse.jface.util.IPropertyChangeListener)
)
and respond to changes to the values of the properties.
anExtensionId
- The extension id defined by a navigatorContent
extension.
public String getViewerId()
public INavigatorViewerDescriptor getViewerDescriptor()
INavigatorViewerDescriptor
public boolean isActive(String anExtensionId)
anExtensionId
- The unqiue identifier from a content extension.
For more information on what active
means.
public boolean isVisible(String anExtensionId)
anExtensionId
- The unqiue identifier from a content extension.
For more information on what visible
means.
public String[] getVisibleExtensionIds()
bindExtensions(String[], boolean)
.
public INavigatorContentDescriptor[] getVisibleExtensions()
bindExtensions(String[], boolean)
.
public INavigatorContentDescriptor[] bindExtensions(String[] extensionIds, boolean isRoot)
Once a content extension has been bound to the INavigatorContentService,
clients may use
INavigatorActivationService.activateExtensions(String[], boolean)
or
INavigatorActivationService.deactivateExtensions(String[], boolean)
to control the activation state of the extension. See
INavigatorContentService
for more information on the difference
between visible and active.
extensionIds
- The list of extensions to make visible.isRoot
- whether the context provider shold be a root content provider
public void restoreState(IMemento aMemento)
aMemento
- The memento for extensions to use when restoring previous
settings.public void saveState(IMemento aMemento)
aMemento
- The memento for extensions to use when persisting previous
settings.public void addListener(INavigatorContentServiceListener aListener)
aListener
- A listener to be attached.public void removeListener(INavigatorContentServiceListener aListener)
aListener
- A listener to be detached.public void update()
public void dispose()
public Set findRootContentExtensions(Object anElement)
anElement
- The element to use in the query
INavigatorContentExtension
s that are
visible and active for this content service and
either declared through a
org.eclipse.ui.navigator.viewer/viewerContentBinding to
be a root element or have a triggerPoints expression that
is enabled for the given element.public Set findContentExtensionsByTriggerPoint(Object anElement)
anElement
- The element to use in the query
INavigatorContentExtension
s that are
visible and active for this content service and
have a triggerPoints expression that is enabled
for the given element.public Set findContentExtensionsWithPossibleChild(Object anElement)
anElement
- The element to use in the query
INavigatorContentExtension
s that are
visible and active for this content service and
have a possibleChildren expression that is enabled
for the given element.public INavigatorFilterService getFilterService()
INavigatorFilterService
that can provide information
to a viewer about what filters are visible and active.public INavigatorSorterService getSorterService()
CommonViewerSorter
which delegates to this service. Clients do
not need to provide their own ViewerSorter
unless they wish to
override this functionality.
INavigatorSorterService
that can provide
ViewerSorter
based on the context of the parent.public INavigatorPipelineService getPipelineService()
CommonViewer
do not
need to be concerned with this service as the refreshes are automatically
computed using this service.
INavigatorPipelineService
which can determine the
correct updates to apply to a viewer.public INavigatorDnDService getDnDService()
CommonDragAdapterAssistant
and CommonDropAdapterAssistant
for this content service.
INavigatorDnDService
which can add additional
TransferTypes for the DragAdapter and setup the data correctly
for those extended Transfer Types.public INavigatorActivationService getActivationService()
INavigatorActivationService
for this content service.public INavigatorSaveablesService getSaveablesService()
ISaveablesSource
.
INavigatorSaveablesService
for this content service.public INavigatorContentExtension getContentExtensionById(String anExtensionId)
anExtensionId
- The id used to define the org.eclipse.ui.navigator.navigatorContent/navigatorContent extension.
public INavigatorContentDescriptor getContentDescriptorById(String anExtensionId)
anExtensionId
- The id used to define the org.eclipse.ui.navigator.navigatorContent/navigatorContent extension.
|
Eclipse Platform Release 3.3 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Guidelines for using Eclipse APIs.
Copyright (c) IBM Corp. and others 2000, 2007. All rights reserved.