http://www.eclipse.org/platform: Commands (Eclipse Foundation) 
Copyright (c) 2004, 2015 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation

/*******************************************************************************
 * Copyright (c) 2004, 2015 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.core.commands;

import org.eclipse.core.commands.common.EventManager;



This class is a partial implementation of IHandler. This abstract implementation provides support for handler listeners. You should subclass from this method unless you want to implement your own listener support. Subclasses should call fireHandlerChanged(HandlerEvent)when the handler changes. Subclasses can also override isEnabled() and isHandled(). 


Since:3.1
/**
 * <p>
 * This class is a partial implementation of <code>IHandler</code>. This
 * abstract implementation provides support for handler listeners. You should
 * subclass from this method unless you want to implement your own listener
 * support. Subclasses should call
 * {@link AbstractHandler#fireHandlerChanged(HandlerEvent)}when the handler
 * changes. Subclasses can also override {@link AbstractHandler#isEnabled()} and
 * {@link AbstractHandler#isHandled()}.
 * </p>
 *
 * @since 3.1
 */
public abstract class AbstractHandler extends EventManager implements IHandler2 {

	
Track this base class enabled state.

Since:3.4
/**
	 * Track this base class enabled state.
	 *
	 * @since 3.4
	 */
	private boolean baseEnabled = true;

	@Override
	public void addHandlerListener(final IHandlerListener handlerListener) {
		addListenerObject(handlerListener);
	}

	
The default implementation does nothing. Subclasses who attach listeners
to other objects are encouraged to detach them in this method.

/**
	 * The default implementation does nothing. Subclasses who attach listeners
	 * to other objects are encouraged to detach them in this method.
	 */
	@Override
	public void dispose() {
		// Do nothing.
	}

	
Fires an event to all registered listeners describing changes to this
instance.


Subclasses may extend the definition of this method (i.e., if a different
type of listener can be attached to a subclass). This is used primarily
for support of AbstractHandler in
org.eclipse.ui.workbench, and clients should be wary of
overriding this behaviour. If this method is overridden, then the first
line of the method should be "super.fireHandlerChanged(handlerEvent);".



Params:
  • handlerEvent – 
           the event describing changes to this instance. Must not be
           null.
/**
	 * Fires an event to all registered listeners describing changes to this
	 * instance.
	 * <p>
	 * Subclasses may extend the definition of this method (i.e., if a different
	 * type of listener can be attached to a subclass). This is used primarily
	 * for support of <code>AbstractHandler</code> in
	 * <code>org.eclipse.ui.workbench</code>, and clients should be wary of
	 * overriding this behaviour. If this method is overridden, then the first
	 * line of the method should be "<code>super.fireHandlerChanged(handlerEvent);</code>".
	 * </p>
	 *
	 * @param handlerEvent
	 *            the event describing changes to this instance. Must not be
	 *            <code>null</code>.
	 */
	protected void fireHandlerChanged(final HandlerEvent handlerEvent) {
		if (handlerEvent == null) {
			throw new NullPointerException();
		}

		for (Object listener : getListeners()) {
			final IHandlerListener handlerListener = (IHandlerListener) listener;
			handlerListener.handlerChanged(handlerEvent);
		}
	}

	
Whether this handler is capable of executing at this time. Subclasses may override this method. If clients override this method they should also consider overriding setEnabled(Object) so they can be notified about framework execution contexts. 
See Also:
Returns:true
/**
	 * Whether this handler is capable of executing at this time. Subclasses may
	 * override this method. If clients override this method they should also
	 * consider overriding {@link #setEnabled(Object)} so they can be notified
	 * about framework execution contexts.
	 *
	 * @return <code>true</code>
	 * @see #setEnabled(Object)
	 * @see #setBaseEnabled(boolean)
	 */
	@Override
	public boolean isEnabled() {
		return baseEnabled;
	}

	
Allow the default isEnabled() to answer our enabled state. It will fire a HandlerEvent if necessary. If clients use this method they should also consider overriding setEnabled(Object) so they can be notified about framework execution contexts. 
Params:
  • state – 
           the enabled state
Since:3.4
/**
	 * Allow the default {@link #isEnabled()} to answer our enabled state. It
	 * will fire a HandlerEvent if necessary. If clients use this method they
	 * should also consider overriding {@link #setEnabled(Object)} so they can
	 * be notified about framework execution contexts.
	 *
	 * @param state
	 *            the enabled state
	 * @since 3.4
	 */
	protected void setBaseEnabled(boolean state) {
		if (baseEnabled == state) {
			return;
		}
		baseEnabled = state;
		fireHandlerChanged(new HandlerEvent(this, true, false));
	}

	
Called by the framework to allow the handler to update its enabled state
by extracting the same information available at execution time. Clients
may override if they need to extract information from the application
context.

Params:
  • evaluationContext – 
           the application context. May be null
See Also:
Since:3.4
/**
	 * Called by the framework to allow the handler to update its enabled state
	 * by extracting the same information available at execution time. Clients
	 * may override if they need to extract information from the application
	 * context.
	 *
	 * @param evaluationContext
	 *            the application context. May be <code>null</code>
	 * @since 3.4
	 * @see #setBaseEnabled(boolean)
	 */
	@Override
	public void setEnabled(Object evaluationContext) {
	}

	
Whether this handler is capable of handling delegated responsibilities at
this time. Subclasses may override this method.

Returns:true
/**
	 * Whether this handler is capable of handling delegated responsibilities at
	 * this time. Subclasses may override this method.
	 *
	 * @return <code>true</code>
	 */
	@Override
	public boolean isHandled() {
		return true;
	}

	

Returns true iff there is one or more IHandlerListeners attached to this
AbstractHandler.




Subclasses may extend the definition of this method (i.e., if a different
type of listener can be attached to a subclass). This is used primarily
for support of AbstractHandler in
org.eclipse.ui.workbench, and clients should be wary of
overriding this behaviour. If this method is overridden, then the return
value should include "super.hasListeners() ||".



Returns:true iff there is one or more IHandlerListeners attached to this
        AbstractHandler
/**
	 * <p>
	 * Returns true iff there is one or more IHandlerListeners attached to this
	 * AbstractHandler.
	 * </p>
	 * <p>
	 * Subclasses may extend the definition of this method (i.e., if a different
	 * type of listener can be attached to a subclass). This is used primarily
	 * for support of <code>AbstractHandler</code> in
	 * <code>org.eclipse.ui.workbench</code>, and clients should be wary of
	 * overriding this behaviour. If this method is overridden, then the return
	 * value should include "<code>super.hasListeners() ||</code>".
	 * </p>
	 *
	 * @return true iff there is one or more IHandlerListeners attached to this
	 *         AbstractHandler
	 */
	protected boolean hasListeners() {
		return isListenerAttached();
	}

	@Override
	public void removeHandlerListener(final IHandlerListener handlerListener) {
		removeListenerObject(handlerListener);
	}
}