Eclipse Plug-in Developer Guide
Previous Page	Home	Next Page

---

navigatorContent

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

<!ATTLIST navigatorContent

id                CDATA #REQUIRED

name              CDATA #REQUIRED

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

contentProvider   CDATA #IMPLIED

icon              CDATA #IMPLIED

activeByDefault   (true | false)

providesSaveables (true | false)

labelProvider     CDATA #IMPLIED

>

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.

• id - A unique ID to identify this extension. Used for extension activation and by other extensions that would like to extend the defined extension (e.g. add another org.eclipse.ui.navigator.CommonActionProvider)
• name - Specify a display name for the Content Extension. The display name is used in the activation dialog to allow clients to turn an extension on or off.
• priority - Indicates the relative priority of this extension to other extensions. Used by the Common Navigator to handle sorting and organization of the contributed content from this extension in relation to content from other extensions. Defaults to "normal"
• contentProvider - Supplies the name of a class which implements org.eclipse.jface.viewers.ITreeContentProvider or org.eclipse.ui.navigator.ICommonContentProvider.
  
  The content provider will be consulted when adding children to the tree. Use the enablement, triggerPoints, or possibleChildren clauses to indicate what kinds of content should trigger a request to your content provider.
  
  Elements contributed from the content provider are not guaranteed to appear in the tree in the same order. Clients should take advantage of the sorting extension (commonSorter) to ensure proper ordering of their elements.
  
  All elements contributed by this content provider are associated with this navigatorContent extension for the purposes of determining the label provider, action providers, sorters, drop assistants and common wizards.
• icon - A plugin-relative path to an icon for use when displaying the metadata about the content extension to the user.
• activeByDefault - Indicates whether the current extension will be active by default. Each content extension may be turned on or off by the user. The active state is differentiated from the visible state. See org.eclipse.ui.navigator.viewer/viewerContentBinding for more information on visibility
• providesSaveables - Indicates whether this extension provides saveables. The default is false. If set to true, the content provider must adapt to SaveablesProvider.
• labelProvider - Supplies the name of a class which implements org.eclipse.jface.viewers.ILabelProvider or for more advanced functionality, the org.eclipse.ui.navigator.ICommonLabelProvider.
  
  Clients may also implement org.eclipse.ui.navigator.IDescriptionProvider in order to add text to the status bar at the bottom of the Eclipse workbench based on the selection in the viewer.
  
  Since 3.4, clients may also implement org.eclipse.jface.viewers.DelegatingStyledCellLabelProvider.IStyledLabelProvider to provide styled text labels. Note that the empty styled string signals that the label provider does not wish to render the label.

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

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.

• class -
• id - Clients may optionally define an id to use for filtering purposes (either through activities or viewerContentBindings).
• dependsOn - Specifies the ID of an action provider that configures some menu or submenu that must be prepared before this action provider is applied.
  
  Specifying a dependency on another action provider does not guarantee that this action provider will be invoked whereever the required action provider is invoked. The downstream action provider must be bound to the particular viewer to be invoked.
  
  If the required action provider is disabled or unbound to the current viewer, then this action provider will not be applied. If a cycle exists, the framework will try to continue, but there are no guarantees as to what menu items or action bar contributions will be available.
• overrides - Specify the id of an actionProvider which is defined by an upstream contributor that must be overridden. The upstream actionProvider will not be given an opportunity to contribute menu options or retargetable actions when this actionProvider is visible and enabled.
• priority - Indicates the relative priority of this extension to other extensions. Used by the Common Navigator to handle sorting and organization of the contributed content from this extension in relation to content from other extensions. Defaults to "normal"
• appearsBefore - Specifies the ID of the action provider that this action provider appears before. This action provider will be processed (menus filled, etc) before the specified action provider is processed.

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

• type - The type atttribute should be the value of the root category of the expected wizard. The possible values include "import" for org.eclipse.ui.importWizards, "export" org.eclipse.ui.exportWizards, and "new" for org.eclipse.ui.newWizards
• wizardId - The id of the desired wizard shortcut as defined by org.eclipse.ui.importWizards, org.eclipse.ui.exportWizards, or org.eclipse.ui.newWizards
• menuGroupId - Indicates a user-defined logical grouping id. commonWizard extensions with matching menuGroupIds will be indicated as related items when rendered as menu options to endusers. How the grouping will be done is not guaranteed. In particular, clients should never anticipate a menu separator or group marker of the given name to be present in the menu.
• associatedExtensionId - A commonWizard may be defined as the nested child of a navigatorContent extension point, in which case the associatedExtensionId is automatically set to the id of its enclosing naviagatorContent element. However, when specified as a top-level extension, a commonWizard may indicate an content extension that it should be associated with explicitly. When a commonWizard is associated with a content extension, it will inherit the visibility and the activation of that content extension. It will not inherit the enablement; so you must specify an enablement for the wizard menu item to appear.
  
  That is, if the content extension is bound to a Common Navigator (see org.eclipse.ui.navigator.viewer/viewerContentBinding) and the user has the content extension activated either by default or through the "Available Extensions" dialog, then the commonWizard menu option would appear. However, when the user deactivates that content extension, the commonWizard menu option would no longer be shown in the menu.
  
  

<!ELEMENT commonFilter ( filterExpression?)>

<!ATTLIST commonFilter

id              CDATA #REQUIRED

name            CDATA #REQUIRED

description     CDATA #IMPLIED

class           CDATA #IMPLIED

