Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 


Eclipse Platform
Release 3.5

org.eclipse.ui.navigator
Interface INavigatorContentService


public interface INavigatorContentService

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:

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.

Since:
3.2
Restriction:
This interface is not intended to be implemented by clients.
Restriction:
This interface is not intended to be extended 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

createCommonContentProvider

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.

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.

Returns:
An enhanced content provider that will use this content service to drive the viewer.

createCommonLabelProvider

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.

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.

Returns:
An enhanced label provider that will use this content service to drive labels in the viewer.

createCommonDescriptionProvider

IDescriptionProvider createCommonDescriptionProvider()
Returns:
The description provider for this content service.

findStateModel

IExtensionStateModel findStateModel(
String anExtensionId)
The state model stores properties associated with the extension. Each content extension has its own contained state model. Components of the extension (content provider, label provider, action providers, etc) may attach themselves as listeners to the model ( IExtensionStateModel.addPropertyChangeListener(org.eclipse.jface.util.IPropertyChangeListener)) and respond to changes to the values of the properties.

Parameters:
anExtensionId - The extension id defined by a navigatorContent extension.
Returns:
The state model for the given extension id.

getViewerId

String getViewerId()
The viewer id is used to locate matching viewerContentBindings. In general, this would be the id of the view defined by a org.eclipse.ui.views extension. However, there is no formal requirement that this is the case.

Returns:
The viewerId used to create this content service.

getViewerDescriptor

INavigatorViewerDescriptor getViewerDescriptor()
The viewer descriptor provides some basic information about the abstract viewer that uses this content service.

Returns:
The viewer descriptor for this content service.
See Also:
INavigatorViewerDescriptor

isActive

boolean isActive(
String anExtensionId)
See above for the definition of active.

Parameters:
anExtensionId - The unqiue identifier from a content extension.
Returns:
True if and only if the given extension id is active for this content service.
See Also:
For more information on what active means.

isVisible

boolean isVisible(
String anExtensionId)
See above for the definition of visible.

Parameters:
anExtensionId - The unqiue identifier from a content extension.
Returns:
True if and only if the given extension id is visible to this content service.
See Also:
For more information on what visible means.

getVisibleExtensionIds

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

Returns:
The set of visible extension ids for this content service

getVisibleExtensions

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

Returns:
The set of visible content descriptors for this content service

bindExtensions

INavigatorContentDescriptor[] bindExtensions(
String[] extensionIds,
                                             boolean isRoot)
Bind the set of given extensions to this content service. Programmatic bindings allow clients to make extensions visible to an instance of the content service by appending to the bindings declared through org.eclipse.ui.navigator.viewer. Programmatic bindings are not persisted and are not remembered or propagated to other instances of the INavigatorContentService in the same session. Programmatic bindings cannot be undone for a given instance of the INavigatorContentService and do not override declarative bindings.

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.

Parameters:
extensionIds - The list of extensions to make visible.
isRoot - whether the context provider should be a root content provider
Returns:
A list of all INavigatorContentDescriptors that correspond to the given extensionIds.

restoreState

void restoreState(
IMemento aMemento)
Restore the state associated with the memento.

Parameters:
aMemento - The memento for extensions to use when restoring previous settings.

saveState

void saveState(
IMemento aMemento)
Persist any session-to-session state with the memento.

Parameters:
aMemento - The memento for extensions to use when persisting previous settings.

addListener

void addListener(
INavigatorContentServiceListener aListener)
Add a listener to be notified whenever an extension is loaded.

Parameters:
aListener - A listener to be attached.

removeListener

void removeListener(
INavigatorContentServiceListener aListener)
Remove a listener (by identity) from the set of listeners.

Parameters:
aListener - A listener to be detached.

update

void update()
The root content providers are recalculated by this method. The attached viewer is also refreshed as a result of this method.


dispose

void dispose()
Release any acquired resources and instantiated content extensions.


findRootContentExtensions

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.

Parameters:
anElement - The element to use in the query
Returns:
The set of INavigatorContentExtensions 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.

findContentExtensionsByTriggerPoint

Set findContentExtensionsByTriggerPoint(
Object anElement)
Search for extensions that declare the given element in their triggerPoints expression.

Parameters:
anElement - The element to use in the query
Returns:
The set of INavigatorContentExtensions that are visible and active for this content service and have a triggerPoints expression that is enabled for the given element.

findContentExtensionsWithPossibleChild

Set findContentExtensionsWithPossibleChild(
Object anElement)
Search for extensions that declare the given element in their possibleChildren expression.

Parameters:
anElement - The element to use in the query
Returns:
The set of INavigatorContentExtensions that are visible and active for this content service and have a possibleChildren expression that is enabled for the given element.

getFilterService

INavigatorFilterService getFilterService()
The filter service can provide the available filters for the viewer, and manage which filters are active.

Returns:
An INavigatorFilterService that can provide information to a viewer about what filters are visible and active.

getSorterService

INavigatorSorterService getSorterService()
The sorter service provides the appropriate sorter based on the current items being sorted. By default, the CommonViewer uses CommonViewerSorter which delegates to this service. Clients do not need to provide their own ViewerSorter unless they wish to override this functionality.

Returns:
An INavigatorSorterService that can provide ViewerSorter based on the context of the parent.

getPipelineService

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. Clients that use the CommonViewer do not need to be concerned with this service as the refreshes are automatically computed using this service.

Returns:
The INavigatorPipelineService which can determine the correct updates to apply to a viewer.

getDnDService

INavigatorDnDService getDnDService()
The DND Service provides instances of CommonDragAdapterAssistant and CommonDropAdapterAssistant for this content service.

Returns:
The INavigatorDnDService which can add additional TransferTypes for the DragAdapter and setup the data correctly for those extended Transfer Types.

getActivationService

INavigatorActivationService getActivationService()
The activation service is used to toggle whether certain extensions have the opportunity to contribute content and/or actions.

Returns:
The INavigatorActivationService for this content service.

getSaveablesService

INavigatorSaveablesService getSaveablesService()
The saveable service helps implementing ISaveablesSource.

Returns:
the INavigatorSaveablesService for this content service.

getContentExtensionById

INavigatorContentExtension getContentExtensionById(
String anExtensionId)
Return the content extension for the given id.

Parameters:
anExtensionId - The id used to define the org.eclipse.ui.navigator.navigatorContent/navigatorContent extension.
Returns:
An instance of the content extension for the given extension id. May return null if the id is invalid.

getContentDescriptorById

INavigatorContentDescriptor getContentDescriptorById(
String anExtensionId)
Return the content extension for the given id.

Parameters:
anExtensionId - The id used to define the org.eclipse.ui.navigator.navigatorContent/navigatorContent extension.
Returns:
An instance of the content extension for the given extension id. May return null if the id is invalid.
Since:
3.3

Eclipse Platform
Release 3.5

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire