Navigator Content

Identifier:
org.eclipse.ui.navigator.navigatorContent

Since:
3.2

Description:
A content extension provides a content and label provider that can be used by a navigator content service. The navigatorContent extension defines the specific classes for the content provider, label provider, and action provider in addition to the types of elements the extension knows about.

The triggerPoints expression describes the elements that will cause this extension to be invoked for either children or for labels. The possibleChildren expression describes the elements that the extension may be able to provide a parent for. Clients should describe all elements that could be set as the selection to ensure that the link with editor support can properly expand to the right node.

Configuration Markup:

<!ELEMENT extension ((navigatorContent* | actionProvider* | commonWizard* | commonFilter*))>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT navigatorContent ((enablement | (triggerPoints , possibleChildren))? , actionProvider* , commonSorter* , override? , dropAssistant* , commonWizard* , initialActivation?)>

<!ATTLIST navigatorContent

id                CDATA #REQUIRED

name              CDATA #REQUIRED

priority          (lowest|lower|low|normal|high|higher|highest)

appearsBefore     IDREF #IMPLIED

contentProvider   CDATA #IMPLIED

labelProvider     CDATA #IMPLIED

icon              CDATA #IMPLIED

activeByDefault   (true | false)

providesSaveables (true | false)

sortOnly          (true | false) >

A navigator content extension defines a content provider and label provider that can be used to provide children whenever an element matches the triggerPoints expression and also to provide a parent whenever an element matches the possibleChildren expression.

Optionally, clients may also provide an action provider which can provide menu contributions and action bar contributions when an element is selected that the extension contributed, or that matches the triggerPoints expression. Clients may also choose to contribute a sorter to sort elements that are contributed by the extension.

When an extension is deactivated by the user, the content and label providers are disposed. However, because many of the Image resources might be in use by other extensions in the Common Navigator Viewer, clients should not dispose of Image Resources until the viewer itself is disposed.



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

The enablement expression allows clients to specify the same expression for both triggerPoints and possibleChildren.

In the case of actionProvider, clients must define an expression that will indicate to the framework when their org.eclipse.ui.navigator.CommonActionProvider should be invoked. Because of contributions to the IActionBars, clients must be invoked whenever an object they are interested in is selected. Therefore, clients should use discretion in deciding when their extension should be enabled.



