bundles/org.eclipse.jface/src/org/eclipse/jface/commands/CommandImageManagerEvent.java

/*******************************************************************************
 * Copyright (c) 2004, 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
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.commands;

/**
 * <p>
 * An event indicating that the image bindings have changed.
 * </p>
 * <p>
 * Clients must neither instantiate nor extend.
 * </p>
 * <p>
 * <strong>EXPERIMENTAL</strong>. This class or interface has been added as
 * part of a work in progress. There is a guarantee neither that this API will
 * work nor that it will remain the same. Please do not use this API without
 * consulting with the Platform/UI team.
 * </p>
 * 
 * @since 3.2
 * @see ICommandImageManagerListener#commandImageManagerChanged(CommandImageManagerEvent)
 */
public final class CommandImageManagerEvent {

	/**
	 * The identifiers of the commands whose image bindings have changed. This
	 * value is never <code>null</code> and never empty.
	 */
	private final String[] changedCommandIds;

	/**
	 * The command image manager that has changed. This value is never
	 * <code>null</code>.
	 */
	private final CommandImageManager commandImageManager;

	/**
	 * The style of image that changed.
	 */
	private final String style;

	/**
	 * The type of image that changed.
	 */
	private final int type;

	/**
	 * Creates a new instance of this class.
	 * 
	 * @param commandImageManager
	 *            the instance of the manager that changed; must not be
	 *            <code>null</code>.
	 * @param changedCommandIds
	 *            The identifiers of the commands whose image bindings have
	 *            changed; this value must not be <code>null</code> and must
	 *            not be empty. This value is not copied.
	 */
	CommandImageManagerEvent(final CommandImageManager commandImageManager,
			final String[] changedCommandIds, final int type, final String style) {
		if (commandImageManager == null) {
			throw new NullPointerException("An event must refer to its manager"); //$NON-NLS-1$
		}

		if ((changedCommandIds == null) || (changedCommandIds.length < 1)) {
			throw new IllegalArgumentException(
					"There must be at least one change command identifier"); //$NON-NLS-1$
		}

		this.commandImageManager = commandImageManager;
		this.changedCommandIds = changedCommandIds;
		this.type = type;
		this.style = style;
	}

	/**
	 * Returns the identifiers of the commands whose bindings have changed.
	 * 
	 * @return The identifiers of the commands whose bindings have changed;
	 *         neither <code>null</code> nor empty.
	 */
	public final String[] getChangedCommandIds() {
		final String[] copy = new String[changedCommandIds.length];
		System.arraycopy(changedCommandIds, 0, copy, 0,
				changedCommandIds.length);
		return copy;
	}

	/**
	 * Returns the instance of the interface that changed.
	 * 
	 * @return the instance of the interface that changed. Guaranteed not to be
	 *         <code>null</code>.
	 */
	public final CommandImageManager getCommandImageManager() {
		return commandImageManager;
	}

	/**
	 * Returns whether one of the images of the given command has changed.
	 * 
	 * @param commandId
	 *            The identifier of the command to check; must not be
	 *            <code>null</code>.
	 * @return <code>true</code> if one of the command's images has changed;
	 *         <code>false</code> otherwise.
	 */
	public final boolean isCommandIdChanged(final String commandId) {
		// PERFORMANCE
		for (int i = 0; i < changedCommandIds.length; i++) {
			if (commandId.equals(changedCommandIds[i])) {
				return true;
			}
		}

		return false;
	}

	/**
	 * Returns whether the image for the command has changed.
	 * 
	 * @param commandId
	 *            The identifier of the command to check; must not be
	 *            <code>null</code>.
	 * @return <code>true</code> if the command's image has changed
	 * @see CommandImageManager#getImageDescriptor(String)
	 */
	public final boolean isCommandImageChanged(final String commandId) {
		return isCommandIdChanged(commandId)
				&& (type == CommandImageManager.TYPE_DEFAULT)
				&& (style == null);
	}

	/**
	 * Returns whether the image of the given type for the command has changed.
	 * 
	 * @param commandId
	 *            The identifier of the command to check; must not be
	 *            <code>null</code>.
	 * @param type
	 *            The type of image, one of
	 *            {@link CommandImageManager#TYPE_DEFAULT},
	 *            {@link CommandImageManager#TYPE_DISABLED} or
	 *            {@link CommandImageManager#TYPE_HOVER}.
	 * @return <code>true</code> if the command's image of the given type has
	 *         changed.
	 * @see CommandImageManager#getImageDescriptor(String, int)
	 */
	public final boolean isCommandImageChanged(final String commandId,
			final int type) {
		return isCommandIdChanged(commandId)
				&& ((type == CommandImageManager.TYPE_DEFAULT) || (type == this.type))
				&& (style == null);
	}

	/**
	 * Returns whether the image of the given type and style for the command has
	 * changed.
	 * 
	 * @param commandId
	 *            The identifier of the command to check; must not be
	 *            <code>null</code>.
	 * @param type
	 *            The type of image, one of
	 *            {@link CommandImageManager#TYPE_DEFAULT},
	 *            {@link CommandImageManager#TYPE_DISABLED} or
	 *            {@link CommandImageManager#TYPE_HOVER}.
	 * @param style
	 *            The style of the image; may be anything.
	 * @return <code>true</code> if the command's image of the given type and
	 *         style has changed.
	 * @see CommandImageManager#getImageDescriptor(String, int, String)
	 */
	public final boolean isCommandImageChanged(final String commandId,
			final int type, final String style) {
		return isCommandIdChanged(commandId)
				&& ((type == CommandImageManager.TYPE_DEFAULT) || (type == this.type))
				&& ((style == null) || (style.equals(this.style)));
	}

	/**
	 * Returns whether the image of the given style for the command has changed.
	 * 
	 * @param commandId
	 *            The identifier of the command to check; must not be
	 *            <code>null</code>.
	 * @param style
	 *            The style of the image; may be anything.
	 * @return <code>true</code> if the command's image of the given style has
	 *         changed.
	 * @see CommandImageManager#getImageDescriptor(String, String)
	 */
	public final boolean isCommandImageChanged(final String commandId,
			final String style) {
		return isCommandIdChanged(commandId)
				&& (type == CommandImageManager.TYPE_DEFAULT)
				&& ((style == null) || (style.equals(this.style)));
	}
}