1 /******************************************************************************* 2 * Copyright (c) 2006, 2015 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 * Matthew Hall - bugs 206839, 124684, 239302, 245647, 194734, 195222, 14 * 264286 15 * Ovidio Mallo - bug 270494 16 *******************************************************************************/ 17 18 package org.eclipse.jface.databinding.viewers; 19 20 import org.eclipse.core.databinding.observable.Observables; 21 import org.eclipse.core.databinding.observable.list.IObservableList; 22 import org.eclipse.core.databinding.observable.set.IObservableSet; 23 import org.eclipse.core.databinding.observable.value.IObservableValue; 24 import org.eclipse.jface.databinding.viewers.typed.ViewerProperties; 25 import org.eclipse.jface.internal.databinding.viewers.ViewerObservableValueDecorator; 26 import org.eclipse.jface.viewers.CheckboxTableViewer; 27 import org.eclipse.jface.viewers.CheckboxTreeViewer; 28 import org.eclipse.jface.viewers.ICheckable; 29 import org.eclipse.jface.viewers.IPostSelectionProvider; 30 import org.eclipse.jface.viewers.ISelectionProvider; 31 import org.eclipse.jface.viewers.IStructuredSelection; 32 import org.eclipse.jface.viewers.StructuredViewer; 33 import org.eclipse.jface.viewers.Viewer; 34 35 /** 36 * Factory methods for creating observables for JFace viewers 37 * 38 * @since 1.1 39 */ 40 @SuppressWarnings("rawtypes") 41 public class ViewersObservables { checkNull(Object obj)42 private static void checkNull(Object obj) { 43 if (obj == null) 44 throw new IllegalArgumentException(); 45 } 46 47 /** 48 * Returns an observable which delays notification of value change events 49 * from <code>observable</code> until <code>delay</code> milliseconds have 50 * passed since the last change event, or until a FocusOut event is received 51 * from the underlying viewer control (whichever happens earlier). This 52 * class helps to delay validation until the user stops changing the value 53 * (e.g. until a user stops changing a viewer selection). To notify about 54 * pending changes, the returned observable value will fire a stale event 55 * when the wrapped observable value fires a change event, but this change 56 * is being delayed. 57 * 58 * @param delay 59 * the delay in milliseconds 60 * @param observable 61 * the observable being delayed 62 * @return an observable which delays notification of value change events 63 * from <code>observable</code> until <code>delay</code> 64 * milliseconds have passed since the last change event. 65 * 66 * @since 1.3 67 */ observeDelayedValue(int delay, IViewerObservableValue<T> observable)68 public static <T> IViewerObservableValue<T> observeDelayedValue(int delay, IViewerObservableValue<T> observable) { 69 return new ViewerObservableValueDecorator<>(Observables.observeDelayedValue(delay, observable), 70 observable.getViewer()); 71 } 72 73 /** 74 * Returns an observable value that tracks the current selection of the 75 * given selection provider. If the selection provider provides selections 76 * of type {@link IStructuredSelection}, the observable value will be the 77 * first element of the structured selection as returned by 78 * {@link IStructuredSelection#getFirstElement()}. 79 * 80 * @param selectionProvider provider to get selection from; not <code>null</code> 81 * @return the observable value tracking the (single) selection of the given 82 * selection provider 83 * 84 * @deprecated use <code>ViewerProperties</code> instead 85 */ 86 @Deprecated observeSingleSelection( ISelectionProvider selectionProvider)87 public static IObservableValue observeSingleSelection( 88 ISelectionProvider selectionProvider) { 89 checkNull(selectionProvider); 90 return ViewerProperties.singleSelection().observe(selectionProvider); 91 } 92 93 /** 94 * Returns an observable value that tracks the current <i>post</i> selection 95 * of the given post selection provider. If the selection provider provides 96 * selections of type {@link IStructuredSelection}, the observable value 97 * will be the first element of the structured selection as returned by 98 * {@link IStructuredSelection#getFirstElement()}. 99 * 100 * @param selectionProvider 101 * The selection provider on which to track the <i>post</i> 102 * selection. 103 * @return the observable value tracking the (single) <i>post</i> selection 104 * of the given post selection provider 105 * 106 * @since 1.4 107 * 108 * @deprecated use <code>ViewerProperties</code> instead 109 */ 110 @Deprecated observeSinglePostSelection( IPostSelectionProvider selectionProvider)111 public static IObservableValue observeSinglePostSelection( 112 IPostSelectionProvider selectionProvider) { 113 checkNull(selectionProvider); 114 return ViewerProperties.singlePostSelection() 115 .observe(selectionProvider); 116 } 117 118 /** 119 * Returns an observable list that tracks the current selection of the given 120 * selection provider. Assumes that the selection provider provides 121 * selections of type {@link IStructuredSelection}. Note that the observable 122 * list will not honor the full contract of <code>java.util.List</code> in 123 * that it may delete or reorder elements based on what the selection 124 * provider returns from {@link ISelectionProvider#getSelection()} after 125 * having called 126 * {@link ISelectionProvider#setSelection(org.eclipse.jface.viewers.ISelection)} 127 * based on the requested change to the observable list. The affected 128 * methods are <code>add</code>, <code>addAll</code>, and <code>set</code>. 129 * 130 * @param selectionProvider provider to get selection from; not <code>null</code> 131 * @return the observable value tracking the (multi) selection of the given 132 * selection provider 133 * 134 * @since 1.2 135 * 136 * @deprecated use <code>ViewerProperties</code> instead 137 */ 138 @Deprecated observeMultiSelection( ISelectionProvider selectionProvider)139 public static IObservableList observeMultiSelection( 140 ISelectionProvider selectionProvider) { 141 checkNull(selectionProvider); 142 return ViewerProperties.multipleSelection().observe(selectionProvider); 143 } 144 145 /** 146 * Returns an observable list that tracks the current <i>post</i> selection 147 * of the given post selection provider. Assumes that the selection provider 148 * provides selections of type {@link IStructuredSelection}. Note that the 149 * observable list will not honor the full contract of 150 * <code>java.util.List</code> in that it may delete or reorder elements 151 * based on what the selection provider returns from 152 * {@link ISelectionProvider#getSelection()} after having called 153 * {@link ISelectionProvider#setSelection(org.eclipse.jface.viewers.ISelection)} 154 * based on the requested change to the observable list. The affected 155 * methods are <code>add</code>, <code>addAll</code>, and <code>set</code>. 156 * 157 * @param selectionProvider 158 * The selection provider on which to track the <i>post</i> 159 * selection. 160 * @return the observable value tracking the (multi) <i>post</i> selection 161 * of the given post selection provider 162 * 163 * @since 1.4 164 * 165 * @deprecated use <code>ViewerProperties</code> instead 166 */ 167 @Deprecated observeMultiPostSelection( IPostSelectionProvider selectionProvider)168 public static IObservableList observeMultiPostSelection( 169 IPostSelectionProvider selectionProvider) { 170 checkNull(selectionProvider); 171 return ViewerProperties.multiplePostSelection().observe( 172 selectionProvider); 173 } 174 175 /** 176 * Returns an observable value that tracks the current selection of the 177 * given viewer. If the viewer provides selections of type 178 * {@link IStructuredSelection}, the observable value will be the first 179 * element of the structured selection as returned by 180 * {@link IStructuredSelection#getFirstElement()}. 181 * 182 * @param viewer 183 * the viewer 184 * @return the observable value tracking the (single) selection of the given 185 * viewer 186 * @since 1.2 187 * 188 * @deprecated use <code>ViewerProperties</code> instead 189 */ 190 @Deprecated observeSingleSelection(Viewer viewer)191 public static IViewerObservableValue observeSingleSelection(Viewer viewer) { 192 checkNull(viewer); 193 return ViewerProperties.singleSelection().observe(viewer); 194 } 195 196 /** 197 * Returns an observable value that tracks the current <i>post</i> selection 198 * of the given structured viewer. If the viewer provides selections of type 199 * {@link IStructuredSelection}, the observable value will be the first 200 * element of the structured selection as returned by 201 * {@link IStructuredSelection#getFirstElement()}. 202 * 203 * @param viewer 204 * The viewer on which to track the <i>post</i> selection. 205 * @return the observable value tracking the (single) <i>post</i> selection 206 * of the given structured viewer 207 * 208 * @since 1.4 209 * 210 * @deprecated use <code>ViewerProperties</code> instead 211 */ 212 @Deprecated observeSinglePostSelection( StructuredViewer viewer)213 public static IViewerObservableValue observeSinglePostSelection( 214 StructuredViewer viewer) { 215 checkNull(viewer); 216 return ViewerProperties.singlePostSelection().observe(viewer); 217 } 218 219 /** 220 * Returns an observable list that tracks the current selection of the given 221 * viewer. Assumes that the viewer provides selections of type 222 * {@link IStructuredSelection}. Note that the observable list will not 223 * honor the full contract of <code>java.util.List</code> in that it may 224 * delete or reorder elements based on what the viewer returns from 225 * {@link ISelectionProvider#getSelection()} after having called 226 * {@link ISelectionProvider#setSelection(org.eclipse.jface.viewers.ISelection)} 227 * based on the requested change to the observable list. The affected 228 * methods are <code>add</code>, <code>addAll</code>, and <code>set</code>. 229 * 230 * @param viewer 231 * The viewer on which to track the selection. 232 * @return the observable value tracking the (multi) selection of the given 233 * selection provider 234 * 235 * @since 1.2 236 * 237 * @deprecated use <code>ViewerProperties</code> instead 238 */ 239 @Deprecated observeMultiSelection(Viewer viewer)240 public static IViewerObservableList observeMultiSelection(Viewer viewer) { 241 checkNull(viewer); 242 return ViewerProperties.multipleSelection().observe(viewer); 243 } 244 245 /** 246 * Returns an observable list that tracks the current <i>post</i> selection 247 * of the given structured viewer. Assumes that the viewer provides 248 * selections of type {@link IStructuredSelection}. Note that the observable 249 * list will not honor the full contract of <code>java.util.List</code> in 250 * that it may delete or reorder elements based on what the viewer returns 251 * from {@link ISelectionProvider#getSelection()} after having called 252 * {@link ISelectionProvider#setSelection(org.eclipse.jface.viewers.ISelection)} 253 * based on the requested change to the observable list. The affected 254 * methods are <code>add</code>, <code>addAll</code>, and <code>set</code>. 255 * 256 * @param viewer 257 * The viewer on which to track the <i>post</i> selection. 258 * @return the observable value tracking the (multi) <i>post</i> selection 259 * of the given structured viewer 260 * 261 * @since 1.4 262 * 263 * @deprecated use <code>ViewerProperties</code> instead 264 */ 265 @Deprecated observeMultiPostSelection( StructuredViewer viewer)266 public static IViewerObservableList observeMultiPostSelection( 267 StructuredViewer viewer) { 268 checkNull(viewer); 269 return ViewerProperties.multiplePostSelection().observe(viewer); 270 } 271 272 /** 273 * Returns an observable value that tracks the input of the given viewer. 274 * <p> 275 * The returned observer is blind to changes in the viewer's input unless 276 * its {@link IObservableValue#setValue(Object)} method is called directly. 277 * 278 * @param viewer 279 * the viewer to observe 280 * @return an observable value tracking the input of the given viewer 281 * @since 1.2 282 * 283 * @deprecated use <code>ViewerProperties</code> instead 284 */ 285 @Deprecated observeInput(Viewer viewer)286 public static IObservableValue observeInput(Viewer viewer) { 287 checkNull(viewer); 288 return ViewerProperties.<StructuredViewer, Object>input().observe(viewer); 289 } 290 291 /** 292 * Returns an observable set that tracks the checked elements of the given 293 * <code>ICheckable</code>. 294 * 295 * @param checkable 296 * {@link ICheckable} containing the checked elements to track 297 * @param elementType 298 * element type of the returned set 299 * @return an observable set tracking the checked elements of the given 300 * checkable. 301 * @since 1.2 302 * 303 * @deprecated use <code>ViewerProperties</code> instead 304 */ 305 @Deprecated observeCheckedElements(ICheckable checkable, Object elementType)306 public static IObservableSet observeCheckedElements(ICheckable checkable, 307 Object elementType) { 308 checkNull(checkable); 309 return ViewerProperties.checkedElements(elementType).observe(checkable); 310 } 311 312 /** 313 * Returns an observable set that tracks the checked elements of the given 314 * viewer. Assumes that the viewer implements {@link ICheckable}. 315 * 316 * @param viewer 317 * {@link CheckboxTableViewer} containing the checked elements to 318 * track. 319 * @param elementType 320 * element type of the returned set 321 * @return an observable set that tracks the checked elements of the given 322 * viewer. 323 * @since 1.2 324 * 325 * @deprecated use <code>ViewerProperties</code> instead 326 */ 327 @Deprecated observeCheckedElements(CheckboxTableViewer viewer, Object elementType)328 public static IViewerObservableSet observeCheckedElements(CheckboxTableViewer viewer, Object elementType) { 329 checkNull(viewer); 330 return ViewerProperties.checkedElements(elementType).observe((Viewer) viewer); 331 } 332 333 /** 334 * Returns an observable set that tracks the checked elements of the given 335 * viewer. Assumes that the viewer implements {@link ICheckable}. 336 * 337 * @param viewer 338 * {@link CheckboxTreeViewer} containing the checked elements to 339 * track. 340 * @param elementType 341 * element type of the returned set 342 * @return an observable set that tracks the checked elements of the given 343 * viewer. 344 * @since 1.2 345 * 346 * @deprecated use <code>ViewerProperties</code> instead 347 */ 348 @Deprecated observeCheckedElements(CheckboxTreeViewer viewer, Object elementType)349 public static IViewerObservableSet observeCheckedElements(CheckboxTreeViewer viewer, Object elementType) { 350 checkNull(viewer); 351 return ViewerProperties.checkedElements(elementType).observe((Viewer) viewer); 352 } 353 354 /** 355 * Returns an observable set that tracks the filters of the given viewer. 356 * Note that the returned set will not track changes that are made using 357 * direct API on StructuredViewer (by calling 358 * {@link StructuredViewer#addFilter(org.eclipse.jface.viewers.ViewerFilter) 359 * addFilter()}, 360 * {@link StructuredViewer#removeFilter(org.eclipse.jface.viewers.ViewerFilter) 361 * removeFilter()}, or 362 * {@link StructuredViewer#setFilters(org.eclipse.jface.viewers.ViewerFilter[]) 363 * setFilters()}) -- it is assumed that filters are only changed through the 364 * returned set. 365 * 366 * @param viewer 367 * viewer containing the filters to be tracked 368 * @return an observable set that tracks the filters of the given viewer. 369 * @since 1.3 370 * 371 * @deprecated use <code>ViewerProperties</code> instead 372 */ 373 @Deprecated observeFilters(StructuredViewer viewer)374 public static IViewerObservableSet observeFilters(StructuredViewer viewer) { 375 checkNull(viewer); 376 return ViewerProperties.filters().observe((Viewer) viewer); 377 } 378 } 379