<!ELEMENT triggerPoints (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

The triggerPoints expression defines the nodes to be used when resolving the Common Navigator content provider's getElements() or getChildren(). This is also used to select the extension for providing labels, images, descriptions and for sorting.



<!ELEMENT possibleChildren (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

The possibleChildren expression defines the node to be used when resolving the Common Navigator content provider's getParent(). It is also used to help determine the parent when handling drop operations.



<!ELEMENT actionProvider (enablement?)>

<!ATTLIST actionProvider

class         CDATA #REQUIRED

id            CDATA #IMPLIED

dependsOn     CDATA #IMPLIED

overrides     CDATA #IMPLIED

priority      (lowest|lower|low|normal|high|higher|highest)

appearsBefore IDREF #IMPLIED>

Supplies the name of a class that implements org.eclipse.ui.navigator.CommonActionProvider. The action provider has an opportunity to contribute to the context menu and the retargetable actions defined in the IActionBars for the view that holds the navigator. Clients may also contribute directly to the view menu through the IActionBars view menu.

A top level actionProvider is visible to an abstract viewer if there is a viewerActionBinding for that actionProvider. For actionProviders that are nested under a navigatorContent element, the visibility will be controlled by the id of the navigatorContent extension id. Child action providers will automatically be picked up by matching viewerContentBindings. See org.eclipse.ui.navigator.viewer for more information on visibility bindings.

Clients may provide actionProvider(s) under the root extension element (peer to other navigatorContent) in order to better control their enablement and viewer binding (see viewerActionBinding).

For root actionProviders with no id, the id defaults to "org.eclipse.ui.navigator.actionProvider.X". For these actionProviders to be given the opportunity to contribute the menus or action bars of a viewer, a viewerActionBinding must be defined (as part of the org.eclipse.ui.navigator.viewer extension point) which declares a binding between the specific viewer and the default id ("org.eclipse.ui.navigator.actionProvider.*"). See the documentation for viewerActionBinding under the schema documentation of org.eclipse.ui.navigator.viewer for more information.

Any items contributed to the toolbar or the view menu should be removed when the actionProviders is disposed.



<!ELEMENT commonWizard (enablement)>

<!ATTLIST commonWizard

type                  (import|export|new)

wizardId              CDATA #REQUIRED

menuGroupId           CDATA #IMPLIED

associatedExtensionId CDATA #IMPLIED>

Defines a binding between an existing Eclipse New/Import/Export Wizard and a given set of items. Each valid binding determines which menu items will appear in the submenus for New/Import/Export in the context menu of a Common Navigator Viewer. Since Eclipse 3.2.1, the wizard menu items respect Eclipse Capabilities (see org.eclipse.ui.activites for more information).

All of the following conditions must be met for a commonWizard item to appear in the menu: (1) The commonWizard is NOT filtered by an Eclipse Capability, (2) The identifier of the commonWizard is NOT null, (3) The associated navigatorContent extension is visible for the current content service (the content service used to initialize the NavigatorActionService or supplied to WizardActionGroup), (4) The associated navigatorContent extension is active for the current content service, and (5) The enablement of the commonWizard returns true for the current selection that was supplied to the context menu.



<!ELEMENT commonFilter (filterExpression?)>

<!ATTLIST commonFilter

id              CDATA #REQUIRED

name            CDATA #REQUIRED

description     CDATA #IMPLIED

class           CDATA #IMPLIED

activeByDefault (true | false)

visibleInUI     (true | false) >

Defines a filter that can big associated with a particular Common Viewer. Common filters are bound to a viewer like content extensions by using org.eclipse.ui.navigator.viewer/viewerContentBinding.



<!ELEMENT filterExpression (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

An optional Eclipse Core Expression that defines what the filter should hide from a particular view.

For instance, clients may decide to hide all resources that have a particular pattern in their name (like "*.acme"). When the filter is active (turned on by default or by the user), then all resources that end in "acme" would be hidden from the view of the user.

Clients may use either filterExpression or the "class" attribute, but not both.



<!ELEMENT commonSorter (parentExpression?)>

<!ATTLIST commonSorter

id    CDATA #IMPLIED

class CDATA #REQUIRED>

A commonSorter declares an subclass of org.eclipse.jface.viewers.ViewerComparator which is used to sort children in the tree. The nested parentExpression describes when the commonSorter should be used. If an element matches the parentExpression, then its children will be sorted by this commonSorter.

Since Eclipse 4.7.0 org.eclipse.jface.viewers.ViewerComparator is allowed to be used as commonSorter contributions. Before 4.7.0, only instances of org.eclipse.jface.viewers.ViewerSorter were allowed as commonSorter.



<!ELEMENT parentExpression (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

A parentExpression is used by commonSorter to identify when it is applicable. If the parentExpression for a commonSorter matches a given element, then that commonSorter will be used to sort the children of that element (as returned by the content provider of the content service).



<!ELEMENT override EMPTY>

<!ATTLIST override

suppressedExtensionId CDATA #REQUIRED

policy                (InvokeOnlyIfSuppressedExtAlsoVisibleAndActive|InvokeAlwaysRegardlessOfSuppressedExt) "InvokeAlwaysRegardlessOfSuppressedExt">

When the triggerPoints expression of the suppressed extension and the declared extension are both enabled on a given element, this extension will be invoked after its supressed extension. The suppressed extension will contribute the original content and this extension can modify that content using the pipeline mechanism by implementing org.eclipse.ui.navigator.IPipelinedTreeContentProvider.

When you specify an override element with a content provider which implements org.eclipse.ui.navigator.IPipelinedTreeContentProvider, you can intercept requests for children, parents, and direct updates to the viewer.

If the content provider in the override element does not implement org.eclipse.ui.navigator.IPipelinedTreeContentProvider, this extension will be considered to provide label/description information for content contributed by one of the overridden extensions.



<!ELEMENT dropAssistant (possibleDropTargets)>

<!ATTLIST dropAssistant

id    CDATA #REQUIRED

class CDATA #REQUIRED>

Provides a subclass of org.eclipse.ui.navigator.CommonDropAdapterAssistant which can provide programatic validation for a drop operation, request additional transfer types, and handle the drop operation.

A dropAssistant will be invoked whenever elements that are dragged match the possibleChildren expression of the containing navigatorContent extension and the drop target of the operation is described by the possibleDropTargets expression of the dropAssistant element.

An extension may have multiple drop adapters with mutually exclusive possibleDropTargets expressions. The first drop adapter found that matches the given drop target and returns an OK status for CommonDropAdapterAssistant.validateDrop(...) will be given an opportunity to handle the drop.



<!ELEMENT possibleDropTargets (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

Describe the possible drop targets that a particular dropAssistant can handle.



<!ELEMENT initialActivation (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

A core expression which is checked with the navigator starts to determine of this navigator content extension is to be activated. Only meaningful if activeByDefault is set to false.



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

A generic root element. The element can be used inside an extension point to define its enablement expression. The children of an enablement expression are combined using the "and" operator.



<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate | reference)>

This element represents a NOT operation on the result of evaluating its sub-element expression.



<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

This element represents an AND operation on the result of evaluating all its sub-elements expressions.



<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

This element represent an OR operation on the result of evaluating all its sub-element expressions.



<!ELEMENT instanceof EMPTY>

<!ATTLIST instanceof

value CDATA #REQUIRED>

This element is used to perform an instanceof check of the object in focus. The expression returns EvaluationResult.TRUE if the object's type is a sub type of the type specified by the attribute value. Otherwise EvaluationResult.FALSE is returned.



<!ELEMENT test EMPTY>

<!ATTLIST test

property              CDATA #REQUIRED

args                  CDATA #IMPLIED

value                 CDATA #IMPLIED

forcePluginActivation (true | false) >

This element is used to evaluate the property state of the object in focus. The set of testable properties can be extended using the org.eclipse.core.expressions.propertyTesters extension point. The test expression returns EvaluationResult.NOT_LOADED if the property tester doing the actual testing isn't loaded yet and the attribute forcePluginActivation is set to false. If forcePluginActivation is set to true and the evaluation context used to evaluate this expression support plug-in activation then evaluating the property will result in activating the plug-in defining the tester.



<!ELEMENT systemTest EMPTY>

<!ATTLIST systemTest

property CDATA #REQUIRED

value    CDATA #REQUIRED>

Tests a system property by calling the System.getProperty method and compares the result with the value specified through the value attribute.



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

This element is used to perform an equals check of the object in focus. The expression returns EvaluationResult.TRUE if the object is equal to the value provided by the attribute value. Otherwise EvaluationResult.FALSE is returned.



<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED>

This element is used to test the number of elements in a collection.



<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

<!ATTLIST with

variable CDATA #REQUIRED>

This element changes the object to be inspected for all its child element to the object referenced by the given variable. If the variable can not be resolved then the expression will throw an ExpressionException when evaluating it. The children of a with expression are combined using the "and" operator.



<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

This element changes the object to be inspected for all its child element to the object referenced by the given variable. If the variable can not be resolved then the expression will throw an ExpressionException when evaluating it. The children of a resolve expression are combined using the "and" operator.



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

<!ATTLIST adapt

type CDATA #REQUIRED>

This element is used to adapt the object in focus to the type specified by the attribute type. The expression returns EvaluationResult.NOT_LOADED if either the adapter or the type referenced isn't loaded yet. It throws an ExpressionException during evaluation if the type name doesn't exist at all. The children of an adapt expression are combined using the "and" operator.



<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate , reference)*>

<!ATTLIST iterate

operator (or|and)

ifEmpty  (true | false) >

This element is used to iterate over a variable that is of type java.util.Collection, or a variable that adapts to org.eclipse.core.expressions.IIterable. If the object in focus is not one of the above then a CoreException with an ExpressionStatus will be thrown while evaluating the expression. The child expressions of an iterate expression are combined using the "and" operator.



<!ELEMENT reference EMPTY>

<!ATTLIST reference

definitionId IDREF #REQUIRED>

This element is used to reference an expression from the org.eclipse.core.expressions.definitions extension point. The expression definition will be evaluated within the current expression element using the current evaluation context.



Examples:

Adding content

The following example describes a content extension that provides resource content. The triggerPoints expression determines when this extension is initially invoked. If a viewerContentBinding matches this extension with the "isRoot" attribute set to true, then the extension will be used, regardless of whether the root element matches the triggerPoints expression.


<extension  
  point="org.eclipse.ui.navigator.navigatorContent">
 <navigatorContent
            name="%resource.extension.name"
            priority="low"
            icon="icons/full/eview16/resource_persp.gif"
            activeByDefault="true"
               contentProvider="org.eclipse.ui.navigator.resources.internal.workbench.ResourceExtensionContentProvider"
               labelProvider="org.eclipse.ui.navigator.resources.internal.workbench.ResourceExtensionLabelProvider"   
               sorter="org.eclipse.ui.navigator.resources.internal.workbench.ResourceSorter"
            id="org.eclipse.ui.navigator.resourceContent">         
  <triggerPoints>
           <or>         
              <instanceof 
                    value="org.eclipse.core.resources.IWorkspaceRoot" /> 
              <instanceof
                    value="org.eclipse.core.resources.IProject" />  
              <instanceof  
                     value="org.eclipse.core.resources.IFolder" /> 
           </or>
  </triggerPoints>
        <possibleChildren>
           <or>         
              <instanceof 
                    value="org.eclipse.core.resources.IWorkspaceRoot" /> 
              <instanceof
                    value="org.eclipse.core.resources.IProject" /> 
              <instanceof 
                     value="org.eclipse.core.resources.IResource" /> 
              <instanceof  
                     value="org.eclipse.core.resources.IFolder" />
              <instanceof 
                     value="org.eclipse.core.resources.IFile" /> 
         </or>
     </possibleChildren>
 </navigatorContent>
</extension>

Adding Actions

Clients may use object or viewer contributions (see org.eclipse.ui.popupMenus) to provide actions for their view. Sometimes, clients require a greater degree of flexibility than either of these approaches allow, and therefore the Common Navigator framework supports adding action providers. "Action providers" subclass org.eclipse.ui.actions.ActionGroup and have opportunities to fill the action bars and the menus based on different events (selection and right click respectively).

Clients may either associate one or more action providers with a particular content extension, or declare the action providers as top level contributions, unassociated with any particular content extension. Top level action provideers must be associated with a particular instance of vierwer using the org.eclipse.ui.navigator.viewer/viewerActionBinding extension point. Nested action providers are automatically bound to a viewer based on whether their containing content extension is also bound to the viewer (see org.eclipse.ui.navigator/viewerContentBinding).

The following example demonstrates both approaches. The "TestNestedActionProvider" will be given an opporunity to contribute to the menu and org.eclipse.ui.IActionBars only when the "org.eclipse.ui.tests.navigator.testContent" extension is visible and active. If the user deactivates the test extension from the "Filters and Customization" dialog, then the nested action provider will no longer be given the opportunity to contribute.


<extension  
  point="org.eclipse.ui.navigator.navigatorContent"> 
      <navigatorContent 
            id="org.eclipse.ui.tests.navigator.testContent" 
            name="%test.navigator.extension"
            contentProvider="org.eclipse.ui.tests.navigator.extension.TestContentProvider"
            labelProvider="org.eclipse.ui.tests.navigator.extension.TestLabelProvider"
            activeByDefault="true"
            priority="normal">
         <triggerPoints>
            <instanceof value="org.eclipse.core.resources.IProject"/>
         </triggerPoints> 
        <actionProvider
            class="org.eclipse.ui.tests.navigator.extension.TestNestedActionProvider"
            id="org.eclipse.ui.tests.navigator.extension.TestNestedActionProvider">
          <enablement>
             <instanceof value="org.eclipse.core.resources.IResource"/>
          </enablement>
        </actionProvider>
      </navigatorContent>  
        <actionProvider
             class="org.eclipse.ui.navigator.resources.internal.actions.NewActionProvider"
             id="org.eclipse.ui.navigator.resources.NewActions"> 
         <enablement>
    <or>
     <adapt type="org.eclipse.core.resources.IFile" /> 
     <adapt type="org.eclipse.core.resources.IFolder" />
            <adapt type="org.eclipse.core.resources.IProject" /> 
                 <adapt type="org.eclipse.core.resources.IWorkspaceRoot" /> 
    </or>
          </enablement>
  </actionProvider>
</extension>  

Clients may define filters using either subclasses of org.eclipse.jface.viewers.ViewerFilter or through Eclipse core expressions. The folowing example demonstrates both techniques. Clients may only use of the two options. Extensions that specify both in error will result in only the core expression filter being respected. The name and description fields are translateable, and should externalized strings in real environments.


<extension  
  point="org.eclipse.ui.navigator.navigatorContent">
 <commonFilter
      class="org.eclipse.ui.tests.navigator.extension.TestItemsThatEndIn3"
            description="Hide TestItem objects that end in the number &quot;3&quot;"
            id="org.eclipse.ui.tests.navigator.filters.TestItemsThatEndWith3"
            name="TestItems that end with &quot;3&quot;"
            activeByDefault="true"
            /> 
 <commonFilter
            description="Hides all instances of Test Item"
            id="org.eclipse.ui.tests.navigator.filters.AllTestItems"
            name="A TestItem Exp Filter (should be sorted alphab..)">
         <filterExpression>
            <instanceof value="org.eclipse.ui.tests.navigator.extension.TestExtensionTreeData"/>
         </filterExpression>
 </commonFilter>

A common sorter is determined for a set of children based on their parent. The sorter class must subclass the org.eclipse.jface.viewers.ViewerComparator.



<extension  
  point="org.eclipse.ui.navigator.navigatorContent">
 <commonSorter
      class="org.eclipse.ui.navigator.resources.internal.workbench.ResourceExtensionSorter"
            id="org.eclipse.ui.navigator.resources.sorters.defaultSorter">
  <parentExpression>
         <or>         
       <instanceof 
           value="org.eclipse.core.resources.IWorkspaceRoot" /> 
          <instanceof
           value="org.eclipse.core.resources.IProject" /> 
          <instanceof 
           value="org.eclipse.core.resources.IResource" /> 
          <instanceof  
           value="org.eclipse.core.resources.IFolder" />
          <instanceof 
           value="org.eclipse.core.resources.IFile" /> 
   </or>
  </parentExpression>
 </commonSorter>
</extension>

The following example demonstrates how to add wizard shortcut actions for "New Folder" and "New File", which are enabled on the specific subclasses of org.eclipse.core.resources.IResource. Clients may use whatever parts of the org.eclipse.core.expressions that are necessary to describe when the menu options should be available. The wizardId specified below must correspond to one of the org.eclipse.ui.xxxWizards extension points.

For clients building their own viewers or view parts, be sure to use org.eclipse.ui.navigator.WizardActionGroup to correctly populate the menu. See that class for more documentation on using this feature.



<extension  
  point="org.eclipse.ui.navigator.navigatorContent">
 <commonWizard
      type="new"
   wizardId="org.eclipse.ui.wizards.new.folder">
  <enablement>
   <or>
    <adapt type="org.eclipse.core.resources.IFile" /> 
    <adapt type="org.eclipse.core.resources.IFolder" />
           <adapt type="org.eclipse.core.resources.IProject" /> 
             <adapt type="org.eclipse.core.resources.IWorkspaceRoot" /> 
   </or>
  </enablement>
 </commonWizard>   
 <commonWizard
            type="new"
            wizardId="org.eclipse.ui.wizards.new.file">
  <enablement>
   <or>
    <adapt type="org.eclipse.core.resources.IFile" /> 
    <adapt type="org.eclipse.core.resources.IFolder" />
           <adapt type="org.eclipse.core.resources.IProject" /> 
             <adapt type="org.eclipse.core.resources.IWorkspaceRoot" /> 
   </or>
  </enablement>
 </commonWizard>
</extension> 


Copyright (c) 2002, 2011 IBM Corporation and others.
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html/ SPDX-License-Identifier: EPL-2.0