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;
011:
012: import org.eclipse.jface.viewers.ISelection;
013:
014: /**
015: * A selection service tracks the selection within an object.
016: * <p>
017: * A listener that wants to be notified when the selection becomes
018: * <code>null</code> must implement the <code>INullSelectionListener</code>
019: * interface.
020: * </p>
021: * <p>
022: * This interface is not intended to be implemented by clients.
023: * </p>
024: * @see org.eclipse.ui.ISelectionListener
025: * @see org.eclipse.ui.INullSelectionListener
026: */
027: public interface ISelectionService {
028: /**
029: * Adds the given selection listener.
030: * Has no effect if an identical listener is already registered.
031: *
032: * @param listener a selection listener
033: */
034: public void addSelectionListener(ISelectionListener listener);
035:
036: /**
037: * Adds a part-specific selection listener which is notified when selection changes
038: * in the part with the given id. This is independent of part activation - the part
039: * need not be active for notification to be sent.
040: * <p>
041: * When the part is created, the listener is passed the part's initial selection.
042: * When the part is disposed, the listener is passed a <code>null</code> selection,
043: * but only if the listener implements <code>INullSelectionListener</code>.
044: * </p>
045: * <p>
046: * Note: This will not correctly track editor parts as each editor does
047: * not have a unique partId.
048: * </p>
049: *
050: * @param partId the id of the part to track
051: * @param listener a selection listener
052: * @since 2.0
053: */
054: public void addSelectionListener(String partId,
055: ISelectionListener listener);
056:
057: /**
058: * Adds the given post selection listener.It is equivalent to selection
059: * changed if the selection was triggered by the mouse but it has a
060: * delay if the selection is triggered by the keyboard arrows.
061: * Has no effect if an identical listener is already registered.
062: *
063: * Note: Works only for StructuredViewer(s).
064: *
065: * @param listener a selection listener
066: */
067: public void addPostSelectionListener(ISelectionListener listener);
068:
069: /**
070: * Adds a part-specific selection listener which is notified when selection changes
071: * in the part with the given id. This is independent of part activation - the part
072: * need not be active for notification to be sent.
073: * <p>
074: * When the part is created, the listener is passed the part's initial selection.
075: * When the part is disposed, the listener is passed a <code>null</code> selection,
076: * but only if the listener implements <code>INullSelectionListener</code>.
077: * </p>
078: * <p>
079: * Note: This will not correctly track editor parts as each editor does
080: * not have a unique partId.
081: * </p>
082: *
083: * @param partId the id of the part to track
084: * @param listener a selection listener
085: * @since 2.0
086: */
087: public void addPostSelectionListener(String partId,
088: ISelectionListener listener);
089:
090: /**
091: * Returns the current selection in the active part. If the selection in the
092: * active part is <em>undefined</em> (the active part has no selection provider)
093: * the result will be <code>null</code>.
094: *
095: * @return the current selection, or <code>null</code> if undefined
096: */
097: public ISelection getSelection();
098:
099: /**
100: * Returns the current selection in the part with the given id. If the part is not open,
101: * or if the selection in the active part is <em>undefined</em> (the active part has no selection provider)
102: * the result will be <code>null</code>.
103: *
104: * @param partId the id of the part
105: * @return the current selection, or <code>null</code> if undefined
106: * @since 2.0
107: */
108: public ISelection getSelection(String partId);
109:
110: /**
111: * Removes the given selection listener.
112: * Has no effect if an identical listener is not registered.
113: *
114: * @param listener a selection listener
115: */
116: public void removeSelectionListener(ISelectionListener listener);
117:
118: /**
119: * Removes the given part-specific selection listener.
120: * Has no effect if an identical listener is not registered for the given part id.
121: *
122: * @param partId the id of the part to track
123: * @param listener a selection listener
124: * @since 2.0
125: */
126: public void removeSelectionListener(String partId,
127: ISelectionListener listener);
128:
129: /**
130: * Removes the given post selection listener.
131: * Has no effect if an identical listener is not registered.
132: *
133: * @param listener a selection listener
134: */
135: public void removePostSelectionListener(ISelectionListener listener);
136:
137: /**
138: * Removes the given part-specific post selection listener.
139: * Has no effect if an identical listener is not registered for the given part id.
140: *
141: * @param partId the id of the part to track
142: * @param listener a selection listener
143: * @since 2.0
144: */
145: public void removePostSelectionListener(String partId,
146: ISelectionListener listener);
147: }
|