# 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

>

- point - a fully qualified identifier of the target extension point, in this case, `org.eclipse.gmf.runtime.common.ui.services.action.actionFilterProviders`.
- id - an optional identifier of the extension instance
- name - an optional human readable name of the extension instance

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

- class - the name of a fully qualified class that implements the the `org.eclipse.gmf.runtime.common.ui.services.action.filter.IActionFilterProvider` and `org.eclipse.gmf.runtime.common.core.service.IProvider` interfaces

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

- name - the name of the provider priority, one of `Lowest`, `Low`, `Medium`, `High`, or `Highest`

<!ELEMENT Attribute EMPTY>

<!ATTLIST Attribute

name CDATA #REQUIRED

value CDATA #IMPLIED

>

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

- name - the name of the action filter attribute, which is used to identify the provider that should perform the test for objectState elements used in action enablement or visibility criteria
- value - the optional value of the action filter attribute. When provided it is also used to identify the provider that should perform the test for objectState elements use in action enablement or visibility criteria.

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

- class - the fully qualified name of the class that implements `org.eclipse.gmf.runtime.common.core.service.IProviderPolicy`

###### 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