org.eclipse.jface.viewers.Viewer Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.eclipse.jface Show documentation
Show all versions of org.eclipse.jface Show documentation
This is org.eclipse.jface jar used by Scout SDK
The newest version!
/*******************************************************************************
* Copyright (c) 2000, 2015 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
* Lars Vogel - Bug 430873, 475689
*******************************************************************************/
package org.eclipse.jface.viewers;
import org.eclipse.core.runtime.Assert;
import org.eclipse.core.runtime.ListenerList;
import org.eclipse.jface.util.SafeRunnable;
import org.eclipse.swt.events.HelpEvent;
import org.eclipse.swt.events.HelpListener;
import org.eclipse.swt.widgets.Control;
import org.eclipse.swt.widgets.Item;
/**
* A viewer is a model-based adapter on a widget.
*
* A viewer can be created as an adapter on a pre-existing control (e.g.,
* creating a ListViewer on an existing List control).
* All viewers also provide a convenience constructor for creating the control.
*
*
* Implementing a concrete viewer typically involves the following steps:
*
* -
* create SWT controls for viewer (in constructor) (optional)
*
* -
* initialize SWT controls from input (inputChanged)
*
* -
* define viewer-specific update methods
*
* -
* support selections (
setSelection, getSelection)
*
*
*
*/
public abstract class Viewer implements IInputSelectionProvider {
/**
* List of selection change listeners (element type: ISelectionChangedListener).
*
* @see #fireSelectionChanged
*/
private ListenerList selectionChangedListeners = new ListenerList();
/**
* List of help request listeners (element type: org.eclipse.swt.events.HelpListener).
* Help request listeners.
*
* @see #handleHelpRequest
*/
private ListenerList helpListeners = new ListenerList();
/**
* The names of this viewer's properties.
* null if this viewer has no properties.
*
* @see #setData
*/
private String[] keys;
/**
* The values of this viewer's properties.
* null if this viewer has no properties.
* This array parallels the value of the keys field.
*
* @see #setData
*/
private Object[] values;
/**
* Remembers whether we've hooked the help listener on the control or not.
*/
private boolean helpHooked = false;
/**
* Help listener for the control, created lazily when client's first help listener is added.
*/
private HelpListener helpListener = null;
/**
* Unique key for associating element data with widgets.
* @see org.eclipse.swt.widgets.Widget#setData(String, Object)
*/
protected static final String WIDGET_DATA_KEY = "org.eclipse.jface.viewers.WIDGET_DATA";//$NON-NLS-1$
/**
* Creates a new viewer.
*/
protected Viewer() {
}
/**
* Adds a listener for help requests in this viewer.
* Has no effect if an identical listener is already registered.
*
* @param listener a help listener
*/
public void addHelpListener(HelpListener listener) {
helpListeners.add(listener);
if (!helpHooked) {
Control control = getControl();
if (control != null && !control.isDisposed()) {
if (this.helpListener == null) {
this.helpListener = this::handleHelpRequest;
}
control.addHelpListener(this.helpListener);
helpHooked = true;
}
}
}
@Override
public void addSelectionChangedListener(ISelectionChangedListener listener) {
selectionChangedListeners.add(listener);
}
/**
* Notifies any help listeners that help has been requested.
* Only listeners registered at the time this method is called are notified.
*
* @param event a help event
*
* @see HelpListener#helpRequested(org.eclipse.swt.events.HelpEvent)
*/
protected void fireHelpRequested(HelpEvent event) {
Object[] listeners = helpListeners.getListeners();
for (Object listener : listeners) {
((HelpListener) listener).helpRequested(event);
}
}
/**
* Notifies any selection changed listeners that the viewer's selection has changed.
* Only listeners registered at the time this method is called are notified.
*
* @param event a selection changed event
*
* @see ISelectionChangedListener#selectionChanged
*/
protected void fireSelectionChanged(final SelectionChangedEvent event) {
Object[] listeners = selectionChangedListeners.getListeners();
for (Object listener : listeners) {
final ISelectionChangedListener l = (ISelectionChangedListener) listener;
SafeRunnable.run(new SafeRunnable() {
@Override
public void run() {
l.selectionChanged(event);
}
});
}
}
/**
* Returns the primary control associated with this viewer.
*
* @return the SWT control which displays this viewer's content
*/
public abstract Control getControl();
/**
* Returns the value of the property with the given name,
* or null if the property is not found.
*
* The default implementation performs a (linear) search of
* an internal table. Overriding this method is generally not
* required if the number of different keys is small. If a more
* efficient representation of a viewer's properties is required,
* override both getData and setData.
*
*
* @param key the property name
* @return the property value, or null if
* the property is not found
*/
public Object getData(String key) {
Assert.isNotNull(key);
if (keys == null) {
return null;
}
for (int i = 0; i < keys.length; i++) {
if (keys[i].equals(key)) {
return values[i];
}
}
return null;
}
@Override
public abstract Object getInput();
@Override
public abstract ISelection getSelection();
/**
* Handles a help request from the underlying SWT control.
* The default behavior is to fire a help request,
* with the event's data modified to hold this viewer.
* @param event the event
*
*/
protected void handleHelpRequest(HelpEvent event) {
Object oldData = event.data;
event.data = this;
fireHelpRequested(event);
event.data = oldData;
}
/**
* Internal hook method called when the input to this viewer is
* initially set or subsequently changed.
*
* The default implementation does nothing. Subclassers may override
* this method to do something when a viewer's input is set.
* A typical use is populate the viewer.
*
*
* @param input the new input of this viewer, or null if none
* @param oldInput the old input element or null if there
* was previously no input
*/
protected void inputChanged(Object input, Object oldInput) {
}
/**
* Refreshes this viewer completely with information freshly obtained from this
* viewer's model.
*/
public abstract void refresh();
/**
* Removes the given help listener from this viewer.
* Has no effect if an identical listener is not registered.
*
* @param listener a help listener
*/
public void removeHelpListener(HelpListener listener) {
helpListeners.remove(listener);
if (helpListeners.size() == 0) {
Control control = getControl();
if (control != null && !control.isDisposed()) {
control.removeHelpListener(this.helpListener);
helpHooked = false;
}
}
}
@Override
public void removeSelectionChangedListener(
ISelectionChangedListener listener) {
selectionChangedListeners.remove(listener);
}
/**
* Scrolls the viewer's control down by one item from the given
* display-relative coordinates. Returns the newly revealed Item,
* or null if no scrolling occurred or if the viewer
* doesn't represent an item-based widget.
*
* @param x horizontal coordinate
* @param y vertical coordinate
* @return the item scrolled down to
*/
public Item scrollDown(int x, int y) {
return null;
}
/**
* Scrolls the viewer's control up by one item from the given
* display-relative coordinates. Returns the newly revealed Item,
* or null if no scrolling occurred or if the viewer
* doesn't represent an item-based widget.
*
* @param x horizontal coordinate
* @param y vertical coordinate
* @return the item scrolled up to
*/
public Item scrollUp(int x, int y) {
return null;
}
/**
* Sets the value of the property with the given name to the
* given value, or to null if the property is to be
* removed. If this viewer has such a property, its value is
* replaced; otherwise a new property is added.
*
* The default implementation records properties in an internal
* table which is searched linearly. Overriding this method is generally not
* required if the number of different keys is small. If a more
* efficient representation of a viewer's properties is required,
* override both getData and setData.
*
*
* @param key the property name
* @param value the property value, or null if
* the property is not found
*/
public void setData(String key, Object value) {
Assert.isNotNull(key);
/* Remove the key/value pair */
if (value == null) {
if (keys == null) {
return;
}
int index = 0;
while (index < keys.length && !keys[index].equals(key)) {
index++;
}
if (index == keys.length) {
return;
}
if (keys.length == 1) {
keys = null;
values = null;
} else {
String[] newKeys = new String[keys.length - 1];
Object[] newValues = new Object[values.length - 1];
System.arraycopy(keys, 0, newKeys, 0, index);
System.arraycopy(keys, index + 1, newKeys, index,
newKeys.length - index);
System.arraycopy(values, 0, newValues, 0, index);
System.arraycopy(values, index + 1, newValues, index,
newValues.length - index);
keys = newKeys;
values = newValues;
}
return;
}
/* Add the key/value pair */
if (keys == null) {
keys = new String[] { key };
values = new Object[] { value };
return;
}
for (int i = 0; i < keys.length; i++) {
if (keys[i].equals(key)) {
values[i] = value;
return;
}
}
String[] newKeys = new String[keys.length + 1];
Object[] newValues = new Object[values.length + 1];
System.arraycopy(keys, 0, newKeys, 0, keys.length);
System.arraycopy(values, 0, newValues, 0, values.length);
newKeys[keys.length] = key;
newValues[values.length] = value;
keys = newKeys;
values = newValues;
}
/**
* Sets or clears the input for this viewer.
*
* @param input the input of this viewer, or null if none
*/
public abstract void setInput(Object input);
/**
* The viewer implementation of this ISelectionProvider
* method make the new selection for this viewer without making it visible.
*
* This method is equivalent to setSelection(selection,false).
*
*
* Note that some implementations may not be able to set the selection
* without also revealing it, for example (as of 3.3) TreeViewer.
*
*/
@Override
public void setSelection(ISelection selection) {
setSelection(selection, false);
}
/**
* Sets a new selection for this viewer and optionally makes it visible.
*
* Subclasses must implement this method.
*
*
* @param selection the new selection
* @param reveal true if the selection is to be made
* visible, and false otherwise
*/
public abstract void setSelection(ISelection selection, boolean reveal);
}