001: /*******************************************************************************
002: * Copyright (c) 2000, 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.activities;
011:
012: import java.util.Set;
013:
014: /**
015: * An instance of this interface is a category as defined by the extension
016: * point <code>org.eclipse.ui.activities</code>.
017: * <p>
018: * An instance of this interface can be obtained from an instance of
019: * <code>IActivityManager</code> for any identifier, whether or not a category
020: * with that identifier is defined in the extension registry.
021: * </p>
022: * <p>
023: * The handle-based nature of this API allows it to work well with runtime
024: * plugin activation and deactivation, which can cause dynamic changes to the
025: * extension registry.
026: * </p>
027: * <p>
028: * This interface is not intended to be extended or implemented by clients.
029: * </p>
030: *
031: * @since 3.0
032: * @see IActivityManager
033: */
034: public interface ICategory extends Comparable {
035:
036: /**
037: * Registers an instance of <code>ICategoryListener</code> to listen for
038: * changes to properties of this instance.
039: *
040: * @param categoryListener
041: * the instance to register. Must not be <code>null</code>.
042: * If an attempt is made to register an instance which is
043: * already registered with this instance, no operation is
044: * performed.
045: */
046: void addCategoryListener(ICategoryListener categoryListener);
047:
048: /**
049: * Returns the set of category activity bindings for this instance.
050: * <p>
051: * This method will return all category activity bindings for this
052: * instance, whether or not this instance is defined.
053: * </p>
054: * <p>
055: * Notification is sent to all registered listeners if this property
056: * changes.
057: * </p>
058: *
059: * @return the set of category activity bindings. This set may be empty,
060: * but is guaranteed not to be <code>null</code>. If this set is
061: * not empty, it is guaranteed to only contain instances of <code>ICategoryActivityBinding</code>.
062: * @see ICategoryActivityBinding
063: */
064: Set getCategoryActivityBindings();
065:
066: /**
067: * Returns the identifier of this instance.
068: *
069: * @return the identifier of this instance. Guaranteed not to be <code>null</code>.
070: */
071: String getId();
072:
073: /**
074: * Returns the name of this instance suitable for display to the user.
075: * <p>
076: * Notification is sent to all registered listeners if this property
077: * changes.
078: * </p>
079: *
080: * @return the name of this instance. Guaranteed not to be <code>null</code>.
081: * @throws NotDefinedException
082: * if this instance is not defined.
083: */
084: String getName() throws NotDefinedException;
085:
086: /**
087: * Returns the description of this instance suitable for display to the user.
088: * <p>
089: * Notification is sent to all registered listeners if this property
090: * changes.
091: * </p>
092: *
093: * @return the description of this instance. Guaranteed not to be <code>null</code>.
094: * @throws NotDefinedException
095: * if this instance is not defined.
096: */
097: String getDescription() throws NotDefinedException;
098:
099: /**
100: * Returns whether or not this instance is defined.
101: * <p>
102: * Notification is sent to all registered listeners if this property
103: * changes.
104: * </p>
105: *
106: * @return <code>true</code>, iff this instance is defined.
107: */
108: boolean isDefined();
109:
110: /**
111: * Removes an instance of <code>ICategoryListener</code> listening
112: * for changes to properties of this instance.
113: *
114: * @param categoryListener
115: * the instance to remove. Must not be <code>null</code>.
116: * If an attempt is made to remove an instance which is not
117: * already registered with this instance, no operation is
118: * performed.
119: */
120: void removeCategoryListener(ICategoryListener categoryListener);
121: }
|