001: /*******************************************************************************
002: * Copyright (c) 2004, 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.internal.commands;
011:
012: /**
013: * <p>
014: * An event indicating that the image bindings have changed.
015: * </p>
016: * <p>
017: * Clients must neither instantiate nor extend.
018: * </p>
019: * <p>
020: * <strong>PROVISIONAL</strong>. This class or interface has been added as
021: * part of a work in progress. There is a guarantee neither that this API will
022: * work nor that it will remain the same. Please do not use this API without
023: * consulting with the Platform/UI team.
024: * </p>
025: * <p>
026: * This class is eventually intended to exist in
027: * <code>org.eclipse.jface.commands</code>.
028: * </p>
029: *
030: * @since 3.2
031: * @see ICommandImageManagerListener#commandImageManagerChanged(CommandImageManagerEvent)
032: */
033: public final class CommandImageManagerEvent {
034:
035: /**
036: * The identifiers of the commands whose image bindings have changed. This
037: * value is never <code>null</code> and never empty.
038: */
039: private final String[] changedCommandIds;
040:
041: /**
042: * The command image manager that has changed. This value is never
043: * <code>null</code>.
044: */
045: private final CommandImageManager commandImageManager;
046:
047: /**
048: * The style of image that changed.
049: */
050: private final String style;
051:
052: /**
053: * The type of image that changed.
054: */
055: private final int type;
056:
057: /**
058: * Creates a new instance of this class.
059: *
060: * @param commandImageManager
061: * the instance of the manager that changed; must not be
062: * <code>null</code>.
063: * @param changedCommandIds
064: * The identifiers of the commands whose image bindings have
065: * changed; this value must not be <code>null</code> and must
066: * not be empty. This value is not copied.
067: */
068: CommandImageManagerEvent(
069: final CommandImageManager commandImageManager,
070: final String[] changedCommandIds, final int type,
071: final String style) {
072: if (commandImageManager == null) {
073: throw new NullPointerException(
074: "An event must refer to its manager"); //$NON-NLS-1$
075: }
076:
077: if ((changedCommandIds == null)
078: || (changedCommandIds.length < 1)) {
079: throw new IllegalArgumentException(
080: "There must be at least one change command identifier"); //$NON-NLS-1$
081: }
082:
083: this .commandImageManager = commandImageManager;
084: this .changedCommandIds = changedCommandIds;
085: this .type = type;
086: this .style = style;
087: }
088:
089: /**
090: * Returns the identifiers of the commands whose bindings have changed.
091: *
092: * @return The identifiers of the commands whose bindings have changed;
093: * neither <code>null</code> nor empty.
094: */
095: public final String[] getChangedCommandIds() {
096: final String[] copy = new String[changedCommandIds.length];
097: System.arraycopy(changedCommandIds, 0, copy, 0,
098: changedCommandIds.length);
099: return copy;
100: }
101:
102: /**
103: * Returns the instance of the interface that changed.
104: *
105: * @return the instance of the interface that changed. Guaranteed not to be
106: * <code>null</code>.
107: */
108: public final CommandImageManager getCommandImageManager() {
109: return commandImageManager;
110: }
111:
112: /**
113: * Returns whether one of the images of the given command has changed.
114: *
115: * @param commandId
116: * The identifier of the command to check; must not be
117: * <code>null</code>.
118: * @return <code>true</code> if one of the command's images has changed;
119: * <code>false</code> otherwise.
120: */
121: public final boolean isCommandIdChanged(final String commandId) {
122: // PERFORMANCE
123: for (int i = 0; i < changedCommandIds.length; i++) {
124: if (commandId.equals(changedCommandIds[i])) {
125: return true;
126: }
127: }
128:
129: return false;
130: }
131:
132: /**
133: * Returns whether the image for the command has changed.
134: *
135: * @param commandId
136: * The identifier of the command to check; must not be
137: * <code>null</code>.
138: * @return <code>true</code> if the command's image has changed
139: * @see CommandImageManager#getImageDescriptor(String)
140: */
141: public final boolean isCommandImageChanged(final String commandId) {
142: return isCommandIdChanged(commandId)
143: && (type == CommandImageManager.TYPE_DEFAULT)
144: && (style == null);
145: }
146:
147: /**
148: * Returns whether the image of the given type for the command has changed.
149: *
150: * @param commandId
151: * The identifier of the command to check; must not be
152: * <code>null</code>.
153: * @param type
154: * The type of image, one of
155: * {@link CommandImageManager#TYPE_DEFAULT},
156: * {@link CommandImageManager#TYPE_DISABLED} or
157: * {@link CommandImageManager#TYPE_HOVER}.
158: * @return <code>true</code> if the command's image of the given type has
159: * changed.
160: * @see CommandImageManager#getImageDescriptor(String, int)
161: */
162: public final boolean isCommandImageChanged(final String commandId,
163: final int type) {
164: return isCommandIdChanged(commandId)
165: && ((type == CommandImageManager.TYPE_DEFAULT) || (type == this .type))
166: && (style == null);
167: }
168:
169: /**
170: * Returns whether the image of the given type and style for the command has
171: * changed.
172: *
173: * @param commandId
174: * The identifier of the command to check; must not be
175: * <code>null</code>.
176: * @param type
177: * The type of image, one of
178: * {@link CommandImageManager#TYPE_DEFAULT},
179: * {@link CommandImageManager#TYPE_DISABLED} or
180: * {@link CommandImageManager#TYPE_HOVER}.
181: * @param style
182: * The style of the image; may be anything.
183: * @return <code>true</code> if the command's image of the given type and
184: * style has changed.
185: * @see CommandImageManager#getImageDescriptor(String, int, String)
186: */
187: public final boolean isCommandImageChanged(final String commandId,
188: final int type, final String style) {
189: return isCommandIdChanged(commandId)
190: && ((type == CommandImageManager.TYPE_DEFAULT) || (type == this .type))
191: && ((style == null) || (style.equals(this .style)));
192: }
193:
194: /**
195: * Returns whether the image of the given style for the command has changed.
196: *
197: * @param commandId
198: * The identifier of the command to check; must not be
199: * <code>null</code>.
200: * @param style
201: * The style of the image; may be anything.
202: * @return <code>true</code> if the command's image of the given style has
203: * changed.
204: * @see CommandImageManager#getImageDescriptor(String, String)
205: */
206: public final boolean isCommandImageChanged(final String commandId,
207: final String style) {
208: return isCommandIdChanged(commandId)
209: && (type == CommandImageManager.TYPE_DEFAULT)
210: && ((style == null) || (style.equals(this.style)));
211: }
212: }
|