1 /******************************************************************************* 2 * Copyright (c) 2000, 2006 IBM Corporation and others. 3 * All rights reserved. This program and the accompanying materials 4 * are made available under the terms of the Eclipse Public License v1.0 5 * which accompanies this distribution, and is available at 6 * http://www.eclipse.org/legal/epl-v10.html 7 * 8 * Contributors: 9 * IBM Corporation - initial API and implementation 10 *******************************************************************************/ 11 package org.eclipse.ui; 12 13 /** 14 * An adapter which performs action filtering. 15 * <p> 16 * Within the workbench a plugin may extend the actions which appear in the 17 * context menu for any object. The visibility of each action extension is controlled 18 * by action filtering. By default, the workbench will filter each action extension using 19 * the <code>objectClass</code> and optional <code>nameFilter</code> attributes defined 20 * in xml. If the action extension passes this test the action will be added to the 21 * context menu for the object. 22 * </p> 23 * <p> 24 * In some situations the object class and name are not enough to describe the intended 25 * target action. In those situations an action extension may define one or more 26 * <code>filter</code> sub-elements. Each one of these elements describes one attribute of 27 * the action target using a <code>name value</code> pair. The attributes for an object 28 * are type specific and beyond the domain of the workbench itself, so the workbench 29 * will delegate filtering at this level to an <code>IActionFilter</code>. This is a 30 * filtering strategy which is provided by the selection itself and may perform type 31 * specific filtering. 32 * </p> 33 * <p> 34 * The workbench will retrieve the filter from the selected object by testing to see 35 * if it implements <code>IActionFilter</code>. If that fails, the workbench will ask for 36 * a filter through through the <code>IAdaptable</code> mechanism. If a filter is 37 * found the workbench will pass each name value pair to the filter to determine if it 38 * matches the state of the selected object. If so, or there is no filter, the action 39 * will be added to the context menu for the object. 40 * </p> 41 * <p> 42 * Clients that implement this filter mechanism are strongly encouraged to extend this 43 * interface to provide a list of attribute names and possible values that are 44 * considered public for other clients to reference. 45 * </p> 46 * 47 * @see org.eclipse.core.runtime.IAdaptable 48 */ 49 public interface IActionFilter { 50 /** 51 * Returns whether the specific attribute matches the state of the target 52 * object. 53 * 54 * @param target the target object 55 * @param name the attribute name 56 * @param value the attribute value 57 * @return <code>true</code> if the attribute matches; <code>false</code> otherwise 58 */ 59 public boolean testAttribute(Object target, String name, String value); 60 } 61