1 /******************************************************************************* 2 * Copyright (c) 2000, 2016 IBM Corporation and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * IBM Corporation - initial API and implementation 13 *******************************************************************************/ 14 package org.eclipse.ui; 15 16 import org.eclipse.jface.viewers.ISelection; 17 18 /** 19 * A selection service tracks the selection within an object. 20 * <p> 21 * A listener that wants to be notified when the selection becomes 22 * <code>null</code> must implement the <code>INullSelectionListener</code> 23 * interface. 24 * </p> 25 * <p> 26 * This service can be acquired from your service locator: 27 * </p> 28 * 29 * <pre> 30 * ISelectionService service = (ISelectionService) getSite().getService(ISelectionService.class); 31 * </pre> 32 * 33 * This service is not available globally, only from the workbench window level 34 * down. 35 * 36 * @see org.eclipse.ui.ISelectionListener 37 * @see org.eclipse.ui.INullSelectionListener 38 * @see org.eclipse.ui.services.IServiceLocator#getService(Class) 39 * @noimplement This interface is not intended to be implemented by clients. 40 */ 41 public interface ISelectionService { 42 /** 43 * Adds the given selection listener. Has no effect if an identical listener is 44 * already registered. 45 * <p> 46 * <b>Note:</b> listeners should be removed when no longer necessary. If not, 47 * they will be removed when the IServiceLocator used to acquire this service is 48 * disposed. 49 * </p> 50 * <p> 51 * <b>Note:</b> only update the UI when the UI is visible. See the 52 * {@link SelectionListenerFactory} for listeners that will only be called when 53 * the UI is visible to the user. 54 * </p> 55 * 56 * 57 * @param listener a selection listener 58 * @see #removeSelectionListener(ISelectionListener) 59 * @see SelectionListenerFactory#createVisibleListener(IWorkbenchPart, 60 * ISelectionListener) 61 * @see SelectionListenerFactory#createVisibleSelfMutedListener(IWorkbenchPart, 62 * ISelectionListener) 63 */ addSelectionListener(ISelectionListener listener)64 void addSelectionListener(ISelectionListener listener); 65 66 /** 67 * Adds a part-specific selection listener which is notified when selection 68 * changes in the part with the given id. This is independent of part activation 69 * - the part need not be active for notification to be sent. 70 * <p> 71 * When the part is created, the listener is passed the part's initial 72 * selection. When the part is disposed, the listener is passed a 73 * <code>null</code> selection, but only if the listener implements 74 * <code>INullSelectionListener</code>. 75 * </p> 76 * <p> 77 * <b>Note:</b> this will not correctly track editor parts as each editor does 78 * not have a unique partId. 79 * </p> 80 * <p> 81 * <b>Note:</b> listeners should be removed when no longer necessary. If not, 82 * they will be removed when the IServiceLocator used to acquire this service is 83 * disposed. 84 * </p> 85 * <p> 86 * <b>Note:</b> only update the UI when the UI is visible. See the 87 * {@link SelectionListenerFactory} for listeners that will only be called when 88 * the UI is visible to the user. 89 * </p> 90 * 91 * @param partId the id of the part to track 92 * @param listener a selection listener 93 * @since 2.0 94 * @see #removeSelectionListener(String, ISelectionListener) 95 * @see SelectionListenerFactory#createVisibleListener(IWorkbenchPart, 96 * ISelectionListener) 97 * @see SelectionListenerFactory#createVisibleSelfMutedListener(IWorkbenchPart, 98 * ISelectionListener) 99 */ addSelectionListener(String partId, ISelectionListener listener)100 void addSelectionListener(String partId, ISelectionListener listener); 101 102 /** 103 * Adds the given post selection listener.It is equivalent to selection changed 104 * if the selection was triggered by the mouse but it has a delay if the 105 * selection is triggered by the keyboard arrows. Has no effect if an identical 106 * listener is already registered. 107 * 108 * Note: Works only for StructuredViewer(s). 109 * <p> 110 * <b>Note:</b> listeners should be removed when no longer necessary. If not, 111 * they will be removed when the IServiceLocator used to acquire this service is 112 * disposed. 113 * </p> 114 * <p> 115 * <b>Note:</b> only update the UI when the UI is visible. See the 116 * {@link SelectionListenerFactory} for listeners that will only be called when 117 * the UI is visible to the user. 118 * </p> 119 * 120 * 121 * @param listener a selection listener 122 * @see #removePostSelectionListener(ISelectionListener) 123 * @see SelectionListenerFactory#createVisibleListener(IWorkbenchPart, 124 * ISelectionListener) 125 * @see SelectionListenerFactory#createVisibleSelfMutedListener(IWorkbenchPart, 126 * ISelectionListener) 127 */ addPostSelectionListener(ISelectionListener listener)128 void addPostSelectionListener(ISelectionListener listener); 129 130 /** 131 * Adds a part-specific selection listener which is notified when selection 132 * changes in the part with the given id. This is independent of part activation 133 * - the part need not be active for notification to be sent. 134 * <p> 135 * When the part is created, the listener is passed the part's initial 136 * selection. When the part is disposed, the listener is passed a 137 * <code>null</code> selection, but only if the listener implements 138 * <code>INullSelectionListener</code>. 139 * </p> 140 * <p> 141 * <b>Note:</b> this will not correctly track editor parts as each editor does 142 * not have a unique partId. 143 * </p> 144 * <p> 145 * <b>Note:</b> listeners should be removed when no longer necessary. If not, 146 * they will be removed when the IServiceLocator used to acquire this service is 147 * disposed. 148 * </p> 149 * <p> 150 * <b>Note:</b> only update the UI when the UI is visible. See the 151 * {@link SelectionListenerFactory} for listeners that will only be called when 152 * the UI is visible to the user. 153 * </p> 154 * 155 * @param partId the id of the part to track 156 * @param listener a selection listener 157 * @since 2.0 158 * @see #removePostSelectionListener(String, ISelectionListener) 159 * @see SelectionListenerFactory#createVisibleListener(IWorkbenchPart, 160 * ISelectionListener) 161 * @see SelectionListenerFactory#createVisibleSelfMutedListener(IWorkbenchPart, 162 * ISelectionListener) 163 */ addPostSelectionListener(String partId, ISelectionListener listener)164 void addPostSelectionListener(String partId, ISelectionListener listener); 165 166 /** 167 * Returns the current selection in the active part. If the selection in the 168 * active part is <em>undefined</em> (the active part has no selection provider) 169 * the result will be <code>null</code>. 170 * 171 * @return the current selection, or <code>null</code> if undefined 172 */ getSelection()173 ISelection getSelection(); 174 175 /** 176 * Returns the current selection in the part with the given id. If the part is 177 * not open, or if the selection in the active part is <em>undefined</em> (the 178 * active part has no selection provider) the result will be <code>null</code>. 179 * 180 * @param partId the id of the part 181 * @return the current selection, or <code>null</code> if undefined 182 * @since 2.0 183 */ getSelection(String partId)184 ISelection getSelection(String partId); 185 186 /** 187 * Removes the given selection listener. Has no effect if an identical listener 188 * is not registered. 189 * 190 * @param listener a selection listener 191 */ removeSelectionListener(ISelectionListener listener)192 void removeSelectionListener(ISelectionListener listener); 193 194 /** 195 * Removes the given part-specific selection listener. Has no effect if an 196 * identical listener is not registered for the given part id. 197 * 198 * @param partId the id of the part to track 199 * @param listener a selection listener 200 * @since 2.0 201 */ removeSelectionListener(String partId, ISelectionListener listener)202 void removeSelectionListener(String partId, ISelectionListener listener); 203 204 /** 205 * Removes the given post selection listener. Has no effect if an identical 206 * listener is not registered. 207 * 208 * @param listener a selection listener 209 */ removePostSelectionListener(ISelectionListener listener)210 void removePostSelectionListener(ISelectionListener listener); 211 212 /** 213 * Removes the given part-specific post selection listener. Has no effect if an 214 * identical listener is not registered for the given part id. 215 * 216 * @param partId the id of the part to track 217 * @param listener a selection listener 218 * @since 2.0 219 */ removePostSelectionListener(String partId, ISelectionListener listener)220 void removePostSelectionListener(String partId, ISelectionListener listener); 221 } 222