Common Viewer Configuration

org.eclipse.ui.navigator.viewer

3.2

The viewer element defines the configuration for a common viewer. The extension may provide a custom popup menu id, override whether the viewer provides link with editor support, provides a filter dialog, and/or provides an "Available customizations" dialog. In addition, nested configuration elements give full control over the structure and behavior of the popup context menu.

viewerContentBinding binds defined content extensions (through the navigatorContent extension point) to viewers (defined through the org.eclipse.ui.views extension point). Any content extension bound to a viewer is described as visible. A content service (org.eclipse.ui.navigator.INavigatorContentService) will not return any extensions which are not visible for its viewer id.

EXPERIMENTAL. This class or interface has been added as part of a work in progress. There is a guarantee neither that this API will work nor that it will remain the same. Please do not use this API without consulting with the Platform/UI team.

<!ELEMENT extension (viewer* , viewerContentBinding* , viewerActionBinding*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT viewer (popupMenu? , options?)>

<!ATTLIST viewer

viewerId    CDATA #REQUIRED

popupMenuId CDATA #IMPLIED>

Provides basic configuration to establish the characteristics of a viewer. Clients must also define an org.eclipse.ui.views extension to create the view part.



<!ELEMENT viewerContentBinding (includes? , excludes?)>

<!ATTLIST viewerContentBinding

viewerId CDATA #REQUIRED>

Clients must define one or more viwerContentBinding elements to describe which content extensions and common filters are visible to the viewer. A content extension or common filter is visible if the id of the content extension or common filter matches an includes statement under a viewerContentBinding and is not excluded by an excludes statement. If a content extension or common filter is not visible to a viewer, then the extension will never be asked for content by a content service for that viewer or be presented to the user in the available filters dialog.

Clients may define an includes element to select which extensions are visible to the viewer, and similarly an excludes element for extensions that should not be made visible to the viewer. Clients may further define the extensions that should be explicitly queried for root elements (through ITreeContentProvider.getElements()) by the "isRoot" attribute. If one or more contentExtension elements have "isRoot" set to true within the includes statement, only those extensions will be queried for root elements. The "isRoot" attribute has no effect for exclusions.

A viewer may have multiple viewerContentBindings defined, and their includes/excludes statements will be aggregated to produce the final behavior.



<!ELEMENT viewerActionBinding (includes? , excludes?)>

<!ATTLIST viewerActionBinding

viewerId CDATA #REQUIRED>

Clients must define which action providers are visible to their viewer. Clients may define an includes element to select which extensions are visible to the viewer, and similarly an excludes element for extensions that should not be made visible to the viewer.

A viewer may have multiple viewerActionBindings defined, and their includes/excludes statements will be aggregated to produce the final behavior.

For actionProvider definitions which are not nested under a navigatorContent definition, clients may specify a custom id. If clients do not specify an id, the id defaults to "org.eclipse.ui.navigator.actionProvider". For clients that wish to pick up actionProviders with no specific id, clients must define a viewerActionBinding for the default id. See the examples section for how this is done.



<!ELEMENT includes ((contentExtension+) | (actionExtension+))>

Define a set of patterns that should be included when looking for content extensions for the viewer that matches the "viewerId" attribute. When the includes and excludes statements intersect, the includes statement will be given precedence.



<!ELEMENT excludes ((contentExtension+) | (actionExtension+))>

Define a set of patterns that should be excluded when looking for content extensions for the viewer that matches the "viewerId" attribute. When the includes and excludes statements intersect, the includes statement will be given precedence.



<!ELEMENT contentExtension EMPTY>

<!ATTLIST contentExtension

pattern CDATA #REQUIRED

isRoot  (true | false) >

Indicates the id (or matching pattern) of a content extension that should be queried by ITreeContentProvider.getElements() or ITreeContentProvider.getChildren() for the root of the viewer or a common filter that should be available to the user in the "Available Filters" dialog.

Clients may specify "isRoot" to select specific root extensions to override the extensions which would otherwise be enabled for the viewer input element (based on the matching triggerPoints expression for the viewer input element).

See the documentation for viewerContentBinding for more information.



<!ELEMENT actionExtension EMPTY>

<!ATTLIST actionExtension

pattern CDATA #REQUIRED>

Indicates that the action extension that should be given opportunities to contribute to the context menu and action bars.

See the documentation for viewerActionBinding for more information.



<!ELEMENT popupMenu (insertionPoint*)>

<!ATTLIST popupMenu

id                          CDATA #IMPLIED

allowsPlatformContributions (true | false) >

A popupMenu element may only be defined if the "popupMenuId" attribute of the viewer element is not specified.

The popupMenu element allows further customization of the context menu associated with the viewer. For the options to be applied correctly, an instance of the viewer must delegate to a org.eclipse.ui.navigator.NavigatorActionService, which behaves like a normal org.eclipse.ui.ActionGroup. See the documentation for this API class for more information on exploiting this functionality. For clients that use an instance of org.eclipse.ui.navigator.CommonNavigator do not need to do any extra work.

A popupMenu declares one or more insertionPoints that will be used by contributors to organize their contributions into a meaningful, more user-friendly, consistent list.

If clients only specify the "popupMenuId" attribute of the viewer element, then the set of insertionPoints used by the context menu will default to the following list in the given order: 

"group.new"             separator="true"
"group.goto"            
"group.open"            separator="true"
"group.openWith"
"group.show"            separator="true"
"group.edit"            separator="true"
"group.reorganize"
"group.port"
"group.generate"        separator="true"
"group.search"          separator="true"
"group.build"           separator="true"
"additions"             separator="true" 
"group.properties"      separator="true"

Clients that wish to refer to these values programmatically may use the corresponding constants in org.eclipse.ui.navigator.ICommonMenuConstants.

Clients that wish to customize their menus are encouraged to start with this list and add or remove insertion points as necessary. Clients are also encouraged to follow the pattern of beginning each group name with "group.".

If the popupMenu element is specified and contains NO insertionPoint children elements, then the context menu will have no published insertion points. Of course, programmatic clients are not restricted from adding their own insertion points as necessary. Clients defining viewers are encouraged to publish their insertion points for documentation purposes and clarity for downstream extensions to their viewers/navigators, or to explicitly document which insertion points are considered API and which are considered internal.



<!ELEMENT insertionPoint EMPTY>

<!ATTLIST insertionPoint

name      CDATA #REQUIRED

separator (true | false) >

Defines an insertion point for the context menu. Indcludes the name of the point for clients to refer to, and whether the insertion point should be rendered as a separator or a group marker.



<!ELEMENT options (property+)>

Provide options to the viewer to custom how it is presented to the user. See org.eclipse.ui.navigator.INavigatorViewerDescriptor for the available properties.



<!ELEMENT property EMPTY>

<!ATTLIST property

name  CDATA #REQUIRED

value CDATA #REQUIRED>

Provide a name=value pair. The value will be provided as-is to the viewer (so empty strings will be propagated as empty strings)



The following example configures the popup menu id for a viewer. 


   
<extension
         point=
"org.eclipse.ui.navigator.viewer"
>

      
<viewer 
         id=
"org.eclipse.testViewer"
 
         popupMenuId=
"org.eclipse.testViewer#PopupMenu"
/>

   
</extension>

Since the popupMenu child element of viewer is not used in the above example, the default set of insertionPoints will be used. This set is defined as follows. See the documentation for the popupMenu element for more information. 

"group.new"             separator="true"
"group.goto"            
"group.open"            separator="true"
"group.openWith"
"group.show"            separator="true"
"group.edit"            separator="true"
"group.reorganize"
"group.port"
"group.generate"        separator="true"
"group.search"          separator="true"
"group.build"           separator="true"
"additions"             separator="true" 
"group.properties"      separator="true"

The following example demonstrates a viewer configuration which declares custom popupMenu/insertionPoints, but restricts object and viewer contributions with the "allowsPlatformContributions" attribute. Clients may only contribute to the defined menu via org.eclipse.ui.navigator.CommonActionProviders declared for the viewer (either top-level or associated with content extensions).

Note that the "popupMenuId" attribute is not concurrently specified with the popupMenu element. Only one or the other, but not both, is a valid configuration. 

   
<extension
         point=
"org.eclipse.ui.navigator.viewer"
>

       
<viewer
             viewerId=
"org.eclipse.ui.navigator.resourceContent"
>

          
<popupMenu
                allowsPlatformContributions=
"false"

                id=
"org.eclipse.ui.navigator.resourceContent#PopupMenu"
>
  
             
<insertionPoint name=
"group.new"
/>

             
<insertionPoint
                   name=
"group.open"

                   separator=
"true"
/>

             
<insertionPoint name=
"group.openWith"
/>
             
             
<insertionPoint
                   name=
"group.port"

                   separator=
"true"
/>
 
             
<insertionPoint
                   name=
"additions"

                   separator=
"true"
/>
              
             
<insertionPoint
                   name=
"group.properties"

                   separator=
"true"
/>

          
</popupMenu>

       
</viewer>

       
<viewerContentBinding 
             viewerId=
"org.eclipse.ui.navigator.resourceContent"
>

            
<includes>

                
<contentExtension pattern=
"org.eclipse.ui.navigator.resourceContent"
 />

            
</includes>

       
</viewerContentBinding>

   
</extension>

The following example declares that one content extension (id: "org.eclipse.ui.navigator.resourceContent") is bound to a viewer matching the id "org.eclipse.ui.navigator.resourceContent". (In this example the content extension and viewer ids match, but this is not required.) Further, any content extension with an id that begins with "org.eclipse.ui.navigator.tests." will be ignored. 

   
<extension
         point=
"org.eclipse.ui.navigator.viewer"
>

       
<viewerContentBinding 
             viewerId=
"org.eclipse.ui.navigator.resourceContent"
>

            
<includes>

                
<contentExtension pattern=
"org.eclipse.ui.navigator.resourceContent"
 />

            
</includes>

            
<excludes>

                
<contentExtension pattern=
"org.eclipse.ui.navigator.tests.*"
 />

            
</excludes>

       
</viewerContentBinding>

   
</extension>

The following example declares a viewerActionBinding for all actionProviders (not nested under a navigatorContent extension) that match the regular expression "org.acme.actions.*" but not "org.acme.actions.tests.*". This expression will make any actionProvider whose id begins with "org.acme.actions." but not "org.acme.actions.tests." visible to the viewer with the id "org.acme.viewer". Of course, the viewerActionBindings only apply to actionProvider elements that are not nested under a navigatorContent element. The visibility of nested actionProvider elements is controlled by viewerContentBindings for the enclosing navigatorContent element. 

   
<extension
         point=
"org.eclipse.ui.navigator.viewer"
>

       
<viewerActionBinding 
             viewerId=
"org.acme.viewer"
>

            
<includes>

                
<contentExtension pattern=
"org.acme.actions.*"
 />

            
</includes>

            
<excludes>

                
<contentExtension pattern=
"org.acme.actions.tests.*"
 />

            
</excludes>

       
</viewerActionBinding>

   
</extension>

The following example makes any actionProvider with no "id" attribute visible to the viewer "org.acme.viewer". The actionProviders with no "id" attribute have a default id of "org.eclipse.ui.navigator.actionProvider". Of course, the viewerActionBindings only apply to actionProvider elements that are not nested under a navigatorContent element. The visibility of nested actionProvider elements is controlled by viewerContentBindings for the enclosing navigatorContent element. 

   
<extension
         point=
"org.eclipse.ui.navigator.viewer"
>

       
<viewerActionBinding 
             viewerId=
"org.acme.viewer"
>

            
<includes>

                
<contentExtension pattern=
"org.eclipse.ui.navigator.actionProvider"
 />

            
</includes>
 
       
</viewerActionBinding>

   
</extension>