001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 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.contexts;
011:
012: /**
013: * An instance of this interface is an context as defined by the extension point
014: * <code>org.eclipse.ui.contexts</code>.
015: * <p>
016: * An instance of this interface can be obtained from an instance of
017: * <code>IContextManager</code> for any identifier, whether or not an context
018: * with that identifier is defined in the extension registry.
019: * </p>
020: * <p>
021: * The handle-based nature of this API allows it to work well with runtime
022: * plugin activation and deactivation. If a context is defined, that means that
023: * its corresponding plug-in is active. If the plug-in is then deactivated, the
024: * context will still exist but it will be undefined. An attempts to use an
025: * undefined context will result in a <code>NotDefinedException</code> being
026: * thrown.
027: * </p>
028: * <p>
029: * This interface is not intended to be extended or implemented by clients.
030: * </p>
031: *
032: * @since 3.0
033: * @see org.eclipse.ui.contexts.IContextManager
034: * @see org.eclipse.core.commands.contexts.Context
035: * @deprecated Please use the "org.eclipse.core.commands" plug-in instead.
036: */
037: public interface IContext extends Comparable {
038:
039: /**
040: * Registers an instance of <code>IContextListener</code> to listen for
041: * changes to properties of this instance.
042: *
043: * @param contextListener
044: * the instance to register. Must not be <code>null</code>. If
045: * an attempt is made to register an instance which is already
046: * registered with this instance, no operation is performed.
047: */
048: void addContextListener(IContextListener contextListener);
049:
050: /**
051: * Returns the identifier of this instance.
052: *
053: * @return the identifier of this instance. Guaranteed not to be
054: * <code>null</code>.
055: */
056: String getId();
057:
058: /**
059: * Returns the name of this instance suitable for display to the user.
060: * <p>
061: * Notification is sent to all registered listeners if this property
062: * changes.
063: * </p>
064: *
065: * @return the name of this instance. Guaranteed not to be <code>null</code>.
066: * @throws NotDefinedException
067: * if this instance is not defined.
068: */
069: String getName() throws NotDefinedException;
070:
071: /**
072: * Returns the identifier of the parent of this instance.
073: * <p>
074: * Notification is sent to all registered listeners if this property
075: * changes.
076: * </p>
077: *
078: * @return the identifier of the parent of this instance. May be
079: * <code>null</code>.
080: * @throws NotDefinedException
081: * if this instance is not defined.
082: */
083: String getParentId() throws NotDefinedException;
084:
085: /**
086: * Returns whether or not this instance is defined.
087: * <p>
088: * Notification is sent to all registered listeners if this property
089: * changes.
090: * </p>
091: *
092: * @return true, iff this instance is defined.
093: */
094: boolean isDefined();
095:
096: /**
097: * Returns whether or not this instance is enabled.
098: * <p>
099: * Notification is sent to all registered listeners if this property
100: * changes.
101: * </p>
102: *
103: * @return true, iff this instance is enabled.
104: */
105: boolean isEnabled();
106:
107: /**
108: * Unregisters an instance of <code>IContextListener</code> listening for
109: * changes to properties of this instance.
110: *
111: * @param contextListener
112: * the instance to unregister. Must not be <code>null</code>.
113: * If an attempt is made to unregister an instance which is not
114: * already registered with this instance, no operation is
115: * performed.
116: */
117: void removeContextListener(IContextListener contextListener);
118: }
|