activeByDefault (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.

• id - A unique identifier that will be used for management of this filterExpression. The id will be used by the org.eclipse.ui.navigator.viewer/viewerContentBinding to bind this filter to a matching viewer.
• name - A translateable name that will be used to refer to this particular filter in dialogs presented to the user.
• description - A translatable description of what this filter is designed to hide from the view.
• class - Clients may choose to define an explicit ViewerFilter subclass via the "class" attribute. Alternatively, clients may choose to nest a filterExpression element to describe what the filter should hide. Clients may use either filterExpression or the "class" attribute, but not both.
• activeByDefault - A value of true indicates the filter should be "on" by default. The user may customize whether the filter is on or off regardless of the value of this attribute. This attribute defines whether the filter is "on" the first time the view is brought up.

<!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.ViewerSorter 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.

• id - The id is used to identify the sorter when debugging a viewer.
• class - A subclass of org.eclipse.jface.viewers.ViewerSorter.

<!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, but its suppressed extension will not. Clients that specify an override element may provide a content provider which implements org.eclipse.ui.navigator.IPipelinedTreeContentProvider, which provides methods to intercept requests for children, parents, and direct updates to the viewer.

• suppressedExtensionId - The id of an extension should be suppressed when this extension is visible and active.
• policy - The policy declares how the extension should be invoked by the framework. If the policy is left unspecified, then it defaults to InvokeAlwaysRegardlessOfSuppressedExt. The available policies are as follows:
  
  • InvokeOnlyIfSuppressedExtAlsoVisibleAndActive: This extension is expressly an overriding extension; unless its suppressed extension is visible and active to the viewer, this extension should not be given opportunities to contribute. When using this policy, this extension will only be invoked when the triggerPoints expression of its suppressed extension and the triggerPoints expression of this extension are enabled for a given element. Therefore, the triggerPoints and possibleChildren expressions of this extension should be a subset of the triggerPoints and possibleChildren expressions respectively of its suppressed extension.
  • InvokeAlwaysRegardlessOfSuppressedExt (default): Indicates that this extension is a first class extension; it should be given opportunities to contribute content regardless if its suppressedExtensionId is visible or active to the viewer. Thus, the extension is a first-class extension and an overriding extension. It will be invoked whenever its triggerPoints expression is matched. When the suppressed extension and its triggerPoints extension is matched, it will be invoked with the contributed items from its suppressed extension; the suppressed extension will not be given an opportunity to directly contribute.

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

• id - The id is used to refer to the drop assistant internally. The id should be unique.
• class - An implementation of org.eclipse.ui.navigator.CommonDropAdapterAssistant

<!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 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 represent a NOT operation on the result of evaluating it's sub-element expression.

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

This element represent an AND operation on the result of evaluating all it's 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 it's 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.

• value - a fully qualified name of a class or interface.

<!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 propery tester 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.

• property - the name of an object's property to test.
• args - additional arguments passed to the property tester. Multiple arguments are separated by commas. Each individual argument is converted into a Java base type using the same rules as defined for the value attribute of the test expression.
• value - the expected value of the property. Can be omitted if the property is a boolean property. The test expression is supposed to return EvaluationResult.TRUE if the property matches the value and EvaluationResult.FALSE otherwise. The value attribute is converted into a Java base type using the following rules:
  • the string "true" is converted into Boolean.TRUE
  • the string "false" is converted into Boolean.FALSE
  • if the string contains a dot then the interpreter tries to convert the value into a Float object. If this fails the string is treated as a java.lang.String
  • if the string only consists of numbers then the interpreter converts the value in an Integer object.
  • in all other cases the string is treated as a java.lang.String
  • the conversion of the string into a Boolean, Float, or Integer can be suppressed by surrounding the string with single quotes. For example, the attribute value="'true'" is converted into the string "true"
• forcePluginActivation - a flag indicating whether the plug-in contributing the property tester should be loaded if necessary. As such, this flag should be used judiciously, in order to avoid unnecessary plug-in activations. Most clients should avoid setting this flag to true. This flag is only honored if the evaluation context used to evaluate this expression allows plug-in activation. Otherwise the flag is ignored and no plug-in loading takes place.

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

• property - the name of an system property to test.
• value - the expected value of the property. The value is interpreted as a string value.

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

• value - the expected value. The value provided as a string is converted into a Java base type using the same rules as for the value attribute of the test expression.

<!ELEMENT count EMPTY>

<!ATTLIST count

value CDATA #REQUIRED

>

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

• value - an expression to specify the number of elements in a list. Following wildcard characters can be used:

  *

  any number of elements

  ?

  no elements or one element

  +

  one or more elements

  !

  no elements

  -N)

  less than N elements

  (N-

  greater than N elements

  integer value

  the list must contain the exact number of elements

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

• variable - the name of the variable to be used for further inspection. It is up to the evaluator of an extension point to provide the variable in the variable pool.

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

• variable - the name of the variable to be resolved. This variable is then used as the object in focus for child element evaluation. It is up to the evaluator of an extension point to provide a corresponding variable resolver (see IVariableResolver) through the evaluation context passed to the root expression element when evaluating the expression.
• args - additional arguments passed to the variable resolver. Multiple arguments are separated by commas. Each individual argument is converted into a Java base type using the same rules as defined for the value attribute of the test expression.

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

• type - the type to which the object in focus is to be adapted.

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

• operator - either "and" or "or". The operator defines how the results of all the child expressions applied to each child of the Collection or IIterable will be combined and what (if any) short circuit evaluation will be used. If not specified, "and" will be used.
• ifEmpty - the value return from the iterate expression if the collection is empty. If not specified then true is returned when the operator equals "and" and false is return if the operator equals "or".

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

• definitionId - The unique id of an expression from org.eclipse.core.expressions.definitions.

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 "Available customizations" 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.ViewerSorter.

<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, 2009 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v10.html