001: /*******************************************************************************
002: * Copyright (c) 2005, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.handlers;
011:
012: import org.eclipse.core.commands.IHandler;
013: import org.eclipse.core.expressions.IEvaluationContext;
014: import org.eclipse.ui.internal.services.IEvaluationResultCache;
015:
016: /**
017: * <p>
018: * A token representing the activation of a handler. This token can later be
019: * used to cancel that activation. Without this token, then handler will only
020: * become inactive if the component in which the handler was activated is
021: * destroyed.
022: * </p>
023: * <p>
024: * This interface is not intended to be implemented or extended by clients.
025: * </p>
026: *
027: * @since 3.1
028: * @see org.eclipse.ui.ISources
029: * @see org.eclipse.ui.ISourceProvider
030: */
031: public interface IHandlerActivation extends IEvaluationResultCache,
032: Comparable {
033:
034: /**
035: * The depth at which the root exists.
036: *
037: * @since 3.2
038: */
039: public static final int ROOT_DEPTH = 1;
040:
041: /**
042: * Clears the cached computation of the <code>isActive</code> method, if
043: * any. This method is only intended for internal use. It provides a
044: * mechanism by which <code>ISourceProvider</code> events can invalidate
045: * state on a <code>IHandlerActivation</code> instance.
046: *
047: * @deprecated Use {@link IEvaluationResultCache#clearResult()} instead.
048: */
049: public void clearActive();
050:
051: /**
052: * Returns the identifier of the command whose handler is being activated.
053: *
054: * @return The command identifier; never <code>null</code>.
055: */
056: public String getCommandId();
057:
058: /**
059: * Returns the depth at which this activation was created within the
060: * services hierarchy. The root of the hierarchy is at a depth of
061: * <code>1</code>. This is used as the final tie-breaker in the event
062: * that no other method can be used to determine a winner.
063: *
064: * @return The depth at which the handler was inserted into the services
065: * hierarchy; should be a positive integer.
066: * @since 3.2
067: */
068: public int getDepth();
069:
070: /**
071: * Returns the handler that should be activated.
072: *
073: * @return The handler; may be <code>null</code>.
074: */
075: public IHandler getHandler();
076:
077: /**
078: * Returns the handler service from which this activation was requested.
079: * This is used to ensure that an activation can only be retracted from the
080: * same service which issued it.
081: *
082: * @return The handler service; never <code>null</code>.
083: */
084: public IHandlerService getHandlerService();
085:
086: /**
087: * Returns whether this handler activation is currently active -- given the
088: * current state of the workbench. This method should cache its computation.
089: * The cache will be cleared by a call to <code>clearActive</code>.
090: *
091: * @param context
092: * The context in which this state should be evaluated; must not
093: * be <code>null</code>.
094: * @return <code>true</code> if the activation is currently active;
095: * <code>false</code> otherwise.
096: * @deprecated Use
097: * {@link IEvaluationResultCache#evaluate(IEvaluationContext)}
098: * instead.
099: */
100: public boolean isActive(IEvaluationContext context);
101: }
|