Action Filter Providers Extension Point

Identifier:
org.eclipse.gmf.runtime.common.ui.services.action.actionFilterProviders

Description:

This extension point is used to configure providers for the action filter service (org.eclipse.gmf.runtime.common.ui.services.action.filter.ActionFilterService).

This service allows action filter attributes to be added to existing types, so long as they adapt to IActionFilter by returning the ActionFilterService. These action filter attributes can then be used inside the objectState element for enablement or visibility of static action contributions. It also permits the entire workbench selection to be considered so that an action can be enabled if it is supported on one or more elements in the selection.

The action filter service will select a provider using one of the following criteria:

  1. by provider descriptor, which uses static XML to determine whether a provider provides the attribute test operation. A given provider can declare, in XML, that it supports zero or more name/value pairs (attribute elements); if the name/value of a given action expression matches any of these, its is assumed to provide the operation.
  2. by provider policy. If no name/value pairs are specified in XML for a given provider, the service will try to load a policy for the provider (using the standard mechanism), if one is specified, and ask the policy if it provides the operation.
  3. by the provider itself. If no name/value pairs and no policy have been specified, the service will load the provider itself and ask it if it provides the operation. Typically, it is preferred to make use of one of the first two criteria for providers.

Note that the value attribute is optional. When available in the provider's XML, the value will be used in conjunction with the name attribute to determine if that provider should be considered. When not available, only the name will be used to make the decision. For example, the value attribute for objectState elements of action expressions is sometimes set to either "enablement" or "visibility". Some action filter providers use this information to determine whether the criteria is being tested to determine enablement or visibility for a contribution.

Configuration Markup:

<!ELEMENT extension (ActionFilterProvider)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT ActionFilterProvider (Priority , Attribute* , Policy?)>

<!ATTLIST ActionFilterProvider

class CDATA #REQUIRED>

This element is used to describe an action filter provider that will contribute action filter attributes to be used inside objectState elements for enablement or visibility of static action contributions.



<!ELEMENT Priority EMPTY>

<!ATTLIST Priority

name (Lowest|Low|Medium|High|Highest) >

This element is used to specify the priority that this provider has relative to other action filter providers that are registered to handle the same action filter attribute. When such a conflict occurs, the provider with the highest priority will be selected to provide the action filter.



<!ELEMENT Attribute EMPTY>

<!ATTLIST Attribute

name  CDATA #REQUIRED

value CDATA #IMPLIED>

This element is used to describe a new action filter attribute.



<!ELEMENT Policy EMPTY>

<!ATTLIST Policy

class CDATA #IMPLIED>

This element can be used to specify a policy used to determine whether or not this provider should be asked to test an action filter attribute. The policy is only used if there are no attribute elements defined for the provider. To delay plugin loading, the recommended strategy for policies is to define them in a separate package and add the package to the Eclipse-LazyStart in the Manifest.MF so that loading the policy class does not load the plug-in.



Examples:
The following is an example of an action filter provider extension:

   <extension
         id="actionFilterProviders"
         name="%ext.actionFilterProviders"
         point="org.eclipse.gmf.runtime.common.ui.services.action.actionFilterProviders">
      <ActionFilterProvider
            class="org.eclipse.test.project.ui.providers.action.AllAreElementsActionFilterProvider">
         <Priority
               name="Highest">
         </Priority>
         <Attribute
               name="AllAreElements"
               value="enablement">
         </Attribute>
         <Attribute
               name="AllAreElements"
               value="visibility">
         </Attribute>
      </ActionFilterProvider>
   </extension>
            


Copyright (c) 2003, 2005 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 http://www.eclipse.org/legal/epl-v10.html